You are viewing the version of this documentation from Perl 5.32.1. View the latest version

CONTENTS

NAME

Math::BigInt - Arbitrary size integer/float 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!)

# warns if Math::BigInt::GMP cannot be found
use Math::BigInt lib => 'GMP';

# to suppress the warning use this:
# use Math::BigInt try => 'GMP';

# dies if GMP cannot be loaded:
# use Math::BigInt only => 'GMP';

my $str = '1234567890';
my @values = (64, 74, 18);
my $n = 1; my $sign = '-';

# 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->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->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

# 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->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->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->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->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

# 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->bdstr();        # string in decimal 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->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.

Octal numbers are typically prefixed by "0", but since leading zeros are stripped, these methods can not automatically recognize octal numbers, so use the constructor from_oct() to interpret octal strings.

Some examples of valid string input

Input string                Resulting value
123                         123
1.23e2                      123
12300e-2                    123
0xcafe                      51966
0b1101                      13
67_538_754                  67538754
-4_5_6.7_8_9e+0_1_0         -4567890000000

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() defaults to 0, while Math::BigInt->new('') results in 'NaN'. This might change in the future, so use always the following explicit forms to get a zero or NaN:

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

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.

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, thus the following operation creates a Math::BigInt, not a Math::BigFloat:

my $i = Math::BigInt->new(123);
my $f = Math::BigFloat->new('123.1');

print $i + $f, "\n";                # prints 246
downgrade()

Set/get the class for downgrading. The default is undef. 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') or binary (with leading '0b').

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

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

bone()
$x = Math::BigInt->bone();          # +1
$x = Math::BigInt->bone("+");       # +1
$x = Math::BigInt->bone("-");       # -1
$x->bone();                         # +1
$x->bone("+");                      # +1
$x->bone('-');                      # -1

Creates a new Math::BigInt object representing one. The optional argument is either '-' or '+', indicating whether you want plus one or minus one. If used as an instance method, assigns the value to the invocand.

binf()
$x = Math::BigInt->binf($sign);

Creates a new Math::BigInt object representing infinity. The optional argument is either '-' or '+', indicating whether you want infinity or minus infinity. If used as an instance method, assigns the value to the invocand.

$x->binf();
$x->binf('-');
bnan()
$x = Math::BigInt->bnan();

Creates a new Math::BigInt object representing NaN (Not A Number). If used as an instance method, assigns the value to the invocand.

$x->bnan();
bpi()
$x = Math::BigInt->bpi(100);        # 3
$x->bpi(100);                       # 3

Creates a new Math::BigInt object representing PI. If used as an instance method, assigns the value to the invocand. With Math::BigInt this always returns 3.

If upgrading is in effect, returns PI, rounded to N digits with the current rounding mode:

use Math::BigFloat;
use Math::BigInt upgrade => "Math::BigFloat";
print Math::BigInt->bpi(3), "\n";           # 3.14
print Math::BigInt->bpi(100), "\n";         # 3.1415....
copy()
$x->copy();         # make a true copy of $x (unlike $y = $x)
as_int()
as_number()

These methods are called when Math::BigInt encounters an object it doesn't know how to handle. For instance, assume $x is a Math::BigInt, or subclass thereof, and $y is defined, but not a Math::BigInt, or subclass thereof. If you do

$x -> badd($y);

$y needs to be converted into an object that $x can deal with. This is done by first checking if $y is something that $x might be upgraded to. If that is the case, no further attempts are made. The next is to see if $y supports the method as_int(). If it does, as_int() is called, but if it doesn't, the next thing is to see if $y supports the method as_number(). If it does, as_number() is called. The method as_int() (and as_number()) is expected to return either an object that has the same class as $x, a subclass thereof, or a string that ref($x)->new() can parse to create an object.

as_number() is an alias to as_int(). as_number was introduced in v1.22, while as_int() was introduced in v1.68.

In Math::BigInt, as_int() has the same effect as copy().

Boolean methods

None of these methods modify the invocand object.

is_zero()
$x->is_zero();              # true if $x is 0

Returns true if the invocand is zero and false otherwise.

is_one( [ SIGN ])
$x->is_one();               # true if $x is +1
$x->is_one("+");            # ditto
$x->is_one("-");            # true if $x is -1

Returns true if the invocand is one and false otherwise.

