You are viewing the version of this documentation from Perl 5.41.4. This is a development version of Perl.

CONTENTS

NAME

Math::BigInt - arbitrary size integer math package

SYNOPSIS

use Math::BigInt;

# or make it faster with huge numbers: install (optional)
# Math::BigInt::GMP and always use (it falls back to
# pure Perl if the GMP library is not installed):
# (See also the L<MATH LIBRARY> section!)

# to warn if Math::BigInt::GMP cannot be found, use
use Math::BigInt lib => 'GMP';

# to suppress the warning if Math::BigInt::GMP cannot be found, use
# use Math::BigInt try => 'GMP';

# to die if Math::BigInt::GMP cannot be found, use
# use Math::BigInt only => 'GMP';

# Configuration methods (may be used as class methods and instance methods)

Math::BigInt->accuracy();     # get class accuracy
Math::BigInt->accuracy($n);   # set class accuracy
Math::BigInt->precision();    # get class precision
Math::BigInt->precision($n);  # set class precision
Math::BigInt->round_mode();   # get class rounding mode
Math::BigInt->round_mode($m); # set global round mode, must be one of
                              # 'even', 'odd', '+inf', '-inf', 'zero',
                              # 'trunc', or 'common'
Math::BigInt->div_scale($n);  # set fallback accuracy
Math::BigInt->trap_inf($b);   # trap infinities or not
Math::BigInt->trap_nan($b);   # trap NaNs or not
Math::BigInt->config();       # return hash with configuration

# Constructor methods (when the class methods below are used as instance
# methods, the value is assigned the invocand)

$x = Math::BigInt->new($str);             # defaults to 0
$x = Math::BigInt->new('0x123');          # from hexadecimal
$x = Math::BigInt->new('0b101');          # from binary
$x = Math::BigInt->from_hex('cafe');      # from hexadecimal
$x = Math::BigInt->from_oct('377');       # from octal
$x = Math::BigInt->from_bin('1101');      # from binary
$x = Math::BigInt->from_base('why', 36);  # from any base
$x = Math::BigInt->from_base_num([1, 0], 2);  # from any base
$x = Math::BigInt->bzero();               # create a +0
$x = Math::BigInt->bone();                # create a +1
$x = Math::BigInt->bone('-');             # create a -1
$x = Math::BigInt->binf();                # create a +inf
$x = Math::BigInt->binf('-');             # create a -inf
$x = Math::BigInt->bnan();                # create a Not-A-Number
$x = Math::BigInt->bpi();                 # returns pi

$y = $x->copy();        # make a copy (unlike $y = $x)
$y = $x->as_int();      # return as a Math::BigInt
$y = $x->as_float();    # return as a Math::BigFloat
$y = $x->as_rat();      # return as a Math::BigRat

# Boolean methods (these don't modify the invocand)

$x->is_zero();          # if $x is 0
$x->is_one();           # if $x is +1
$x->is_one("+");        # ditto
$x->is_one("-");        # if $x is -1
$x->is_inf();           # if $x is +inf or -inf
$x->is_inf("+");        # if $x is +inf
$x->is_inf("-");        # if $x is -inf
$x->is_nan();           # if $x is NaN

$x->is_positive();      # if $x > 0
$x->is_pos();           # ditto
$x->is_negative();      # if $x < 0
$x->is_neg();           # ditto

$x->is_odd();           # if $x is odd
$x->is_even();          # if $x is even
$x->is_int();           # if $x is an integer

# Comparison methods

$x->bcmp($y);           # compare numbers (undef, < 0, == 0, > 0)
$x->bacmp($y);          # compare absolutely (undef, < 0, == 0, > 0)
$x->beq($y);            # true if and only if $x == $y
$x->bne($y);            # true if and only if $x != $y
$x->blt($y);            # true if and only if $x < $y
$x->ble($y);            # true if and only if $x <= $y
$x->bgt($y);            # true if and only if $x > $y
$x->bge($y);            # true if and only if $x >= $y

# Arithmetic methods

