/ 
Math-BigNum-0.03
River stage zero No dependents
/ Math::BigNum

NAME

Math::BigNum - Arbitrary size precision for integers, rationals and floating-point numbers

VERSION

Version 0.03

SYNOPSIS

use Math::BigNum qw(:constant);
print 1/2 * (100->fac + 1);

DESCRIPTION

Math::BigNum provides a transparent interface to Math::GMPz, Math::GMPq and Math::MPFR, focusing on performance and easy-to-use. In most cases, it can be used as a drop-in replacement for the bignum and bigrat pragmas.

MOTIVATION

This module came into existence as a response to Dana Jacobsen's request for a transparent interface to Math::GMPz and Math::MPFR, that he talked about at the YAPC NA, in 2015. See his great presentation at: https://www.youtube.com/watch?v=Dhl4_Chvm_g.

The main aim of this module is to provide a fast and correct alternative to Math::BigInt, Maht::BigFloat and Math::BigRat, as well as to bigint, bignum and bigrat pragmas.

HOW IT WORKS

Math::BigNum tries really hard to do the right thing and as efficiently as possible. For example, if you say $x**$y, it first checks to see if $x and $y are integers, so it can optimize the operation to integer exponentiation, by calling the corresponding mpz function. Otherwise, it will fallback to the corresponding mpfr function.

All numbers in Math::BigNum are stored as rational Math::GMPq objects. Each operation outside the functions provided by Math::GMPq, is done by converting the internal objects to Math::GMPz or Math::MPFR objects and calling the corresponding functions, converting the results back to Math::GMPq objects, without loosing any precision in the process.

IMPORT/EXPORT

Math::BigNum does not export anything by default, but it recognizes the following list of words:

:constant       # will make any number a Math::BigNum object
                # it will also export the "Inf" and "NaN" constants,
                # which represent +Infinity and NaN special values

e               # "e" constant (2.7182...)
pi              # "pi" constant (3.1415...)
tau             # "tau" constant (which is: 2*pi)
phi             # Golden ratio constant (1.618...)
G               # Catalan's constant (0.91596...)
Y               # Euler-Mascheroni constant (0.57721...)
Inf             # +Infinity constant
NaN             # Not-a-Number constant

The syntax for importing something, is:

use Math::BigNum qw(:constant pi);
say cos(2*pi);

NOTE: :constant is lexical to the current scope only.

PRECISION

The default precision of floating-point numbers is 128 bits, which is equivalent with about 32 digits of precision in base 10.

The precision can be changed by modifying the $Math::BigNum::PREC variable, such as:

local $Math::BigNum::PREC = 1024;

However, an important thing to take into account, unlike the Math::MPFR objects, Math::BigNum objects do not have a fixed precision stored inside. Rather, they can grow or shrink dynamically, regardless of the global precision.

The global precision controls only the precision of the floating-point functions and the stringification of floating-point numbers.

For example, if we change the precision to 3 decimal digits (where 4 is the conversion factor), we get the following results:

local $Math::BigNum::PREC = 3*4
say sqrt(2);                   # => 1.414
say 98**7;                     # => 86812553324672
say 1 / 98**7                  # => 1.15e-14

As shown above, integers do not obey the global precision, because they can grow or shrink dynamically, without a specific limit. This is true for rational numbers as well.

A rational number never losses precision in rational operations, therefore if we say:

my $x = 1 / 3;
say $x * 3;                    # => 1
say 1 / $x;                    # => 3
say 3 / $x;                    # => 9

...the results are exactly what we expect to be.

NOTATIONS

Methods that begin with a b followed by the actual name (e.g.: bsqrt), are mutable methods that change the self object in-place, while their counter-parts (e.g.: sqrt) do not. Instead, they will create and return a new object.

Also, Math::BigNum features another kind of methods that begin with an i followed by the actual name (e.g.: isqrt). This methods will do integer operations, by truncating their arguments to integers, whenever needed.

The returned types are noted as follows:

BigNum      #-> a "Math::BigNum" object
Inf         #-> a "Math::BigNum::Inf" object
Nan         #-> a "Math::BigNum::Nan" object
Scalar      #-> a Perl number or string
Bool        #-> true or false (actually: 1 or 0)
Any         #-> any value, including a reference

When two or more types are separated with pipe characters (|), it means that the corresponding function can return any of the specified types.

PERFORMANCE

The performance varies greatly, but, in most cases, Math::BigNum it's between 2x up to 10x faster than Math::BigFloat with the GMP backend, and about 100x faster than Math::BigFloat without the GMP backend (to be modest).

