BigInt.php
Implements integer numbers of arbitrary length. BigInt are integer numbers with sign and arbitrary length suitable for monetary calculations and other numerical non-intensive tasks. For currencies allowing fractional parts (as USD and EUR) calculations can be done using cents as unit, or even smaller fractions if required for higher precision. With ordinary values that may be involved in typical business applications, BigInt performs several thousands of operations per second on a common PC. Moreover, the source is short, fast to be parsed and included, simple to use and maintain. If you need a faster implementation of big numbers, look for the BCMath or the GMP extensions of PHP. A note about the interface provided by this class. Every object of the class holds a big number, so most of the methods have this value as implicit argument, here represented with the word » $this «. Methods that require two or more big numbers take $this as the first argument. Once created, an object is never changed, i.e. it is immutable. Example:
$n = new BigInt("123456789"); echo $n->pow(3), "\n"; # displays 1881676371789154860897069 $price = new BigInt("123456"); # 1,234.56 EUR $VAT = $price->mul( new BigInt(20) ) # apply VAT 20% ->add( new BigInt(50) ) # rounding ->div( new BigInt(100) ); # rescale $total = $price->add($VAT); echo "You are going to spend ", $total->format(2); # displays 1,481.40 See also: BigFloat is a class that performs calculations with floating point numbers and arbitrary precision.
Author: Umberto Salsi
Copyright: 2007 by icosaedro.it di Umberto Salsi
Version: $Date: 2018/06/06 09:52:53 $
License: http://www.icosaedro.it/license/bsd-style.html www.icosaedro.it/license/bsd-style.html BSD-style.
Class constants
VERSION
Properties
$optimize
public static boolean $optimize
Calculations on small numbers are performed using int. When only small numbers are involved and there is no risk of overflow, calculations are made using int numbers for better performances. It can be set to FALSE for testing purposes of the class, but should be left to TRUE for common usage.
Methods
__construct()
public void __construct(mixed $x) throws InvalidArgumentException
Builds a BigInt. The arguments can be int, float or string, otherwise an exception is thrown. int numbers can always be converted exactly into BigInt numbers. If $x is a string, always use BigInt::isValid() before passing arbitrary strings, i.e. user submitted input. Spaces are not allowed, so use trim(). If $x is a float it gets truncated, so 1.9 evaluates as 1 and -1.9 evaluates as -1. INF and NAN yield exception as they cannot be represented internally. WARNING: avoid to use floating-point numbers as they may give unexpected results. For example on my PC the function printf(«%.0F», 1e23) prints «99999999999999991611392» rather than the expected «1» followed by 23 zeroes because that is the best internal binary representation assigned by the PHP interpreter when the instruction was parsed; in other words it is not an issue of printf() nor an issue of the BigInt class but one of the several limitation of the floating-point numbers.
Parameters:
$x — The value to be converted to BigInt. It may be: int, float, string.
Throws:
InvalidArgumentException — The argument passed is of the wrong type, or it is a non-finite float (NAN, INF or -INF), or the string does not represent a valid number.
__toString()
public string __toString()
Implements Printable::__toString()
Returns the number represented as string.
Return: The string that represents the BigInt: a possible » — » sign is followed by one or more digits.
abs()
public BigInt abs()
Returns the number without the sign.
Return: The number without the sign.
add()
public BigInt add(BigInt $b)
Addition.
Parameters:
$b — The second term to add.
Return: The sum $this+$b.
cmp()
public int cmp(BigInt $b)
Compare $this with $b.
Parameters:
$b — The number to be compared.
Return: Negative if $this is less than $b, positive if $this is greater than $b, zero if they are equal.
compareTo()
public int compareTo(object $other) throws CastException
Implements Sortable::compareTo()
Implements the Comparable interface.
Parameters:
$other — Another BigInt number to compare.
Return: Negative if $this < $other, positive if $this >$other, zero if they are equal.
Throws:
CastException — If the object passed is NULL or is not an exact instance of this class.
div()
public BigInt div(BigInt $b) throws InvalidArgumentException
Calculate the quotient of the division.
Parameters:
$b — The divisor.
Return: The quotient.
Throws:
InvalidArgumentException — if $b is zero.
div_rem()
public BigInt div_rem(BigInt $b, return BigInt & $rem) throws InvalidArgumentException
Calculate quotient and remainder of the division.
Parameters:
$b — The divisor.
$rem — Here returns the resulting remainder.
Return: The quotient, that is a number $q so that $this = $q * $b + $rem, being $rem a number of module minor than $q.
Throws:
InvalidArgumentException — if $b is zero.
equals()
public boolean equals(object $other)
Implements Comparable::equals()
Compares this number with another for equality.
Parameters:
$other — The other BigInt.
Return: True only if the other number is not NULL, is exactly instance of this class (not an extended one) and carries the same value.
format()
public string format(int $decimals = 0, string $dec_sept = «.», string $thousands_sept = «,»)
Formats the big number. Examples:
$n = new BigInt("1234567890"); echo $n->format(); # 1,234,567,890 echo $n->format(2); # 12,345,678.90 $n = new BigInt("1"); echo $n->format(2); # 0.01 Parameters:
$decimals — Number of rightmost digits to be considered as fractional part. Ignored if not positive.
$dec_sept — Separator string between integral part and fractional part. Ignored if the number of decimals is not positive.
$thousands_sept — Separator string between thousands.
Return: The BigInt formatted.
fromBase()
public static BigInt fromBase(string $n, int $b) throws InvalidArgumentException
Parses an integer number in the given base.
Parameters:
$n — Number as a string, consisting in a possible leading sign followed by one or more digits in the given base. «Digits» are the usual ten digits from «0» up to «9» and the letters from «a» up to «z».
$b — Base in the range from 2 up to 36.
Throws:
InvalidArgumentException — Non a valid number in the given base. Base out of the allowed range.
getHash()
isValid()
public static boolean isValid(string $n)
Returns TRUE if the string represents a valid BigInt. Valid BigInt numbers may have a sign +/- followed by one or more decimal digits. Spaces and any other character are not allowed, so you should apply the trim() function to user submitted strings:
$n = trim( $_POST['n'] ); if( BigInt::isValid($n) ) .
Examples of valid numbers: «0» «-1» «+12345»
Parameters:
$n — The string to be evaluated as BigInt.
Return: TRUE if the string represents a valid BigInt.
minus()
public BigInt minus()
Returns the number with the sign reversed.
Return: The number with the sign reversed.
mul()
public BigInt mul(BigInt $b)
Multiplication.
Parameters:
$b — The second factor.
Return: The product $this*$b.
parse()
public static BigInt parse(string $s, int $decimals = 0, string $dec_sept = «.», string $thousands_sept = «,») throws InvalidArgumentException
Parse a string as a BigInt number.
Parameters:
$s — String to parse.
$decimals — Number of rightmost digits to be considered as fractional part. Ignored if not positive.
$dec_sept — Separator string between integral part and fractional part. Ignored if the number of decimals is not positive.
$thousands_sept — Separator string between thousands.
Throws:
InvalidArgumentException — Failed to parse.
pow()
public BigInt pow(int $e)
Returns the base $this raised to the power $e.
Parameters:
$e — The exponent of $this.
Return: $this raised to the power $e. Please note that $e is a simple int number, not a BigInt.
rem()
public BigInt rem(BigInt $b) throws InvalidArgumentException
Calculate the remainder of the division.
Parameters:
$b — The divisor.
Return: The remainder.
Throws:
InvalidArgumentException — if $b is zero.
scale()
public int scale()
Returns the scale factor.
Return: The number of digits minus one. The scale factor of 1 is zero, the scale factor of 10 is 1.
shift()
public BigInt shift(int $p)
Scale to a given power of ten.
Parameters:
$p — The exponent of 10.
Return: $this * 10^$p.
sign()
public int sign()
Returns the sign of the number.
Return: +1 if the number is positive, -1 if negative, 0 if zero.
sub()
public BigInt sub(BigInt $b)
Subtraction.
Parameters:
$b — The term to subtract.
Return: The difference $this-$b.
toBase()
public string toBase(int $b)
Returns this number represented in the given base.
Parameters:
$b — Base in the range [2,36].
Return: Possible minus sign followed by digits of the base. «Digits» are the usual ten digits from «0» up to «9» and the letters from «a» up to «z».
toFloat()
public float toFloat() throws OutOfRangeException
Return the BigInt as float without loss of precision. A floating point number can store exactly an integer number larger than int. On most platforms, int is a 32-bit, 2-complement value, whereas float is a 53-bit, signed value in the IEEE 754, double precision, representation, that can store an integer number of modulus up to 2^53-1 = 9007199254740991. This function determinates dynamically the size of the mantissa of the underlying platform, so that an exception is thrown if the BigInt is too big and cannot be represented with a float without loss of precision.
Return: The float that represents $this.
Throws:
OutOfRangeException — if $this is too big to fit float without loss of precision.
toInt()
public int toInt() throws OutOfRangeException
Return the BigInt as int. PHP provides the constant PHP_INT_MAX that contains the maximum positive int number, typically 2^32-1 = 2147483647. Since the 2-complement representation is used, the minimum negative number then is -PHP_INT_MAX-1. This function returns the equivalent int number, or throws an exception if the BigInt number is too big to be represented as int.
Return: The int that represents $this.
Throws:
OutOfRangeException — if $this is too big to fit int.
Private properties: $hash , $m , $sgn
Private methods: add2() , cmp_m() , normalize() , sub2()
Requirements
Required modules: core , file , pcre , phpinfo , spl