$x->bneg();             # negation
$x->babs();             # absolute value
$x->bsgn();             # sign function (-1, 0, 1, or NaN)
$x->bnorm();            # normalize (no-op)
$x->binc();             # increment $x by 1
$x->bdec();             # decrement $x by 1
$x->badd($y);           # addition (add $y to $x)
$x->bsub($y);           # subtraction (subtract $y from $x)
$x->bmul($y);           # multiplication (multiply $x by $y)
$x->bmuladd($y,$z);     # $x = $x * $y + $z
$x->bdiv($y);           # division (floored), set $x to quotient
                        # return (quo,rem) or quo if scalar
$x->btdiv($y);          # division (truncated), set $x to quotient
                        # return (quo,rem) or quo if scalar
$x->bmod($y);           # modulus (x % y)
$x->btmod($y);          # modulus (truncated)
$x->bmodinv($mod);      # modular multiplicative inverse
$x->bmodpow($y,$mod);   # modular exponentiation (($x ** $y) % $mod)
$x->binv()              # inverse (1/$x)
$x->bpow($y);           # power of arguments (x ** y)
$x->blog();             # logarithm of $x to base e (Euler's number)
$x->blog($base);        # logarithm of $x to base $base (e.g., base 2)
$x->bexp();             # calculate e ** $x where e is Euler's number
$x->bilog2();           # log2($x) rounded down to nearest int
$x->bilog10();          # log10($x) rounded down to nearest int
$x->bclog2();           # log2($x) rounded up to nearest int
$x->bclog10();          # log19($x) rounded up to nearest int
$x->bnok($y);           # x over y (binomial coefficient n over k)
$x->buparrow($n, $y);   # Knuth's up-arrow notation
$x->backermann($y);     # the Ackermann function
$x->bsin();             # sine
$x->bcos();             # cosine
$x->batan();            # inverse tangent
$x->batan2($y);         # two-argument inverse tangent
$x->bsqrt();            # calculate square root
$x->broot($y);          # $y'th root of $x (e.g. $y == 3 => cubic root)
$x->bfac();             # factorial of $x (1*2*3*4*..$x)
$x->bdfac();            # double factorial of $x ($x*($x-2)*($x-4)*...)
$x->btfac();            # triple factorial of $x ($x*($x-3)*($x-6)*...)
$x->bmfac($k);          # $k'th multi-factorial of $x ($x*($x-$k)*...)

$x->blsft($n);          # left shift $n places in base 2
$x->blsft($n,$b);       # left shift $n places in base $b
                        # returns (quo,rem) or quo (scalar context)
$x->brsft($n);          # right shift $n places in base 2
$x->brsft($n,$b);       # right shift $n places in base $b
                        # returns (quo,rem) or quo (scalar context)

# Bitwise methods

$x->bblsft($y);         # bitwise left shift
$x->bbrsft($y);         # bitwise right shift
$x->band($y);           # bitwise and
$x->bior($y);           # bitwise inclusive or
$x->bxor($y);           # bitwise exclusive or
$x->bnot();             # bitwise not (two's complement)

# Rounding methods
$x->round($A,$P,$mode); # round to accuracy or precision using
                        # rounding mode $mode
$x->bround($n);         # accuracy: preserve $n digits
$x->bfround($n);        # $n > 0: round to $nth digit left of dec. point
                        # $n < 0: round to $nth digit right of dec. point
$x->bfloor();           # round towards minus infinity
$x->bceil();            # round towards plus infinity
$x->bint();             # round towards zero

# Other mathematical methods

$x->bgcd($y);            # greatest common divisor
$x->blcm($y);            # least common multiple

# Object property methods (do not modify the invocand)

$x->sign();              # the sign, either +, - or NaN
$x->digit($n);           # the nth digit, counting from the right
$x->digit(-$n);          # the nth digit, counting from the left
$x->length();            # return number of digits in number
($xl,$f) = $x->length(); # length of number and length of fraction
                         # part, latter is always 0 digits long
                         # for Math::BigInt objects
$x->mantissa();          # return (signed) mantissa as a Math::BigInt
$x->exponent();          # return exponent as a Math::BigInt
$x->parts();             # return (mantissa,exponent) as a Math::BigInt
$x->sparts();            # mantissa and exponent (as integers)
$x->nparts();            # mantissa and exponent (normalised)
$x->eparts();            # mantissa and exponent (engineering notation)
$x->dparts();            # integer and fraction part
$x->fparts();            # numerator and denominator
$x->numerator();         # numerator
$x->denominator();       # denominator