is_finite()
$x->is_finite();    # true if $x is not +inf, -inf or NaN

Returns true if the invocand is a finite number, i.e., it is neither +inf, -inf, nor NaN.

is_inf( [ SIGN ] )
$x->is_inf();               # true if $x is +inf
$x->is_inf("+");            # ditto
$x->is_inf("-");            # true if $x is -inf

Returns true if the invocand is infinite and false otherwise.

is_nan()
$x->is_nan();               # true if $x is NaN
is_positive()
is_pos()
$x->is_positive();          # true if > 0
$x->is_pos();               # ditto

Returns true if the invocand is positive and false otherwise. A NaN is neither positive nor negative.

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

Returns true if the invocand is negative and false otherwise. A NaN is neither positive nor negative.

is_non_positive()
$x->is_non_positive();      # true if <= 0

Returns true if the invocand is negative or zero.

is_non_negative()
$x->is_non_negative();      # true if >= 0

Returns true if the invocand is positive or zero.

is_odd()
$x->is_odd();               # true if odd, false for even

Returns true if the invocand is odd and false otherwise. NaN, +inf, and -inf are neither odd nor even.

is_even()
$x->is_even();              # true if $x is even

Returns true if the invocand is even and false otherwise. NaN, +inf, -inf are not integers and are neither odd nor even.

is_int()
$x->is_int();               # true if $x is an integer

Returns true if the invocand is an integer and false otherwise. NaN, +inf, -inf are not integers.

Comparison methods

None of these methods modify the invocand object. Note that a NaN is neither less than, greater than, or equal to anything else, even a NaN.

bcmp()
$x->bcmp($y);

Returns -1, 0, 1 depending on whether $x is less than, equal to, or grater than $y. Returns undef if any operand is a NaN.

bacmp()
$x->bacmp($y);

Returns -1, 0, 1 depending on whether the absolute value of $x is less than, equal to, or grater than the absolute value of $y. Returns undef if any operand is a NaN.

beq()
$x -> beq($y);

Returns true if and only if $x is equal to $y, and false otherwise.

bne()
$x -> bne($y);

Returns true if and only if $x is not equal to $y, and false otherwise.

blt()
$x -> blt($y);

Returns true if and only if $x is equal to $y, and false otherwise.

ble()
$x -> ble($y);

Returns true if and only if $x is less than or equal to $y, and false otherwise.

bgt()
$x -> bgt($y);

Returns true if and only if $x is greater than $y, and false otherwise.

bge()
$x -> bge($y);

Returns true if and only if $x is greater than or equal to $y, and false otherwise.

Arithmetic methods

These methods modify the invocand object and returns it.

bneg()
$x->bneg();

Negate the number, e.g. change the sign between '+' and '-', or between '+inf' and '-inf', respectively. Does nothing for NaN or zero.

babs()
$x->babs();

Set the number to its absolute value, e.g. change the sign from '-' to '+' and from '-inf' to '+inf', respectively. Does nothing for NaN or positive numbers.

bsgn()
$x->bsgn();

Signum function. Set the number to -1, 0, or 1, depending on whether the number is negative, zero, or positive, respectively. Does not modify NaNs.

bnorm()
$x->bnorm();                        # normalize (no-op)

Normalize the number. This is a no-op and is provided only for backwards compatibility.

binc()
$x->binc();                 # increment x by 1
bdec()
$x->bdec();                 # decrement x by 1
badd()
$x->badd($y);               # addition (add $y to $x)
bsub()
$x->bsub($y);               # subtraction (subtract $y from $x)
bmul()
$x->bmul($y);               # multiplication (multiply $x by $y)
bmuladd()
$x->bmuladd($y,$z);

Multiply $x by $y, and then add $z to the result,

This method was added in v1.87 of Math::BigInt (June 2007).

bdiv()
$x->bdiv($y);               # divide, set $x to quotient

Divides $x by $y by doing floored division (F-division), where the quotient is the floored (rounded towards negative infinity) quotient of the two operands. In list context, returns the quotient and the remainder. The remainder is either zero or has the same sign as the second operand. In scalar context, only the quotient is returned.

The quotient is always the greatest integer less than or equal to the real-valued quotient of the two operands, and the remainder (when it is non-zero) always has the same sign as the second operand; so, for example,

  1 /  4  => ( 0,  1)
  1 / -4  => (-1, -3)
 -3 /  4  => (-1,  1)
 -3 / -4  => ( 0, -3)