Math::BigNum is fast because of the following facts:

  • minimal overhead in object creation.

  • minimal Perl code is executed per operation.

  • the GMP and MPFR libraries are extremely efficient.

To achieve the best performance, try to follow this rules:

  • use the b* methods whenever you can.

  • use the i* methods wherever applicable.

  • pass Perl numbers as arguments to methods, whenever you can.

  • avoid the stringification of Math::BigNum objects as much as possible.

  • don't use copy followed by a b* method! Just leave out the b.

SUBROUTINES/METHODS

new

BigNum->new(Scalar)            # => BigNum
BigNum->new(Scalar, Scalar)    # => BigNum

Returns a new BigNum object with the value specified in the first argument, which can be a Perl numerical value, a string representing a number in a rational form, such as "1/2", a string holding a floating-point number, such as "0.5", or a string holding an integer, such as "255".

The second argument specifies the base of the number, which can range from 2 to 36 inclusive and defaults to 10.

For setting an hexadecimal number, we can say:

my $x = Math::BigNum->new("deadbeef", 16);

NOTE: no prefix, such as "0x" or "0b", is allowed as part of the number.

nan

BigNum->nan                    # => Nan

Returns a new Nan object.

inf

BigNum->inf                    # => Inf

Returns a new Inf object to represent positive Infinity.

ninf

BigNum->ninf                   # => -Inf

Returns an Inf object to represent negative Infinity.

one

BigNum->one                    # => BigNum

Returns a BigNum object containing the value 1.

zero

BigNum->zero                   # => BigNum

Returns a BigNum object containing the value 0.

mone

BigNum->mone                   # => BigNum

Returns a BigNum object containing the value -1.

stringify

$x->stringify                  # => Scalar

Returns a string representing the value of $x, either as an integer or as a floating-point number. For $x=1/2, it returns "0.5".

numify

$x->numify                     # => Scalar

Returns a Perl numerical scalar with the value of $x, truncated if needed.

boolify

$x->boolify                    # => Bool

Returns a true value when the number is not zero. False otherwise.

copy

$x->copy                       # => BigNum

Returns a deep copy of $x.

pi

BigNum->pi                     # => BigNum

Returns the number PI, which is 3.1415....

tau

BigNum->tau                    # => BigNum

Returns the number TAU, which is 2*PI.

ln2

BigNum->ln2                    # => BigNum

Returns the natural logarithm of 2.

Y

BigNum->Y                      # => BigNum

Returns the Euler-Mascheroni constant, which is 0.57721....

G

BigNum->G                      # => BigNum

Returns the value of Catalan's constant, also known as Beta(2) or G, and starts as: 0.91596....

e

BigNum->e                      # => BigNum

Returns the e mathematical constant, which is 2.718....

phi

BigNum->phi                    # => BigNum

Returns the value of the golden ratio, which is 1.61803....

bzero

$x->bzero                      # => BigNum

Changes $x in-place to hold the value 0.

bone

$x->bone                       # => BigNum

Changes $x in-place to hold the value +1.

bmone

$x->bmone                      # => BigNum

Changes $x in-place to hold the value -1.

binf

$x->binf                       # => Inf

Changes $x in-place to positive Infinity.

bninf

$x->bninf                      # => -Inf

Changes $x in-place to negative Infinity.

bnan

$x->bnan                       # => Nan

Changes $x in-place to the special Not-a-Number value.

add

$x->add(BigNum)                # => BigNum
$x->add(Scalar)                # => BigNum

BigNum + BigNum                # => BigNum
BigNum + Scalar                # => BigNum
Scalar + BigNum                # => BigNum

Adds $y to $x and returns the result.

badd

$x->badd(BigNum)               # => BigNum
$x->badd(Scalar)               # => BigNum

BigNum += BigNum               # => BigNum
BigNum += Scalar               # => BigNum

Adds $y to $x, changing $x in-place.

iadd

$x->iadd(BigNum)               # => BigNum
$x->iadd(Scalar)               # => BigNum

Integer addition of $y to $x. Both values are truncated to integers before addition.

biadd

$x->biadd(BigNum)              # => BigNum
$x->biadd(Scalar)              # => BigNum

Integer addition of $y from $x, changing $x in-place. Both values are truncated to integers before addition.

sub

$x->sub(BigNum)                # => BigNum
$x->sub(Scalar)                # => BigNum

BigNum - BigNum                # => BigNum
BigNum - Scalar                # => BigNum
Scalar - BigNum                # => BigNum

Subtracts $y from $x and returns the result.

