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

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

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.

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

as_float()

Return the argument as a Math::BigFloat object.

as_rat()

Return the argument as a Math::BigRat object.

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.