BigInt

Implements integer numbers of arbitrary length

Version: $Date: 2009/08/02 08:09:39 $

Copyright: 2007 by icosaedro.it di Umberto Salsi

License: www.icosaedro.it/license/bsd-style.html BSD-style.

PHP version: 5

Required modules: standard, spl, simplexml, dom, pcre

Required packages: none

Author: Umberto Salsi <salsi@icosaedro.it>

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 extension 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.

Source code and updates: http://www.icosaedro.it/bignumbers/ 



class BigInt

{

UPDATES = "http://www.icosaedro.it/cvs.html"

VERSION = "$Date: 2009/08/02 08:09:39 $"
static boolean $optimize = TRUE

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.
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.
void __construct(
        mixed $x)

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:
string __toString()

Returns the number represented as string

Return: The string that represents the BigInt: a possible "-" sign is followed by one or more digits.
string format(
        int $decimals = 0,
        string $dec_point = ".",
        string $thousands_sep = ",")

Formats the big number

$decimals is the number of trailing digits to be considered as decimal part. $thousands_sep is the symbol to insert every three digits of the integer part. Examples: 

  $n = new BigInt("1234567890");
  echo $n->format();  # 1,234,567,890
  echo $n->format(2);  # 12,345,678.90

Parameters:
$decimals   Number of rightmost digits to be considered as fractional part.
$dec_point   Separator string between integral part and fractional part.
$thousands_sep   Separator string between thousands.

Return: The BigInt formatted.
int sign()

Returns the sign of the number

Return: +1 if the number is positive, -1 if negative, 0 if zero.
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 2.
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.
BigInt abs()

Returns the number without the sign

Return: The number without the sign.
BigInt minus()

Returns the number with the sign reversed

Return: The number with the sign reversed.
BigInt add(
        BigInt $b)

Addition

Parameters:
$b   The second term to add.

Return: The sum $this+$b.
BigInt sub(
        BigInt $b)

Subtraction

Parameters:
$b   The term to subtract.

Return: The difference $this-$b.
BigInt mul(
        BigInt $b)

Multiplication

Parameters:
$b   The second factor.

Return: The product $this*$b.
BigInt div_rem(
        BigInt $b,
        return BigInt & $rem)

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:
BigInt div(
        BigInt $b)

Calculate the quotient of the division

Parameters:
$b   The divisor.

Return: The quotient.

Throws:
BigInt rem(
        BigInt $b)

Calculate the remainder of the division

Parameters:
$b   The divisor.

Return: The remainder.

Throws:
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.
BigInt shift(
        int $p)

Scale to a given power of ten

Parameters:
$p   The exponent of 10.

Return: $this * 10^$p.
int toInt()

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:
float toFloat()

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:
}

Generated by PHPLint Documentator