# Conversion methods (do not modify the invocand)

$x->bstr();         # decimal notation, possibly zero padded
$x->bsstr();        # string in scientific notation with integers
$x->bnstr();        # string in normalized notation
$x->bestr();        # string in engineering notation
$x->bfstr();        # string in fractional notation

$x->to_hex();       # as signed hexadecimal string
$x->to_bin();       # as signed binary string
$x->to_oct();       # as signed octal string
$x->to_bytes();     # as byte string
$x->to_base($b);    # as string in any base
$x->to_base_num($b);   # as array of integers in any base

$x->as_hex();       # as signed hexadecimal string with prefixed 0x
$x->as_bin();       # as signed binary string with prefixed 0b
$x->as_oct();       # as signed octal string with prefixed 0

# Other conversion methods

$x->numify();           # return as scalar (might overflow or underflow)

DESCRIPTION

Math::BigInt provides support for arbitrary precision integers. Overloading is also provided for Perl operators.

Input

Input values to these routines may be any scalar number or string that looks like a number and represents an integer. Anything that is accepted by Perl as a literal numeric constant should be accepted by this module, except that finite non-integers return NaN.

Some examples of valid string input

Input string                Resulting value

123                         123
1.23e2                      123
12300e-2                    123

67_538_754                  67538754
-4_5_6.7_8_9e+0_1_0         -4567890000000

0x13a                       314
0x13ap0                     314
0x1.3ap+8                   314
0x0.00013ap+24              314
0x13a000p-12                314

0o472                       314
0o1.164p+8                  314
0o0.0001164p+20             314
0o1164000p-10               314

0472                        472     Note!
01.164p+8                   314
00.0001164p+20              314
01164000p-10                314

0b100111010                 314
0b1.0011101p+8              314
0b0.00010011101p+12         314
0b100111010000p-3           314

Input given as scalar numbers might lose precision. Quote your input to ensure that no digits are lost:

$x = Math::BigInt->new( 56789012345678901234 );   # bad
$x = Math::BigInt->new('56789012345678901234');   # good

Currently, Math::BigInt-new()> (no input argument) and Math::BigInt-new("")> return 0. This might change in the future, so always use the following explicit forms to get a zero:

$zero = Math::BigInt->bzero();

Output

Output values are usually Math::BigInt objects.

Boolean operators is_zero(), is_one(), is_inf(), etc. return true or false.

Comparison operators bcmp() and bacmp()) return -1, 0, 1, or undef.

METHODS

Configuration methods

Each of the methods below (except config(), accuracy() and precision()) accepts three additional parameters. These arguments $A, $P and $R are accuracy, precision and round_mode. Please see the section about "ACCURACY and PRECISION" for more information.

Setting a class variable effects all object instance that are created afterwards.

accuracy()
Math::BigInt->accuracy(5);      # set class accuracy
$x->accuracy(5);                # set instance accuracy

$A = Math::BigInt->accuracy();  # get class accuracy
$A = $x->accuracy();            # get instance accuracy

Set or get the accuracy, i.e., the number of significant digits. The accuracy must be an integer. If the accuracy is set to undef, no rounding is done.

Alternatively, one can round the results explicitly using one of "round()", "bround()" or "bfround()" or by passing the desired accuracy to the method as an additional parameter:

my $x = Math::BigInt->new(30000);
my $y = Math::BigInt->new(7);
print scalar $x->copy()->bdiv($y, 2);               # prints 4300
print scalar $x->copy()->bdiv($y)->bround(2);       # prints 4300

Please see the section about "ACCURACY and PRECISION" for further details.

$y = Math::BigInt->new(1234567);    # $y is not rounded
Math::BigInt->accuracy(4);          # set class accuracy to 4
$x = Math::BigInt->new(1234567);    # $x is rounded automatically
print "$x $y";                      # prints "1235000 1234567"

print $x->accuracy();       # prints "4"
print $y->accuracy();       # also prints "4", since
                            #   class accuracy is 4

Math::BigInt->accuracy(5);  # set class accuracy to 5
print $x->accuracy();       # prints "4", since instance
                            #   accuracy is 4