bsub

$x->bsub(BigNum)               # => BigNum
$x->bsub(Scalar)               # => BigNum

BigNum -= BigNum               # => BigNum
BigNum -= Scalar               # => BigNum

Subtracts $y from $x by changing $x in-place.

isub

$x->isub(BigNum)               # => BigNum
$x->isub(Scalar)               # => BigNum

Integer subtraction of $y from $x. Both values are truncated to integers before subtraction.

bisub

$x->bisub(BigNum)              # => BigNum
$x->bisub(Scalar)              # => BigNum

Integer subtraction of $y from $x, changing $x in-place. Both values are truncated to integers before subtraction.

mul

$x->mul(BigNum)                # => BigNum
$x->mul(Scalar)                # => BigNum

BigNum * BigNum                # => BigNum
BigNum * Scalar                # => BigNum
Scalar * BigNum                # => BigNum

Multiplies $x by $y and returns the result.

bmul

$x->bmul(BigNum)               # => BigNum
$x->bmul(Scalar)               # => BigNum

BigNum *= BigNum               # => BigNum
BigNum *= Scalar               # => BigNum

Multiply $x by $y, changing $x in-place.

imul

$x->imul(BigNum)               # => BigNum
$x->imul(Scalar)               # => BigNum

Integer multiplication of $x by $y. Both values are truncated to integers before multiplication.

bimul

$x->bimul(BigNum)              # => BigNum
$x->bimul(Scalar)              # => BigNum

Integer multiplication of $x by $y, changing $x in-place. Both values are truncated to integers before multiplication.

div

$x->div(BigNum)                # => BigNum | Inf | Nan
$x->div(Scalar)                # => BigNum | Inf | Nan

BigNum / BigNum                # => BigNum | Inf | Nan
BigNum / Scalar                # => BigNum | Inf | Nan
Scalar / BigNum                # => BigNum | Inf | Nan

Divides $x by $y and returns the result. Returns Nan when $x and $y are 0, Inf when $y is $zero and $x is positive, -Inf when $y is zero and $x is negative.

bdiv

$x->bdiv(BigNum)               # => BigNum | Nan | Inf
$x->bdiv(Scalar)               # => BigNum | Nan | Inf

BigNum /= BigNum               # => BigNum | Nan | Inf
BigNum /= Scalar               # => BigNum | Nan | Inf

Divide $x by $y, changing $x in-place. The return values are the same as for div().

idiv

$x->idiv(BigNum)               # => BigNum | Nan | Inf
$x->idiv(Scalar)               # => BigNum | Nan | Inf

Integer division of $x by $y.

bidiv

$x->bidiv(BigNum)              # => BigNum | Nan | Inf
$x->bidiv(Scalar)              # => BigNum | Nan | Inf

Integer division of $x by $y, changing $x in-place.

neg

$x->neg                        # => BigNum
-$x                            # => BigNum

Negative value of $x. Returns abs($x) when $x is negative, and -$x when $x is positive.

bneg

$x->bneg                       # => BigNum

Negative value of $x, changing $x in-place.

abs

$x->abs                        # => BigNum
abs($x)                        # => BigNum

Absolute value of $x.

babs

$x->babs                       # => BigNum

Absolute value of $x, changing $x in-place.

inv

$x->inv                        # => BigNum | Inf

Inverse value of $x. Return Inf when $x is zero. (1/$x)

sqr

$x->sqr                        # => BigNum

Raise $x to the power of 2 and return the result. ($x**2)

sqrt

$x->sqrt                       # => BigNum | Nan
sqrt($x)                       # => BigNum | Nan

Square root of $x. Returns Nan when $x is negative.

bsqrt

$x->bsqrt                      # => BigNum | Nan

Square root of $x, changing $x in-place. Promotes $x to Nan when $x is negative.

isqrt

$x->isqrt                      # => BigNum | Nan

Integer square root of $x. Returns Nan when $x is negative.

bisqrt

$x->bisqrt                     # => BigNum | Nan

Integer square root of $x, changing $x in-place. Promotes $x to Nan when $x is negative.

cbrt

$x->cbrt                       # => BigNum | Nan

Cube root of $x. Returns Nan when $x is negative.

root

$x->root(BigNum)               # => BigNum | Nan
$x->root(Scalar)               # => BigNum | Nan

Nth root of $x. Returns Nan when $x is negative.

broot

$x->broot(BigNum)              # => BigNum | Nan
$x->broot(Scalar)              # => BigNum(1)

Nth root of $x, changing $x in-place. Promotes $x to Nan when $x is negative.

