Decimal

The Decimal class has been created to make easier handling large numbers inside financial applications without precision loss.

Import

To import the Decimal class, you must add the following line in the header of your PHP script:

use Litipk\BigNumbers\Decimal;

Constructors

The Decimal class provides many static constructors.

From any given value:

The most generic constructor, but also the slowest one.

Decimal::create($value, $scale=null)

• $value : Any PHP native variable that represents a number.
• $scale : The precision we want (measured in number of digits behind the fixed point).

From Integers

Decimal::fromInteger($intValue, $scale=null)

From Floating Point Numbers

Decimal::fromFloat($fltValue, $scale=null)

From Strings

Decimal::fromString($strValue, $scale=null)

From other Decimal objects

Constructs a new Decimal object based on a previous one, but changing it's $scale property.

Decimal::fromDecimal(Decimal $b, $scale=null)

Infinite Numbers

Be aware that this methods are only here for convenience, but the recommended way is to directly use the static methods of the InfiniteDecimal class.

Positive Infinite:

$pInfinite = Decimal::getPositiveInfinite();

Negative Infinite:

$nInfinite = Decimal::getNegativeInfinite();

Binary Operators

Remember that all Decimal objects are immutable, all operators return new instances rather than modify the object that called the method.

Addition

// c = a + b
$c = $a->add($b, $scale); // $a and $b are Decimal objects. $scale is optional (positive integer).

Subtraction

// c = a - b
$c = $a->sub($b, $scale); // $a and $b are Decimal objects. $scale is optional (positive integer).

Multiplication

// c = a · b
$c = $a->mul($b, $scale); // $a and $b are Decimal objects. $scale is optional (positive integer).

Division

// c = a / b
$c = $a->div($b, $scale); // $a and $b are Decimal objects. $scale is optional (positive integer).

Pow

// c = a^b
$c = $a->pow($b, $scale); // $a and $b are Decimal objects. $scale is optional (positive integer).

If $b is 0.5 then is preferable to use the sqrt method rather than the pow method.

Comparisons

Equality Comparison. Returns true or false.

Decimal::fromString("5")->equals(Decimal::fromInteger(5)); // returns true
Decimal::fromString("1")->equals(Decimal::fromString("2")); // returns false

Sign Comparison. Returns true or false.

Decimal::fromString("5")->hasSameSign(Decimal::fromString("25")); // returns true
Decimal::fromString("-5")->hasSameSign(Decimal::fromString("9")); // returns false

"Complete" comparison. Returns -1 if less, 0 if equal and 1 if greater.

Decimal::fromInteger(5)->comp(Decimal::fromInteger(1)); // returns 1
Decimal::fromInteger(1)->comp(Decimal::fromInteger(5)); // returns -1
Decimal::fromInteger(5)->comp(Decimal::fromInteger(5)); // returns 0

Unary Operators

Square Root

$b = $a->sqrt($scale); // $scale is optional (positive integer).

Trigonometric Functions

Currently, the precision of these functions is bounded by the PI constant precision.

Sinus:

$b = $a->sin($scale); // $scale is optional (positive integer).

Cosinus:

$b = $a->cos($scale); // $scale is optional (positive integer).

Tangent:

$b = $a->tan($scale); // $scale is optional (positive integer).

Logarithms

Logarithm with base 10:

$b = $a->log10($scale); // $scale is optional (positive integer).

Sign Operations

Absolute value (in this case,the number with positive sign):

$b = $a->abs();

Additive inverse (sign change):

$b = $a->additiveInverse();

"Rounding"

Classic rounding, finding the closest number with given number of decimal digits:

$b = $a->round($scale); // Scale is optional (0 by default, must be a positive integer).

Floor. Finds the closest number with given decimal digits (specified by $scale) discarding the ones above the given number:

$b = $a->floor($scale); // Scale is optional (0 by default, must be a positive integer).

Ceil. Finds the closest number with given decimal digits (specified by $scale) discarding the ones below the given number:

$b = $a->ceil($scale); // Scale is optional (0 by default, must be a positive integer).

Boolean Properties

isZero

// Scale is optional (null by default). If set, the number is rounded before checking if is zero.
Decimal::fromString("0")->isZero($scale); // Returns true
Decimal::fromString("1")->isZero($scale); // Returns false
Decimal::fromString("0.25")->isZero($scale); // The result depends on $scale.

isPositive

Decimal::fromString("5")->isPositive(); // Returns true
Decimal::fromString("-5")->isPositive(); // Returns false

isNegative

Decimal::fromString("5")->isNegative(); // Returns false
Decimal::fromString("-5")->isNegative(); // Returns true

isInfinite

Always returns false for Decimal objects. Be aware that you can create InfiniteDecimal instances from a static method in Decimal only for convenience.

Decimal::fromString("5")->isInfinite(); // returns false
Decimal::getPositiveInfinite()->isInfinite(); // returns true. (But it's an InfiniteDecimal object).
Decimal::getNegativeInfinite()->isInfinite(); // returns true. (But it's an InfiniteDecimal object).

PHP's Native Types Interaction