print $y->accuracy();       # prints "5", since no instance
                            #   accuracy, and class accuracy is 5

Note: Each class has it's own globals separated from Math::BigInt, but it is possible to subclass Math::BigInt and make the globals of the subclass aliases to the ones from Math::BigInt.

precision()
Math::BigInt->precision(-2);     # set class precision
$x->precision(-2);               # set instance precision

$P = Math::BigInt->precision();  # get class precision
$P = $x->precision();            # get instance precision

Set or get the precision, i.e., the place to round relative to the decimal point. The precision must be a integer. Setting the precision to $P means that each number is rounded up or down, depending on the rounding mode, to the nearest multiple of 10**$P. If the precision is set to undef, no rounding is done.

You might want to use "accuracy()" instead. With "accuracy()" you set the number of digits each result should have, with "precision()" you set the place where to round.

Please see the section about "ACCURACY and PRECISION" for further details.

$y = Math::BigInt->new(1234567);    # $y is not rounded
Math::BigInt->precision(4);         # set class precision to 4
$x = Math::BigInt->new(1234567);    # $x is rounded automatically
print $x;                           # prints "1230000"

Note: Each class has its own globals separated from Math::BigInt, but it is possible to subclass Math::BigInt and make the globals of the subclass aliases to the ones from Math::BigInt.

div_scale()

Set/get the fallback accuracy. This is the accuracy used when neither accuracy nor precision is set explicitly. It is used when a computation might otherwise attempt to return an infinite number of digits.

round_mode()

Set/get the rounding mode.

trap_inf()

Set/get the value determining whether infinities should cause a fatal error or not.

trap_nan()

Set/get the value determining whether NaNs should cause a fatal error or not.

upgrade()

Set/get the class for upgrading. When a computation might result in a non-integer, the operands are upgraded to this class. This is used for instance by bignum. The default is undef, i.e., no upgrading.

# with no upgrading
$x = Math::BigInt->new(12);
$y = Math::BigInt->new(5);
print $x / $y, "\n";                # 2 as a Math::BigInt

# with upgrading to Math::BigFloat
Math::BigInt -> upgrade("Math::BigFloat");
print $x / $y, "\n";                # 2.4 as a Math::BigFloat

# with upgrading to Math::BigRat (after loading Math::BigRat)
Math::BigInt -> upgrade("Math::BigRat");
print $x / $y, "\n";                # 12/5 as a Math::BigRat
downgrade()

Set/get the class for downgrading. The default is undef, i.e., no downgrading. Downgrading is not done by Math::BigInt.

modify()
$x->modify('bpowd');

This method returns 0 if the object can be modified with the given operation, or 1 if not.

This is used for instance by Math::BigInt::Constant.

config()
Math::BigInt->config("trap_nan" => 1);      # set
$accu = Math::BigInt->config("accuracy");   # get

Set or get class variables. Read-only parameters are marked as RO. Read-write parameters are marked as RW. The following parameters are supported.

Parameter       RO/RW   Description
                        Example
============================================================
lib             RO      Name of the math backend library
                        Math::BigInt::Calc
lib_version     RO      Version of the math backend library
                        0.30
class           RO      The class of config you just called
                        Math::BigRat
version         RO      version number of the class you used
                        0.10
upgrade         RW      To which class numbers are upgraded
                        undef
downgrade       RW      To which class numbers are downgraded
                        undef
precision       RW      Global precision
                        undef
accuracy        RW      Global accuracy
                        undef
round_mode      RW      Global round mode
                        even
div_scale       RW      Fallback accuracy for division etc.
                        40
trap_nan        RW      Trap NaNs
                        undef
trap_inf        RW      Trap +inf/-inf
                        undef

Constructor methods

new()
$x = Math::BigInt->new($str,$A,$P,$R);