-11 /  2  => (-5,  1)
 11 / -2  => (-5, -1)

The behavior of the overloaded operator % agrees with the behavior of Perl's built-in % operator (as documented in the perlop manpage), and the equation

$x == ($x / $y) * $y + ($x % $y)

holds true for any finite $x and finite, non-zero $y.

Perl's "use integer" might change the behaviour of % and / for scalars. This is because under 'use integer' Perl does what the underlying C library thinks is right, and this varies. However, "use integer" does not change the way things are done with Math::BigInt objects.

btdiv()
$x->btdiv($y);              # divide, set $x to quotient

Divides $x by $y by doing truncated division (T-division), where quotient is the truncated (rouneded towards zero) quotient of the two operands. In list context, returns the quotient and the remainder. The remainder is either zero or has the same sign as the first operand. In scalar context, only the quotient is returned.

bmod()
$x->bmod($y);               # modulus (x % y)

Returns $x modulo $y, i.e., the remainder after floored division (F-division). This method is like Perl's % operator. See "bdiv()".

btmod()
$x->btmod($y);              # modulus

Returns the remainer after truncated division (T-division). See "btdiv()".

bmodinv()
$x->bmodinv($mod);          # modular multiplicative inverse

Returns the multiplicative inverse of $x modulo $mod. If

$y = $x -> copy() -> bmodinv($mod)

then $y is the number closest to zero, and with the same sign as $mod, satisfying

($x * $y) % $mod = 1 % $mod

If $x and $y are non-zero, they must be relative primes, i.e., bgcd($y, $mod)==1. 'NaN' is returned when no modular multiplicative inverse exists.

bmodpow()
$num->bmodpow($exp,$mod);           # modular exponentiation
                                    # ($num**$exp % $mod)

Returns the value of $num taken to the power $exp in the modulus $mod using binary exponentiation. bmodpow is far superior to writing

$num ** $exp % $mod

because it is much faster - it reduces internal variables into the modulus whenever possible, so it operates on smaller numbers.

bmodpow also supports negative exponents.

bmodpow($num, -1, $mod)

is exactly equivalent to

bmodinv($num, $mod)
bpow()
$x->bpow($y);               # power of arguments (x ** y)

bpow() (and the rounding functions) now modifies the first argument and returns it, unlike the old code which left it alone and only returned the result. This is to be consistent with badd() etc. The first three modifies $x, the last one won't:

print bpow($x,$i),"\n";         # modify $x
print $x->bpow($i),"\n";        # ditto
print $x **= $i,"\n";           # the same
print $x ** $i,"\n";            # leave $x alone

The form $x **= $y is faster than $x = $x ** $y;, though.

blog()
$x->blog($base, $accuracy);         # logarithm of x to the base $base

If $base is not defined, Euler's number (e) is used:

print $x->blog(undef, 100);         # log(x) to 100 digits
bexp()
$x->bexp($accuracy);                # calculate e ** X

Calculates the expression e ** $x where e is Euler's number.

This method was added in v1.82 of Math::BigInt (April 2007).

See also "blog()".

bnok()
$x->bnok($y);               # x over y (binomial coefficient n over k)

Calculates the binomial coefficient n over k, also called the "choose" function, which is

( n )       n!
|   |  = --------
( k )    k!(n-k)!