iroot

$x->iroot(BigNum)              # => BigNum | Nan
$x->iroot(Scalar)              # => BigNum | Nan

Nth integer root of $x ($x**(1/$n)). Returns Nan when $x is negative and $y is even.

biroot

$x->biroot(BigNum)             # => BigNum | Nan
$x->biroot(Scalar)             # => BigNum | Nan

Nth integer root of $x, changing $x in-place. Promotes $x to Nan when $x is negative and $y is even.

pow

$x->pow(BigNum)                # => BigNum | Nan
$x->pow(Scalar)                # => BigNum | Nan

BigNum ** BigNum               # => BigNum | Nan
BigNum ** Scalar               # => BigNum | Nan
Scalar ** BigNum               # => BigNum | Nan

Raises $x to power $y. Returns Nan when $x is negative and $y is not an integer.

bpow

$x->bpow(BigNum)               # => BigNum | Nan
$x->bpow(Scalar)               # => BigNum | Nan

Raises $x to power $y, changing $x in-place.

ipow

$x->ipow(BigNum)               # => BigNum
$x->ipow(Scalar)               # => BigNum

Raises $x to power $y, truncating $x and $y to integers, if necessarily.

bipow

$x->bipow(BigNum)              # => BigNum
$x->bipow(Scalar)              # => BigNum

Raises $x to power $y, changing $x in-place.

ln

$x->ln                         # => BigNum | Nan

Logarithm of $x in base e. Returns Nan when $x is negative.

log

$x->log                        # => BigNum | Nan
$x->log(BigNum)                # => BigNum | Nan
$x->log(Scalar)                # => BigNum | Nan
log(BigNum)                    # => BigNum | Nan

Logarithm of $x in base $y. When $y is not specified, it defaults to base e. Returns Nan when $x is negative and -Inf when $x is zero.

blog

$x->blog                       # => BigNum | Nan
$x->blog(BigNum)               # => BigNum | Nan
$x->log(Scalar)                # => BigNum | Nan

Logarithm of $x in base $y, changing the $x in-place. When $y is not specified, it defaults to base e.

log2

$x->log2                       # => BigNum | Nan

Logarithm of $x in base 2. Returns Nan when $x is negative.

log10

$x->log10                      # => BigNum | Nan

Logarithm of $x in base 10. Returns Nan when $x is negative.

exp

$x->exp                        # => BigNum

Exponential of $x in base e. (e**$x)

bexp

$x->bexp                       # => BigNum

Exponential of $x in base e, changing $x in-place.

exp2

$x->exp2                       # => BigNum

Exponential of $x in base 2. (2**$x)

exp10

$x->exp10                      # => BigNum

Exponential of $x in base 10. (10**$x)

sin

$x->sin                        # => BigNum

Returns the sine of $x.

asin

$x->asin                       # => BigNum | Nan

Returns the inverse sine of $x. Returns Nan for <$x < -1> or <$x 1>>.

sinh

$x->sinh                       # => BigNum

Returns the hyperbolic sine of $x.

asinh

$x->asinh                      # => BigNum

Returns the inverse hyperbolic sine of $x.

cos

$x->cos                        # => BigNum

Returns the cosine of $x.

acos

$x->acos                       # => BigNum | Nan

Returns the inverse cosine of $x. Returns Nan for <$x < -1> or <$x 1>>.

cosh

$x->cosh                       # => BigNum

Returns the hyperbolic cosine of $x.

acosh

$x->acosh                      # => BigNum | Nan

Returns the inverse hyperbolic cosine of $x. Returns Nan for <$x < 1>.

tan

$x->tan                        # => BigNum

Returns the tangent of $x.

atan

$x->atan                       # => BigNum

Returns the inverse tangent of $x.

tanh

$x->tanh                       # => BigNum

Returns the hyperbolic tangent of $x.

atanh

$x->atanh                      # => BigNum | Nan

Returns the inverse hyperbolic tangent of $x. Returns Nan for <$x <= -1> or <$x = 1>>.

sec

$x->sec                        # => BigNum

Returns the secant of $x.

asec

$x->asec                       # => BigNum | Nan

Returns the inverse secant of $x. Returns Nan for <$x -1>> and <$x < 1>.

sech

$x->sech                       # => BigNum

Returns the hyperbolic secant of $x.

asech

$x->asech                      # => BigNum | Nan

Returns the inverse hyperbolic secant of $x. Returns a Nan for <$x < 0> or <$x 1>>.

csc

$x->csc                        # => BigNum

Returns the cosecant of $x.

