Math::AnyNum - Arbitrary size precision for integers, rationals, floating-points and complex numbers.
Version 0.22
Math::AnyNum provides a transparent and easy-to-use interface to Math::GMPz, Math::GMPq, Math::MPFR and Math::MPC.
use 5.014; use Math::AnyNum qw(:overload factorial); # Integers say factorial(30); #=> 265252859812191058636308480000000 # Floating-point numbers say sqrt(1 / factorial(100)); #=> 1.0351378111756264713204945[...]e-79 # Rational numbers my $x = 2/3; say ($x * 3); #=> 2 say (2 / $x); #=> 3 say $x; #=> 2/3 # Complex numbers say 3 + 4*i; #=> 3+4i say sqrt(-4); #=> 2i say log(-1); #=> 3.1415926535897932384626433832[...]i
Math::AnyNum focuses primarily on providing a friendly interface and good performance. In most cases, it can be used as a drop-in replacement for the bignum and bigrat pragmas.
The philosophy of Math::AnyNum is that mathematics should just work, therefore the support for complex numbers is virtually transparent, without requiring any explicit conversions. All the conversions are done implicitly, using a fairly sophisticated promotion system, which tries really hard to do the right thing and as efficiently as possible.
Additionally, each Math::AnyNum object is immutable.
Internally, each Math::AnyNum object holds a reference to an object of type Math::GMPz, Math::GMPq, Math::MPFR or Math::MPC. Based on the internal types, it decides what functions to call on each operation and does automatic promotion whenever necessarily.
The promotion rules can be summarized as follows:
(Integer, Integer) -> Integer | Rational | Float | Complex (Integer, Rational) -> Rational | Float | Complex (Integer, Float) -> Float | Complex (Integer, Complex) -> Complex (Rational, Rational) -> Rational | Float | Complex (Rational, Float) -> Float | Complex (Rational, Complex) -> Complex (Float, Float) -> Float | Complex (Float, Complex) -> Complex (Complex, Complex) -> Complex
For explicit conversions, Math::AnyNum provides the following functions:
int(x) # converts x to an integer (NaN if not possible) rat(x) # converts x to a rational (NaN if not possible) float(x) # converts x to a real-float (NaN if not possible) complex(x) # converts x to a complex number (always possible)
The following functions are exportable:
:trig sin sinh asin asinh cos cosh acos acosh tan tanh atan atanh cot coth acot acoth sec sech asec asech csc csch acsc acsch atan2 rad2deg deg2rad :special beta eta gamma lgamma lngamma digamma zeta Ai Ei Li Li2 LambertW BesselJ BesselY lgrt pow sqr sqrt cbrt root exp exp2 exp10 log ln log2 log10 mod polymod erf erfc abs agm hypot norm bernreal harmreal polygonal_root polygonal_root2 :ntheory factorial dfactorial mfactorial primorial binomial lucas fibonacci bernfrac harmfrac lcm gcd valuation kronecker remdiv divmod iadd isub imul idiv imod ipow ipow2 ipow10 iroot isqrt icbrt ilog ilog2 ilog10 invmod powmod isqrtrem irootrem is_power is_square is_prime is_coprime next_prime is_polygonal is_polygonal2 faulhaber_sum ipolygonal_root ipolygonal_root2 polygonal rising_factorial falling_factorial subfactorial multinomial is_smooth :misc rand irand seed iseed floor ceil round sgn neg inv conj int rat float complex real imag reals digits numerator denominator nude popcount as_bin as_hex as_oct as_int as_dec as_frac is_pos is_neg is_int is_rat is_real is_imag is_complex is_inf is_ninf is_nan is_zero is_one is_mone is_even is_odd is_div rat_approx acmp
Each function can be exported individually, as:
use Math::AnyNum qw(zeta);
There is also the possibility of exporting an entire group of functions, as:
use Math::AnyNum qw(:trig);
Additionally, by specifying the :all keyword, will export all the exportable functions and all the constants.
:all
use Math::AnyNum qw(:all);
The :overload keyword enables constant overloading, which makes each number a Math::AnyNum object and also exports the i, Inf and NaN constants:
:overload
i
Inf
NaN
use Math::AnyNum qw(:overload); say 42; #=> "42" (as Int) say 1/2; #=> "1/2" (as Rat) say 0.5; #=> "0.5" (as Float) say 3 + 4*i; #=> "3+4i" (as Complex)
NOTE: :overload is lexical to the current scope only.
The syntax for disabling the :overload behavior in the current scope, is:
no Math::AnyNum; # :overload will be disabled in the current scope
In addition to the exportable functions, Math::AnyNum also provides a list with useful mathematical constants that can be exported, such as:
i # imaginary unit sqrt(-1) e # e mathematical constant 2.718281828459... pi # PI constant 3.141592653589... tau # TAU constant 6.283185307179... ln2 # natural logarithm of 2 0.693147180559... phi # golden ratio 1.618033988749... euler # Euler-Mascheroni constant 0.577215664901... catalan # Catalan constant 0.915965594177... Inf # positive Infinity NaN # Not-a-Number
The syntax for importing a constant, is:
use Math::AnyNum qw(pi); say pi; # 3.141592653589...
Nothing is exported by default.
The default precision for floating-point numbers is 192 bits, which is equivalent with about 50 digits of precision in base 10.
The precision can be changed by modifying the $Math::AnyNum::PREC variable, such as:
$Math::AnyNum::PREC
local $Math::AnyNum::PREC = 1024;
or by specifying the precision at import (this sets the precision globally):
use Math::AnyNum PREC => 1024;
This precision is used internally whenever a Math::MPFR or a Math::MPC object is created.
Math::MPFR
Math::MPC
For example, if we change the precision to 3 decimal digits (where 4 is the conversion factor), we get the following results:
4
local $Math::AnyNum::PREC = 3*4; say sqrt(2); #=> 1.41 say 98**7; #=> 86812553324672 say 1 / 98**7 #=> 1/86812553324672
As shown above, integers and rational numbers do not obey this precision, because they can grow and shrink dynamically, without a specific limit.
Furthermore, a rational number never losses precision and accuracy 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 exact.
Methods that begin with an i followed by the actual name (e.g.: isqrt), do integer operations, by first truncating their arguments to integers, if necessary.
isqrt
The returned types are noted as follows:
Any # any type of number Int # an integer value Rat # a rational value Float # a floating-point value Complex # a complex value NaN # "Not-a-Number" value Inf # +/-Infinity Bool # a Boolean value (1 or 0) Scalar # a Perl scalar
When two or more types are separated with pipe characters (|), it means that the corresponding function can return any of the specified types.
This section includes methods for creating new Math::AnyNum objects and some useful mathematical constants.
Math::AnyNum->new(n) #=> Any Math::AnyNum->new(n, base) #=> Any
Returns a new AnyNum 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", a string holding an integer, such as "255" or a string holding a complex number, such as "3+4i" or "(3 4)".
"1/2"
"0.5"
"255"
"3+4i"
"(3 4)"
my $z = Math::AnyNum->new('42'); # integer my $r = Math::AnyNum->new('3/4'); # rational my $f = Math::AnyNum->new('12.34'); # float my $c = Math::AnyNum->new('3+4i'); # complex
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 $n = Math::AnyNum->new("deadbeef", 16);
NOTE: no prefix, such as "0x" or "0b", is allowed as part of the number.
"0x"
"0b"
Math::AnyNum->new_si(n) #=> Int
Sets a signed native integer.
Example:
my $n = Math::AnyNum->new_si(-42);
Math::AnyNum->new_ui(n) #=> Int
Sets an unsigned native integer.
my $n = Math::AnyNum->new_ui(42);
Math::AnyNum->new_z(str) #=> Int Math::AnyNum->new_z(str, base) #=> Int
Sets an arbitrary large integer from a given string. When no base is specified, it defaults to base 10.
my $n = Math::AnyNum->new_z("12345678910111213141516"); my $m = Math::AnyNum->new_z("fffffffffffffffffff", 16);
Math::AnyNum->new_q(frac) #=> Rat Math::AnyNum->new_q(num, den) #=> Rat Math::AnyNum->new_q(num, den, base) #=> Rat
Sets an arbitrary large rational from a given string. When no base is specified, it defaults to base 10.
my $n = Math::AnyNum->new_q('12345/67890'); my $m = Math::AnyNum->new_q('12345', '67890'); my $o = Math::AnyNum->new_q('fffff', 'aaaaa', 16);
Math::AnyNum->new_f(str) #=> Float Math::AnyNum->new_f(str, base) #=> Float
Sets a floating-point real number from a given string. When no base is specified, it defaults to base 10.
my $n = Math::AnyNum->new_f('12.345'); my $m = Math::AnyNum->new_f('-1.2345e-12'); my $o = Math::AnyNum->new_f('ffffff', 16);
Math::AnyNum->new_c(real) #=> Complex Math::AnyNum->new_c(real, imag) #=> Complex Math::AnyNum->new_c(real, imag, base) #=> Complex
Sets a complex number from a given string. When no base is specified, it defaults to base 10.
my $n = Math::AnyNum->new_c('1.123'); my $m = Math::AnyNum->new_c('3', '4'); my $o = Math::AnyNum->new_c('f', 'a', 16);
Math::AnyNum->nan #=> NaN
Returns an object holding the NaN value.
Math::AnyNum->inf #=> Inf
Returns an object representing positive infinity.
Math::AnyNum->ninf #=> -Inf
Returns an object representing negative infinity.
Math::AnyNum->one #=> Int
Returns an object containing the value 1.
1
Math::AnyNum->mone #=> Int
Returns an object containing the value -1.
-1
Math::AnyNum->zero #=> Int
Returns an object containing the value 0.
0
Math::AnyNum->i #=> Complex
Returns the imaginary unit, which is sqrt(-1).
sqrt(-1)
Math::AnyNum->e #=> Float
Returns the e mathematical constant, which is 2.718....
2.718...
Math::AnyNum->pi #=> Float
Returns the number PI, which is 3.1415....
3.1415...
Math::AnyNum->tau #=> Float
Returns the number TAU, which is 2*pi.
2*pi
Math::AnyNum->ln2 #=> Float
Returns the natural logarithm of 2.
2
Math::AnyNum->phi #=> Float
Returns the value of the golden ratio, which is 1.61803....
1.61803...
Math::AnyNum->euler #=> Float
Returns the Euler-Mascheroni constant, which is 0.57721....
0.57721...
Math::AnyNum->catalan #=> Float
Returns the Catalan constant, also known as Beta(2) or G, and starts as: 0.91596....
Beta(2)
G
0.91596...
This section includes basic arithmetic operations.
x + y #=> Any
Adds x and y and returns the result.
x
y
x - y #=> Any
Subtracts y from x and returns the result.
x * y #=> Any
Multiplies x by y and returns the result.
x / y #=> Any
Divides x by y and returns the result.
x % y #=> Any mod(x, y) #=> Any
Remainder of x when is divided by y. Returns NaN when y is zero.
Implemented as:
x % y = x - y*floor(x/y)
polymod(n, a, b, c, ...) #=> (Any, Any, ..., Any)
Returns a list of mod results corresponding to the divisors in (a, b, c, ...). The divisors are given from smallest "unit" to the largest (e.g. 60 seconds per minute, 60 minutes per hour) and the results are returned in the same way: from smallest to the largest (5 seconds, 4 minutes).
(a, b, c, ...)
my ($s, $m, $h, $d) = polymod($seconds, 60, 60, 24);
conj(x) #=> Any
Complex conjugate of x. Return x when x is a real number.
conj("3+4i") = 3-4*i
inv(x) #=> Any
Multiplicative inverse of x. Equivalent with 1/x.
1/x
neg(x) #=> Any
Additive inverse of x. Equivalent with -x.
-x
abs(x) #=> Any
Absolute value of x.
sqr(x) #=> Any
Multiplies x with itself and returns the result. Equivalent with x*x.
x*x
norm(x) #=> Any
The square of the absolute value of x. Equivalent with abs(x)**2.
abs(x)**2
This section includes the special functions.
sqrt(x) #=> Any
Square root of x. Returns a complex number when x is negative.
cbrt(x) #=> Any
Cube root of x. Returns a complex number when x is negative.
root(x, y) #=> Any
The y root of x. Equivalent with x**(1/y).
x**(1/y)
polygonal_root(n, k) #=> Any
Returns the k-gonal root of n. Also defined for complex numbers.
n
say polygonal_root($n, 3); # triangular root say polygonal_root($n, 5); # pentagonal root
polygonal_root2(n, k) #=> Any
Returns the second k-gonal root of n. Also defined for complex numbers.
say polygonal_root2($n, 5); # second pentagonal root
x ** y #=> Any pow(x, y) #=> Any
Raises x to power y and returns the result.
When x and y are both integers, it does integer exponentiation and returns the exact result.
When x is rational and y is an integer, it does rational exponentiation based on the identity: (a/b)**n = a**n / b**n, which also computes the exact result.
(a/b)**n = a**n / b**n
Otherwise, it does floating-point exponentiation, which is equivalent with exp(log(x) * y).
exp(log(x) * y)
exp(x) #=> Any
Natural exponentiation of x (i.e.: e**x).
e**x
exp2(x) #=> Any
Raises 2 to the power x. (i.e.: 2**x)
2**x
exp10(x) #=> Any
Raises 10 to the power x. (i.e.: 10**x)
10**x
ln(x) #=> Any log(x) #=> Any log(x, y) #=> Any
Logarithm of x to base y (or base e when y is omitted).
NOTE: log(x, y) is equivalent with log(x) / log(y).
log(x, y)
log(x) / log(y)
log2(x) #=> Any log10(x) #=> Any
Logarithm of x to base 2 and base 10, respectively.
lgrt(x) #=> Any
Logarithmic-root of x, which is the solution to a**a = x, where x is known. When the value of x is less than e**(-1/e), it returns a complex number. It also accepts a complex number as input.
a**a = x
e**(-1/e)
lgrt(100) # solves for x in `x**x = 100` and returns: `3.59728...`
LambertW(x) #=> Any
The Lambert-W function. When the value of x is less than -1/e, it returns a complex number. It also accepts a complex number as input.
-1/e
exp(LambertW(log(100))) # solves for x in `x**x = 100` and returns: `3.59728...`
bernfrac(n) #=> Rat | NaN
Returns the nth-Bernoulli number B_n as an exact fraction, starting with bernfrac(0) = 1.
B_n
bernfrac(0) = 1
Algorithm due to Kevin J. McGown (December 8, 2005). Described in his paper: "Computing Bernoulli Numbers Quickly".
Returns NaN for negatives values of n.
bernreal(n) #=> Float | NaN
Returns the nth-Bernoulli number, as a floating-point approximation, with bernreal(0) = 1.
bernreal(0) = 1
harmfrac(n) #=> Rat | NaN
Returns the nth-Harmonic number H_n. The harmonic numbers are the sum of reciprocals of the first n natural numbers: 1 + 1/2 + 1/3 + ... + 1/n.
H_n
1 + 1/2 + 1/3 + ... + 1/n
For values greater than 7000, binary splitting (Fredrik Johansson's elegant formulation) is used.
harmreal(n) #=> Float | NaN
Returns the nth-Harmonic number, as a floating-point approximation, for any real value of n.
Returns NaN for negative integers.
Defined as:
harmreal(n) = digamma(n+1) + euler
where euler is the Euler-Mascheroni constant.
euler
agm(x, y) #=> Any
Arithmetic-geometric mean of x and y. Also defined for complex numbers.
hypot(x, y) #=> Any
The value of the hypotenuse for catheti x and y. Equivalent to sqrt(x**2 + y**2). Also defined for complex numbers.
sqrt(x**2 + y**2)
gamma(x) #=> Float | Inf | NaN
The Gamma function on x. Returns Inf when x is zero, and NaN when x is a negative integer.
lgamma(x) #=> Float | Inf | NaN
The logarithm of the absolute value of the Gamma function.
lngamma(x) #=> Float | Inf | NaN
The natural logarithm of the Gamma function on x.
digamma(x) #=> Float | Inf | NaN
The Digamma function (sometimes called Psi). Returns NaN when x is negative, and -Inf when x is 0.
beta(x, y) #=> Float | Inf | NaN
The beta function (also called the Euler integral of the first kind).
beta(x, y) = gamma(x)*gamma(y) / gamma(x+y)
zeta(x) #=> Float | Inf | NaN
The Riemann zeta function at x. Returns Inf when x is 1.
eta(x) #=> Float | Inf | NaN
The Dirichlet eta function at x.
eta(1) = ln(2) eta(x) = (1 - 2**(1-x)) * zeta(x)
BesselJ(x, n) #=> Float | NaN
The first order Bessel function, J_n(x), where n is a signed integer.
J_n(x)
BesselJ(x, n) # represents J_n(x)
BesselY(x, n) #=> Float | NaN
The second order Bessel function, Y_n(x), where n is a signed integer. Returns NaN for negative values of x.
Y_n(x)
BesselY(x, n) # represents Y_n(x)
erf(x) #=> Float
The error function on x.
erfc(x) #=> Float
Complementary error function on x.
Ai(x) #=> Float
The Airy function on x.
Ei(x) #=> Float | Inf | NaN
Exponential integral of x. Returns -Inf when x is zero, and NaN when x is negative.
Li(x) #=> Float | Inf | NaN
The logarithmic integral of x, defined as: Ei(ln(x)). Returns -Inf when x is 1, and NaN when x is less than or equal to 0.
Ei(ln(x))
Li2(x) #=> Float
The dilogarithm function, defined as the integral of -log(1-t)/t from 0 to x.
-log(1-t)/t
sin(x) #=> Any sinh(x) #=> Any asin(x) #=> Any asinh(x) #=> Any
Sine, hyperbolic sine, inverse sine and inverse hyperbolic sine.
cos(x) #=> Any cosh(x) #=> Any acos(x) #=> Any acosh(x) #=> Any
Cosine, hyperbolic cosine, inverse cosine and inverse hyperbolic cosine.
tan(x) #=> Any tanh(x) #=> Any atan(x) #=> Any atanh(x) #=> Any
Tangent, hyperbolic tangent, inverse tangent and inverse hyperbolic tangent.
cot(x) #=> Any coth(x) #=> Any acot(x) #=> Any acoth(x) #=> Any
Cotangent, hyperbolic cotangent, inverse cotangent and inverse hyperbolic cotangent.
sec(x) #=> Any sech(x) #=> Any asec(x) #=> Any asech(x) #=> Any
Secant, hyperbolic secant, inverse secant and inverse hyperbolic secant.
csc(x) #=> Any csch(x) #=> Any acsc(x) #=> Any acsch(x) #=> Any
Cosecant, hyperbolic cosecant, inverse cosecant and inverse hyperbolic cosecant.
atan2(x, y) #=> Any
The arc tangent of x and y, defined as:
atan2(x, y) = -i * log((y + x*i) / sqrt(x^2 + y^2))
deg2rad(x) #=> Any
Returns the value of x converted from degrees to radians.
deg2rad(180) = pi
rad2deg(x) #=> Any
Returns the value of x converted from radians to degrees.
rad2deg(pi) = 180
All operations in this section are done with integers.
iadd(x, y) #=> Int | NaN isub(x, y) #=> Int | NaN imul(x, y) #=> Int | NaN idiv(x, y) #=> Int | NaN ipow(x, y) #=> Int | NaN
Integer addition, subtraction, multiplication, division and exponentiation.
ipow2(n) #=> Int
Raises 2 to the power n, by first truncating n to an integer. Returns 0 when n is negative.
ipow10(n) #=> Int
Raises 10 to the power n, by first truncating n to an integer. Returns 0 when n is negative.
10
imod(x, y) #=> Int | NaN
The integer modulus operation. Returns NaN when y is zero.
divmod(x, y) #=> (Int, Int) | (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.
invmod(x, y) #=> Int | NaN
Computes the inverse of x modulo y and returns the result. When no inverse exists, the NaN value is returned.
powmod(x, y, z) #=> Int | NaN
Computes (x ** y) % z, where all three values are integers.
(x ** y) % z
Returns NaN when the third argument is 0, or when y is negative and gcd(x, z) != 1.
gcd(x, z) != 1
isqrt(n) #=> Int | NaN icbrt(n) #=> Int | NaN
The integer square root of n and the integer cube root of n. Returns NaN when a real root does not exists.
isqrtrem(n) #=> (Int, Int) | (NaN, NaN)
The integer part of the square root of n and the remainder n - isqrt(n)**2, which will be zero when n is a perfect square.
n - isqrt(n)**2
iroot(n, m) #=> Int | NaN
The integer m-th root of n. Returns NaN when a real does not exists.
m-th
irootrem(n, m) #=> (Int, Int) | (NaN, NaN)
The integer part of the root of n and the remainder n - iroot(n,m)**m.
n - iroot(n,m)**m
Returns (NaN,NaN) when a real root does not exists.
(NaN,NaN)
ilog(n) #=> Int | NaN ilog(n, m) #=> Int | NaN
The integer part of the logarithm of n to base m or base e when m is not specified.
m
n must be greater than 0 and m must greater than 1. Returns NaN otherwise.
ilog2(n) #=> Int | NaN ilog10(n) #=> Int | NaN
The integer part of the logarithm of n to base 2 or base 10, respectively.
x & y #=> Int x | y #=> Int x ^ y #=> Int ~x #=> Int x << y #=> Int x >> y #=> Int
The bitwise integer operations.
gcd(x, y) #=> Int
The greatest common divisor of x and y.
lcm(x, y) #=> Int
The least common multiple of x and y.
valuation(n, k) #=> Scalar
Returns the number of times n is divisible by k.
k
remdiv(n, k) #=> Int
Removes all occurrences of the divisor k from integer n.
In general, the following statement holds true:
remdiv(n, k) == n / k**(valuation(n, k))
kronecker(n, m) #=> Scalar
Returns the Kronecker symbol (n|m), which is a generalization of the Jacobi symbol for all integers m.
faulhaber_sum(n, k) #=> Int | NaN
Computes the sum 1**k + 2**k + 3**k +...+ n**k, using Faulhaber's formula.
1**k + 2**k + 3**k +...+ n**k
k must be a non-negative integer. Returns NaN otherwise.
faulhaber_sum(5, 8) = 1**8 + 2**8 + 3**8 + 4**8 + 5**8
lucas(n) #=> Int | NaN
The n-th Lucas number. Returns NaN when n is negative.
fibonacci(n) #=> Int | NaN
The n-th Fibonacci number. Returns NaN when n is negative.
factorial(n) #=> Int | NaN
Factorial of n (denoted as n!). Returns NaN when n is negative. (1*2*3*...*n)
n!
1*2*3*...*n
dfactorial(n) #=> Int | NaN
Double-factorial of n (denoted as n!!). Returns NaN when n is negative. (requires GMP>=5.1.0)
n!!
dfactorial(7) # 1*3*5*7 = 105 dfactorial(8) # 2*4*6*8 = 384
mfactorial(n, m) #=> Int | NaN
Generalized m-factorial of n. Returns NaN when n or m is negative. (requires GMP>=5.1.0)
subfactorial(n) #=> Int | NaN subfactorial(n, k) #=> Int | NaN
The number of permutations of {1, ..., n} that have exactly k fixed points, given a positive integer n and an optional integer k (if k is ommited, then k=0).
{1, ..., n}
k=0
See also:
https://en.wikipedia.org/wiki/Rencontres_numbers
binomial(n, k) #=> Int | NaN
Computes the binomial coefficient n over k, also called the "choose" function. The result is equivalent to:
n! binomial(n, k) = ------- k!(n-k)!
multinomial(a, b, c, ...) #=> Int | NaN
Computes the multinomial coefficient, given a list of native integers.
multinomial(1, 4, 4, 2) = 34650
https://en.wikipedia.org/wiki/Multinomial_theorem
rising_factorial(n, k) #=> Int | Rat | NaN
Rising factorial, n * (n + 1) * ... * (n + k - 1), defined as:
n * (n + 1) * ... * (n + k - 1)
binomial(n + k - 1, k) * k!
For negative values of k, rising factorial is defined as:
rising_factorial(n, -k) = 1/rising_factorial(n - k, k)
When the denominator is zero, NaN is returned.
falling_factorial(n, k) #=> Int | Rat | NaN
Falling factorial, n * (n - 1) * ... * (n - k + 1), defined as:
n * (n - 1) * ... * (n - k + 1)
binomial(n, k) * k!
For negative values of k, falling factorial is defined as:
falling_factorial(n, -k) = 1/falling_factorial(n + k, k)
primorial(n) #=> Int | NaN
Returns the product of all the primes less than or equal to n. (requires GMP>=5.1.0)
next_prime(n) #=> Int | NaN
Returns the next prime after n.
is_prime(n) #=> Scalar is_prime(n, r) #=> 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 20.
Reasonable accuracy values are between 15 and 50.
https://en.wikipedia.org/wiki/Miller–Rabin_primality_test
https://gmplib.org/manual/Number-Theoretic-Functions.html
is_coprime(n, k) #=> Bool
Returns a true value when n and k are relatively prime to each other. That is, when gcd(n, k) == 1.
gcd(n, k) == 1
is_smooth(n, k) #=> Bool
Returns a true value when all the prime factors of n are less than or equal to k, where n and k are positive integers.
is_smooth(36, 3) # true : 36 = 2^2 * 3^2 is_smooth(39, 6) # false : 39 = 3 * 13, where 13 > 6
is_power(n) is_power(n, k) #=> Bool
Return a true value when n is a perfect power of a given integer k.
When n is not an integer, it always returns false. On the other hand, when k is not an integer, it will implicitly be truncated to an integer. If k is not positive after truncation, 0 is returned.
A true value is returned iff there exists some integer a satisfying the equation: a**k = n.
a
a**k = n
When k is not specified, it returns true if n can be expressed as a**b for some integers a and b, with b greater than 1.
a**b
b
is_power(100, 2) # true: 100 is a square (10**2) is_power(125, 3) # true: 125 is a cube ( 5**3) is_power(279841) # true: 279841 is 23**4
is_square(n) #=> Bool
Returns a true value when n is a perfect square. When n is not an integer, a false value is returned.
polygonal(n, k) #=> Int
Returns the nth k-gonal number. When n is negative, it returns the second k-gonal number.
say join(' ', map { polygonal( $_, 3) } 1..10); # triangular numbers say join(' ', map { polygonal( $_, 5) } 1..10); # pentagonal numbers say join(' ', map { polygonal(-$_, 5) } 1..10); # second pentagonal numbers
ipolygonal_root(n, k) #=> Int | NaN
Integer k-gonal root of n. Returns NaN when a real root does not exists.
say ipolygonal_root($n, 5); # integer pentagonal root say ipolygonal_root(polygonal(10, 5), 5); # prints: "10"
ipolygonal_root2(n, k) #=> Int | NaN
Second integer k-gonal root of n. Returns NaN when a real root does not exists.
say ipolygonal_root2($n, 5); # second integer pentagonal root say ipolygonal_root2(polygonal(-10, 5), 5); # prints: "-10"
is_polygonal(n, k) #=> Bool
Returns a true value when n is a k-gonal number.
The values of n and k can be any arbitrary large integers.
say is_polygonal(145, 5); #=> 1 ("145" is a pentagonal number) say is_polygonal(155, 5); #=> 0
is_polygonal2(n, k) #=> Bool
Returns a true value when n is a second k-gonal number.
say is_polygonal2(145, 5); #=> 0 say is_polygonal2(155, 5); #=> 1 ("155" is a second-pentagonal number)
This section includes various useful methods.
floor(x) #=> Any
Returns x if x is an integer, otherwise it rounds x towards -Infinity.
floor( 2.5) = 2 floor(-2.5) = -3
ceil(x) #=> Any
Returns x if x is an integer, otherwise it rounds x towards +Infinity.
ceil( 2.5) = 3 ceil(-2.5) = -2
round(x) #=> Any round(x, p) #=> Any
Rounds x to the nth place. A negative argument rounds that many digits after the decimal point, while a positive argument rounds that many digits before the decimal point.
round('1234.567') = 1235 round('1234.567', 2) = 1200 round('3.123+4.567i', -2) = 3.12+4.57*i
rand(x) #=> Float rand(x, y) #=> Float
Returns a pseudorandom floating-point value. When an additional argument is provided, it returns a number between x (inclusive) and y (exclusive). Otherwise, returns a number between 0 (inclusive) and x (exclusive).
The PRNG behind this function is called the "Mersenne Twister". Although it generates pseudorandom numbers of very good quality, it is NOT cryptographically secure!
rand(10) # a random number in the interval [0, 10) rand(10, 20) # a random number in the interval [10, 20)
irand(x) #=> Int irand(x, y) #=> Int
Returns a pseudorandom integer. Unlike the rand() function, irand() is inclusive in both sides.
rand()
irand()
When an additional argument is provided, it returns an integer between x (inclusive) and y (inclusive), otherwise returns an integer between 0 (inclusive) and x (inclusive).
If x is greater that y, the returned result will be in the range [y, x].
[y, x]
The PRNG behind this function is called the "Mersenne Twister". Although it generates high-quality pseudorandom integers, it is NOT cryptographically secure!
irand(10) # a random integer in the interval [0, 10] irand(10, 20) # a random integer in the interval [10, 20]
seed(n) #=> Int iseed(n) #=> Int
Reseeds the rand() and the irand() function, respectively, with the value of n, which can be any arbitrary large integer.
Returns back the integer part of n. If n cannot be truncated to an integer, the method dies with an appropriate error message.
sgn(x) #=> Scalar | Complex
Returns -1 when x is negative, 1 when x is positive, and 0 when x is zero.
When x is a complex number, it computes the sign using the identity:
sgn(x) = x / abs(x)
$x->length #=> Scalar
Returns the number of digits in the integer part of x. Returns -1 when x cannot be truncated to an integer.
For -1234.56, it returns 4.
-1234.56
++$x #=> Any $x++ #=> Any
Returns x + 1.
x + 1
--$x #=> Any $x-- #=> Any
Return x - 1.
x - 1
$x->copy #=> Any
Returns a deep-copy of the self-object.
popcount(n) #=> Scalar
Returns the population count of the positive integer part of x, which is the number of 1 bits in its binary representation.
This value is also known as the Hamming weight.
is_int(x) #=> Bool
Returns a true value when x is an integer.
is_rat(x) #=> Bool
Returns a true value when x is a rational number.
is_real(x) #=> Bool
Returns a true value when x is a real number (i.e.: when the imaginary part is zero and it holds a real value in the real part).
is_real(complex('4')) # true is_real(complex('4i')) # false (is imaginary) is_real(complex('3+4i')) # false (is complex)
Returns a true value when x is an imaginary number (i.e.: when the real part is zero and it has a non-zero imaginary part).
is_imag(complex('4')) # false (is real) is_imag(complex('4i')) # true is_imag(complex('3+4i')) # false (is complex)
is_complex(x) #=> Bool
Returns a true value when x is a complex number (i.e.: when the real part and the imaginary part are non-zero).
is_complex(complex('4')) # false (is real) is_complex(complex('4i')) # false (is imaginary) is_complex(complex('3+4i')) # true
is_even(n) #=> Bool
Returns a true value when n is a real integer divisible by 2.
is_odd(n) #=> Bool
Returns a true value when n is a real integer not divisible by 2.
is_div(x, y) #=> Bool
Returns a true value when x is exactly divisible by y (i.e.: when the remainder x % y is zero).
x % y
This is a generalized version of the above two methods and it also works with complex numbers.
is_pos(x) #=> Bool
Returns a true value when x is positive.
is_neg(x) #=> Bool
Returns a true value when x is negative.
is_zero(n) #=> Bool
Returns a true value when n equals 0.
is_one(n) #=> Bool
Returns a true value when n equals 1.
is_mone(n) #=> Bool
Returns a true value when n equals -1.
is_inf(x) #=> Bool
Returns a true value when x holds the positive Infinity special value.
is_ninf(x) #=> Bool
Returns a true value when x holds the negative Infinity special value.
is_nan(x) #=> Bool
Returns a true value when x holds the Not-a-Number special value.
int(x) #=> Int | NaN
Returns the integer part of x. Returns NaN when x cannot be truncated to an integer.
rat(x) #=> Rat | NaN rat(str) #=> Rat | NaN
Converts x to a rational number. Returns NaN when this conversion is not possible.
When the given argument is a decimal expansion string, it will be specially parsed as an exact fraction.
If x is a floating-point number, consider using rat_approx() instead.
rat_approx()
rat('0.5') = 1/2 rat('1234/5678') = 617/2839
rat_approx(n) #=> Rat | NaN
Given a real number n, it returns a very good (sometimes exact) rational approximation to n, computed with continued fractions.
rat_approx(3.14) = 22/7 rat_approx(zeta(-5)) = -1/252
Return NaN when n is not a real number.
float(x) #=> Float | NaN float(str) #=> Float | NaN
Converts x to a floating-point real number.
float('3.14159') = 3.14159 float('777/222') = 3.5
complex(x) #=> Complex complex(str) #=> Complex complex(x, y) #=> Complex
Converts x to a complex number. When a second argument is given, it sets x as the real part and y as the imaginary part.
If x or y are complex numbers, the function returns the result of x + y*i.
x + y*i
complex("3+4i") = 3+4*i complex(3, 4) = 3+4*i complex("5+2i", "-4i") = 9+2*i
"$x" #=> Scalar
Returns a string representing the value of x, in base 10.
!!$x #=> Bool
Returns a false value when the number is zero. True otherwise.
$x->numify #=> Scalar
Returns a Perl numerical scalar containing the value of x, truncated if necessary.
If x is an integer that fits inside a native signed or unsigned integer, the returned result will be exact, otherwise the result is returned as a double, with possible truncation.
If x is a complex number, only the real part is considered.
as_bin(n) #=> Scalar
Returns a string representing the integer part of n in binary (base 2).
as_bin(42) = "101010"
as_oct(n) #=> Scalar
Returns a string representing the integer part of n in octal (base 8).
as_oct(42) = "52"
as_hex(n) #=> Scalar
Returns a string representing the integer part of n in hexadecimal (base 16).
as_hex(42) = "2a"
as_int(n) #=> Scalar as_int(n, b) #=> Scalar
Returns the integer part of n as a string, in a given base. When the base is omitted, it defaults to base 10.
as_int(255) = "255" as_int(255, 16) = "ff"
as_frac(n) #=> Scalar as_frac(n, b) #=> Scalar
Returns n as a fraction in a given base. When the base is omitted, it defaults to base 10.
as_frac(42) = "42/1" as_frac("1/2") = "1/2" as_frac(255, 16) = "ff/1"
as_dec(n) #=> Scalar as_dec(n, digits) #=> Scalar
Returns n as a decimal expansion string, with an optional number of digits. When the second argument is undefined, it uses the default precision.
The value of n can also be a complex number.
as_dec(1/2) = "0.5" as_dec(sqrt(2), 3) = "1.41"
numerator(x) #=> Int | NaN
Returns the numerator of x as a signed Math::AnyNum object. When x is not a rational number, it tries to convert it to a rational. Returns NaN when this conversion is not possible.
Math::AnyNum
numerator("-42") = -42 numerator("-3/4") = -3
denominator(x) #=> Int | NaN
Returns the denominator of x as an unsigned Math::AnyNum object. When x is not a rational number, it tries to convert it to a rational. Returns NaN when this conversion is not possible.
denominator("-42") = 1 denominator("-3/4") = 4
nude(x) #=> (Int | NaN, Int | NaN)
Returns the numerator and the denominator of x.
nude("42") = (42, 1) nude("-3/4") = (-3, 4)
real(x) #=> Any
Returns the real part of x.
real("42") = 42 real("42i") = 0 real("3-4i") = 3
imag(x) #=> Any
Returns the imaginary part of x, if any. Otherwise, returns zero.
imag("42") = 0 imag("42i") = 42 imag("3-4i") = -4
reals(x) #=> (Any, Any)
Return the real and the imaginary part of x as real numbers.
reals("42") = (42, 0) reals("42i") = (0, 42) reals("3-4i") = (3, -4)
digits(n) #=> (Scalar, Scalar, ...) digits(n, b) #=> (Scalar | Int, Scalar | Int, ...)
Returns a list with the digits of n in a given base. When no base is specified, it defaults to base 10.
Only the absolute integer part of n is considered.
The value of b must be greater than 1. Returns an empty list otherwise.
digits(12345) = (5, 4, 3, 2, 1) digits(12345, 100) = (45, 23, 1)
x == y #=> Bool
Equality check: returns a true value when x and y are equal.
x != y #=> Bool
Inequality check: returns a true value when x and y are not equal.
x > y #=> Bool
Returns a true value when x is greater than y.
x >= y #=> Bool
Returns a true value when x is equal or greater than y.
x < y #=> Bool
Returns a true value when x is less than y.
x <= y #=> Bool
Returns a true value when x is equal or less than y.
x <=> y #=> 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.
Complex numbers are compared as:
(real(x) <=> real(y)) || (imag(x) <=> imag(y))
Comparing anything to NaN (including NaN itself), returns undef.
undef
acmp(x, y)
Absolute comparison of x and y.
acmp(x, y) = abs(x) <=> abs(y)
The performance varies greatly, but, in most cases, Math::AnyNum is 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::AnyNum is fast because of the following facts:
minimal overhead in object creations and conversions.
minimal Perl code is executed per operation.
the GMP, MPFR and MPC libraries are extremely efficient.
To achieve the best performance, try to:
use the i* functions/methods wherever applicable.
use floating-point numbers when accuracy is not important.
pass Perl integers as arguments to methods, if you can.
This module came into existence as a response to Dana Jacobsen's request for a transparent interface to Math::GMPz and Math::MPFR, which 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.
The original project was called Math::BigNum, but because of some design flaws, it was very difficult to add support for complex numbers, therefore that project was abandoned and much of its code ended up in this module.
Daniel Șuteu, <trizen@protonmail.com>
<trizen@protonmail.com>
Please report any bugs or feature requests to https://github.com/trizen/Math-AnyNum/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Math::AnyNum
You can also look for information at:
GitHub
https://github.com/trizen/Math-AnyNum
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Math-AnyNum
CPAN Ratings
http://cpanratings.perl.org/d/Math-AnyNum
Search CPAN
http://search.cpan.org/dist/Math-AnyNum/
Fast math libraries
Math::GMP - High speed arbitrary size integer math.
Math::GMPz - perl interface to the GMP library's integer (mpz) functions.
Math::GMPq - perl interface to the GMP library's rational (mpq) functions.
Math::MPFR - perl interface to the MPFR (floating point) library.
Math::MPC - perl interface to the MPC (multi precision complex) library.
Portable math libraries
Math::BigInt - Arbitrary size integer/float math package.
Math::BigFloat - Arbitrary size floating point math package.
Math::BigRat - Arbitrary big rational numbers.
Math utilities
Math::Prime::Util - Utilities related to prime numbers, including fast sieves and factoring.
Copyright 2017-2018 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.
To install Math::AnyNum, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Math::AnyNum
CPAN shell
perl -MCPAN -e shell install Math::AnyNum
For more information on module installation, please visit the detailed CPAN module installation guide.