Creates a new Math::BigInt object from a scalar or another Math::BigInt object. The input is accepted as decimal, hexadecimal (with leading '0x'), octal (with leading ('0o') or binary (with leading '0b').

See "Input" for more info on accepted input formats.

from_dec()
$x = Math::BigInt->from_dec("314159");    # input is decimal

Interpret input as a decimal. It is equivalent to new(), but does not accept anything but strings representing finite, decimal numbers.

from_hex()
$x = Math::BigInt->from_hex("0xcafe");    # input is hexadecimal

Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A single underscore character may be placed right after the prefix, if present, or between any two digits. If the input is invalid, a NaN is returned.

from_oct()
$x = Math::BigInt->from_oct("0775");      # input is octal

Interpret the input as an octal string and return the corresponding value. A "0" (zero) prefix is optional. A single underscore character may be placed right after the prefix, if present, or between any two digits. If the input is invalid, a NaN is returned.

from_bin()
$x = Math::BigInt->from_bin("0b10011");   # input is binary

Interpret the input as a binary string. A "0b" or "b" prefix is optional. A single underscore character may be placed right after the prefix, if present, or between any two digits. If the input is invalid, a NaN is returned.

from_bytes()
$x = Math::BigInt->from_bytes("\xf3\x6b");  # $x = 62315

Interpret the input as a byte string, assuming big endian byte order. The output is always a non-negative, finite integer.

In some special cases, from_bytes() matches the conversion done by unpack():

$b = "\x4e";                             # one char byte string
$x = Math::BigInt->from_bytes($b);       # = 78
$y = unpack "C", $b;                     # ditto, but scalar

$b = "\xf3\x6b";                         # two char byte string
$x = Math::BigInt->from_bytes($b);       # = 62315
$y = unpack "S>", $b;                    # ditto, but scalar

$b = "\x2d\xe0\x49\xad";                 # four char byte string
$x = Math::BigInt->from_bytes($b);       # = 769673645
$y = unpack "L>", $b;                    # ditto, but scalar

$b = "\x2d\xe0\x49\xad\x2d\xe0\x49\xad"; # eight char byte string
$x = Math::BigInt->from_bytes($b);       # = 3305723134637787565
$y = unpack "Q>", $b;                    # ditto, but scalar
from_base()

Given a string, a base, and an optional collation sequence, interpret the string as a number in the given base. The collation sequence describes the value of each character in the string.

If a collation sequence is not given, a default collation sequence is used. If the base is less than or equal to 36, the collation sequence is the string consisting of the 36 characters "0" to "9" and "A" to "Z". In this case, the letter case in the input is ignored. If the base is greater than 36, and smaller than or equal to 62, the collation sequence is the string consisting of the 62 characters "0" to "9", "A" to "Z", and "a" to "z". A base larger than 62 requires the collation sequence to be specified explicitly.

These examples show standard binary, octal, and hexadecimal conversion. All cases return 250.

$x = Math::BigInt->from_base("11111010", 2);
$x = Math::BigInt->from_base("372", 8);
$x = Math::BigInt->from_base("fa", 16);

When the base is less than or equal to 36, and no collation sequence is given, the letter case is ignored, so both of these also return 250:

$x = Math::BigInt->from_base("6Y", 16);
$x = Math::BigInt->from_base("6y", 16);

When the base greater than 36, and no collation sequence is given, the default collation sequence contains both uppercase and lowercase letters, so the letter case in the input is not ignored:

$x = Math::BigInt->from_base("6S", 37);         # $x is 250
$x = Math::BigInt->from_base("6s", 37);         # $x is 276
$x = Math::BigInt->from_base("121", 3);         # $x is 16
$x = Math::BigInt->from_base("XYZ", 36);        # $x is 44027
$x = Math::BigInt->from_base("Why", 42);        # $x is 58314

The collation sequence can be any set of unique characters. These two cases are equivalent

$x = Math::BigInt->from_base("100", 2, "01");   # $x is 4
$x = Math::BigInt->from_base("|--", 2, "-|");   # $x is 4
from_base_num()

Returns a new Math::BigInt object given an array of values and a base. This method is equivalent to from_base(), but works on numbers in an array rather than characters in a string. Unlike from_base(), all input values may be arbitrarily large.

$x = Math::BigInt->from_base_num([1, 1, 0, 1], 2)     # $x is 13
$x = Math::BigInt->from_base_num([3, 125, 39], 128)   # $x is 65191
bzero()
$x = Math::BigInt->bzero();
$x->bzero();

Returns a new Math::BigInt object representing zero. If used as an instance method, assigns the value to the invocand.