acsc

$x->acsc                       # => BigNum | Nan

Returns the inverse cosecant of $x. Returns Nan for <$x -1>> and <$x < 1>.

csch

$x->csch                       # => BigNum

Returns the hyperbolic cosecant of $x.

acsch

$x->acsch                      # => BigNum

Returns the inverse hyperbolic cosecant of $x.

cot

$x->cot                        # => BigNum

Returns the cotangent of $x.

acot

$x->acot                       # => BigNum

Returns the inverse cotangent of $x.

coth

$x->coth                       # => BigNum

Returns the hyperbolic cotangent of $x.

acoth

$x->acoth                      # => BigNum

Returns the inverse hyperbolic cotangent of $x.

atan2

$x->atan2(BigNum)              # => BigNum
$x->atan2(Scalar)              # => BigNum

atan2(BigNum, BigNum)          # => BigNum
atan2(BigNum, Scalar)          # => BigNum
atan2(Scalar, BigNum)          # => BigNum

Arctangent of $x and $y. When $y is -Inf returns PI when <$x = 0>>, or -PI when <$x < 0>.

eq

$x->eq(BigNum)                 # => Bool
$x->eq(Scalar)                 # => Bool

$x == $y                       # => Bool

Equality check: returns a true value when $x and $y are equal.

ne

$x->ne(BigNum)                 # => Bool
$x->ne(Scalar)                 # => Bool

$x != $y                       # => Bool

Inequality check: returns a true value when $x and $y are not equal.

gt

$x->gt(BigNum)                 # => Bool
$x->gt(Scalar)                 # => Bool

BigNum > BigNum                # => Bool
BigNum > Scalar                # => Bool
Scalar > BigNum                # => Bool

Returns a true value when $x is greater than $y.

ge

$x->ge(BigNum)                 # => Bool
$x->ge(Scalar)                 # => Bool

BigNum >= BigNum               # => Bool
BigNum >= Scalar               # => Bool
Scalar >= BigNum               # => Bool

Returns a true value when $x is equal or greater than $y.

lt

$x->lt(BigNum)                 # => Bool
$x->lt(Scalar)                 # => Bool

BigNum < BigNum                # => Bool
BigNum < Scalar                # => Bool
Scalar < BigNum                # => Bool

Returns a true value when $x is less than $y.

le

$x->le(BigNum)                 # => Bool
$x->le(Scalar)                 # => Bool

BigNum <= BigNum               # => Bool
BigNum <= Scalar               # => Bool
Scalar <= BigNum               # => Bool

Returns a true value when $x is equal or less than $y.

cmp

$x->cmp(BigNum)                # => Scalar
$x->cmp(Scalar)                # => Scalar

BigNum <=> BigNum              # => Scalar
BigNum <=> Scalar              # => Scalar
Scalar <=> BigNum              # => Scalar

Compares $x to $y and returns a negative value when $x is less than $y, 0 when $x and $y are equal, and a positive value when $x is greater than $y.

acmp

$x->acmp(BigNum)               # => Scalar
cmp(Scalar, BigNum)            # => Scalar

Compares the absolute values of $x and $y. Returns a negative value when the absolute value of $x is less than the absolute value of $y, 0 when the absolute value of $x is equal to the absolute value of $y, and a positive value when the absolute value of $x is greater than the absolute value of $y.

rand

$x->rand                       # => BigNum
$x->rand(BigNum)               # => BigNum
$x->rand(Scalar)               # => BigNum

Returns a random floating-point number. If an argument is provided, it returns a number between $x and $y, otherwise returns a number lower than $x.

Example:

10->rand;       # a random number between 0 and 10 (exclusive)
10->rand(20);   # a random number between 10 and 20 (exclusive)

mod

$x->mod(BigNum)                # => BigNum | Nan
$x->mod(Scalar)                # => BigNum | Nan

BigNum % BigNum                # => BigNum | Nan
BigNum % Scalar                # => BigNum | Nan
Scalar % BigNum                # => BigNum | Nan

Remainder of $x when is divided by $y. Returns Nan when $y is zero.

bmod

$x->bmod(BigNum)               # => BigNum | Nan
$x->bmod(Scalar)               # => BigNum | Nan

BigNum %= BigNum               # => BigNum | Nan
BigNum %= Scalar               # => BigNum | Nan

Sets $x to the remainder of $x when is divided by $y. Sets $x to Nan when $y is zero.

imod

$x->imod(BigNum)               # => BigNum | Nan
$x->imod(Scalar)               # => BigNum | Nan