when n and k are non-negative. This method implements the full Kronenburg extension (Kronenburg, M.J. "The Binomial Coefficient for Negative Arguments." 18 May 2011. http://arxiv.org/abs/1105.3689/) illustrated by the following pseudo-code:

if n >= 0 and k >= 0:
    return binomial(n, k)
if k >= 0:
    return (-1)^k*binomial(-n+k-1, k)
if k <= n:
    return (-1)^(n-k)*binomial(-k-1, n-k)
else
    return 0

The behaviour is identical to the behaviour of the Maple and Mathematica function for negative integers n, k.

buparrow()
uparrow()
$a -> buparrow($n, $b);         # modifies $a
$x = $a -> uparrow($n, $b);     # does not modify $a

This method implements Knuth's up-arrow notation, where $n is a non-negative integer representing the number of up-arrows. $n = 0 gives multiplication, $n = 1 gives exponentiation, $n = 2 gives tetration, $n = 3 gives hexation etc. The following illustrates the relation between the first values of $n.

See https://en.wikipedia.org/wiki/Knuth%27s_up-arrow_notation.

backermann()
ackermann()
$m -> backermann($n);           # modifies $a
$x = $m -> ackermann($n);       # does not modify $a

This method implements the Ackermann function:

          / n + 1              if m = 0
A(m, n) = | A(m-1, 1)          if m > 0 and n = 0
          \ A(m-1, A(m, n-1))  if m > 0 and n > 0

Its value grows rapidly, even for small inputs. For example, A(4, 2) is an integer of 19729 decimal digits.

See https://en.wikipedia.org/wiki/Ackermann_function

bsin()
my $x = Math::BigInt->new(1);
print $x->bsin(100), "\n";

Calculate the sine of $x, modifying $x in place.

In Math::BigInt, unless upgrading is in effect, the result is truncated to an integer.

This method was added in v1.87 of Math::BigInt (June 2007).

bcos()
my $x = Math::BigInt->new(1);
print $x->bcos(100), "\n";

Calculate the cosine of $x, modifying $x in place.

In Math::BigInt, unless upgrading is in effect, the result is truncated to an integer.

This method was added in v1.87 of Math::BigInt (June 2007).

batan()
my $x = Math::BigFloat->new(0.5);
print $x->batan(100), "\n";

Calculate the arcus tangens of $x, modifying $x in place.

In Math::BigInt, unless upgrading is in effect, the result is truncated to an integer.

This method was added in v1.87 of Math::BigInt (June 2007).

batan2()
my $x = Math::BigInt->new(1);
my $y = Math::BigInt->new(1);
print $y->batan2($x), "\n";

Calculate the arcus tangens of $y divided by $x, modifying $y in place.

In Math::BigInt, unless upgrading is in effect, the result is truncated to an integer.

This method was added in v1.87 of Math::BigInt (June 2007).

bsqrt()
$x->bsqrt();                # calculate square root

bsqrt() returns the square root truncated to an integer.

If you want a better approximation of the square root, then use:

$x = Math::BigFloat->new(12);
Math::BigFloat->precision(0);
Math::BigFloat->round_mode('even');
print $x->copy->bsqrt(),"\n";           # 4

Math::BigFloat->precision(2);
print $x->bsqrt(),"\n";                 # 3.46
print $x->bsqrt(3),"\n";                # 3.464
broot()
$x->broot($N);

Calculates the N'th root of $x.

bfac()
$x->bfac();                 # factorial of $x (1*2*3*4*..*$x)

Returns the factorial of $x, i.e., the product of all positive integers up to and including $x.

bdfac()
$x->bdfac();                # double factorial of $x (1*2*3*4*..*$x)

Returns the double factorial of $x. If $x is an even integer, returns the product of all positive, even integers up to and including $x, i.e., 2*4*6*...*$x. If $x is an odd integer, returns the product of all positive, odd integers, i.e., 1*3*5*...*$x.

bfib()
$F = $n->bfib();            # a single Fibonacci number
@F = $n->bfib();            # a list of Fibonacci numbers

In scalar context, returns a single Fibonacci number. In list context, returns a list of Fibonacci numbers. The invocand is the last element in the output.

The Fibonacci sequence is defined by

F(0) = 0
F(1) = 1
F(n) = F(n-1) + F(n-2)

In list context, F(0) and F(n) is the first and last number in the output, respectively. For example, if $n is 12, then @F = $n->bfib() returns the following values, F(0) to F(12):

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144

The sequence can also be extended to negative index n using the re-arranged recurrence relation

F(n-2) = F(n) - F(n-1)

giving the bidirectional sequence

   n  -7  -6  -5  -4  -3  -2  -1   0   1   2   3   4   5   6   7
F(n)  13  -8   5  -3   2  -1   1   0   1   1   2   3   5   8  13

If $n is -12, the following values, F(0) to F(12), are returned:

0, 1, -1, 2, -3, 5, -8, 13, -21, 34, -55, 89, -144
blucas()
$F = $n->blucas();          # a single Lucas number
@F = $n->blucas();          # a list of Lucas numbers

In scalar context, returns a single Lucas number. In list context, returns a list of Lucas numbers. The invocand is the last element in the output.

The Lucas sequence is defined by

L(0) = 2
L(1) = 1
L(n) = L(n-1) + L(n-2)

In list context, L(0) and L(n) is the first and last number in the output, respectively. For example, if $n is 12, then @L = $n->blucas() returns the following values, L(0) to L(12):

2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322

The sequence can also be extended to negative index n using the re-arranged recurrence relation

L(n-2) = L(n) - L(n-1)

giving the bidirectional sequence

   n  -7  -6  -5  -4  -3  -2  -1   0   1   2   3   4   5   6   7
L(n)  29 -18  11  -7   4  -3   1   2   1   3   4   7  11  18  29

If $n is -12, the following values, L(0) to L(-12), are returned:

2, 1, -3, 4, -7, 11, -18, 29, -47, 76, -123, 199, -322
brsft()
$x->brsft($n);              # right shift $n places in base 2
$x->brsft($n, $b);          # right shift $n places in base $b

The latter is equivalent to

$x -> bdiv($b -> copy() -> bpow($n))
blsft()
$x->blsft($n);              # left shift $n places in base 2
$x->blsft($n, $b);          # left shift $n places in base $b

The latter is equivalent to

$x -> bmul($b -> copy() -> bpow($n))

Bitwise methods

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

Two's complement (bitwise not). This is equivalent to, but faster than,

$x->binc()->bneg();

Rounding methods

round()
$x->round($A,$P,$round_mode);

Round $x to accuracy $A or precision $P using the round mode $round_mode.

bround()
$x->bround($N);               # accuracy: preserve $N digits

Rounds $x to an accuracy of $N digits.

bfround()
$x->bfround($N);

Rounds to a multiple of 10**$N. Examples:

Input            N          Result

123456.123456    3          123500
123456.123456    2          123450
123456.123456   -2          123456.12
123456.123456   -3          123456.123
bfloor()
$x->bfloor();

Round $x towards minus infinity, i.e., set $x to the largest integer less than or equal to $x.

bceil()
$x->bceil();

Round $x towards plus infinity, i.e., set $x to the smallest integer greater than or equal to $x).

