diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Math::BigInt.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Math::BigInt.3pm | 2998 |
1 files changed, 2998 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Math::BigInt.3pm b/upstream/mageia-cauldron/man3pm/Math::BigInt.3pm new file mode 100644 index 00000000..8b5ad787 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Math::BigInt.3pm @@ -0,0 +1,2998 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Math::BigInt 3pm" +.TH Math::BigInt 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Math::BigInt \- arbitrary size integer math package +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Math::BigInt; +\& +\& # or make it faster with huge numbers: install (optional) +\& # Math::BigInt::GMP and always use (it falls back to +\& # pure Perl if the GMP library is not installed): +\& # (See also the L<MATH LIBRARY> section!) +\& +\& # to warn if Math::BigInt::GMP cannot be found, use +\& use Math::BigInt lib => \*(AqGMP\*(Aq; +\& +\& # to suppress the warning if Math::BigInt::GMP cannot be found, use +\& # use Math::BigInt try => \*(AqGMP\*(Aq; +\& +\& # to die if Math::BigInt::GMP cannot be found, use +\& # use Math::BigInt only => \*(AqGMP\*(Aq; +\& +\& # Configuration methods (may be used as class methods and instance methods) +\& +\& Math::BigInt\->accuracy(); # get class accuracy +\& Math::BigInt\->accuracy($n); # set class accuracy +\& Math::BigInt\->precision(); # get class precision +\& Math::BigInt\->precision($n); # set class precision +\& Math::BigInt\->round_mode(); # get class rounding mode +\& Math::BigInt\->round_mode($m); # set global round mode, must be one of +\& # \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, +\& # \*(Aqtrunc\*(Aq, or \*(Aqcommon\*(Aq +\& Math::BigInt\->config(); # return hash with configuration +\& +\& # Constructor methods (when the class methods below are used as instance +\& # methods, the value is assigned the invocand) +\& +\& $x = Math::BigInt\->new($str); # defaults to 0 +\& $x = Math::BigInt\->new(\*(Aq0x123\*(Aq); # from hexadecimal +\& $x = Math::BigInt\->new(\*(Aq0b101\*(Aq); # from binary +\& $x = Math::BigInt\->from_hex(\*(Aqcafe\*(Aq); # from hexadecimal +\& $x = Math::BigInt\->from_oct(\*(Aq377\*(Aq); # from octal +\& $x = Math::BigInt\->from_bin(\*(Aq1101\*(Aq); # from binary +\& $x = Math::BigInt\->from_base(\*(Aqwhy\*(Aq, 36); # from any base +\& $x = Math::BigInt\->from_base_num([1, 0], 2); # from any base +\& $x = Math::BigInt\->bzero(); # create a +0 +\& $x = Math::BigInt\->bone(); # create a +1 +\& $x = Math::BigInt\->bone(\*(Aq\-\*(Aq); # create a \-1 +\& $x = Math::BigInt\->binf(); # create a +inf +\& $x = Math::BigInt\->binf(\*(Aq\-\*(Aq); # create a \-inf +\& $x = Math::BigInt\->bnan(); # create a Not\-A\-Number +\& $x = Math::BigInt\->bpi(); # returns pi +\& +\& $y = $x\->copy(); # make a copy (unlike $y = $x) +\& $y = $x\->as_int(); # return as a Math::BigInt +\& $y = $x\->as_float(); # return as a Math::BigFloat +\& $y = $x\->as_rat(); # return as a Math::BigRat +\& +\& # Boolean methods (these don\*(Aqt modify the invocand) +\& +\& $x\->is_zero(); # if $x is 0 +\& $x\->is_one(); # if $x is +1 +\& $x\->is_one("+"); # ditto +\& $x\->is_one("\-"); # if $x is \-1 +\& $x\->is_inf(); # if $x is +inf or \-inf +\& $x\->is_inf("+"); # if $x is +inf +\& $x\->is_inf("\-"); # if $x is \-inf +\& $x\->is_nan(); # if $x is NaN +\& +\& $x\->is_positive(); # if $x > 0 +\& $x\->is_pos(); # ditto +\& $x\->is_negative(); # if $x < 0 +\& $x\->is_neg(); # ditto +\& +\& $x\->is_odd(); # if $x is odd +\& $x\->is_even(); # if $x is even +\& $x\->is_int(); # if $x is an integer +\& +\& # Comparison methods +\& +\& $x\->bcmp($y); # compare numbers (undef, < 0, == 0, > 0) +\& $x\->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0) +\& $x\->beq($y); # true if and only if $x == $y +\& $x\->bne($y); # true if and only if $x != $y +\& $x\->blt($y); # true if and only if $x < $y +\& $x\->ble($y); # true if and only if $x <= $y +\& $x\->bgt($y); # true if and only if $x > $y +\& $x\->bge($y); # true if and only if $x >= $y +\& +\& # Arithmetic methods +\& +\& $x\->bneg(); # negation +\& $x\->babs(); # absolute value +\& $x\->bsgn(); # sign function (\-1, 0, 1, or NaN) +\& $x\->bnorm(); # normalize (no\-op) +\& $x\->binc(); # increment $x by 1 +\& $x\->bdec(); # decrement $x by 1 +\& $x\->badd($y); # addition (add $y to $x) +\& $x\->bsub($y); # subtraction (subtract $y from $x) +\& $x\->bmul($y); # multiplication (multiply $x by $y) +\& $x\->bmuladd($y,$z); # $x = $x * $y + $z +\& $x\->bdiv($y); # division (floored), set $x to quotient +\& # return (quo,rem) or quo if scalar +\& $x\->btdiv($y); # division (truncated), set $x to quotient +\& # return (quo,rem) or quo if scalar +\& $x\->bmod($y); # modulus (x % y) +\& $x\->btmod($y); # modulus (truncated) +\& $x\->bmodinv($mod); # modular multiplicative inverse +\& $x\->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod) +\& $x\->bpow($y); # power of arguments (x ** y) +\& $x\->blog(); # logarithm of $x to base e (Euler\*(Aqs number) +\& $x\->blog($base); # logarithm of $x to base $base (e.g., base 2) +\& $x\->bexp(); # calculate e ** $x where e is Euler\*(Aqs number +\& $x\->bnok($y); # x over y (binomial coefficient n over k) +\& $x\->buparrow($n, $y); # Knuth\*(Aqs up\-arrow notation +\& $x\->backermann($y); # the Ackermann function +\& $x\->bsin(); # sine +\& $x\->bcos(); # cosine +\& $x\->batan(); # inverse tangent +\& $x\->batan2($y); # two\-argument inverse tangent +\& $x\->bsqrt(); # calculate square root +\& $x\->broot($y); # $y\*(Aqth root of $x (e.g. $y == 3 => cubic root) +\& $x\->bfac(); # factorial of $x (1*2*3*4*..$x) +\& $x\->bdfac(); # double factorial of $x ($x*($x\-2)*($x\-4)*...) +\& $x\->btfac(); # triple factorial of $x ($x*($x\-3)*($x\-6)*...) +\& $x\->bmfac($k); # $k\*(Aqth multi\-factorial of $x ($x*($x\-$k)*...) +\& +\& $x\->blsft($n); # left shift $n places in base 2 +\& $x\->blsft($n,$b); # left shift $n places in base $b +\& # returns (quo,rem) or quo (scalar context) +\& $x\->brsft($n); # right shift $n places in base 2 +\& $x\->brsft($n,$b); # right shift $n places in base $b +\& # returns (quo,rem) or quo (scalar context) +\& +\& # Bitwise methods +\& +\& $x\->band($y); # bitwise and +\& $x\->bior($y); # bitwise inclusive or +\& $x\->bxor($y); # bitwise exclusive or +\& $x\->bnot(); # bitwise not (two\*(Aqs complement) +\& +\& # Rounding methods +\& $x\->round($A,$P,$mode); # round to accuracy or precision using +\& # rounding mode $mode +\& $x\->bround($n); # accuracy: preserve $n digits +\& $x\->bfround($n); # $n > 0: round to $nth digit left of dec. point +\& # $n < 0: round to $nth digit right of dec. point +\& $x\->bfloor(); # round towards minus infinity +\& $x\->bceil(); # round towards plus infinity +\& $x\->bint(); # round towards zero +\& +\& # Other mathematical methods +\& +\& $x\->bgcd($y); # greatest common divisor +\& $x\->blcm($y); # least common multiple +\& +\& # Object property methods (do not modify the invocand) +\& +\& $x\->sign(); # the sign, either +, \- or NaN +\& $x\->digit($n); # the nth digit, counting from the right +\& $x\->digit(\-$n); # the nth digit, counting from the left +\& $x\->length(); # return number of digits in number +\& ($xl,$f) = $x\->length(); # length of number and length of fraction +\& # part, latter is always 0 digits long +\& # for Math::BigInt objects +\& $x\->mantissa(); # return (signed) mantissa as a Math::BigInt +\& $x\->exponent(); # return exponent as a Math::BigInt +\& $x\->parts(); # return (mantissa,exponent) as a Math::BigInt +\& $x\->sparts(); # mantissa and exponent (as integers) +\& $x\->nparts(); # mantissa and exponent (normalised) +\& $x\->eparts(); # mantissa and exponent (engineering notation) +\& $x\->dparts(); # integer and fraction part +\& $x\->fparts(); # numerator and denominator +\& $x\->numerator(); # numerator +\& $x\->denominator(); # denominator +\& +\& # Conversion methods (do not modify the invocand) +\& +\& $x\->bstr(); # decimal notation, possibly zero padded +\& $x\->bsstr(); # string in scientific notation with integers +\& $x\->bnstr(); # string in normalized notation +\& $x\->bestr(); # string in engineering notation +\& $x\->bfstr(); # string in fractional notation +\& +\& $x\->to_hex(); # as signed hexadecimal string +\& $x\->to_bin(); # as signed binary string +\& $x\->to_oct(); # as signed octal string +\& $x\->to_bytes(); # as byte string +\& $x\->to_base($b); # as string in any base +\& $x\->to_base_num($b); # as array of integers in any base +\& +\& $x\->as_hex(); # as signed hexadecimal string with prefixed 0x +\& $x\->as_bin(); # as signed binary string with prefixed 0b +\& $x\->as_oct(); # as signed octal string with prefixed 0 +\& +\& # Other conversion methods +\& +\& $x\->numify(); # return as scalar (might overflow or underflow) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Math::BigInt provides support for arbitrary precision integers. Overloading is +also provided for Perl operators. +.SS Input +.IX Subsection "Input" +Input values to these routines may be any scalar number or string that looks +like a number and represents an integer. Anything that is accepted by Perl as a +literal numeric constant should be accepted by this module, except that finite +non-integers return NaN. +.IP \(bu 4 +Leading and trailing whitespace is ignored. +.IP \(bu 4 +Leading zeros are ignored, except for floating point numbers with a binary +exponent, in which case the number is interpreted as an octal floating point +number. For example, "01.4p+0" gives 1.5, "00.4p+0" gives 0.5, but "0.4p+0" +gives a NaN. And while "0377" gives 255, "0377p0" gives 255. +.IP \(bu 4 +If the string has a "0x" or "0X" prefix, it is interpreted as a hexadecimal +number. +.IP \(bu 4 +If the string has a "0o" or "0O" prefix, it is interpreted as an octal number. A +floating point literal with a "0" prefix is also interpreted as an octal number. +.IP \(bu 4 +If the string has a "0b" or "0B" prefix, it is interpreted as a binary number. +.IP \(bu 4 +Underline characters are allowed in the same way as they are allowed in literal +numerical constants. +.IP \(bu 4 +If the string can not be interpreted, or does not represent a finite integer, +NaN is returned. +.IP \(bu 4 +For hexadecimal, octal, and binary floating point numbers, the exponent must be +separated from the significand (mantissa) by the letter "p" or "P", not "e" or +"E" as with decimal numbers. +.PP +Some examples of valid string input +.PP +.Vb 1 +\& Input string Resulting value +\& +\& 123 123 +\& 1.23e2 123 +\& 12300e\-2 123 +\& +\& 67_538_754 67538754 +\& \-4_5_6.7_8_9e+0_1_0 \-4567890000000 +\& +\& 0x13a 314 +\& 0x13ap0 314 +\& 0x1.3ap+8 314 +\& 0x0.00013ap+24 314 +\& 0x13a000p\-12 314 +\& +\& 0o472 314 +\& 0o1.164p+8 314 +\& 0o0.0001164p+20 314 +\& 0o1164000p\-10 314 +\& +\& 0472 472 Note! +\& 01.164p+8 314 +\& 00.0001164p+20 314 +\& 01164000p\-10 314 +\& +\& 0b100111010 314 +\& 0b1.0011101p+8 314 +\& 0b0.00010011101p+12 314 +\& 0b100111010000p\-3 314 +.Ve +.PP +Input given as scalar numbers might lose precision. Quote your input to ensure +that no digits are lost: +.PP +.Vb 2 +\& $x = Math::BigInt\->new( 56789012345678901234 ); # bad +\& $x = Math::BigInt\->new(\*(Aq56789012345678901234\*(Aq); # good +.Ve +.PP +Currently, \f(CW\*(C`Math::BigInt\-\*(C'\fR\fBnew()\fR> (no input argument) and +\&\f(CW\*(C`Math::BigInt\-\*(C'\fRnew("")> return 0. This might change in the future, so always +use the following explicit forms to get a zero: +.PP +.Vb 1 +\& $zero = Math::BigInt\->bzero(); +.Ve +.SS Output +.IX Subsection "Output" +Output values are usually Math::BigInt objects. +.PP +Boolean operators \f(CWis_zero()\fR, \f(CWis_one()\fR, \f(CWis_inf()\fR, etc. return true or +false. +.PP +Comparison operators \f(CWbcmp()\fR and \f(CWbacmp()\fR) return \-1, 0, 1, or +undef. +.SH METHODS +.IX Header "METHODS" +.SS "Configuration methods" +.IX Subsection "Configuration methods" +Each of the methods below (except \fBconfig()\fR, \fBaccuracy()\fR and \fBprecision()\fR) accepts +three additional parameters. These arguments \f(CW$A\fR, \f(CW$P\fR and \f(CW$R\fR are +\&\f(CW\*(C`accuracy\*(C'\fR, \f(CW\*(C`precision\*(C'\fR and \f(CW\*(C`round_mode\*(C'\fR. Please see the section about +"ACCURACY and PRECISION" for more information. +.PP +Setting a class variable effects all object instance that are created +afterwards. +.IP \fBaccuracy()\fR 4 +.IX Item "accuracy()" +.Vb 2 +\& Math::BigInt\->accuracy(5); # set class accuracy +\& $x\->accuracy(5); # set instance accuracy +\& +\& $A = Math::BigInt\->accuracy(); # get class accuracy +\& $A = $x\->accuracy(); # get instance accuracy +.Ve +.Sp +Set or get the accuracy, i.e., the number of significant digits. The accuracy +must be an integer. If the accuracy is set to \f(CW\*(C`undef\*(C'\fR, no rounding is done. +.Sp +Alternatively, one can round the results explicitly using one of "\fBround()\fR", +"\fBbround()\fR" or "\fBbfround()\fR" or by passing the desired accuracy to the method +as an additional parameter: +.Sp +.Vb 4 +\& my $x = Math::BigInt\->new(30000); +\& my $y = Math::BigInt\->new(7); +\& print scalar $x\->copy()\->bdiv($y, 2); # prints 4300 +\& print scalar $x\->copy()\->bdiv($y)\->bround(2); # prints 4300 +.Ve +.Sp +Please see the section about "ACCURACY and PRECISION" for further details. +.Sp +.Vb 4 +\& $y = Math::BigInt\->new(1234567); # $y is not rounded +\& Math::BigInt\->accuracy(4); # set class accuracy to 4 +\& $x = Math::BigInt\->new(1234567); # $x is rounded automatically +\& print "$x $y"; # prints "1235000 1234567" +\& +\& print $x\->accuracy(); # prints "4" +\& print $y\->accuracy(); # also prints "4", since +\& # class accuracy is 4 +\& +\& Math::BigInt\->accuracy(5); # set class accuracy to 5 +\& print $x\->accuracy(); # prints "4", since instance +\& # accuracy is 4 +\& print $y\->accuracy(); # prints "5", since no instance +\& # accuracy, and class accuracy is 5 +.Ve +.Sp +Note: Each class has it's own globals separated from Math::BigInt, but it is +possible to subclass Math::BigInt and make the globals of the subclass aliases +to the ones from Math::BigInt. +.IP \fBprecision()\fR 4 +.IX Item "precision()" +.Vb 2 +\& Math::BigInt\->precision(\-2); # set class precision +\& $x\->precision(\-2); # set instance precision +\& +\& $P = Math::BigInt\->precision(); # get class precision +\& $P = $x\->precision(); # get instance precision +.Ve +.Sp +Set or get the precision, i.e., the place to round relative to the decimal +point. The precision must be a integer. Setting the precision to \f(CW$P\fR means that +each number is rounded up or down, depending on the rounding mode, to the +nearest multiple of 10**$P. If the precision is set to \f(CW\*(C`undef\*(C'\fR, no rounding is +done. +.Sp +You might want to use "\fBaccuracy()\fR" instead. With "\fBaccuracy()\fR" you set the +number of digits each result should have, with "\fBprecision()\fR" you set the +place where to round. +.Sp +Please see the section about "ACCURACY and PRECISION" for further details. +.Sp +.Vb 4 +\& $y = Math::BigInt\->new(1234567); # $y is not rounded +\& Math::BigInt\->precision(4); # set class precision to 4 +\& $x = Math::BigInt\->new(1234567); # $x is rounded automatically +\& print $x; # prints "1230000" +.Ve +.Sp +Note: Each class has its own globals separated from Math::BigInt, but it is +possible to subclass Math::BigInt and make the globals of the subclass aliases +to the ones from Math::BigInt. +.IP \fBdiv_scale()\fR 4 +.IX Item "div_scale()" +Set/get the fallback accuracy. This is the accuracy used when neither accuracy +nor precision is set explicitly. It is used when a computation might otherwise +attempt to return an infinite number of digits. +.IP \fBround_mode()\fR 4 +.IX Item "round_mode()" +Set/get the rounding mode. +.IP \fBupgrade()\fR 4 +.IX Item "upgrade()" +Set/get the class for upgrading. When a computation might result in a +non-integer, the operands are upgraded to this class. This is used for instance +by bignum. The default is \f(CW\*(C`undef\*(C'\fR, i.e., no upgrading. +.Sp +.Vb 4 +\& # with no upgrading +\& $x = Math::BigInt\->new(12); +\& $y = Math::BigInt\->new(5); +\& print $x / $y, "\en"; # 2 as a Math::BigInt +\& +\& # with upgrading to Math::BigFloat +\& Math::BigInt \-> upgrade("Math::BigFloat"); +\& print $x / $y, "\en"; # 2.4 as a Math::BigFloat +\& +\& # with upgrading to Math::BigRat (after loading Math::BigRat) +\& Math::BigInt \-> upgrade("Math::BigRat"); +\& print $x / $y, "\en"; # 12/5 as a Math::BigRat +.Ve +.IP \fBdowngrade()\fR 4 +.IX Item "downgrade()" +Set/get the class for downgrading. The default is \f(CW\*(C`undef\*(C'\fR, i.e., no +downgrading. Downgrading is not done by Math::BigInt. +.IP \fBmodify()\fR 4 +.IX Item "modify()" +.Vb 1 +\& $x\->modify(\*(Aqbpowd\*(Aq); +.Ve +.Sp +This method returns 0 if the object can be modified with the given operation, +or 1 if not. +.Sp +This is used for instance by Math::BigInt::Constant. +.IP \fBconfig()\fR 4 +.IX Item "config()" +.Vb 2 +\& Math::BigInt\->config("trap_nan" => 1); # set +\& $accu = Math::BigInt\->config("accuracy"); # get +.Ve +.Sp +Set or get class variables. Read-only parameters are marked as RO. Read-write +parameters are marked as RW. The following parameters are supported. +.Sp +.Vb 10 +\& Parameter RO/RW Description +\& Example +\& ============================================================ +\& lib RO Name of the math backend library +\& Math::BigInt::Calc +\& lib_version RO Version of the math backend library +\& 0.30 +\& class RO The class of config you just called +\& Math::BigRat +\& version RO version number of the class you used +\& 0.10 +\& upgrade RW To which class numbers are upgraded +\& undef +\& downgrade RW To which class numbers are downgraded +\& undef +\& precision RW Global precision +\& undef +\& accuracy RW Global accuracy +\& undef +\& round_mode RW Global round mode +\& even +\& div_scale RW Fallback accuracy for division etc. +\& 40 +\& trap_nan RW Trap NaNs +\& undef +\& trap_inf RW Trap +inf/\-inf +\& undef +.Ve +.SS "Constructor methods" +.IX Subsection "Constructor methods" +.IP \fBnew()\fR 4 +.IX Item "new()" +.Vb 1 +\& $x = Math::BigInt\->new($str,$A,$P,$R); +.Ve +.Sp +Creates a new Math::BigInt object from a scalar or another Math::BigInt object. +The input is accepted as decimal, hexadecimal (with leading '0x'), octal (with +leading ('0o') or binary (with leading '0b'). +.Sp +See "Input" for more info on accepted input formats. +.IP \fBfrom_dec()\fR 4 +.IX Item "from_dec()" +.Vb 1 +\& $x = Math::BigInt\->from_dec("314159"); # input is decimal +.Ve +.Sp +Interpret input as a decimal. It is equivalent to \fBnew()\fR, but does not accept +anything but strings representing finite, decimal numbers. +.IP \fBfrom_hex()\fR 4 +.IX Item "from_hex()" +.Vb 1 +\& $x = Math::BigInt\->from_hex("0xcafe"); # input is hexadecimal +.Ve +.Sp +Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A +single underscore character may be placed right after the prefix, if present, +or between any two digits. If the input is invalid, a NaN is returned. +.IP \fBfrom_oct()\fR 4 +.IX Item "from_oct()" +.Vb 1 +\& $x = Math::BigInt\->from_oct("0775"); # input is octal +.Ve +.Sp +Interpret the input as an octal string and return the corresponding value. A +"0" (zero) prefix is optional. A single underscore character may be placed +right after the prefix, if present, or between any two digits. If the input is +invalid, a NaN is returned. +.IP \fBfrom_bin()\fR 4 +.IX Item "from_bin()" +.Vb 1 +\& $x = Math::BigInt\->from_bin("0b10011"); # input is binary +.Ve +.Sp +Interpret the input as a binary string. A "0b" or "b" prefix is optional. A +single underscore character may be placed right after the prefix, if present, +or between any two digits. If the input is invalid, a NaN is returned. +.IP \fBfrom_bytes()\fR 4 +.IX Item "from_bytes()" +.Vb 1 +\& $x = Math::BigInt\->from_bytes("\exf3\ex6b"); # $x = 62315 +.Ve +.Sp +Interpret the input as a byte string, assuming big endian byte order. The +output is always a non-negative, finite integer. +.Sp +In some special cases, \fBfrom_bytes()\fR matches the conversion done by \fBunpack()\fR: +.Sp +.Vb 3 +\& $b = "\ex4e"; # one char byte string +\& $x = Math::BigInt\->from_bytes($b); # = 78 +\& $y = unpack "C", $b; # ditto, but scalar +\& +\& $b = "\exf3\ex6b"; # two char byte string +\& $x = Math::BigInt\->from_bytes($b); # = 62315 +\& $y = unpack "S>", $b; # ditto, but scalar +\& +\& $b = "\ex2d\exe0\ex49\exad"; # four char byte string +\& $x = Math::BigInt\->from_bytes($b); # = 769673645 +\& $y = unpack "L>", $b; # ditto, but scalar +\& +\& $b = "\ex2d\exe0\ex49\exad\ex2d\exe0\ex49\exad"; # eight char byte string +\& $x = Math::BigInt\->from_bytes($b); # = 3305723134637787565 +\& $y = unpack "Q>", $b; # ditto, but scalar +.Ve +.IP \fBfrom_base()\fR 4 +.IX Item "from_base()" +Given a string, a base, and an optional collation sequence, interpret the +string as a number in the given base. The collation sequence describes the +value of each character in the string. +.Sp +If a collation sequence is not given, a default collation sequence is used. If +the base is less than or equal to 36, the collation sequence is the string +consisting of the 36 characters "0" to "9" and "A" to "Z". In this case, the +letter case in the input is ignored. If the base is greater than 36, and +smaller than or equal to 62, the collation sequence is the string consisting of +the 62 characters "0" to "9", "A" to "Z", and "a" to "z". A base larger than 62 +requires the collation sequence to be specified explicitly. +.Sp +These examples show standard binary, octal, and hexadecimal conversion. All +cases return 250. +.Sp +.Vb 3 +\& $x = Math::BigInt\->from_base("11111010", 2); +\& $x = Math::BigInt\->from_base("372", 8); +\& $x = Math::BigInt\->from_base("fa", 16); +.Ve +.Sp +When the base is less than or equal to 36, and no collation sequence is given, +the letter case is ignored, so both of these also return 250: +.Sp +.Vb 2 +\& $x = Math::BigInt\->from_base("6Y", 16); +\& $x = Math::BigInt\->from_base("6y", 16); +.Ve +.Sp +When the base greater than 36, and no collation sequence is given, the default +collation sequence contains both uppercase and lowercase letters, so +the letter case in the input is not ignored: +.Sp +.Vb 5 +\& $x = Math::BigInt\->from_base("6S", 37); # $x is 250 +\& $x = Math::BigInt\->from_base("6s", 37); # $x is 276 +\& $x = Math::BigInt\->from_base("121", 3); # $x is 16 +\& $x = Math::BigInt\->from_base("XYZ", 36); # $x is 44027 +\& $x = Math::BigInt\->from_base("Why", 42); # $x is 58314 +.Ve +.Sp +The collation sequence can be any set of unique characters. These two cases +are equivalent +.Sp +.Vb 2 +\& $x = Math::BigInt\->from_base("100", 2, "01"); # $x is 4 +\& $x = Math::BigInt\->from_base("|\-\-", 2, "\-|"); # $x is 4 +.Ve +.IP \fBfrom_base_num()\fR 4 +.IX Item "from_base_num()" +Returns a new Math::BigInt object given an array of values and a base. This +method is equivalent to \f(CWfrom_base()\fR, but works on numbers in an array rather +than characters in a string. Unlike \f(CWfrom_base()\fR, all input values may be +arbitrarily large. +.Sp +.Vb 2 +\& $x = Math::BigInt\->from_base_num([1, 1, 0, 1], 2) # $x is 13 +\& $x = Math::BigInt\->from_base_num([3, 125, 39], 128) # $x is 65191 +.Ve +.IP \fBbzero()\fR 4 +.IX Item "bzero()" +.Vb 2 +\& $x = Math::BigInt\->bzero(); +\& $x\->bzero(); +.Ve +.Sp +Returns a new Math::BigInt object representing zero. If used as an instance +method, assigns the value to the invocand. +.IP \fBbone()\fR 4 +.IX Item "bone()" +.Vb 6 +\& $x = Math::BigInt\->bone(); # +1 +\& $x = Math::BigInt\->bone("+"); # +1 +\& $x = Math::BigInt\->bone("\-"); # \-1 +\& $x\->bone(); # +1 +\& $x\->bone("+"); # +1 +\& $x\->bone(\*(Aq\-\*(Aq); # \-1 +.Ve +.Sp +Creates a new Math::BigInt object representing one. The optional argument is +either '\-' or '+', indicating whether you want plus one or minus one. If used +as an instance method, assigns the value to the invocand. +.IP \fBbinf()\fR 4 +.IX Item "binf()" +.Vb 1 +\& $x = Math::BigInt\->binf($sign); +.Ve +.Sp +Creates a new Math::BigInt object representing infinity. The optional argument +is either '\-' or '+', indicating whether you want infinity or minus infinity. +If used as an instance method, assigns the value to the invocand. +.Sp +.Vb 2 +\& $x\->binf(); +\& $x\->binf(\*(Aq\-\*(Aq); +.Ve +.IP \fBbnan()\fR 4 +.IX Item "bnan()" +.Vb 1 +\& $x = Math::BigInt\->bnan(); +.Ve +.Sp +Creates a new Math::BigInt object representing NaN (Not A Number). If used as +an instance method, assigns the value to the invocand. +.Sp +.Vb 1 +\& $x\->bnan(); +.Ve +.IP \fBbpi()\fR 4 +.IX Item "bpi()" +.Vb 2 +\& $x = Math::BigInt\->bpi(100); # 3 +\& $x\->bpi(100); # 3 +.Ve +.Sp +Creates a new Math::BigInt object representing PI. If used as an instance +method, assigns the value to the invocand. With Math::BigInt this always +returns 3. +.Sp +If upgrading is in effect, returns PI, rounded to N digits with the current +rounding mode: +.Sp +.Vb 4 +\& use Math::BigFloat; +\& use Math::BigInt upgrade => "Math::BigFloat"; +\& print Math::BigInt\->bpi(3), "\en"; # 3.14 +\& print Math::BigInt\->bpi(100), "\en"; # 3.1415.... +.Ve +.IP \fBcopy()\fR 4 +.IX Item "copy()" +.Vb 1 +\& $x\->copy(); # make a true copy of $x (unlike $y = $x) +.Ve +.IP \fBas_int()\fR 4 +.IX Item "as_int()" +.PD 0 +.IP \fBas_number()\fR 4 +.IX Item "as_number()" +.PD +These methods are called when Math::BigInt encounters an object it doesn't know +how to handle. For instance, assume \f(CW$x\fR is a Math::BigInt, or subclass thereof, +and \f(CW$y\fR is defined, but not a Math::BigInt, or subclass thereof. If you do +.Sp +.Vb 1 +\& $x \-> badd($y); +.Ve +.Sp +\&\f(CW$y\fR needs to be converted into an object that \f(CW$x\fR can deal with. This is done by +first checking if \f(CW$y\fR is something that \f(CW$x\fR might be upgraded to. If that is the +case, no further attempts are made. The next is to see if \f(CW$y\fR supports the +method \f(CWas_int()\fR. If it does, \f(CWas_int()\fR is called, but if it doesn't, the +next thing is to see if \f(CW$y\fR supports the method \f(CWas_number()\fR. If it does, +\&\f(CWas_number()\fR is called. The method \f(CWas_int()\fR (and \f(CWas_number()\fR) is +expected to return either an object that has the same class as \f(CW$x\fR, a subclass +thereof, or a string that \f(CW\*(C`ref($x)\->new()\*(C'\fR can parse to create an object. +.Sp +\&\f(CWas_number()\fR is an alias to \f(CWas_int()\fR. \f(CW\*(C`as_number\*(C'\fR was introduced in +v1.22, while \f(CWas_int()\fR was introduced in v1.68. +.Sp +In Math::BigInt, \f(CWas_int()\fR has the same effect as \f(CWcopy()\fR. +.IP \fBas_float()\fR 4 +.IX Item "as_float()" +Return the argument as a Math::BigFloat object. +.IP \fBas_rat()\fR 4 +.IX Item "as_rat()" +Return the argument as a Math::BigRat object. +.SS "Boolean methods" +.IX Subsection "Boolean methods" +None of these methods modify the invocand object. +.IP \fBis_zero()\fR 4 +.IX Item "is_zero()" +.Vb 1 +\& $x\->is_zero(); # true if $x is 0 +.Ve +.Sp +Returns true if the invocand is zero and false otherwise. +.IP "is_one( [ SIGN ])" 4 +.IX Item "is_one( [ SIGN ])" +.Vb 3 +\& $x\->is_one(); # true if $x is +1 +\& $x\->is_one("+"); # ditto +\& $x\->is_one("\-"); # true if $x is \-1 +.Ve +.Sp +Returns true if the invocand is one and false otherwise. +.IP \fBis_finite()\fR 4 +.IX Item "is_finite()" +.Vb 1 +\& $x\->is_finite(); # true if $x is not +inf, \-inf or NaN +.Ve +.Sp +Returns true if the invocand is a finite number, i.e., it is neither +inf, +\&\-inf, nor NaN. +.IP "is_inf( [ SIGN ] )" 4 +.IX Item "is_inf( [ SIGN ] )" +.Vb 3 +\& $x\->is_inf(); # true if $x is +inf +\& $x\->is_inf("+"); # ditto +\& $x\->is_inf("\-"); # true if $x is \-inf +.Ve +.Sp +Returns true if the invocand is infinite and false otherwise. +.IP \fBis_nan()\fR 4 +.IX Item "is_nan()" +.Vb 1 +\& $x\->is_nan(); # true if $x is NaN +.Ve +.IP \fBis_positive()\fR 4 +.IX Item "is_positive()" +.PD 0 +.IP \fBis_pos()\fR 4 +.IX Item "is_pos()" +.PD +.Vb 2 +\& $x\->is_positive(); # true if > 0 +\& $x\->is_pos(); # ditto +.Ve +.Sp +Returns true if the invocand is positive and false otherwise. A \f(CW\*(C`NaN\*(C'\fR is +neither positive nor negative. +.IP \fBis_negative()\fR 4 +.IX Item "is_negative()" +.PD 0 +.IP \fBis_neg()\fR 4 +.IX Item "is_neg()" +.PD +.Vb 2 +\& $x\->is_negative(); # true if < 0 +\& $x\->is_neg(); # ditto +.Ve +.Sp +Returns true if the invocand is negative and false otherwise. A \f(CW\*(C`NaN\*(C'\fR is +neither positive nor negative. +.IP \fBis_non_positive()\fR 4 +.IX Item "is_non_positive()" +.Vb 1 +\& $x\->is_non_positive(); # true if <= 0 +.Ve +.Sp +Returns true if the invocand is negative or zero. +.IP \fBis_non_negative()\fR 4 +.IX Item "is_non_negative()" +.Vb 1 +\& $x\->is_non_negative(); # true if >= 0 +.Ve +.Sp +Returns true if the invocand is positive or zero. +.IP \fBis_odd()\fR 4 +.IX Item "is_odd()" +.Vb 1 +\& $x\->is_odd(); # true if odd, false for even +.Ve +.Sp +Returns true if the invocand is odd and false otherwise. \f(CW\*(C`NaN\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR, and +\&\f(CW\*(C`\-inf\*(C'\fR are neither odd nor even. +.IP \fBis_even()\fR 4 +.IX Item "is_even()" +.Vb 1 +\& $x\->is_even(); # true if $x is even +.Ve +.Sp +Returns true if the invocand is even and false otherwise. \f(CW\*(C`NaN\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR, +\&\f(CW\*(C`\-inf\*(C'\fR are not integers and are neither odd nor even. +.IP \fBis_int()\fR 4 +.IX Item "is_int()" +.Vb 1 +\& $x\->is_int(); # true if $x is an integer +.Ve +.Sp +Returns true if the invocand is an integer and false otherwise. \f(CW\*(C`NaN\*(C'\fR, +\&\f(CW\*(C`+inf\*(C'\fR, \f(CW\*(C`\-inf\*(C'\fR are not integers. +.SS "Comparison methods" +.IX Subsection "Comparison methods" +None of these methods modify the invocand object. Note that a \f(CW\*(C`NaN\*(C'\fR is neither +less than, greater than, or equal to anything else, even a \f(CW\*(C`NaN\*(C'\fR. +.IP \fBbcmp()\fR 4 +.IX Item "bcmp()" +.Vb 1 +\& $x\->bcmp($y); +.Ve +.Sp +Returns \-1, 0, 1 depending on whether \f(CW$x\fR is less than, equal to, or grater than +\&\f(CW$y\fR. Returns undef if any operand is a NaN. +.IP \fBbacmp()\fR 4 +.IX Item "bacmp()" +.Vb 1 +\& $x\->bacmp($y); +.Ve +.Sp +Returns \-1, 0, 1 depending on whether the absolute value of \f(CW$x\fR is less than, +equal to, or grater than the absolute value of \f(CW$y\fR. Returns undef if any operand +is a NaN. +.IP \fBbeq()\fR 4 +.IX Item "beq()" +.Vb 1 +\& $x \-> beq($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. +.IP \fBbne()\fR 4 +.IX Item "bne()" +.Vb 1 +\& $x \-> bne($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is not equal to \f(CW$y\fR, and false otherwise. +.IP \fBblt()\fR 4 +.IX Item "blt()" +.Vb 1 +\& $x \-> blt($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. +.IP \fBble()\fR 4 +.IX Item "ble()" +.Vb 1 +\& $x \-> ble($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is less than or equal to \f(CW$y\fR, and false +otherwise. +.IP \fBbgt()\fR 4 +.IX Item "bgt()" +.Vb 1 +\& $x \-> bgt($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is greater than \f(CW$y\fR, and false otherwise. +.IP \fBbge()\fR 4 +.IX Item "bge()" +.Vb 1 +\& $x \-> bge($y); +.Ve +.Sp +Returns true if and only if \f(CW$x\fR is greater than or equal to \f(CW$y\fR, and false +otherwise. +.SS "Arithmetic methods" +.IX Subsection "Arithmetic methods" +These methods modify the invocand object and returns it. +.IP \fBbneg()\fR 4 +.IX Item "bneg()" +.Vb 1 +\& $x\->bneg(); +.Ve +.Sp +Negate the number, e.g. change the sign between '+' and '\-', or between '+inf' +and '\-inf', respectively. Does nothing for NaN or zero. +.IP \fBbabs()\fR 4 +.IX Item "babs()" +.Vb 1 +\& $x\->babs(); +.Ve +.Sp +Set the number to its absolute value, e.g. change the sign from '\-' to '+' +and from '\-inf' to '+inf', respectively. Does nothing for NaN or positive +numbers. +.IP \fBbsgn()\fR 4 +.IX Item "bsgn()" +.Vb 1 +\& $x\->bsgn(); +.Ve +.Sp +Signum function. Set the number to \-1, 0, or 1, depending on whether the +number is negative, zero, or positive, respectively. Does not modify NaNs. +.IP \fBbnorm()\fR 4 +.IX Item "bnorm()" +.Vb 1 +\& $x\->bnorm(); # normalize (no\-op) +.Ve +.Sp +Normalize the number. This is a no-op and is provided only for backwards +compatibility. +.IP \fBbinc()\fR 4 +.IX Item "binc()" +.Vb 1 +\& $x\->binc(); # increment x by 1 +.Ve +.IP \fBbdec()\fR 4 +.IX Item "bdec()" +.Vb 1 +\& $x\->bdec(); # decrement x by 1 +.Ve +.IP \fBbadd()\fR 4 +.IX Item "badd()" +.Vb 1 +\& $x\->badd($y); # addition (add $y to $x) +.Ve +.IP \fBbsub()\fR 4 +.IX Item "bsub()" +.Vb 1 +\& $x\->bsub($y); # subtraction (subtract $y from $x) +.Ve +.IP \fBbmul()\fR 4 +.IX Item "bmul()" +.Vb 1 +\& $x\->bmul($y); # multiplication (multiply $x by $y) +.Ve +.IP \fBbmuladd()\fR 4 +.IX Item "bmuladd()" +.Vb 1 +\& $x\->bmuladd($y,$z); +.Ve +.Sp +Multiply \f(CW$x\fR by \f(CW$y\fR, and then add \f(CW$z\fR to the result, +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP \fBbdiv()\fR 4 +.IX Item "bdiv()" +.Vb 1 +\& $x\->bdiv($y); # divide, set $x to quotient +.Ve +.Sp +Divides \f(CW$x\fR by \f(CW$y\fR by doing floored division (F\-division), where the quotient is +the floored (rounded towards negative infinity) quotient of the two operands. +In list context, returns the quotient and the remainder. The remainder is +either zero or has the same sign as the second operand. In scalar context, only +the quotient is returned. +.Sp +The quotient is always the greatest integer less than or equal to the +real-valued quotient of the two operands, and the remainder (when it is +non-zero) always has the same sign as the second operand; so, for example, +.Sp +.Vb 6 +\& 1 / 4 => ( 0, 1) +\& 1 / \-4 => (\-1, \-3) +\& \-3 / 4 => (\-1, 1) +\& \-3 / \-4 => ( 0, \-3) +\& \-11 / 2 => (\-5, 1) +\& 11 / \-2 => (\-5, \-1) +.Ve +.Sp +The behavior of the overloaded operator % agrees with the behavior of Perl's +built-in % operator (as documented in the perlop manpage), and the equation +.Sp +.Vb 1 +\& $x == ($x / $y) * $y + ($x % $y) +.Ve +.Sp +holds true for any finite \f(CW$x\fR and finite, non-zero \f(CW$y\fR. +.Sp +Perl's "use integer" might change the behaviour of % and / for scalars. This is +because under 'use integer' Perl does what the underlying C library thinks is +right, and this varies. However, "use integer" does not change the way things +are done with Math::BigInt objects. +.IP \fBbtdiv()\fR 4 +.IX Item "btdiv()" +.Vb 1 +\& $x\->btdiv($y); # divide, set $x to quotient +.Ve +.Sp +Divides \f(CW$x\fR by \f(CW$y\fR by doing truncated division (T\-division), where quotient is +the truncated (rouneded towards zero) quotient of the two operands. In list +context, returns the quotient and the remainder. The remainder is either zero +or has the same sign as the first operand. In scalar context, only the quotient +is returned. +.IP \fBbmod()\fR 4 +.IX Item "bmod()" +.Vb 1 +\& $x\->bmod($y); # modulus (x % y) +.Ve +.Sp +Returns \f(CW$x\fR modulo \f(CW$y\fR, i.e., the remainder after floored division (F\-division). +This method is like Perl's % operator. See "\fBbdiv()\fR". +.IP \fBbtmod()\fR 4 +.IX Item "btmod()" +.Vb 1 +\& $x\->btmod($y); # modulus +.Ve +.Sp +Returns the remainer after truncated division (T\-division). See "\fBbtdiv()\fR". +.IP \fBbmodinv()\fR 4 +.IX Item "bmodinv()" +.Vb 1 +\& $x\->bmodinv($mod); # modular multiplicative inverse +.Ve +.Sp +Returns the multiplicative inverse of \f(CW$x\fR modulo \f(CW$mod\fR. If +.Sp +.Vb 1 +\& $y = $x \-> copy() \-> bmodinv($mod) +.Ve +.Sp +then \f(CW$y\fR is the number closest to zero, and with the same sign as \f(CW$mod\fR, +satisfying +.Sp +.Vb 1 +\& ($x * $y) % $mod = 1 % $mod +.Ve +.Sp +If \f(CW$x\fR and \f(CW$y\fR are non-zero, they must be relative primes, i.e., +\&\f(CW\*(C`bgcd($y, $mod)==1\*(C'\fR. '\f(CW\*(C`NaN\*(C'\fR' is returned when no modular multiplicative +inverse exists. +.IP \fBbmodpow()\fR 4 +.IX Item "bmodpow()" +.Vb 2 +\& $num\->bmodpow($exp,$mod); # modular exponentiation +\& # ($num**$exp % $mod) +.Ve +.Sp +Returns the value of \f(CW$num\fR taken to the power \f(CW$exp\fR in the modulus +\&\f(CW$mod\fR using binary exponentiation. \f(CW\*(C`bmodpow\*(C'\fR is far superior to +writing +.Sp +.Vb 1 +\& $num ** $exp % $mod +.Ve +.Sp +because it is much faster \- it reduces internal variables into +the modulus whenever possible, so it operates on smaller numbers. +.Sp +\&\f(CW\*(C`bmodpow\*(C'\fR also supports negative exponents. +.Sp +.Vb 1 +\& bmodpow($num, \-1, $mod) +.Ve +.Sp +is exactly equivalent to +.Sp +.Vb 1 +\& bmodinv($num, $mod) +.Ve +.IP \fBbpow()\fR 4 +.IX Item "bpow()" +.Vb 1 +\& $x\->bpow($y); # power of arguments (x ** y) +.Ve +.Sp +\&\f(CWbpow()\fR (and the rounding functions) now modifies the first argument and +returns it, unlike the old code which left it alone and only returned the +result. This is to be consistent with \f(CWbadd()\fR etc. The first three modifies +\&\f(CW$x\fR, the last one won't: +.Sp +.Vb 4 +\& print bpow($x,$i),"\en"; # modify $x +\& print $x\->bpow($i),"\en"; # ditto +\& print $x **= $i,"\en"; # the same +\& print $x ** $i,"\en"; # leave $x alone +.Ve +.Sp +The form \f(CW\*(C`$x **= $y\*(C'\fR is faster than \f(CW\*(C`$x = $x ** $y;\*(C'\fR, though. +.IP \fBblog()\fR 4 +.IX Item "blog()" +.Vb 1 +\& $x\->blog($base, $accuracy); # logarithm of x to the base $base +.Ve +.Sp +If \f(CW$base\fR is not defined, Euler's number (e) is used: +.Sp +.Vb 1 +\& print $x\->blog(undef, 100); # log(x) to 100 digits +.Ve +.IP \fBbexp()\fR 4 +.IX Item "bexp()" +.Vb 1 +\& $x\->bexp($accuracy); # calculate e ** X +.Ve +.Sp +Calculates the expression \f(CW\*(C`e ** $x\*(C'\fR where \f(CW\*(C`e\*(C'\fR is Euler's number. +.Sp +This method was added in v1.82 of Math::BigInt (April 2007). +.Sp +See also "\fBblog()\fR". +.IP \fBbnok()\fR 4 +.IX Item "bnok()" +.Vb 1 +\& $x\->bnok($y); # x over y (binomial coefficient n over k) +.Ve +.Sp +Calculates the binomial coefficient n over k, also called the "choose" +function, which is +.Sp +.Vb 3 +\& ( n ) n! +\& | | = \-\-\-\-\-\-\-\- +\& ( k ) k!(n\-k)! +.Ve +.Sp +when n and k are non-negative. This method implements the full Kronenburg +extension (Kronenburg, M.J. "The Binomial Coefficient for Negative Arguments." +18 May 2011. http://arxiv.org/abs/1105.3689/) illustrated by the following +pseudo-code: +.Sp +.Vb 8 +\& if n >= 0 and k >= 0: +\& return binomial(n, k) +\& if k >= 0: +\& return (\-1)^k*binomial(\-n+k\-1, k) +\& if k <= n: +\& return (\-1)^(n\-k)*binomial(\-k\-1, n\-k) +\& else +\& return 0 +.Ve +.Sp +The behaviour is identical to the behaviour of the Maple and Mathematica +function for negative integers n, k. +.IP \fBbuparrow()\fR 4 +.IX Item "buparrow()" +.PD 0 +.IP \fBuparrow()\fR 4 +.IX Item "uparrow()" +.PD +.Vb 2 +\& $a \-> buparrow($n, $b); # modifies $a +\& $x = $a \-> uparrow($n, $b); # does not modify $a +.Ve +.Sp +This method implements Knuth's up-arrow notation, where \f(CW$n\fR is a non-negative +integer representing the number of up-arrows. \f(CW$n\fR = 0 gives multiplication, \f(CW$n\fR = +1 gives exponentiation, \f(CW$n\fR = 2 gives tetration, \f(CW$n\fR = 3 gives hexation etc. The +following illustrates the relation between the first values of \f(CW$n\fR. +.Sp +See <https://en.wikipedia.org/wiki/Knuth%27s_up\-arrow_notation>. +.IP \fBbackermann()\fR 4 +.IX Item "backermann()" +.PD 0 +.IP \fBackermann()\fR 4 +.IX Item "ackermann()" +.PD +.Vb 2 +\& $m \-> backermann($n); # modifies $a +\& $x = $m \-> ackermann($n); # does not modify $a +.Ve +.Sp +This method implements the Ackermann function: +.Sp +.Vb 3 +\& / n + 1 if m = 0 +\& A(m, n) = | A(m\-1, 1) if m > 0 and n = 0 +\& \e A(m\-1, A(m, n\-1)) if m > 0 and n > 0 +.Ve +.Sp +Its value grows rapidly, even for small inputs. For example, A(4, 2) is an +integer of 19729 decimal digits. +.Sp +See https://en.wikipedia.org/wiki/Ackermann_function +.IP \fBbsin()\fR 4 +.IX Item "bsin()" +.Vb 2 +\& my $x = Math::BigInt\->new(1); +\& print $x\->bsin(100), "\en"; +.Ve +.Sp +Calculate the sine of \f(CW$x\fR, modifying \f(CW$x\fR in place. +.Sp +In Math::BigInt, unless upgrading is in effect, the result is truncated to an +integer. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP \fBbcos()\fR 4 +.IX Item "bcos()" +.Vb 2 +\& my $x = Math::BigInt\->new(1); +\& print $x\->bcos(100), "\en"; +.Ve +.Sp +Calculate the cosine of \f(CW$x\fR, modifying \f(CW$x\fR in place. +.Sp +In Math::BigInt, unless upgrading is in effect, the result is truncated to an +integer. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP \fBbatan()\fR 4 +.IX Item "batan()" +.Vb 2 +\& my $x = Math::BigFloat\->new(0.5); +\& print $x\->batan(100), "\en"; +.Ve +.Sp +Calculate the arcus tangens of \f(CW$x\fR, modifying \f(CW$x\fR in place. +.Sp +In Math::BigInt, unless upgrading is in effect, the result is truncated to an +integer. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP \fBbatan2()\fR 4 +.IX Item "batan2()" +.Vb 3 +\& my $x = Math::BigInt\->new(1); +\& my $y = Math::BigInt\->new(1); +\& print $y\->batan2($x), "\en"; +.Ve +.Sp +Calculate the arcus tangens of \f(CW$y\fR divided by \f(CW$x\fR, modifying \f(CW$y\fR in place. +.Sp +In Math::BigInt, unless upgrading is in effect, the result is truncated to an +integer. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP \fBbsqrt()\fR 4 +.IX Item "bsqrt()" +.Vb 1 +\& $x\->bsqrt(); # calculate square root +.Ve +.Sp +\&\f(CWbsqrt()\fR returns the square root truncated to an integer. +.Sp +If you want a better approximation of the square root, then use: +.Sp +.Vb 4 +\& $x = Math::BigFloat\->new(12); +\& Math::BigFloat\->precision(0); +\& Math::BigFloat\->round_mode(\*(Aqeven\*(Aq); +\& print $x\->copy\->bsqrt(),"\en"; # 4 +\& +\& Math::BigFloat\->precision(2); +\& print $x\->bsqrt(),"\en"; # 3.46 +\& print $x\->bsqrt(3),"\en"; # 3.464 +.Ve +.IP \fBbroot()\fR 4 +.IX Item "broot()" +.Vb 1 +\& $x\->broot($N); +.Ve +.Sp +Calculates the N'th root of \f(CW$x\fR. +.IP \fBbfac()\fR 4 +.IX Item "bfac()" +.Vb 1 +\& $x\->bfac(); # factorial of $x +.Ve +.Sp +Returns the factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-1)*($x\-2)*...*2*1, the product of +all positive integers up to and including \f(CW$x\fR. \f(CW$x\fR must be > \-1. The +factorial of N is commonly written as N!, or N!1, when using the multifactorial +notation. +.IP \fBbdfac()\fR 4 +.IX Item "bdfac()" +.Vb 1 +\& $x\->bdfac(); # double factorial of $x +.Ve +.Sp +Returns the double factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-2)*($x\-4)*... \f(CW$x\fR must be +> \-2. The double factorial of N is commonly written as N!!, or N!2, when using +the multifactorial notation. +.IP \fBbtfac()\fR 4 +.IX Item "btfac()" +.Vb 1 +\& $x\->btfac(); # triple factorial of $x +.Ve +.Sp +Returns the triple factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-3)*($x\-6)*... \f(CW$x\fR must be +> \-3. The triple factorial of N is commonly written as N!!!, or N!3, when using +the multifactorial notation. +.IP \fBbmfac()\fR 4 +.IX Item "bmfac()" +.Vb 1 +\& $x\->bmfac($k); # $k\*(Aqth multifactorial of $x +.Ve +.Sp +Returns the multi-factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-$k)*($x\-2*$k)*... \f(CW$x\fR must +be > \-$k. The multi-factorial of N is commonly written as N!K. +.IP \fBbfib()\fR 4 +.IX Item "bfib()" +.Vb 2 +\& $F = $n\->bfib(); # a single Fibonacci number +\& @F = $n\->bfib(); # a list of Fibonacci numbers +.Ve +.Sp +In scalar context, returns a single Fibonacci number. In list context, returns +a list of Fibonacci numbers. The invocand is the last element in the output. +.Sp +The Fibonacci sequence is defined by +.Sp +.Vb 3 +\& F(0) = 0 +\& F(1) = 1 +\& F(n) = F(n\-1) + F(n\-2) +.Ve +.Sp +In list context, F(0) and F(n) is the first and last number in the output, +respectively. For example, if \f(CW$n\fR is 12, then \f(CW\*(C`@F = $n\->bfib()\*(C'\fR returns the +following values, F(0) to F(12): +.Sp +.Vb 1 +\& 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144 +.Ve +.Sp +The sequence can also be extended to negative index n using the re-arranged +recurrence relation +.Sp +.Vb 1 +\& F(n\-2) = F(n) \- F(n\-1) +.Ve +.Sp +giving the bidirectional sequence +.Sp +.Vb 2 +\& n \-7 \-6 \-5 \-4 \-3 \-2 \-1 0 1 2 3 4 5 6 7 +\& F(n) 13 \-8 5 \-3 2 \-1 1 0 1 1 2 3 5 8 13 +.Ve +.Sp +If \f(CW$n\fR is \-12, the following values, F(0) to F(12), are returned: +.Sp +.Vb 1 +\& 0, 1, \-1, 2, \-3, 5, \-8, 13, \-21, 34, \-55, 89, \-144 +.Ve +.IP \fBblucas()\fR 4 +.IX Item "blucas()" +.Vb 2 +\& $F = $n\->blucas(); # a single Lucas number +\& @F = $n\->blucas(); # a list of Lucas numbers +.Ve +.Sp +In scalar context, returns a single Lucas number. In list context, returns a +list of Lucas numbers. The invocand is the last element in the output. +.Sp +The Lucas sequence is defined by +.Sp +.Vb 3 +\& L(0) = 2 +\& L(1) = 1 +\& L(n) = L(n\-1) + L(n\-2) +.Ve +.Sp +In list context, L(0) and L(n) is the first and last number in the output, +respectively. For example, if \f(CW$n\fR is 12, then \f(CW\*(C`@L = $n\->blucas()\*(C'\fR returns +the following values, L(0) to L(12): +.Sp +.Vb 1 +\& 2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322 +.Ve +.Sp +The sequence can also be extended to negative index n using the re-arranged +recurrence relation +.Sp +.Vb 1 +\& L(n\-2) = L(n) \- L(n\-1) +.Ve +.Sp +giving the bidirectional sequence +.Sp +.Vb 2 +\& n \-7 \-6 \-5 \-4 \-3 \-2 \-1 0 1 2 3 4 5 6 7 +\& L(n) 29 \-18 11 \-7 4 \-3 1 2 1 3 4 7 11 18 29 +.Ve +.Sp +If \f(CW$n\fR is \-12, the following values, L(0) to L(\-12), are returned: +.Sp +.Vb 1 +\& 2, 1, \-3, 4, \-7, 11, \-18, 29, \-47, 76, \-123, 199, \-322 +.Ve +.IP \fBbrsft()\fR 4 +.IX Item "brsft()" +.Vb 2 +\& $x\->brsft($n); # right shift $n places in base 2 +\& $x\->brsft($n, $b); # right shift $n places in base $b +.Ve +.Sp +The latter is equivalent to +.Sp +.Vb 1 +\& $x \-> bdiv($b \-> copy() \-> bpow($n)) +.Ve +.IP \fBblsft()\fR 4 +.IX Item "blsft()" +.Vb 2 +\& $x\->blsft($n); # left shift $n places in base 2 +\& $x\->blsft($n, $b); # left shift $n places in base $b +.Ve +.Sp +The latter is equivalent to +.Sp +.Vb 1 +\& $x \-> bmul($b \-> copy() \-> bpow($n)) +.Ve +.SS "Bitwise methods" +.IX Subsection "Bitwise methods" +.IP \fBband()\fR 4 +.IX Item "band()" +.Vb 1 +\& $x\->band($y); # bitwise and +.Ve +.IP \fBbior()\fR 4 +.IX Item "bior()" +.Vb 1 +\& $x\->bior($y); # bitwise inclusive or +.Ve +.IP \fBbxor()\fR 4 +.IX Item "bxor()" +.Vb 1 +\& $x\->bxor($y); # bitwise exclusive or +.Ve +.IP \fBbnot()\fR 4 +.IX Item "bnot()" +.Vb 1 +\& $x\->bnot(); # bitwise not (two\*(Aqs complement) +.Ve +.Sp +Two's complement (bitwise not). This is equivalent to, but faster than, +.Sp +.Vb 1 +\& $x\->binc()\->bneg(); +.Ve +.SS "Rounding methods" +.IX Subsection "Rounding methods" +.IP \fBround()\fR 4 +.IX Item "round()" +.Vb 1 +\& $x\->round($A,$P,$round_mode); +.Ve +.Sp +Round \f(CW$x\fR to accuracy \f(CW$A\fR or precision \f(CW$P\fR using the round mode +\&\f(CW$round_mode\fR. +.IP \fBbround()\fR 4 +.IX Item "bround()" +.Vb 1 +\& $x\->bround($N); # accuracy: preserve $N digits +.Ve +.Sp +Rounds \f(CW$x\fR to an accuracy of \f(CW$N\fR digits. +.IP \fBbfround()\fR 4 +.IX Item "bfround()" +.Vb 1 +\& $x\->bfround($N); +.Ve +.Sp +Rounds to a multiple of 10**$N. Examples: +.Sp +.Vb 1 +\& Input N Result +\& +\& 123456.123456 3 123500 +\& 123456.123456 2 123450 +\& 123456.123456 \-2 123456.12 +\& 123456.123456 \-3 123456.123 +.Ve +.IP \fBbfloor()\fR 4 +.IX Item "bfloor()" +.Vb 1 +\& $x\->bfloor(); +.Ve +.Sp +Round \f(CW$x\fR towards minus infinity, i.e., set \f(CW$x\fR to the largest integer less than +or equal to \f(CW$x\fR. +.IP \fBbceil()\fR 4 +.IX Item "bceil()" +.Vb 1 +\& $x\->bceil(); +.Ve +.Sp +Round \f(CW$x\fR towards plus infinity, i.e., set \f(CW$x\fR to the smallest integer greater +than or equal to \f(CW$x\fR). +.IP \fBbint()\fR 4 +.IX Item "bint()" +.Vb 1 +\& $x\->bint(); +.Ve +.Sp +Round \f(CW$x\fR towards zero. +.SS "Other mathematical methods" +.IX Subsection "Other mathematical methods" +.IP \fBbgcd()\fR 4 +.IX Item "bgcd()" +.Vb 2 +\& $x \-> bgcd($y); # GCD of $x and $y +\& $x \-> bgcd($y, $z, ...); # GCD of $x, $y, $z, ... +.Ve +.Sp +Returns the greatest common divisor (GCD). +.IP \fBblcm()\fR 4 +.IX Item "blcm()" +.Vb 2 +\& $x \-> blcm($y); # LCM of $x and $y +\& $x \-> blcm($y, $z, ...); # LCM of $x, $y, $z, ... +.Ve +.Sp +Returns the least common multiple (LCM). +.SS "Object property methods" +.IX Subsection "Object property methods" +.IP \fBsign()\fR 4 +.IX Item "sign()" +.Vb 1 +\& $x\->sign(); +.Ve +.Sp +Return the sign, of \f(CW$x\fR, meaning either \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, \f(CW\*(C`\-inf\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR or NaN. +.Sp +If you want \f(CW$x\fR to have a certain sign, use one of the following methods: +.Sp +.Vb 5 +\& $x\->babs(); # \*(Aq+\*(Aq +\& $x\->babs()\->bneg(); # \*(Aq\-\*(Aq +\& $x\->bnan(); # \*(AqNaN\*(Aq +\& $x\->binf(); # \*(Aq+inf\*(Aq +\& $x\->binf(\*(Aq\-\*(Aq); # \*(Aq\-inf\*(Aq +.Ve +.IP \fBdigit()\fR 4 +.IX Item "digit()" +.Vb 1 +\& $x\->digit($n); # return the nth digit, counting from right +.Ve +.Sp +If \f(CW$n\fR is negative, returns the digit counting from left. +.IP \fBdigitsum()\fR 4 +.IX Item "digitsum()" +.Vb 1 +\& $x\->digitsum(); +.Ve +.Sp +Computes the sum of the base 10 digits and returns it. +.IP \fBbdigitsum()\fR 4 +.IX Item "bdigitsum()" +.Vb 1 +\& $x\->bdigitsum(); +.Ve +.Sp +Computes the sum of the base 10 digits and assigns the result to the invocand. +.IP \fBlength()\fR 4 +.IX Item "length()" +.Vb 2 +\& $x\->length(); +\& ($xl, $fl) = $x\->length(); +.Ve +.Sp +Returns the number of digits in the decimal representation of the number. In +list context, returns the length of the integer and fraction part. For +Math::BigInt objects, the length of the fraction part is always 0. +.Sp +The following probably doesn't do what you expect: +.Sp +.Vb 2 +\& $c = Math::BigInt\->new(123); +\& print $c\->length(),"\en"; # prints 30 +.Ve +.Sp +It prints both the number of digits in the number and in the fraction part +since print calls \f(CWlength()\fR in list context. Use something like: +.Sp +.Vb 1 +\& print scalar $c\->length(),"\en"; # prints 3 +.Ve +.IP \fBmantissa()\fR 4 +.IX Item "mantissa()" +.Vb 1 +\& $x\->mantissa(); +.Ve +.Sp +Return the signed mantissa of \f(CW$x\fR as a Math::BigInt. +.IP \fBexponent()\fR 4 +.IX Item "exponent()" +.Vb 1 +\& $x\->exponent(); +.Ve +.Sp +Return the exponent of \f(CW$x\fR as a Math::BigInt. +.IP \fBparts()\fR 4 +.IX Item "parts()" +.Vb 1 +\& $x\->parts(); +.Ve +.Sp +Returns the significand (mantissa) and the exponent as integers. In +Math::BigFloat, both are returned as Math::BigInt objects. +.IP \fBsparts()\fR 4 +.IX Item "sparts()" +Returns the significand (mantissa) and the exponent as integers. In scalar +context, only the significand is returned. The significand is the integer with +the smallest absolute value. The output of \f(CWsparts()\fR corresponds to the +output from \f(CWbsstr()\fR. +.Sp +In Math::BigInt, this method is identical to \f(CWparts()\fR. +.IP \fBnparts()\fR 4 +.IX Item "nparts()" +Returns the significand (mantissa) and exponent corresponding to normalized +notation. In scalar context, only the significand is returned. For finite +non-zero numbers, the significand's absolute value is greater than or equal to +1 and less than 10. The output of \f(CWnparts()\fR corresponds to the output from +\&\f(CWbnstr()\fR. In Math::BigInt, if the significand can not be represented as an +integer, upgrading is performed or NaN is returned. +.IP \fBeparts()\fR 4 +.IX Item "eparts()" +Returns the significand (mantissa) and exponent corresponding to engineering +notation. In scalar context, only the significand is returned. For finite +non-zero numbers, the significand's absolute value is greater than or equal to +1 and less than 1000, and the exponent is a multiple of 3. The output of +\&\f(CWeparts()\fR corresponds to the output from \f(CWbestr()\fR. In Math::BigInt, if the +significand can not be represented as an integer, upgrading is performed or NaN +is returned. +.IP \fBdparts()\fR 4 +.IX Item "dparts()" +Returns the integer part and the fraction part. If the fraction part can not be +represented as an integer, upgrading is performed or NaN is returned. The +output of \f(CWdparts()\fR corresponds to the output from \f(CWbdstr()\fR. +.IP \fBfparts()\fR 4 +.IX Item "fparts()" +Returns the smallest possible numerator and denominator so that the numerator +divided by the denominator gives back the original value. For finite numbers, +both values are integers. Mnemonic: fraction. +.IP \fBnumerator()\fR 4 +.IX Item "numerator()" +Together with "\fBdenominator()\fR", returns the smallest integers so that the +numerator divided by the denominator reproduces the original value. With +Math::BigInt, \fBnumerator()\fR simply returns a copy of the invocand. +.IP \fBdenominator()\fR 4 +.IX Item "denominator()" +Together with "\fBnumerator()\fR", returns the smallest integers so that the +numerator divided by the denominator reproduces the original value. With +Math::BigInt, \fBdenominator()\fR always returns either a 1 or a NaN. +.SS "String conversion methods" +.IX Subsection "String conversion methods" +.IP \fBbstr()\fR 4 +.IX Item "bstr()" +Returns a string representing the number using decimal notation. In +Math::BigFloat, the output is zero padded according to the current accuracy or +precision, if any of those are defined. +.IP \fBbsstr()\fR 4 +.IX Item "bsstr()" +Returns a string representing the number using scientific notation where both +the significand (mantissa) and the exponent are integers. The output +corresponds to the output from \f(CWsparts()\fR. +.Sp +.Vb 5 +\& 123 is returned as "123e+0" +\& 1230 is returned as "123e+1" +\& 12300 is returned as "123e+2" +\& 12000 is returned as "12e+3" +\& 10000 is returned as "1e+4" +.Ve +.IP \fBbnstr()\fR 4 +.IX Item "bnstr()" +Returns a string representing the number using normalized notation, the most +common variant of scientific notation. For finite non-zero numbers, the +absolute value of the significand is greater than or equal to 1 and less than +10. The output corresponds to the output from \f(CWnparts()\fR. +.Sp +.Vb 5 +\& 123 is returned as "1.23e+2" +\& 1230 is returned as "1.23e+3" +\& 12300 is returned as "1.23e+4" +\& 12000 is returned as "1.2e+4" +\& 10000 is returned as "1e+4" +.Ve +.IP \fBbestr()\fR 4 +.IX Item "bestr()" +Returns a string representing the number using engineering notation. For finite +non-zero numbers, the absolute value of the significand is greater than or +equal to 1 and less than 1000, and the exponent is a multiple of 3. The output +corresponds to the output from \f(CWeparts()\fR. +.Sp +.Vb 5 +\& 123 is returned as "123e+0" +\& 1230 is returned as "1.23e+3" +\& 12300 is returned as "12.3e+3" +\& 12000 is returned as "12e+3" +\& 10000 is returned as "10e+3" +.Ve +.IP \fBbdstr()\fR 4 +.IX Item "bdstr()" +Returns a string representing the number using decimal notation. The output +corresponds to the output from \f(CWdparts()\fR. +.Sp +.Vb 5 +\& 123 is returned as "123" +\& 1230 is returned as "1230" +\& 12300 is returned as "12300" +\& 12000 is returned as "12000" +\& 10000 is returned as "10000" +.Ve +.IP \fBbfstr()\fR 4 +.IX Item "bfstr()" +Returns a string representing the number using fractional notation. The output +corresponds to the output from \f(CWfparts()\fR. +.Sp +.Vb 5 +\& 12.345 is returned as "2469/200" +\& 123.45 is returned as "2469/20" +\& 1234.5 is returned as "2469/2" +\& 12345 is returned as "12345" +\& 123450 is returned as "123450" +.Ve +.IP \fBto_hex()\fR 4 +.IX Item "to_hex()" +.Vb 1 +\& $x\->to_hex(); +.Ve +.Sp +Returns a hexadecimal string representation of the number. See also \fBfrom_hex()\fR. +.IP \fBto_bin()\fR 4 +.IX Item "to_bin()" +.Vb 1 +\& $x\->to_bin(); +.Ve +.Sp +Returns a binary string representation of the number. See also \fBfrom_bin()\fR. +.IP \fBto_oct()\fR 4 +.IX Item "to_oct()" +.Vb 1 +\& $x\->to_oct(); +.Ve +.Sp +Returns an octal string representation of the number. See also \fBfrom_oct()\fR. +.IP \fBto_bytes()\fR 4 +.IX Item "to_bytes()" +.Vb 2 +\& $x = Math::BigInt\->new("1667327589"); +\& $s = $x\->to_bytes(); # $s = "cafe" +.Ve +.Sp +Returns a byte string representation of the number using big endian byte order. +The invocand must be a non-negative, finite integer. See also \fBfrom_bytes()\fR. +.IP \fBto_base()\fR 4 +.IX Item "to_base()" +.Vb 4 +\& $x = Math::BigInt\->new("250"); +\& $x\->to_base(2); # returns "11111010" +\& $x\->to_base(8); # returns "372" +\& $x\->to_base(16); # returns "fa" +.Ve +.Sp +Returns a string representation of the number in the given base. If a collation +sequence is given, the collation sequence determines which characters are used +in the output. +.Sp +Here are some more examples +.Sp +.Vb 4 +\& $x = Math::BigInt\->new("16")\->to_base(3); # returns "121" +\& $x = Math::BigInt\->new("44027")\->to_base(36); # returns "XYZ" +\& $x = Math::BigInt\->new("58314")\->to_base(42); # returns "Why" +\& $x = Math::BigInt\->new("4")\->to_base(2, "\-|"); # returns "|\-\-" +.Ve +.Sp +See \fBfrom_base()\fR for information and examples. +.IP \fBto_base_num()\fR 4 +.IX Item "to_base_num()" +Converts the given number to the given base. This method is equivalent to +\&\f(CW_to_base()\fR, but returns numbers in an array rather than characters in a +string. In the output, the first element is the most significant. Unlike +\&\f(CW_to_base()\fR, all input values may be arbitrarily large. +.Sp +.Vb 2 +\& $x = Math::BigInt\->new(13); +\& $x\->to_base_num(2); # returns [1, 1, 0, 1] +\& +\& $x = Math::BigInt\->new(65191); +\& $x\->to_base_num(128); # returns [3, 125, 39] +.Ve +.IP \fBas_hex()\fR 4 +.IX Item "as_hex()" +.Vb 1 +\& $x\->as_hex(); +.Ve +.Sp +As, \f(CWto_hex()\fR, but with a "0x" prefix. +.IP \fBas_bin()\fR 4 +.IX Item "as_bin()" +.Vb 1 +\& $x\->as_bin(); +.Ve +.Sp +As, \f(CWto_bin()\fR, but with a "0b" prefix. +.IP \fBas_oct()\fR 4 +.IX Item "as_oct()" +.Vb 1 +\& $x\->as_oct(); +.Ve +.Sp +As, \f(CWto_oct()\fR, but with a "0" prefix. +.IP \fBas_bytes()\fR 4 +.IX Item "as_bytes()" +This is just an alias for \f(CWto_bytes()\fR. +.SS "Other conversion methods" +.IX Subsection "Other conversion methods" +.IP \fBnumify()\fR 4 +.IX Item "numify()" +.Vb 1 +\& print $x\->numify(); +.Ve +.Sp +Returns a Perl scalar from \f(CW$x\fR. It is used automatically whenever a scalar is +needed, for instance in array index operations. +.SS "Utility methods" +.IX Subsection "Utility methods" +These utility methods are made public +.IP \fBdec_str_to_dec_flt_str()\fR 4 +.IX Item "dec_str_to_dec_flt_str()" +Takes a string representing any valid number using decimal notation and converts +it to a string representing the same number using decimal floating point +notation. The output consists of five parts joined together: the sign of the +significand, the absolute value of the significand as the smallest possible +integer, the letter "e", the sign of the exponent, and the absolute value of the +exponent. If the input is invalid, nothing is returned. +.Sp +.Vb 1 +\& $str2 = $class \-> dec_str_to_dec_flt_str($str1); +.Ve +.Sp +Some examples +.Sp +.Vb 4 +\& Input Output +\& 31400.00e\-4 +314e\-2 +\& \-0.00012300e8 \-123e+2 +\& 0 +0e+0 +.Ve +.IP \fBhex_str_to_dec_flt_str()\fR 4 +.IX Item "hex_str_to_dec_flt_str()" +Takes a string representing any valid number using hexadecimal notation and +converts it to a string representing the same number using decimal floating +point notation. The output has the same format as that of +"\fBdec_str_to_dec_flt_str()\fR". +.Sp +.Vb 1 +\& $str2 = $class \-> hex_str_to_dec_flt_str($str1); +.Ve +.Sp +Some examples +.Sp +.Vb 2 +\& Input Output +\& 0xff +255e+0 +.Ve +.Sp +Some examples +.IP \fBoct_str_to_dec_flt_str()\fR 4 +.IX Item "oct_str_to_dec_flt_str()" +Takes a string representing any valid number using octal notation and converts +it to a string representing the same number using decimal floating point +notation. The output has the same format as that of +"\fBdec_str_to_dec_flt_str()\fR". +.Sp +.Vb 1 +\& $str2 = $class \-> oct_str_to_dec_flt_str($str1); +.Ve +.IP \fBbin_str_to_dec_flt_str()\fR 4 +.IX Item "bin_str_to_dec_flt_str()" +Takes a string representing any valid number using binary notation and converts +it to a string representing the same number using decimal floating point +notation. The output has the same format as that of +"\fBdec_str_to_dec_flt_str()\fR". +.Sp +.Vb 1 +\& $str2 = $class \-> bin_str_to_dec_flt_str($str1); +.Ve +.IP \fBdec_str_to_dec_str()\fR 4 +.IX Item "dec_str_to_dec_str()" +Takes a string representing any valid number using decimal notation and converts +it to a string representing the same number using decimal notation. If the +number represents an integer, the output consists of a sign and the absolute +value. If the number represents a non-integer, the output consists of a sign, +the integer part of the number, the decimal point ".", and the fraction part of +the number without any trailing zeros. If the input is invalid, nothing is +returned. +.IP \fBhex_str_to_dec_str()\fR 4 +.IX Item "hex_str_to_dec_str()" +Takes a string representing any valid number using hexadecimal notation and +converts it to a string representing the same number using decimal notation. The +output has the same format as that of "\fBdec_str_to_dec_str()\fR". +.IP \fBoct_str_to_dec_str()\fR 4 +.IX Item "oct_str_to_dec_str()" +Takes a string representing any valid number using octal notation and converts +it to a string representing the same number using decimal notation. The +output has the same format as that of "\fBdec_str_to_dec_str()\fR". +.IP \fBbin_str_to_dec_str()\fR 4 +.IX Item "bin_str_to_dec_str()" +Takes a string representing any valid number using binary notation and converts +it to a string representing the same number using decimal notation. The output +has the same format as that of "\fBdec_str_to_dec_str()\fR". +.SH "ACCURACY and PRECISION" +.IX Header "ACCURACY and PRECISION" +Math::BigInt and Math::BigFloat have full support for accuracy and precision +based rounding, both automatically after every operation, as well as manually. +.PP +This section describes the accuracy/precision handling in Math::BigInt and +Math::BigFloat as it used to be and as it is now, complete with an explanation +of all terms and abbreviations. +.PP +Not yet implemented things (but with correct description) are marked with '!', +things that need to be answered are marked with '?'. +.PP +In the next paragraph follows a short description of terms used here (because +these may differ from terms used by others people or documentation). +.PP +During the rest of this document, the shortcuts A (for accuracy), P (for +precision), F (fallback) and R (rounding mode) are be used. +.SS "Precision P" +.IX Subsection "Precision P" +Precision is a fixed number of digits before (positive) or after (negative) the +decimal point. For example, 123.45 has a precision of \-2. 0 means an integer +like 123 (or 120). A precision of 2 means at least two digits to the left of +the decimal point are zero, so 123 with P = 1 becomes 120. Note that numbers +with zeros before the decimal point may have different precisions, because 1200 +can have P = 0, 1 or 2 (depending on what the initial value was). It could also +have p < 0, when the digits after the decimal point are zero. +.PP +The string output (of floating point numbers) is padded with zeros: +.PP +.Vb 9 +\& Initial value P A Result String +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& 1234.01 \-3 1000 1000 +\& 1234 \-2 1200 1200 +\& 1234.5 \-1 1230 1230 +\& 1234.001 1 1234 1234.0 +\& 1234.01 0 1234 1234 +\& 1234.01 2 1234.01 1234.01 +\& 1234.01 5 1234.01 1234.01000 +.Ve +.PP +For Math::BigInt objects, no padding occurs. +.SS "Accuracy A" +.IX Subsection "Accuracy A" +Number of significant digits. Leading zeros are not counted. A number may have +an accuracy greater than the non-zero digits when there are zeros in it or +trailing zeros. For example, 123.456 has A of 6, 10203 has 5, 123.0506 has 7, +123.45000 has 8 and 0.000123 has 3. +.PP +The string output (of floating point numbers) is padded with zeros: +.PP +.Vb 5 +\& Initial value P A Result String +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& 1234.01 3 1230 1230 +\& 1234.01 6 1234.01 1234.01 +\& 1234.1 8 1234.1 1234.1000 +.Ve +.PP +For Math::BigInt objects, no padding occurs. +.SS "Fallback F" +.IX Subsection "Fallback F" +When both A and P are undefined, this is used as a fallback accuracy when +dividing numbers. +.SS "Rounding mode R" +.IX Subsection "Rounding mode R" +When rounding a number, different 'styles' or 'kinds' of rounding are possible. +(Note that random rounding, as in Math::Round, is not implemented.) +.PP +\fIDirected rounding\fR +.IX Subsection "Directed rounding" +.PP +These round modes always round in the same direction. +.IP 'trunc' 4 +.IX Item "'trunc'" +Round towards zero. Remove all digits following the rounding place, i.e., +replace them with zeros. Thus, 987.65 rounded to tens (P=1) becomes 980, and +rounded to the fourth significant digit becomes 987.6 (A=4). 123.456 rounded to +the second place after the decimal point (P=\-2) becomes 123.46. This +corresponds to the IEEE 754 rounding mode 'roundTowardZero'. +.PP +\fIRounding to nearest\fR +.IX Subsection "Rounding to nearest" +.PP +These rounding modes round to the nearest digit. They differ in how they +determine which way to round in the ambiguous case when there is a tie. +.IP 'even' 4 +.IX Item "'even'" +Round towards the nearest even digit, e.g., when rounding to nearest integer, +\&\-5.5 becomes \-6, 4.5 becomes 4, but 4.501 becomes 5. This corresponds to the +IEEE 754 rounding mode 'roundTiesToEven'. +.IP 'odd' 4 +.IX Item "'odd'" +Round towards the nearest odd digit, e.g., when rounding to nearest integer, +4.5 becomes 5, \-5.5 becomes \-5, but 5.501 becomes 6. This corresponds to the +IEEE 754 rounding mode 'roundTiesToOdd'. +.IP '+inf' 4 +.IX Item "'+inf'" +Round towards plus infinity, i.e., always round up. E.g., when rounding to the +nearest integer, 4.5 becomes 5, \-5.5 becomes \-5, and 4.501 also becomes 5. This +corresponds to the IEEE 754 rounding mode 'roundTiesToPositive'. +.IP '\-inf' 4 +.IX Item "'-inf'" +Round towards minus infinity, i.e., always round down. E.g., when rounding to +the nearest integer, 4.5 becomes 4, \-5.5 becomes \-6, but 4.501 becomes 5. This +corresponds to the IEEE 754 rounding mode 'roundTiesToNegative'. +.IP 'zero' 4 +.IX Item "'zero'" +Round towards zero, i.e., round positive numbers down and negative numbers up. +E.g., when rounding to the nearest integer, 4.5 becomes 4, \-5.5 becomes \-5, but +4.501 becomes 5. This corresponds to the IEEE 754 rounding mode +\&'roundTiesToZero'. +.IP 'common' 4 +.IX Item "'common'" +Round away from zero, i.e., round to the number with the largest absolute +value. E.g., when rounding to the nearest integer, \-1.5 becomes \-2, 1.5 becomes +2 and 1.49 becomes 1. This corresponds to the IEEE 754 rounding mode +\&'roundTiesToAway'. +.PP +The handling of A & P in MBI/MBF (the old core code shipped with Perl versions +<= 5.7.2) is like this: +.IP Precision 4 +.IX Item "Precision" +.Vb 3 +\& * bfround($p) is able to round to $p number of digits after the decimal +\& point +\& * otherwise P is unused +.Ve +.IP "Accuracy (significant digits)" 4 +.IX Item "Accuracy (significant digits)" +.Vb 10 +\& * bround($a) rounds to $a significant digits +\& * only bdiv() and bsqrt() take A as (optional) parameter +\& + other operations simply create the same number (bneg etc), or +\& more (bmul) of digits +\& + rounding/truncating is only done when explicitly calling one +\& of bround or bfround, and never for Math::BigInt (not implemented) +\& * bsqrt() simply hands its accuracy argument over to bdiv. +\& * the documentation and the comment in the code indicate two +\& different ways on how bdiv() determines the maximum number +\& of digits it should calculate, and the actual code does yet +\& another thing +\& POD: +\& max($Math::BigFloat::div_scale,length(dividend)+length(divisor)) +\& Comment: +\& result has at most max(scale, length(dividend), length(divisor)) digits +\& Actual code: +\& scale = max(scale, length(dividend)\-1,length(divisor)\-1); +\& scale += length(divisor) \- length(dividend); +\& So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10 +\& So for lx = 3, ly = 9, scale = 10, scale will actually be 16 +\& (10+9\-3). Actually, the \*(Aqdifference\*(Aq added to the scale is cal\- +\& culated from the number of "significant digits" in dividend and +\& divisor, which is derived by looking at the length of the man\- +\& tissa. Which is wrong, since it includes the + sign (oops) and +\& actually gets 2 for \*(Aq+100\*(Aq and 4 for \*(Aq+101\*(Aq. Oops again. Thus +\& 124/3 with div_scale=1 will get you \*(Aq41.3\*(Aq based on the strange +\& assumption that 124 has 3 significant digits, while 120/7 will +\& get you \*(Aq17\*(Aq, not \*(Aq17.1\*(Aq since 120 is thought to have 2 signif\- +\& icant digits. The rounding after the division then uses the +\& remainder and $y to determine whether it must round up or down. +\& ? I have no idea which is the right way. That\*(Aqs why I used a slightly more +\& ? simple scheme and tweaked the few failing testcases to match it. +.Ve +.PP +This is how it works now: +.IP Setting/Accessing 4 +.IX Item "Setting/Accessing" +.Vb 10 +\& * You can set the A global via Math::BigInt\->accuracy() or +\& Math::BigFloat\->accuracy() or whatever class you are using. +\& * You can also set P globally by using Math::SomeClass\->precision() +\& likewise. +\& * Globals are classwide, and not inherited by subclasses. +\& * to undefine A, use Math::SomeClass\->accuracy(undef); +\& * to undefine P, use Math::SomeClass\->precision(undef); +\& * Setting Math::SomeClass\->accuracy() clears automatically +\& Math::SomeClass\->precision(), and vice versa. +\& * To be valid, A must be > 0, P can have any value. +\& * If P is negative, this means round to the P\*(Aqth place to the right of the +\& decimal point; positive values mean to the left of the decimal point. +\& P of 0 means round to integer. +\& * to find out the current global A, use Math::SomeClass\->accuracy() +\& * to find out the current global P, use Math::SomeClass\->precision() +\& * use $x\->accuracy() respective $x\->precision() for the local +\& setting of $x. +\& * Please note that $x\->accuracy() respective $x\->precision() +\& return eventually defined global A or P, when $x\*(Aqs A or P is not +\& set. +.Ve +.IP "Creating numbers" 4 +.IX Item "Creating numbers" +.Vb 12 +\& * When you create a number, you can give the desired A or P via: +\& $x = Math::BigInt\->new($number,$A,$P); +\& * Only one of A or P can be defined, otherwise the result is NaN +\& * If no A or P is give ($x = Math::BigInt\->new($number) form), then the +\& globals (if set) will be used. Thus changing the global defaults later on +\& will not change the A or P of previously created numbers (i.e., A and P of +\& $x will be what was in effect when $x was created) +\& * If given undef for A and P, NO rounding will occur, and the globals will +\& NOT be used. This is used by subclasses to create numbers without +\& suffering rounding in the parent. Thus a subclass is able to have its own +\& globals enforced upon creation of a number by using +\& $x = Math::BigInt\->new($number,undef,undef): +\& +\& use Math::BigInt::SomeSubclass; +\& use Math::BigInt; +\& +\& Math::BigInt\->accuracy(2); +\& Math::BigInt::SomeSubclass\->accuracy(3); +\& $x = Math::BigInt::SomeSubclass\->new(1234); +\& +\& $x is now 1230, and not 1200. A subclass might choose to implement +\& this otherwise, e.g. falling back to the parent\*(Aqs A and P. +.Ve +.IP Usage 4 +.IX Item "Usage" +.Vb 7 +\& * If A or P are enabled/defined, they are used to round the result of each +\& operation according to the rules below +\& * Negative P is ignored in Math::BigInt, since Math::BigInt objects never +\& have digits after the decimal point +\& * Math::BigFloat uses Math::BigInt internally, but setting A or P inside +\& Math::BigInt as globals does not tamper with the parts of a Math::BigFloat. +\& A flag is used to mark all Math::BigFloat numbers as \*(Aqnever round\*(Aq. +.Ve +.IP Precedence 4 +.IX Item "Precedence" +.Vb 10 +\& * It only makes sense that a number has only one of A or P at a time. +\& If you set either A or P on one object, or globally, the other one will +\& be automatically cleared. +\& * If two objects are involved in an operation, and one of them has A in +\& effect, and the other P, this results in an error (NaN). +\& * A takes precedence over P (Hint: A comes before P). +\& If neither of them is defined, nothing is used, i.e. the result will have +\& as many digits as it can (with an exception for bdiv/bsqrt) and will not +\& be rounded. +\& * There is another setting for bdiv() (and thus for bsqrt()). If neither of +\& A or P is defined, bdiv() will use a fallback (F) of $div_scale digits. +\& If either the dividend\*(Aqs or the divisor\*(Aqs mantissa has more digits than +\& the value of F, the higher value will be used instead of F. +\& This is to limit the digits (A) of the result (just consider what would +\& happen with unlimited A and P in the case of 1/3 :\-) +\& * bdiv will calculate (at least) 4 more digits than required (determined by +\& A, P or F), and, if F is not used, round the result +\& (this will still fail in the case of a result like 0.12345000000001 with A +\& or P of 5, but this can not be helped \- or can it?) +\& * Thus you can have the math done by on Math::Big* class in two modi: +\& + never round (this is the default): +\& This is done by setting A and P to undef. No math operation +\& will round the result, with bdiv() and bsqrt() as exceptions to guard +\& against overflows. You must explicitly call bround(), bfround() or +\& round() (the latter with parameters). +\& Note: Once you have rounded a number, the settings will \*(Aqstick\*(Aq on it +\& and \*(Aqinfect\*(Aq all other numbers engaged in math operations with it, since +\& local settings have the highest precedence. So, to get SaferRound[tm], +\& use a copy() before rounding like this: +\& +\& $x = Math::BigFloat\->new(12.34); +\& $y = Math::BigFloat\->new(98.76); +\& $z = $x * $y; # 1218.6984 +\& print $x\->copy()\->bround(3); # 12.3 (but A is now 3!) +\& $z = $x * $y; # still 1218.6984, without +\& # copy would have been 1210! +\& +\& + round after each op: +\& After each single operation (except for testing like is_zero()), the +\& method round() is called and the result is rounded appropriately. By +\& setting proper values for A and P, you can have all\-the\-same\-A or +\& all\-the\-same\-P modes. For example, Math::Currency might set A to undef, +\& and P to \-2, globally. +\& +\& ?Maybe an extra option that forbids local A & P settings would be in order, +\& ?so that intermediate rounding does not \*(Aqpoison\*(Aq further math? +.Ve +.IP "Overriding globals" 4 +.IX Item "Overriding globals" +.Vb 10 +\& * you will be able to give A, P and R as an argument to all the calculation +\& routines; the second parameter is A, the third one is P, and the fourth is +\& R (shift right by one for binary operations like badd). P is used only if +\& the first parameter (A) is undefined. These three parameters override the +\& globals in the order detailed as follows, i.e. the first defined value +\& wins: +\& (local: per object, global: global default, parameter: argument to sub) +\& + parameter A +\& + parameter P +\& + local A (if defined on both of the operands: smaller one is taken) +\& + local P (if defined on both of the operands: bigger one is taken) +\& + global A +\& + global P +\& + global F +\& * bsqrt() will hand its arguments to bdiv(), as it used to, only now for two +\& arguments (A and P) instead of one +.Ve +.IP "Local settings" 4 +.IX Item "Local settings" +.Vb 5 +\& * You can set A or P locally by using $x\->accuracy() or +\& $x\->precision() +\& and thus force different A and P for different objects/numbers. +\& * Setting A or P this way immediately rounds $x to the new value. +\& * $x\->accuracy() clears $x\->precision(), and vice versa. +.Ve +.IP Rounding 4 +.IX Item "Rounding" +.Vb 10 +\& * the rounding routines will use the respective global or local settings. +\& bround() is for accuracy rounding, while bfround() is for precision +\& * the two rounding functions take as the second parameter one of the +\& following rounding modes (R): +\& \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, \*(Aqtrunc\*(Aq, \*(Aqcommon\*(Aq +\& * you can set/get the global R by using Math::SomeClass\->round_mode() +\& or by setting $Math::SomeClass::round_mode +\& * after each operation, $result\->round() is called, and the result may +\& eventually be rounded (that is, if A or P were set either locally, +\& globally or as parameter to the operation) +\& * to manually round a number, call $x\->round($A,$P,$round_mode); +\& this will round the number by using the appropriate rounding function +\& and then normalize it. +\& * rounding modifies the local settings of the number: +\& +\& $x = Math::BigFloat\->new(123.456); +\& $x\->accuracy(5); +\& $x\->bround(4); +\& +\& Here 4 takes precedence over 5, so 123.5 is the result and $x\->accuracy() +\& will be 4 from now on. +.Ve +.IP "Default values" 4 +.IX Item "Default values" +.Vb 4 +\& * R: \*(Aqeven\*(Aq +\& * F: 40 +\& * A: undef +\& * P: undef +.Ve +.IP Remarks 4 +.IX Item "Remarks" +.Vb 5 +\& * The defaults are set up so that the new code gives the same results as +\& the old code (except in a few cases on bdiv): +\& + Both A and P are undefined and thus will not be used for rounding +\& after each operation. +\& + round() is thus a no\-op, unless given extra parameters A and P +.Ve +.SH "Infinity and Not a Number" +.IX Header "Infinity and Not a Number" +While Math::BigInt has extensive handling of inf and NaN, certain quirks +remain. +.IP \fBoct()\fR/\fBhex()\fR 4 +.IX Item "oct()/hex()" +These perl routines currently (as of Perl v.5.8.6) cannot handle passed inf. +.Sp +.Vb 9 +\& te@linux:~> perl \-wle \*(Aqprint 2 ** 3333\*(Aq +\& Inf +\& te@linux:~> perl \-wle \*(Aqprint 2 ** 3333 == 2 ** 3333\*(Aq +\& 1 +\& te@linux:~> perl \-wle \*(Aqprint oct(2 ** 3333)\*(Aq +\& 0 +\& te@linux:~> perl \-wle \*(Aqprint hex(2 ** 3333)\*(Aq +\& Illegal hexadecimal digit \*(AqI\*(Aq ignored at \-e line 1. +\& 0 +.Ve +.Sp +The same problems occur if you pass them Math::BigInt\->\fBbinf()\fR objects. Since +overloading these routines is not possible, this cannot be fixed from +Math::BigInt. +.SH INTERNALS +.IX Header "INTERNALS" +You should neither care about nor depend on the internal representation; it +might change without notice. Use \fBONLY\fR method calls like \f(CW\*(C`$x\->sign();\*(C'\fR +instead relying on the internal representation. +.SS "MATH LIBRARY" +.IX Subsection "MATH LIBRARY" +The mathematical computations are performed by a backend library. It is not +required to specify which backend library to use, but some backend libraries +are much faster than the default library. +.PP +\fIThe default library\fR +.IX Subsection "The default library" +.PP +The default library is Math::BigInt::Calc, which is implemented in pure Perl +and hence does not require a compiler. +.PP +\fISpecifying a library\fR +.IX Subsection "Specifying a library" +.PP +The simple case +.PP +.Vb 1 +\& use Math::BigInt; +.Ve +.PP +is equivalent to saying +.PP +.Vb 1 +\& use Math::BigInt try => \*(AqCalc\*(Aq; +.Ve +.PP +You can use a different backend library with, e.g., +.PP +.Vb 1 +\& use Math::BigInt try => \*(AqGMP\*(Aq; +.Ve +.PP +which attempts to load the Math::BigInt::GMP library, and falls back to the +default library if the specified library can't be loaded. +.PP +Multiple libraries can be specified by separating them by a comma, e.g., +.PP +.Vb 1 +\& use Math::BigInt try => \*(AqGMP,Pari\*(Aq; +.Ve +.PP +If you request a specific set of libraries and do not allow fallback to the +default library, specify them using "only", +.PP +.Vb 1 +\& use Math::BigInt only => \*(AqGMP,Pari\*(Aq; +.Ve +.PP +If you prefer a specific set of libraries, but want to see a warning if the +fallback library is used, specify them using "lib", +.PP +.Vb 1 +\& use Math::BigInt lib => \*(AqGMP,Pari\*(Aq; +.Ve +.PP +The following first tries to find Math::BigInt::Foo, then Math::BigInt::Bar, and +if this also fails, reverts to Math::BigInt::Calc: +.PP +.Vb 1 +\& use Math::BigInt try => \*(AqFoo,Math::BigInt::Bar\*(Aq; +.Ve +.PP +\fIWhich library to use?\fR +.IX Subsection "Which library to use?" +.PP +\&\fBNote\fR: General purpose packages should not be explicit about the library to +use; let the script author decide which is best. +.PP +Math::BigInt::GMP, Math::BigInt::Pari, and Math::BigInt::GMPz are in +cases involving big numbers much faster than Math::BigInt::Calc. However +these libraries are slower when dealing with very small numbers (less than about +20 digits) and when converting very large numbers to decimal (for instance for +printing, rounding, calculating their length in decimal etc.). +.PP +So please select carefully what library you want to use. +.PP +Different low-level libraries use different formats to store the numbers, so +mixing them won't work. You should not depend on the number having a specific +internal format. +.PP +See the respective math library module documentation for further details. +.PP +\fILoading multiple libraries\fR +.IX Subsection "Loading multiple libraries" +.PP +The first library that is successfully loaded is the one that will be used. Any +further attempts at loading a different module will be ignored. This is to avoid +the situation where module A requires math library X, and module B requires math +library Y, causing modules A and B to be incompatible. For example, +.PP +.Vb 2 +\& use Math::BigInt; # loads default "Calc" +\& use Math::BigFloat only => "GMP"; # ignores "GMP" +.Ve +.SS SIGN +.IX Subsection "SIGN" +The sign is either '+', '\-', 'NaN', '+inf' or '\-inf'. +.PP +A sign of 'NaN' is used to represent the result when input arguments are not +numbers or as a result of 0/0. '+inf' and '\-inf' represent plus respectively +minus infinity. You get '+inf' when dividing a positive number by 0, and '\-inf' +when dividing any negative number by 0. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 1 +\& use Math::BigInt; +\& +\& sub bigint { Math::BigInt\->new(shift); } +\& +\& $x = Math::BigInt\->bstr("1234") # string "1234" +\& $x = "$x"; # same as bstr() +\& $x = Math::BigInt\->bneg("1234"); # Math::BigInt "\-1234" +\& $x = Math::BigInt\->babs("\-12345"); # Math::BigInt "12345" +\& $x = Math::BigInt\->bnorm("\-0.00"); # Math::BigInt "0" +\& $x = bigint(1) + bigint(2); # Math::BigInt "3" +\& $x = bigint(1) + "2"; # ditto ("2" becomes a Math::BigInt) +\& $x = bigint(1); # Math::BigInt "1" +\& $x = $x + 5 / 2; # Math::BigInt "3" +\& $x = $x ** 3; # Math::BigInt "27" +\& $x *= 2; # Math::BigInt "54" +\& $x = Math::BigInt\->new(0); # Math::BigInt "0" +\& $x\-\-; # Math::BigInt "\-1" +\& $x = Math::BigInt\->badd(4,5) # Math::BigInt "9" +\& print $x\->bsstr(); # 9e+0 +.Ve +.PP +Examples for rounding: +.PP +.Vb 2 +\& use Math::BigFloat; +\& use Test::More; +\& +\& $x = Math::BigFloat\->new(123.4567); +\& $y = Math::BigFloat\->new(123.456789); +\& Math::BigFloat\->accuracy(4); # no more A than 4 +\& +\& is ($x\->copy()\->bround(),123.4); # even rounding +\& print $x\->copy()\->bround(),"\en"; # 123.4 +\& Math::BigFloat\->round_mode(\*(Aqodd\*(Aq); # round to odd +\& print $x\->copy()\->bround(),"\en"; # 123.5 +\& Math::BigFloat\->accuracy(5); # no more A than 5 +\& Math::BigFloat\->round_mode(\*(Aqodd\*(Aq); # round to odd +\& print $x\->copy()\->bround(),"\en"; # 123.46 +\& $y = $x\->copy()\->bround(4),"\en"; # A = 4: 123.4 +\& print "$y, ",$y\->accuracy(),"\en"; # 123.4, 4 +\& +\& Math::BigFloat\->accuracy(undef); # A not important now +\& Math::BigFloat\->precision(2); # P important +\& print $x\->copy()\->bnorm(),"\en"; # 123.46 +\& print $x\->copy()\->bround(),"\en"; # 123.46 +.Ve +.PP +Examples for converting: +.PP +.Vb 2 +\& my $x = Math::BigInt\->new(\*(Aq0b1\*(Aq.\*(Aq01\*(Aq x 123); +\& print "bin: ",$x\->as_bin()," hex:",$x\->as_hex()," dec: ",$x,"\en"; +.Ve +.SH "NUMERIC LITERALS" +.IX Header "NUMERIC LITERALS" +After \f(CW\*(C`use Math::BigInt \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope +are converted to \f(CW\*(C`Math::BigInt\*(C'\fR objects. This conversion happens at compile +time. Every non-integer is convert to a NaN. +.PP +For example, +.PP +.Vb 1 +\& perl \-MMath::BigInt=:constant \-le \*(Aqprint 2**150\*(Aq +.Ve +.PP +prints the exact value of \f(CW\*(C`2**150\*(C'\fR. Note that without conversion of constants +to objects the expression \f(CW\*(C`2**150\*(C'\fR is calculated using Perl scalars, which +leads to an inaccurate result. +.PP +Please note that strings are not affected, so that +.PP +.Vb 1 +\& use Math::BigInt qw/:constant/; +\& +\& $x = "1234567890123456789012345678901234567890" +\& + "123456789123456789"; +.Ve +.PP +does give you what you expect. You need an explicit Math::BigInt\->\fBnew()\fR around +at least one of the operands. You should also quote large constants to prevent +loss of precision: +.PP +.Vb 1 +\& use Math::BigInt; +\& +\& $x = Math::BigInt\->new("1234567889123456789123456789123456789"); +.Ve +.PP +Without the quotes Perl first converts the large number to a floating point +constant at compile time, and then converts the result to a Math::BigInt object +at run time, which results in an inaccurate result. +.SS "Hexadecimal, octal, and binary floating point literals" +.IX Subsection "Hexadecimal, octal, and binary floating point literals" +Perl (and this module) accepts hexadecimal, octal, and binary floating point +literals, but use them with care with Perl versions before v5.32.0, because some +versions of Perl silently give the wrong result. Below are some examples of +different ways to write the number decimal 314. +.PP +Hexadecimal floating point literals: +.PP +.Vb 3 +\& 0x1.3ap+8 0X1.3AP+8 +\& 0x1.3ap8 0X1.3AP8 +\& 0x13a0p\-4 0X13A0P\-4 +.Ve +.PP +Octal floating point literals (with "0" prefix): +.PP +.Vb 3 +\& 01.164p+8 01.164P+8 +\& 01.164p8 01.164P8 +\& 011640p\-4 011640P\-4 +.Ve +.PP +Octal floating point literals (with "0o" prefix) (requires v5.34.0): +.PP +.Vb 3 +\& 0o1.164p+8 0O1.164P+8 +\& 0o1.164p8 0O1.164P8 +\& 0o11640p\-4 0O11640P\-4 +.Ve +.PP +Binary floating point literals: +.PP +.Vb 3 +\& 0b1.0011101p+8 0B1.0011101P+8 +\& 0b1.0011101p8 0B1.0011101P8 +\& 0b10011101000p\-2 0B10011101000P\-2 +.Ve +.SH PERFORMANCE +.IX Header "PERFORMANCE" +Using the form \f(CW$x\fR += \f(CW$y\fR; etc over \f(CW$x\fR = \f(CW$x\fR + \f(CW$y\fR is faster, since a copy of \f(CW$x\fR +must be made in the second case. For long numbers, the copy can eat up to 20% +of the work (in the case of addition/subtraction, less for +multiplication/division). If \f(CW$y\fR is very small compared to \f(CW$x\fR, the form \f(CW$x\fR += \f(CW$y\fR +is MUCH faster than \f(CW$x\fR = \f(CW$x\fR + \f(CW$y\fR since making the copy of \f(CW$x\fR takes more time +then the actual addition. +.PP +With a technique called copy-on-write, the cost of copying with overload could +be minimized or even completely avoided. A test implementation of COW did show +performance gains for overloaded math, but introduced a performance loss due to +a constant overhead for all other operations. So Math::BigInt does currently +not COW. +.PP +The rewritten version of this module (vs. v0.01) is slower on certain +operations, like \f(CWnew()\fR, \f(CWbstr()\fR and \f(CWnumify()\fR. The reason are that it +does now more work and handles much more cases. The time spent in these +operations is usually gained in the other math operations so that code on the +average should get (much) faster. If they don't, please contact the author. +.PP +Some operations may be slower for small numbers, but are significantly faster +for big numbers. Other operations are now constant (O(1), like \f(CWbneg()\fR, +\&\f(CWbabs()\fR etc), instead of O(N) and thus nearly always take much less time. +These optimizations were done on purpose. +.PP +If you find the Calc module to slow, try to install any of the replacement +modules and see if they help you. +.SS "Alternative math libraries" +.IX Subsection "Alternative math libraries" +You can use an alternative library to drive Math::BigInt. See the section +"MATH LIBRARY" for more information. +.PP +For more benchmark results see <http://bloodgate.com/perl/benchmarks.html>. +.SH SUBCLASSING +.IX Header "SUBCLASSING" +.SS "Subclassing Math::BigInt" +.IX Subsection "Subclassing Math::BigInt" +The basic design of Math::BigInt allows simple subclasses with very little +work, as long as a few simple rules are followed: +.IP \(bu 4 +The public API must remain consistent, i.e. if a sub-class is overloading +addition, the sub-class must use the same name, in this case \fBbadd()\fR. The reason +for this is that Math::BigInt is optimized to call the object methods directly. +.IP \(bu 4 +The private object hash keys like \f(CW\*(C`$x\->{sign}\*(C'\fR may not be changed, but +additional keys can be added, like \f(CW\*(C`$x\->{_custom}\*(C'\fR. +.IP \(bu 4 +Accessor functions are available for all existing object hash keys and should +be used instead of directly accessing the internal hash keys. The reason for +this is that Math::BigInt itself has a pluggable interface which permits it to +support different storage methods. +.PP +More complex sub-classes may have to replicate more of the logic internal of +Math::BigInt if they need to change more basic behaviors. A subclass that needs +to merely change the output only needs to overload \f(CWbstr()\fR. +.PP +All other object methods and overloaded functions can be directly inherited +from the parent class. +.PP +At the very minimum, any subclass needs to provide its own \f(CWnew()\fR and can +store additional hash keys in the object. There are also some package globals +that must be defined, e.g.: +.PP +.Vb 5 +\& # Globals +\& $accuracy = undef; +\& $precision = \-2; # round to 2 decimal places +\& $round_mode = \*(Aqeven\*(Aq; +\& $div_scale = 40; +.Ve +.PP +Additionally, you might want to provide the following two globals to allow +auto-upgrading and auto-downgrading to work correctly: +.PP +.Vb 2 +\& $upgrade = undef; +\& $downgrade = undef; +.Ve +.PP +This allows Math::BigInt to correctly retrieve package globals from the +subclass, like \f(CW$SubClass::precision\fR. See t/Math/BigInt/Subclass.pm or +t/Math/BigFloat/SubClass.pm completely functional subclass examples. +.PP +Don't forget to +.PP +.Vb 1 +\& use overload; +.Ve +.PP +in your subclass to automatically inherit the overloading from the parent. If +you like, you can change part of the overloading, look at Math::String for an +example. +.SH UPGRADING +.IX Header "UPGRADING" +When used like this: +.PP +.Vb 1 +\& use Math::BigInt upgrade => \*(AqFoo::Bar\*(Aq; +.Ve +.PP +certain operations 'upgrade' their calculation and thus the result to the class +Foo::Bar. Usually this is used in conjunction with Math::BigFloat: +.PP +.Vb 1 +\& use Math::BigInt upgrade => \*(AqMath::BigFloat\*(Aq; +.Ve +.PP +As a shortcut, you can use the module bignum: +.PP +.Vb 1 +\& use bignum; +.Ve +.PP +Also good for one-liners: +.PP +.Vb 1 +\& perl \-Mbignum \-le \*(Aqprint 2 ** 255\*(Aq +.Ve +.PP +This makes it possible to mix arguments of different classes (as in 2.5 + 2) as +well es preserve accuracy (as in \fBsqrt\fR\|(3)). +.PP +Beware: This feature is not fully implemented yet. +.SS Auto-upgrade +.IX Subsection "Auto-upgrade" +The following methods upgrade themselves unconditionally; that is if upgrade is +in effect, they always hands up their work: +.PP +.Vb 1 +\& div bsqrt blog bexp bpi bsin bcos batan batan2 +.Ve +.PP +All other methods upgrade themselves only when one (or all) of their arguments +are of the class mentioned in \f(CW$upgrade\fR. +.SH EXPORTS +.IX Header "EXPORTS" +\&\f(CW\*(C`Math::BigInt\*(C'\fR exports nothing by default, but can export the following +methods: +.PP +.Vb 2 +\& bgcd +\& blcm +.Ve +.SH CAVEATS +.IX Header "CAVEATS" +Some things might not work as you expect them. Below is documented what is +known to be troublesome: +.IP "Comparing numbers as strings" 4 +.IX Item "Comparing numbers as strings" +Both \f(CWbstr()\fR and \f(CWbsstr()\fR as well as stringify via overload drop the +leading '+'. This is to be consistent with Perl and to make \f(CW\*(C`cmp\*(C'\fR (especially +with overloading) to work as you expect. It also solves problems with +\&\f(CW\*(C`Test.pm\*(C'\fR and Test::More, which stringify arguments before comparing them. +.Sp +Mark Biggar said, when asked about to drop the '+' altogether, or make only +\&\f(CW\*(C`cmp\*(C'\fR work: +.Sp +.Vb 4 +\& I agree (with the first alternative), don\*(Aqt add the \*(Aq+\*(Aq on positive +\& numbers. It\*(Aqs not as important anymore with the new internal form +\& for numbers. It made doing things like abs and neg easier, but +\& those have to be done differently now anyway. +.Ve +.Sp +So, the following examples now works as expected: +.Sp +.Vb 2 +\& use Test::More tests => 1; +\& use Math::BigInt; +\& +\& my $x = Math::BigInt \-> new(3*3); +\& my $y = Math::BigInt \-> new(3*3); +\& +\& is($x,3*3, \*(Aqmultiplication\*(Aq); +\& print "$x eq 9" if $x eq $y; +\& print "$x eq 9" if $x eq \*(Aq9\*(Aq; +\& print "$x eq 9" if $x eq 3*3; +.Ve +.Sp +Additionally, the following still works: +.Sp +.Vb 3 +\& print "$x == 9" if $x == $y; +\& print "$x == 9" if $x == 9; +\& print "$x == 9" if $x == 3*3; +.Ve +.Sp +There is now a \f(CWbsstr()\fR method to get the string in scientific notation aka +\&\f(CW1e+2\fR instead of \f(CW100\fR. Be advised that overloaded 'eq' always uses \fBbstr()\fR +for comparison, but Perl represents some numbers as 100 and others as 1e+308. +If in doubt, convert both arguments to Math::BigInt before comparing them as +strings: +.Sp +.Vb 2 +\& use Test::More tests => 3; +\& use Math::BigInt; +\& +\& $x = Math::BigInt\->new(\*(Aq1e56\*(Aq); +\& $y = 1e56; +\& is($x,$y); # fails +\& is($x\->bsstr(), $y); # okay +\& $y = Math::BigInt\->new($y); +\& is($x, $y); # okay +.Ve +.Sp +Alternatively, simply use \f(CW\*(C`<=>\*(C'\fR for comparisons, this always gets it +right. There is not yet a way to get a number automatically represented as a +string that matches exactly the way Perl represents it. +.Sp +See also the section about "Infinity and Not a Number" for problems in +comparing NaNs. +.IP \fBint()\fR 4 +.IX Item "int()" +\&\f(CWint()\fR returns (at least for Perl v5.7.1 and up) another Math::BigInt, not a +Perl scalar: +.Sp +.Vb 4 +\& $x = Math::BigInt\->new(123); +\& $y = int($x); # 123 as a Math::BigInt +\& $x = Math::BigFloat\->new(123.45); +\& $y = int($x); # 123 as a Math::BigFloat +.Ve +.Sp +If you want a real Perl scalar, use \f(CWnumify()\fR: +.Sp +.Vb 1 +\& $y = $x\->numify(); # 123 as a scalar +.Ve +.Sp +This is seldom necessary, though, because this is done automatically, like when +you access an array: +.Sp +.Vb 1 +\& $z = $array[$x]; # does work automatically +.Ve +.IP "Modifying and =" 4 +.IX Item "Modifying and =" +Beware of: +.Sp +.Vb 2 +\& $x = Math::BigFloat\->new(5); +\& $y = $x; +.Ve +.Sp +This makes a second reference to the \fBsame\fR object and stores it in \f(CW$y\fR. Thus +anything that modifies \f(CW$x\fR (except overloaded operators) also modifies \f(CW$y\fR, and +vice versa. Or in other words, \f(CW\*(C`=\*(C'\fR is only safe if you modify your +Math::BigInt objects only via overloaded math. As soon as you use a method call +it breaks: +.Sp +.Vb 2 +\& $x\->bmul(2); +\& print "$x, $y\en"; # prints \*(Aq10, 10\*(Aq +.Ve +.Sp +If you want a true copy of \f(CW$x\fR, use: +.Sp +.Vb 1 +\& $y = $x\->copy(); +.Ve +.Sp +You can also chain the calls like this, this first makes a copy and then +multiply it by 2: +.Sp +.Vb 1 +\& $y = $x\->copy()\->bmul(2); +.Ve +.Sp +See also the documentation for overload.pm regarding \f(CW\*(C`=\*(C'\fR. +.IP "Overloading \-$x" 4 +.IX Item "Overloading -$x" +The following: +.Sp +.Vb 1 +\& $x = \-$x; +.Ve +.Sp +is slower than +.Sp +.Vb 1 +\& $x\->bneg(); +.Ve +.Sp +since overload calls \f(CW\*(C`sub($x,0,1);\*(C'\fR instead of \f(CWneg($x)\fR. The first variant +needs to preserve \f(CW$x\fR since it does not know that it later gets overwritten. +This makes a copy of \f(CW$x\fR and takes O(N), but \f(CW$x\fR\->\fBbneg()\fR is O(1). +.IP "Mixing different object types" 4 +.IX Item "Mixing different object types" +With overloaded operators, it is the first (dominating) operand that determines +which method is called. Here are some examples showing what actually gets +called in various cases. +.Sp +.Vb 2 +\& use Math::BigInt; +\& use Math::BigFloat; +\& +\& $mbf = Math::BigFloat\->new(5); +\& $mbi2 = Math::BigInt\->new(5); +\& $mbi = Math::BigInt\->new(2); +\& # what actually gets called: +\& $float = $mbf + $mbi; # $mbf\->badd($mbi) +\& $float = $mbf / $mbi; # $mbf\->bdiv($mbi) +\& $integer = $mbi + $mbf; # $mbi\->badd($mbf) +\& $integer = $mbi2 / $mbi; # $mbi2\->bdiv($mbi) +\& $integer = $mbi2 / $mbf; # $mbi2\->bdiv($mbf) +.Ve +.Sp +For instance, Math::BigInt\->\fBbdiv()\fR always returns a Math::BigInt, regardless of +whether the second operant is a Math::BigFloat. To get a Math::BigFloat you +either need to call the operation manually, make sure each operand already is a +Math::BigFloat, or cast to that type via Math::BigFloat\->\fBnew()\fR: +.Sp +.Vb 1 +\& $float = Math::BigFloat\->new($mbi2) / $mbi; # = 2.5 +.Ve +.Sp +Beware of casting the entire expression, as this would cast the +result, at which point it is too late: +.Sp +.Vb 1 +\& $float = Math::BigFloat\->new($mbi2 / $mbi); # = 2 +.Ve +.Sp +Beware also of the order of more complicated expressions like: +.Sp +.Vb 2 +\& $integer = ($mbi2 + $mbi) / $mbf; # int / float => int +\& $integer = $mbi2 / Math::BigFloat\->new($mbi); # ditto +.Ve +.Sp +If in doubt, break the expression into simpler terms, or cast all operands +to the desired resulting type. +.Sp +Scalar values are a bit different, since: +.Sp +.Vb 2 +\& $float = 2 + $mbf; +\& $float = $mbf + 2; +.Ve +.Sp +both result in the proper type due to the way the overloaded math works. +.Sp +This section also applies to other overloaded math packages, like Math::String. +.Sp +One solution to you problem might be autoupgrading|upgrading. See the +pragmas bignum, bigint and bigrat for an easy way to do this. +.SH BUGS +.IX Header "BUGS" +Please report any bugs or feature requests to +\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at +<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). +We will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. +.SH SUPPORT +.IX Header "SUPPORT" +You can find documentation for this module with the perldoc command. +.PP +.Vb 1 +\& perldoc Math::BigInt +.Ve +.PP +You can also look for information at: +.IP \(bu 4 +GitHub +.Sp +<https://github.com/pjacklam/p5\-Math\-BigInt> +.IP \(bu 4 +RT: CPAN's request tracker +.Sp +<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> +.IP \(bu 4 +MetaCPAN +.Sp +<https://metacpan.org/release/Math\-BigInt> +.IP \(bu 4 +CPAN Testers Matrix +.Sp +<http://matrix.cpantesters.org/?dist=Math\-BigInt> +.IP \(bu 4 +CPAN Ratings +.Sp +<https://cpanratings.perl.org/dist/Math\-BigInt> +.IP \(bu 4 +The Bignum mailing list +.RS 4 +.IP \(bu 4 +Post to mailing list +.Sp +\&\f(CW\*(C`bignum at lists.scsys.co.uk\*(C'\fR +.IP \(bu 4 +View mailing list +.Sp +<http://lists.scsys.co.uk/pipermail/bignum/> +.IP \(bu 4 +Subscribe/Unsubscribe +.Sp +<http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/bignum> +.RE +.RS 4 +.RE +.SH LICENSE +.IX Header "LICENSE" +This program is free software; you may redistribute it and/or modify it under +the same terms as Perl itself. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Math::BigFloat and Math::BigRat as well as the backends +Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari. +.PP +The pragmas bignum, bigint and bigrat also might be of interest +because they solve the autoupgrading/downgrading issue, at least partly. +.SH AUTHORS +.IX Header "AUTHORS" +.IP \(bu 4 +Mark Biggar, overloaded interface by Ilya Zakharevich, 1996\-2001. +.IP \(bu 4 +Completely rewritten by Tels <http://bloodgate.com>, 2001\-2008. +.IP \(bu 4 +Florian Ragwitz <flora@cpan.org>, 2010. +.IP \(bu 4 +Peter John Acklam <pjacklam@gmail.com>, 2011\-. +.PP +Many people contributed in one or more ways to the final beast, see the file +CREDITS for an (incomplete) list. If you miss your name, please drop me a +mail. Thank you! |