Math::AnyNum - Arbitrary size precision for integers, rationals, floating-points and complex numbers.
Version 0.06
Math::AnyNum provides a transparent and easy-to-use interface to Math::GMPq, Math::GMPz, 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 number is virtually transparent, without requiring any explicit conversions. All the needed conversions are done implicitly, using a sophisticated promotion system, that tries really hard to do the right thing and as efficiently as possible.
In addition, 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 conversion, Math::AnyNum provides the following methods:
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 sqrt cbrt root exp ln log log2 log10 mod abs erf erfc sqr norm hypot agm bernreal harmreal :ntheory factorial dfactorial mfactorial primorial binomial lucas fibonacci bernfrac harmfrac lcm gcd valuation kronecker remdiv divmod iadd isub imul idiv imod ipow iroot isqrt icbrt ilog ilog2 ilog10 isqrtrem irootrem powmod invmod is_power is_square is_prime next_prime :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
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.
This constants are:
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.
A rational number never losses 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 3+4i.
"1/2"
"0.5"
"255"
3+4i
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->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->euler #=> Float
Returns the Euler-Mascheroni constant, which is 0.57721....
0.57721...
Math::AnyNum->catalan #=> Float
Returns the value of Catalan's constant, also known as Beta(2) or G, and starts as: 0.91596....
0.91596...
Math::AnyNum->i #=> Float
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->phi #=> Float
Returns the value of the golden ratio, which is 1.61803....
1.61803...
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)
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) #=> Float | Inf | NaN
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 x is negative.
root(x, y) #=> Any
The y root of x. Equivalent with x**(1/y).
x**(1/y)
x ** y #=> Any pos(x, y) #=> Any
Raises x to power y and returns the result.
When both x and y are integers, it does integer exponentiation and returns the exact result.
When only 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
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 or base 10, respectively.
lgrt(x) #=> Any
Logarithmic-root of x, which is the largest solution to a**a = b, where b is known. When the value of x is less than e**(-1/e), it returns a complex number. It also accepts complex numbers as input.
a**a = b
b
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 complex numbers 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, computed with an optimized version of Seidel's algorithm, starting with bernfrac(0) = 1.
B_n
bernfrac(0) = 1
For n >= 50, a more efficient algorithm is used, based on zeta(n).
Returns NaN for negatives values of n.
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).
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. Returns Inf when x is negative or equal to zero.
lngamma(x) #=> Float | Inf
The natural logarithm of the Gamma function on x. Returns Inf when x is negative or equal to zero.
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 arctangent of the quotient of its arguments (i.e.: atan(x/y)).
atan(x/y)
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.
Integer addition, subtraction, multiplication, division and exponentiation.
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)
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
Calculates (x ** y) % z, where all three values are integers.
(x ** y) % z
Returns NaN when the third argument is 0.
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 the root is not real.
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 n is negative.
(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
Return NaN when n is negative.
ilog2(n) #=> Int | NaN ilog10(n) #=> Int | NaN
The integer part of the logarithm of n to base 2 or base 10, respectively.
10
x & y #=> Int x | y #=> Int x ^ y #=> Int ~x #=> Int x << y #=> Int x >> y #=> Int
The integer-logical 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 factor 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.
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. Returns NaN when n is negative. (1*2*3*...*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 is negative. (requires GMP>=5.1.0)
binomial(n, k) #=> Int
Calculates the binomial coefficient n over k, also called the "choose" function. The result is equivalent to:
( n ) n! | | = ------- ( k ) k!(n-k)!
primorial(n) #=> Int
Returns the product of all the primes less than or equal to n. (requires GMP>=5.1.0)
next_prime(n) #=> Int
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.
See also:
https://en.wikipedia.org/wiki/Miller–Rabin_primality_test
https://gmplib.org/manual/Number-Theoretic-Functions.html
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.
a**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.
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 range [0, 10) rand(10, 20) # a random number in the range [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 method is called the "Mersenne Twister". Although it generates high-quality pseudorandom integers, it is NOT cryptographically secure!
irand(10) # a random integer in the range [0, 10] irand(10, 20) # a random integer in the range [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)
length(x) #=> Scalar
Returns the number digits in the integer part of x. Returns -1 when x cannot be converted 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 it's not possible to truncate the number to an integer.
rat(x) #=> Rat | NaN rat(str) #=> Rat | NaN
Convert x to a rational number. Returns NaN when this conversion is not possible.
rat('0.5') = 1/2 rat('1234/5678') = 617/2839
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
Converts x to a complex number.
complex("3+4i") = 3+4*i
"$x" #=> Scalar
Returns a string representing the value of x, either as a base-10 integer, or a decimal expansion.
!!$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 needed.
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 value 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 in a given base as a string. 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 a string representing 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 a decimal expansion of the number n, as a string, with an optional number of digits. When the second argument is undefined, it uses the default precision.
Number 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 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 is not possible.
numerator("-42") = -42 numerator("-3/4") = -3
denominator(x) #=> Int | NaN
Returns the numerator 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 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(x) #=> (Scalar, Scalar, ...) digits(x, b) #=> (Scalar, Scalar, ...)
Returns a list with the digits of x in a given base. When no base is specified, it defaults to base 10.
Only the absolute integer part of x is considered.
digits(-1234.56) = (1,2,3,4) digits(4095, 16) = ('f','f','f')
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
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 follow this rules:
use the i* functions/methods wherever applicable.
use floating-point numbers when accuracy is not important.
pass Perl numbers 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 hard to add support for complex numbers, therefore the project was abandoned and much of its code ended up in this module.
Daniel Șuteu, <trizenx at gmail.com>
<trizenx at gmail.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 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.