Integer remainder of $x when is divided by $y. If necessary, $x and $y are implicitly truncated to integers. Nan is returned when $y is zero.

bimod

$x->bimod(BigNum)              # => BigNum | Nan
$x->bimod(Scalar)              # => BigNum | Nan

Sets $x to the remainder of $x divided by $y. If necessary, $x and $y are implicitly truncated to integers. Sets $x to Nan when $y is zero.

divmod

$x->divmod(BigNum)             # => (BigNum, BigNum) | (Nan, Nan)
$x->divmod(Scalar)             # => (BigNum, BigNum) | (Nan, Nan)

Returns the quotient and the remainder from division of $x by $y, where both are integers. When $y is zero, it returns two Nan values.

modinv

$x->modinv(BigNum)             # => BigNum | Nan
$x->modinv(Scalar)             # => BigNum | Nan

Computes the inverse of $x modulo $y and returns the result. If an inverse doesn't exist the Nan value is returned.

modpow

$x->modpow(BigNum, BigNum)     # => BigNum

Calculates ($x ** $y) % $z, where all three values are integers.

is_zero

$x->is_zero                    # => Bool

Returns a true value when $x is 0.

is_one

$x->is_one                     # => Bool

Returns a true value when $x is +1.

is_mone

$x->is_mone                    # => Bool

Returns a true value when $x is -1.

is_pos

$x->is_pos                     # => Bool

Returns a true value when $x is greater than zero.

is_neg

$x->is_neg                     # => Bool

Returns a true value when $x is less than zero.

is_int

$x->is_int                     # => Bool

Returns a true value when $x is an integer.

is_real

$x->is_real                    # => Bool

Always returns a true value when invoked on a Math::BigNum object.

is_inf

$x->is_inf                     # => Bool

Always returns a false value when invoked on a Math::BigNum object.

is_nan

$x->is_nan                     # => Bool

Always returns a false value when invoked on a Math::BigNum object.

is_ninf

$x->is_ninf                    # => Bool

Always returns a false value when invoked on a Math::BigNum object.

is_even

$x->is_even                    # => Bool

Returns a true value when $x is divisible by 2. Returns 0 if $x is NOT an integer.

is_odd

$x->is_odd                     # => Bool

Returns a true value when $x is NOT divisible by 2. Returns 0 if $x is NOT an integer.

is_div

$x->is_div(BigNum)             # => Bool
$x->is_div(Scalar)             # => Bool

Returns a true value if $x is divisible by $y. False otherwise. If $y is zero, returns 0.

is_psqr

$n->is_psqr                    # => Bool

Returns a true value when $n is a perfect square. False otherwise. When $n is not an integer, returns 0.

is_ppow

$n->is_ppow                    # => Bool

Returns a true value when $n is a perfect power. False otherwise. When $n is not an integer, returns 0.

sign

$x->sign                       # => Scalar

Returns '-' when $x is negative, '+' when $x is positive, and '' when $x is zero.

min

$x->min(BigNum)                # => BigNum

Returns $x if $x is lower than $y. Returns $y otherwise.

max

$x->max(BigNum)                # => BigNum

Returns $x if $x is greater than $y. Returns $y otherwise.

gcd

$x->gcd(BigNum)                # => BigNum
$x->gcd(Scalar)                # => BigNum

The greatest common divisor of $x and $y.

lcm

$x->lcd(BigNum)                # => BigNum
$x->lcd(Scalar)                # => BigNum

The least common multiple of $x and $y.

int

$x->int                        # => BigNum
int($x)                        # => BigNum

Returns a truncated integer from the value of $x.

bint

$x->bint                       # => BigNum

Truncates $x to an integer in-place.

float

$x->float                      # => BigNum

Returns a truncated number that fits inside number of bits specified in $Math::BigNum::PREC.

as_frac

$x->as_frac                    # => Scalar

Returns a string representing the number as a fraction. For $x=0.5, it returns "1/2". For $x=3, it returns "3/1".

as_rat

$x->as_rat                     # => Scalar

Almost the same as as_frac(), except that integers are returned as they are, without adding the "1" denominator. For $x=0.5, it returns "1/2". For $x=3, it simply returns "3".

as_float

$x->as_float                   # => Scalar
$x->as_float(Scalar)           # => Scalar
$x->as_float(BigNum)           # => Scalar

Returns the self-number as a floating-point scalar. The method also accepts an optional argument for precision after the decimal point. When no argument is provided, it uses the default precision.

Example for $x = 1/3:

$x->as_float(4);        # returns "0.3333"

If the self number is an integer, it will be returned as it is.

