Long numbers & operations with them

Object-oriented wrapper for BCMath with some additional functionality.

Conventions

Number(s)

A value (set of values) of type Number, or an integer/float type, or a string that can be cast to a number (including a record with an exponent of the form 1.2e−3).

If the method accepts both a single value and an array, then this array must not be empty, otherwise an exception will be thrown.

Precision

Calculation precision (number of decimal places) - a non-negative integer or NULL to preserve the accuracy of the original value.

By default, if precision is not explicitly specified, all operations use same precision as the original value; for example, adding number 12 and string «13.50» will result in 26, since 25.50 will be rounded to 0 decimal places, which is precision of an integer.

If you want to give the operation result with the highest precision among all arguments, then you should specify PHP_INT_MAX as the precision.

Round

Rounding type. Used when the accuracy of the final value should be less than the accuracy of the initial value. There are three types of rounding to a value with the specified precision (examples are given for precision equal to 1):

• floor - to the nearest bottom: 2.67 → 2.6, −2.67 → −2.7;
• ceil - to the nearest top: 2.67 → 2.7, −2.67 → −2.6;
• round - to the nearest one, the modulus of the difference with which this number has a minimum: 1.19 → 1.2, −0.19 → −0.2, −1.14 → −1.1, 2.15 → 2.2.

The default rounding type is round. Additional see Rounding.

Interface

1. Round defines by constants: ROUND_FLOOR = -1, ROUND_NORM = 0, ROUND_CEIL = 1;
2. returns integer: -1 - if value is less than zero, 1 - if greater than zero, 0 - if equals to zero;
3. the initial value must not be negative, otherwise an exception will be thrown;
4. returns 0 if the two operands are equal, 1 if the 1st is larger than the 2nd, -1 otherwise; see bccomp results;
5. strict comparisons are used by default, i.e. ≥ and ≤; the Bounds bitmask can reduce the strictness to > and <; use constants for this: RANGE_EXCLUDE_MIN = 1, RANGE_EXCLUDE_MAX = 2 and RANGE_EXCLUDE_BOTH = 3.

Additional see Magic Methods and Serializable interface.

Exceptions

All package exceptions are in namespace Jzucen\LongNumber\Exception and

• implement one ExceptionInterface interface, i.e. it is possible to catch all errors at once;
• have the same names as SPL Exceptions, and also extend them, i.e. can be catched by base names;
• have codes from their own hexadecimal hundred: 01xx for BadFunctionCallException, 02xx for BadMethodCallException, and so on;
• have template strings for each code; constructions of the form {var_name} are used as substitutions;
• have constructor interface: __construct(int $code = 0, array $context = null, Throwable $previous = null)

Sample

use Jzucen\LongNumber\Number as LN;
use Jzucen\LongNumber\Exception as LNE;

$one = new LN(12);
$two = new LN('13.50');

echo $one->getAddition($two); // 26 will be displayed,
// because 12+13.5=25.5 and will be rounded to 0 precision as the final precision is not specified,
// that is, the precision of the first number will be taken.

function divisionByZero(): void
{
    echo (new LN(rand()))->getDivision(new LN(0));
}

function outputException(Throwable $error): void
{
    $class = get_class($error);
    echo "{$class}: {$error->getMessage()}\n{$error->getTraceAsString()}\n";
}

try {
	divisionByZero();
} catch (LNE\ExceptionInterface $exception) { // all package exceptions
    outputException($exception);
}

try {
	divisionByZero();
} catch (LNE\DomainException $exception) { // all package DomainException-s
    outputException($exception);
}

try {
	divisionByZero();
} catch (DomainException $exception) { // all PHP and package DomainException-s
    outputException($exception);
}