bint()
$x->bint();

Round $x towards zero.

Other mathematical methods

bgcd()
$x -> bgcd($y);             # GCD of $x and $y
$x -> bgcd($y, $z, ...);    # GCD of $x, $y, $z, ...

Returns the greatest common divisor (GCD).

blcm()
$x -> blcm($y);             # LCM of $x and $y
$x -> blcm($y, $z, ...);    # LCM of $x, $y, $z, ...

Returns the least common multiple (LCM).

Object property methods

sign()
$x->sign();

Return the sign, of $x, meaning either +, -, -inf, +inf or NaN.

If you want $x to have a certain sign, use one of the following methods:

$x->babs();                 # '+'
$x->babs()->bneg();         # '-'
$x->bnan();                 # 'NaN'
$x->binf();                 # '+inf'
$x->binf('-');              # '-inf'
digit()
$x->digit($n);       # return the nth digit, counting from right

If $n is negative, returns the digit counting from left.

digitsum()
$x->digitsum();

Computes the sum of the base 10 digits and returns it.

bdigitsum()
$x->bdigitsum();

Computes the sum of the base 10 digits and assigns the result to the invocand.

length()
$x->length();
($xl, $fl) = $x->length();

Returns the number of digits in the decimal representation of the number. In list context, returns the length of the integer and fraction part. For Math::BigInt objects, the length of the fraction part is always 0.

The following probably doesn't do what you expect:

$c = Math::BigInt->new(123);
print $c->length(),"\n";                # prints 30

It prints both the number of digits in the number and in the fraction part since print calls length() in list context. Use something like:

print scalar $c->length(),"\n";         # prints 3
mantissa()
$x->mantissa();

Return the signed mantissa of $x as a Math::BigInt.

exponent()
$x->exponent();

Return the exponent of $x as a Math::BigInt.

parts()
$x->parts();

Returns the significand (mantissa) and the exponent as integers. In Math::BigFloat, both are returned as Math::BigInt objects.

sparts()

Returns the significand (mantissa) and the exponent as integers. In scalar context, only the significand is returned. The significand is the integer with the smallest absolute value. The output of sparts() corresponds to the output from bsstr().

In Math::BigInt, this method is identical to parts().