<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fNumber">Class Documentation</a>''' - <a href="/api/fNumber">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fNumber.php" target="_blank">Source Code</a>
<<toc></toc>>
- fDate - fMoney - '''fNumber''' - fTime - fTimestamp
)))
The fNumber class is a value object to represent large integers and arbitrary precision decimal values. The fNumber class is essential when dealing with calculations that must be precise, such as monetary value (consequently the fMoney class is built on top of fNumber). It supplies the same math functionality that is built into PHP, minus the trigonometric operations.
An fNumber object requires just a single parameter for the constructor, the value to represent. It can be a string, an object with a `__toString()` method, or an integer. If the value being represented is too large to store in an integer, the integer value should be enter via a string to prevent data loss. Also, float values should never be used since they have an inherent loss of precision that this class is designed to overcome.
There is a second optional parameter to the constructor that allows specifying the precision of the number. If no precision is specified, the precision of the value is used.
Basic arithmetic is performed using the method ::add(), ::sub(), ::mul() and ::div(). Since the fNumber class is a value object, all operations return a new fNumber object instead of modifying the existing one. Also, all methods accept any valid number representation including strings, fNumber objects and integers.
The returned fNumber object will have the same precision as the object being called unless the optional parameter `$scale` is included.
Addition is performed by calling the method ::add() and providing an `$addend`.
Subtraction is performed by calling the method ::sub() and providing a `$subtrahend`.
Multiplication is performed by calling the method ::mul() and providing a `$multiplicand`.
Division is performed by calling the method ::div() and providing a `$divisor`.
The remainder of integer division can be calculated by the method ::mod() and the remainder of fractional division can be calculated by the method ::fmod().
The `mod()` method will convert the current number to an integer and then divide it by the single parameter, `$divisor`, that is passed to the method. The `$divisor` is also converted to an integer before the calculation is performed.
The `fmod()` method allows dividing a fractional number by another fractional number, returning the remainder. The first parameter is the `$divisor` to use, while a second optional parameter, `$scale`, allows specifying the scale of the remainder that is being returned.
The fNumber class provides functionality to calculate both square roots and integer powers via the ::sqrt() and ::pow() methods.
The `sqrt()` method accepts a single optional parameter, the `$scale` of the result.
The `pow()` method accepts two parameters, the required `$exponent` to raise the number to, and the optional `$scale` for the resulting number.
Under certain situations, especially when dealing with cryptography, it is necessary to raise integers to large powers and then calculate the remainder of the division of that product by another integer. Normal calculation by raising the original number to a large power and then dividing to find the remainder often takes far too much computation. There are, however, some mathematical shortcuts to make such calculations significantly faster.
The ::powmod() method allows calculating the remainder of the original number raised to an `$exponent` and then divided by the `$modulus`.
The fNumber class include comparison methods for testing equality - ::eq(), less than - ::lt(), less than or equal - ::lte(), greater than - ::gt() and greater than or equal - ::gte(). Each method accepts two parameters, the `$number` to compare to and an optional `$scale` to use for comparison.
The `$number` to compare to may be any valid fNumber object, string or integer. The `$scale` parameter sets how many digits after the decimal point to use during comparison. If no scale is specified, the highest scale of the two numbers will be used.
There are two options to format fNumber objects, either ::__toString() or ::format(). The `format()` method will include thousands separators in the returned value, while `__toString()` will not. The inherent scale of the number will be used when displaying the value. To change the scale, use the ::trunc() or ::round() method first.
would output the following
If the parameter `$remove_zero_fraction` is set to `TRUE` and the value has a fraction that is just zeros, the resulting output will not contain a decimal point or a fraction.
The precision of an fNumber can be modified by using the ::ceil(), ::floor(), ::round() and ::trunc() methods.
The `ceil()` method performs a ceiling operation, rounding up to the next highest integer.
The `floor()` method preforms a floor operation, rounding down to the next lowest integer.
The `trunc()` method changes the scale of the number to 0 without performing any rounding.
The `round()` method allows rounding a number to a specified number of decimal places, using the `$scale` parameter. It is even possible to round left of the decimal point using negative scales. Rounding is done using the common method, that is when the digit one place beyond the `$scale` is 5 or greater the `$scale` digit is increased vy 1, otherwise the digit is left the same.
The fNumber class can calculate the absolute value of a number via the ::abs() method, the negated value via the ::neg() method and can return the sign of a number via the ::sign() method.
Here are a few basic example of using the `abs()` and `neg()` methods:
The `sign()` method will return `-1` if the number is negative, `0` if the number is zero and `1` if the number is positive.
The value of pi can be obtained up to a scale of 500 by calling the static method ::pi() and providing the desired `$scale`.
For some calculations, representing numbers in a base other than base 10 is necessary. The static method ::baseConvert() allow converting integers between any two bases ranging from base 2 (binary) to base 16 (hexadecimal). Three parameters are required, the integer to convert, the base being converted from and the base being converted to.
would output the following
When formatting numbers in different locales, it will often be the case that the thousands separator and decimal point are different than the one in the United States. The methods ::registerFormatCallback() and ::registerUnformatCallback() allow for both creating a different formatting and also removing such formatting when creating a new fNumber object.