as_int

$x->as_int                     # => Scalar
$x->as_int(Scalar)             # => Scalar
$x->as_int(BigNum)             # => Scalar

Returns the self-number as an integer in a given base. When the base is omitted, it defaults to 10.

Example for $x = 255:

$x->as_int          # returns: "255"
$x->as_int(16)      # returns: "ff"

as_bin

$x->as_bin                     # => Scalar

Returns a string representing the value of $x in binary. For $x=42, it returns "101010".

as_oct

$x->as_oct                     # => Scalar

Returns a string representing the value of $x in octal. For $x=42, it returns "52".

as_hex

$x->as_hex                     # => Scalar

Returns a string representing the value of $x in hexadecimal. For $x=42, it returns "2a".

in_base

$x->in_base(BigNum)            # => Scalar
$x->in_base(Scalar)            # => Scalar

Returns a string with the value of $x in a given base, where the base can range from 2 to 36 inclusive. If $x is not an integer, the result is returned in rationalized form.

digits

$x->digits                     # => List of scalars

Returns a list with the digits of $x in base 10 before the decimal point. For $x=-1234.56, it returns (1,2,3,4)

length

$x->length                     # => Scalar

Returns the number of digits of $x in base 10 before the decimal point. For $x=-1234.56, it returns 4.

numerator

$x->numerator                  # => BigNum

Returns a copy of the numerator as signed BigNum.

denominator

$x->denominator                # => BigNum

Returns a copy of the denominator as positive BigNum.

floor

$x->floor                      # => BigNum

Returns $x if $x is an integer, otherwise it rounds $x towards -Infinity. For $x=2.5, returns 2, and for $x=-2.5, returns -3.

ceil

$x->ceil                       # => BigNum

Returns $x if $x is an integer, otherwise it rounds $x towards +Infinity. For $x=2.5, returns 3, and for $x=-2.5, returns -2.

round

$x->round(BigNum)              # => BigNum
$x->round(Scalar)              # => BigNum

Rounds $x to the nth place. A negative argument rounds that many digits after the decimal point, while a positive argument rounds before the decimal point. This method uses the "round half to even" algorithm, which is the default rounding mode used in IEEE 754 computing functions and operators.

bround

$x->bround(BigNum)             # => BigNum
$x->bround(Scalar)             # => BigNum

Rounds $x in-place to nth places.

inc

$x->inc                        # => BigNum

Returns $x + 1.

binc

$x->binc                       # => BigNum
++$x                           # => BigNum
$x++                           # => BigNum

Increments $x in-place by 1.

dec

$x->dec                        # => BigNum

Returns $x - 1.

bdec

$x->bdec                       # => BigNum
--$x                           # => BigNum
$x--                           # => BigNum

Decrements $x in-place by 1.

and

$x->and(BigNum)                # => BigNum
$x->and(Scalar)                # => BigNum

BigNum & BigNum                # => BigNum
BigNum & Scalar                # => BigNum
Scalar & BigNum                # => BigNum

Integer logical-and operation.

band

$x->band(BigNum)               # => BigNum
$x->band(Scalar)               # => BigNum

BigNum &= BigNum               # => BigNum
BigNum &= Scalar               # => BigNum

Integer logical-and operation, changing $x in-place.

ior

$x->ior(BigNum)                # => BigNum
$x->ior(Scalar)                # => BigNum

BigNum | BigNum                # => BigNum
BigNum | Scalar                # => BigNum
Scalar | BigNum                # => BigNum

Integer logical inclusive-or operation.

bior

$x->bior(BigNum)               # => BigNum
$x->bior(Scalar)               # => BigNum

BigNum |= BigNum               # => BigNum
BigNum |= Scalar               # => BigNum

Integer logical inclusive-or operation, changing $x in-place.

xor

$x->xor(BigNum)                # => BigNum
$x->xor(Scalar)                # => BigNum

BigNum ^ BigNum                # => BigNum
BigNum ^ Scalar                # => BigNum
Scalar ^ BigNum                # => BigNum

Integer logical exclusive-or operation.

bxor

$x->bxor(BigNum)               # => BigNum
$x->bxor(Scalar)               # => BigNum

BigNum ^= BigNum               # => BigNum
BigNum ^= Scalar               # => BigNum

Integer logical exclusive-or operation, changing $x in-place.

not

$x->not                        # => BigNum
~BigNum                        # => BigNum

Integer logical-not operation. (The one's complement of $x).

bnot

$x->bnot                       # => BigNum

Integer logical-not operation, changing $x in-place.

lsft

$x->lsft(BigNum)               # => BigNum
$x->lsft(Scalar)               # => BigNum

BigNum << BigNum               # => BigNum
BigNum << Scalar               # => BigNum
Scalar << BigNum               # => BigNum

Integer left-shift operation. ($x * (2 ** $y))

blsft

$x->blsft(BigNum)              # => BigNum
$x->blsft(Scalar)              # => BigNum

BigNum <<= BigNum              # => BigNum
BigNum <<= Scalar              # => BigNum

Integer left-shift operation, changing $x in-place. Promotes $x to Nan when $y is negative. ($x * (2 ** $y))

rsft

$x->rsft(BigNum)               # => BigNum
$x->rsft(Scalar)               # => BigNum

BigNum >> BigNum               # => BigNum
BigNum >> Scalar               # => BigNum
Scalar >> BigNum               # => BigNum

Integer right-shift operation. ($x / (2 ** $y))

brsft

$x->brsft(BigNum)              # => BigNum
$x->brsft(Scalar)              # => BigNum

BigNum >>= BigNum              # => BigNum
BigNum >>= Scalar              # => BigNum

Integer right-shift operation, changing $x in-place. ($x / (2 ** $y))

fac

$n->fac                        # => BigNum | Nan

Factorial of $n. Returns Nan when $n is negative. (1*2*3*...*$n)

bfac

$n->bfac                       # => BigNum | Nan

Factorial of $n, by changing $n in-place.

dfac

$n->dfac                       # => BigNum | Nan

Double factorial of $n. Returns Nan when $n is negative.

primorial

$n->primorial                  # => BigNum | Nan

Returns the product of all the primes less than or equal to $n.

fib

$n->fib                        # => BigNum | Nan

The $n'th Fibonacci number. Returns Nan when $n is negative.

lucas

$n->lucas                      # => BigNum | Nan

The $n'th Lucas number. Returns Nan when $n is negative.

binomial

$n->binomial(BigNum)           # => BigNum
$n->binomial(Scalar)           # => BigNum

Calculates the binomial coefficient n over k, also called the "choose" function. The result is equivalent to:

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

is_prime

$n->is_prime                   # => Scalar
$x->is_prime(BigNum)           # => Scalar
$n->is_prime(Scalar)           # => Scalar

Returns 2 if $n is definitely prime, 1 if $n is probably prime (without being certain), or 0 if $n is definitely composite. This method does some trial divisions, then some Miller-Rabin probabilistic primality tests. It also accepts an optional argument for specifying the accuracy of the test. By default, it uses an accuracy value of 12, which guarantees correctness up to 2**78.

See also: https://en.wikipedia.org/wiki/Miller–Rabin_primality_test

next_prime

$n->next_prime                 # => BigNum

Returns the next prime after $n.

agm

$x->agm(BigNum)                # => BigNum
$x->agm(Scalar)                # => BigNum

Arithmetic-geometric mean of $x and $y.

hypot

$x->hypot(BigNum)              # => BigNum
$x->hypot(Scalar)              # => BigNum

The value of the hypotenuse for catheti $x and $y. (sqrt($x**2 + $y**2))

gamma

$x->gamma                      # => BigNum | Inf | Nan

The Gamma function on $x. Returns Inf when $x is zero, and Nan when $x is negative.

lngamma

$x->lngamma                    # => BigNum | Inf

The natural logarithm of the Gamma function on $x. Returns Inf when $x is negative or equal to zero.

lgamma

$x->lgamma                     # => BigNum | Inf

The logarithm of the absolute value of the Gamma function. Returns Inf when $x is negative or equal to zero.

digamma

$x->digamma                    # => BigNum | Inf | Nan

The Digamma function (sometimes also called Psi). Returns Nan when $x is negative, and -Inf when $x is 0.

zeta

$x->zeta                       # => BigNum | Inf

The zeta function on $x. Returns Inf when $x is 1.

erf

$x->erf                        # => BigNum

The error function on $x.

erfc

$x->erfc                       # => BigNum

Complementary error function on $x.

eint

$x->eint                       # => BigNum | Inf | Nan

Exponential integral of $x. Returns -Inf when $x is zero, and Nan when $x is negative.

li2

$x->li2                        # => BigNum

The dilogarithm function, defined as the integral of -log(1-t)/t from 0 to $x.

AUTHOR

Daniel Șuteu, <trizenx at gmail.com>

BUGS

Please report any bugs or feature requests to bug-math-bignum at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-BigNum. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Math::BigNum

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2016 Daniel Șuteu.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.