man Math::BigInt (3): Arbitrary size integer/float math package

(3)

  $i = Math::BigInt -> new('123_456_789_123_456_789');

    $x = Math::BigInt->new(56789012345678901234);   # bad
    $x = Math::BigInt->new('56789012345678901234'); # good

        perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'

        perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'

        $zero = Math::BigInt->bzero();
        $nan = Math::BigInt->bnan();

"bnorm()"
"is_odd()"
"is_even()"
"is_zero()"
"is_one()"
"is_nan()"
"bcmp()"
"bacmp()"
$A
$P
$R
"accuracy"
"precision"
"round_mode"
    use Data::Dumper;
    print Dumper ( Math::BigInt->config() );
    print Math::BigInt->config()->{lib},"\n";

    key           Description
                  Example
    ============================================================
    lib           Name of the low-level math library
                  Math::BigInt::Calc
    lib_version   Version of low-level math library (see 'lib')
                  0.30
    class         The class name of config() you just called
                  Math::BigInt
    upgrade       To which class math operations might be
                  upgraded Math::BigFloat
    downgrade     To which class math operations might be
                  downgraded undef
    precision     Global precision
                  undef
    accuracy      Global accuracy
                  undef
    round_mode    Global round mode
                  even
    version       version number of the class you used
                  1.61
    div_scale     Fallback accuracy for div
                  40
    trap_nan      If true, traps creation of NaN via croak()
                  1
    trap_inf      If true, traps creation of +inf/-inf via croak()
                  1

"config()"
        trap_inf trap_nan
        upgrade downgrade precision accuracy round_mode div_scale

        $new_cfg = Math::BigInt->config(
            { trap_inf => 1, precision => 5 }
        );

    $x->accuracy(5);         # local for $x
    CLASS->accuracy(5);      # global for all members of CLASS
                             # Note: This also applies to new()!
    $A = $x->accuracy();     # read out accuracy that affects $x
    $A = CLASS->accuracy();  # read out global accuracy

"CLASS->accuracy($A)"
    my $x = Math::BigInt->new(30000);
    my $y = Math::BigInt->new(7);
    print scalar $x->copy()->bdiv($y, 2);               # print 4300
    print scalar $x->copy()->bdiv($y)->bround(2);       # print 4300

    $x->accuracy(undef);
    Math::BigInt->accuracy(undef);

"$x->accuracy()"
$x:
    $y = Math::BigInt->new(1234567);       # unrounded
    print Math::BigInt->accuracy(4),"\n";  # set 4, print 4
    $x = Math::BigInt->new(123456);        # $x will be automatic-
                                           # ally rounded!
    print "$x $y\n";                       # '123500 1234567'
    print $x->accuracy(),"\n";             # will be 4
    print $y->accuracy(),"\n";             # also 4, since
                                           # global is 4
    print Math::BigInt->accuracy(5),"\n";  # set to 5, print 5
    print $x->accuracy(),"\n";             # still 4
    print $y->accuracy(),"\n";             # 5, since global is 5

    $x->precision(-2);          # local for $x, round at the second
                                # digit right of the dot
    $x->precision(2);           # ditto, round at the second digit
                                # left of the dot
    CLASS->precision(5);        # Global for all members of CLASS
                                # This also applies to new()!
    CLASS->precision(-5);       # ditto
    $P = CLASS->precision();    # read out global precision
    $P = $x->precision();       # read out precision that affects $x

"precision()"
    $x->precision(undef);
    Math::BigInt->precision(undef);

"$x->precision()"
$x
$x:
    $y = Math::BigInt->new(1234567);        # unrounded
    print Math::BigInt->precision(4),"\n";  # set 4, print 4
    $x = Math::BigInt->new(123456);  # will be automatically rounded
    print $x;                               # print "120000"!

    $x->brsft($y,$n);

$x
$y
$n
$x
$n
$y
    $x = Math::BigInt->new(10);
    $x->brsft(1);                       # same as $x >> 1: 5
    $x = Math::BigInt->new(1234);
    $x->brsft(2,10);                    # result 12

$x:
    $x = Math::BigInt->new(-5);
    print $x->brsft(1);

    $x = Math::BigInt->new($str,$A,$P,$R);

    $x = Math::BigInt->from_oct("0775");      # input is octal

    $x = Math::BigInt->from_hex("0xcafe");    # input is hexadecimal

    $x = Math::BigInt->from_bin("0b10011");   # input is binary

    $x = Math::BigInt->bnan();

    $x->bnan();

    $x = Math::BigInt->bzero();

    $x->bzero();

    $x = Math::BigInt->binf($sign);

    $x->binf();
    $x->binf('-');

    $x = Math::BigInt->bone($sign);

    $x->bone();                 # +1
    $x->bone('-');              # -1

    $x->is_zero();              # true if arg is +0
    $x->is_nan();               # true if arg is NaN
    $x->is_one();               # true if arg is +1
    $x->is_one('-');            # true if arg is -1
    $x->is_inf();               # true if +inf
    $x->is_inf('-');            # true if -inf (sign is default '+')

    if ($x == 0)

    $x->is_pos();                       # true if > 0
    $x->is_neg();                       # true if < 0

"NaN"
"+inf"
"-inf"
"zero"
"is_positive()"
"is_negative()"
"is_pos()"
"is_neg()"
"is_positive()"
"is_negative()"
"is_pos()"
"is_neg()"
    $x->is_odd();               # true if odd, false for even
    $x->is_even();              # true if even, false for odd
    $x->is_int();               # true if $x is an integer

"NaN"
"+inf"
"-inf"
"NaN"
"+inf"
"-inf"
    $x->bcmp($y);

$x
$y
    $x->bacmp($y);

$x
$y
    $x -> beq($y);

$x
$y
    $x -> bne($y);

$x
$y
    $x -> blt($y);

$x
$y
    $x -> ble($y);

$x
$y
    $x -> bgt($y);

$x
$y
    $x -> bge($y);

$x
$y
    $x->sign();

$x
"+"
"-"
"-inf"
"+inf"
$x
    $x->babs();                 # '+'
    $x->babs()->bneg();         # '-'
    $x->bnan();                 # 'NaN'
    $x->binf();                 # '+inf'
    $x->binf('-');              # '-inf'

    $x->digit($n);       # return the nth digit, counting from right

$n
    $x->bneg();

    $x->babs();

    $x->bsgn();

    $x->bnorm();                        # normalize (no-op)

    $x->bnot();

    $x->binc()->bneg();

    $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
$y
$z
    $x->bdiv($y);               # divide, set $x to quotient

$x
$y
    $x->btdiv($y);              # divide, set $x to quotient

$x
$y
    $x->bmod($y);               # modulus (x % y)

$x
$y
    $x->btmod($y);              # modulus

    $x->bmodinv($mod);          # modular multiplicative inverse

$x
$mod
    $y = $x -> copy() -> bmodinv($mod)

$y
$mod
    ($x * $y) % $mod = 1 % $mod

$x
$y
"bgcd($y, $mod)==1"
"NaN"
    $num->bmodpow($exp,$mod);           # modular exponentiation
                                        # ($num**$exp % $mod)

$num
$exp
$mod
"bmodpow"
    $num ** $exp % $mod

"bmodpow"
    bmodpow($num, -1, $mod)

    bmodinv($num, $mod)

    $x->bpow($y);               # power of arguments (x ** y)

    $x->blog($base, $accuracy);         # logarithm of x to the base $base

$base
    print $x->blog(undef, 100);         # log(x) to 100 digits

    $x->bexp($accuracy);                # calculate e ** X

"e ** $x"
"e"
    $x->bnok($y);               # x over y (binomial coefficient n over k)

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

    print Math::BigInt->bpi(100), "\n";         # 3

3
    use Math::BigFloat;
    use Math::BigInt upgrade => Math::BigFloat;
    print Math::BigInt->bpi(3), "\n";           # 3.14
    print Math::BigInt->bpi(100), "\n";         # 3.1415....

    my $x = Math::BigInt->new(1);
    print $x->bcos(100), "\n";

$x
$x
    my $x = Math::BigInt->new(1);
    print $x->bsin(100), "\n";

$x
$x
    my $x = Math::BigInt->new(1);
    my $y = Math::BigInt->new(1);
    print $y->batan2($x), "\n";

$y
$x
$y
    my $x = Math::BigFloat->new(0.5);
    print $x->batan(100), "\n";

$x
$x
    $x->blsft($n);              # left shift $n places in base 2
    $x->blsft($n, $b);          # left shift $n places in base $b

    $x -> bmul($b -> copy() -> bpow($n))

    $x->brsft($n);              # right shift $n places in base 2
    $x->brsft($n, $b);          # right shift $n places in base $b

    $x -> bdiv($b -> copy() -> bpow($n))

    $x->band($y);               # bitwise and

    $x->bior($y);               # bitwise inclusive or

    $x->bxor($y);               # bitwise exclusive or

    $x->bnot();                 # bitwise not (two's complement)

    $x->bsqrt();                # calculate square-root

    $x->broot($N);

$x
    $x->bfac();                 # factorial of $x (1*2*3*4*..$x)

    $x->round($A,$P,$round_mode);

$x
$A
$P
$round_mode
    $x->bround($N);               # accuracy: preserve $N digits

    $x->bfround($N);

        Input           N               Result
        ===================================================
        123456.123456   3               123500
        123456.123456   2               123450
        123456.123456   -2              123456.12
        123456.123456   -3              123456.123

    $x->bfloor();

$x
$x
$x
$x
$x
    $x->bceil();

$x
$x
$x
$x
$x
    $x->bint();

$x
$x
$x
    bgcd(@values);           # greatest common divisor (no OO style)

    blcm(@values);           # lowest common multiple (no OO style)

    $x->length();
    ($xl,$fl) = $x->length();

    $x->exponent();

$x
    $x->mantissa();

$x
    $x->parts();        # return (mantissa,exponent) as BigInt

    $x->copy();         # make a true copy of $x (unlike $y = $x;)

$x
$y
    $x -> badd($y);

$y
$x
$y
$x
$y
"as_int()"
"as_int()"
$y
"as_number()"
"as_number()"
"as_int()"
"as_number()"
$x
"ref($x)->new()"
"as_number()"
"as_int()"
"as_number"
"as_int()"
"as_int()"
"copy()"
    $x->bstr();

$x
    $x->bsstr();     # normalized string in scientific notation

    $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

        print $x->numify();

$x
    $x->modify('bpowd');

        my $i = Math::BigInt->new(123);
        my $f = Math::BigFloat->new('123.1');
        print $i + $f,"\n";                     # print 246

        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

        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

  * bfround($p) is able to round to $p number of digits after the decimal
    point
  * otherwise P is unused

  * 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 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 'difference' 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 '+100' and 4 for '+101'. Oops again. Thus
    124/3 with div_scale=1 will get you '41.3' based on the strange
    assumption that 124 has 3 significant digits, while 120/7 will
    get you '17', not '17.1' 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's why I used a slightly more
 ?  simple scheme and tweaked the few failing testcases to match it.

  * 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'th 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's A or P is not
    set.

  * 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's A and P.

  * 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 BigInts 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 BigFloat.
    A flag is used to mark all Math::BigFloat numbers as 'never round'.

  * 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's or the divisor's 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 'stick' on it
      and 'infect' 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 'poison' further math?

  * 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

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

  * 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):
    'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
  * 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.

  * R: 'even'
  * F: 40
  * A: undef
  * P: undef

  * 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

        te@linux:~> perl -wle 'print 2 ** 3333'
        Inf
        te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
        1
        te@linux:~> perl -wle 'print oct(2 ** 3333)'
        0
        te@linux:~> perl -wle 'print hex(2 ** 3333)'
        Illegal hexadecimal digit 'I' ignored at -e line 1.
        0

"NaN != NaN"
"log(-inf)"
"$x->sign();"
"Math::BigInt::Calc"
        use Math::BigInt try => 'Calc';

        use Math::BigInt try => 'GMP';

        use Math::BigInt only => 'GMP,Pari';

        use Math::BigInt try => 'Foo,Math::BigInt::Bar';

"mantissa()"
"exponent()"
        $m = $x->mantissa();
        $e = $x->exponent();
        $y = $m * ( 10 ** $e );
        print "ok\n" if $x == $y;

"($m,$e) = $x->parts()"
$e
"+inf"
"NaN"
"$x == 0"
1
0E1
$m
$e
$m
  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");      # BigInt "-1234"
  $x = Math::BigInt->babs("-12345");    # BigInt "12345"
  $x = Math::BigInt->bnorm("-0.00");    # BigInt "0"
  $x = bigint(1) + bigint(2);           # BigInt "3"
  $x = bigint(1) + "2";                 # ditto (auto-BigIntify of "2")
  $x = bigint(1);                       # BigInt "1"
  $x = $x + 5 / 2;                      # BigInt "3"
  $x = $x ** 3;                         # BigInt "27"
  $x *= 2;                              # BigInt "54"
  $x = Math::BigInt->new(0);            # BigInt "0"
  $x--;                                 # BigInt "-1"
  $x = Math::BigInt->badd(4,5)          # BigInt "9"
  print $x->bsstr();                    # 9e+0

  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(),"\n";      # 123.4
  Math::BigFloat->round_mode('odd');    # round to odd
  print $x->copy()->bround(),"\n";      # 123.5
  Math::BigFloat->accuracy(5);          # no more A than 5
  Math::BigFloat->round_mode('odd');    # round to odd
  print $x->copy()->bround(),"\n";      # 123.46
  $y = $x->copy()->bround(4),"\n";      # A = 4: 123.4
  print "$y, ",$y->accuracy(),"\n";     # 123.4, 4
  Math::BigFloat->accuracy(undef);      # A not important now
  Math::BigFloat->precision(2);         # P important
  print $x->copy()->bnorm(),"\n";       # 123.46
  print $x->copy()->bround(),"\n";      # 123.46

  my $x = Math::BigInt->new('0b1'.'01' x 123);
  print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";

"use Math::BigInt ':constant'"
"Math::BigInt"
  perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'

"2**100"
        use Math::BigInt qw/:constant/;
        $x = 1234567890123456789012345678901234567890
                + 123456789123456789;
        $y = '1234567890123456789012345678901234567890'
                + '123456789123456789';

        use Math::BigInt;
        $x = Math::BigInt->new('1234567889123456789123456789123456789');

        use Math::BigInt ':constant';
        print ref(123e2),"\n";
        print ref(123.2e2),"\n";

$x
$y
$x
$x
$y
$x
$y
$x
$x
$y
$x
$x
$y
$x
"new()"
"bstr()"
"numify()"
"bneg()"
"babs()"
"$x->{sign}"
"$x->{_custom}"
"bstr()"
"new()"
  # Globals
  $accuracy = undef;
  $precision = -2;       # round to 2 decimal places
  $round_mode = 'even';
  $div_scale = 40;

  $upgrade = undef;
  $downgrade = undef;

$SubClass::precision
        use overload;

        use Math::BigInt upgrade => 'Foo::Bar';

        use Math::BigInt upgrade => 'Math::BigFloat';

        use bignum;

        perl -Mbignum -le 'print 2 ** 255'

$upgrade
"Math::BigInt"
        bgcd
        blcm

"bstr()"
"bsstr()"
"cmp"
"Test.pm"
"cmp"
        I agree (with the first alternative), don't add the '+' on positive
        numbers.  It's 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.

        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, 'multiplication');
        print "$x eq 9" if $x eq $y;
        print "$x eq 9" if $x eq '9';
        print "$x eq 9" if $x eq 3*3;

        print "$x == 9" if $x == $y;
        print "$x == 9" if $x == 9;
        print "$x == 9" if $x == 3*3;

"bsstr()"
1e+2
100
        use Test::More tests => 3;
        use Math::BigInt;
        $x = Math::BigInt->new('1e56'); $y = 1e56;
        is ($x,$y);                     # will fail
        is ($x->bsstr(),$y);            # okay
        $y = Math::BigInt->new($y);
        is ($x,$y);                     # okay

"<=>"
"int()"
        $x = Math::BigInt->new(123);
        $y = int($x);                           # BigInt 123
        $x = Math::BigFloat->new(123.45);
        $y = int($x);                           # BigInt 123

"as_number()"
"as_int"
        $x = Math::BigFloat->new(123.45);
        $y = $x->as_number();                   # BigInt 123
        $y = $x->as_int();                      # ditto

"numify()"
        $y = $x->numify();                      # 123 as scalar

        $z = $array[$x];                        # does work automatically

        $c = Math::BigInt->new(123);
        print $c->length(),"\n";                # prints 30

"length()"
        print scalar $c->length(),"\n";         # prints 3

        print $c->bdiv(10000),"\n";

"bdiv()"
"bdiv()"
$c
        print $c / 10000,"\n";

$c
        print scalar $c->bdiv(10000),"\n";

          1 / 4  => ( 0, 1)
          1 / -4 => (-1,-3)
         -3 / 4  => (-1, 1)
         -3 / -4 => ( 0,-3)
        -11 / 2  => (-5,1)
         11 /-2  => (-5,-1)

        $x == ($x / $y) * $y + ($x % $y)

$x
$y
$y
$x
        A /  B  =   C,     R so that C *    B +    R =    A
     =========================================================
        5 /   8 =   0,     5         0 *    8 +    5 =    5
        0 /   8 =   0,     0         0 *    8 +    0 =    0
        0 / inf =   0,     0         0 *  inf +    0 =    0
        0 /-inf =   0,     0         0 * -inf +    0 =    0
        5 / inf =   0,     5         0 *  inf +    5 =    5
        5 /-inf =   0,     5         0 * -inf +    5 =    5
        -5/ inf =   0,    -5         0 *  inf +   -5 =   -5
        -5/-inf =   0,    -5         0 * -inf +   -5 =   -5
       inf/   5 =  inf,    0       inf *    5 +    0 =  inf
      -inf/   5 = -inf,    0      -inf *    5 +    0 = -inf
       inf/  -5 = -inf,    0      -inf *   -5 +    0 =  inf
      -inf/  -5 =  inf,    0       inf *   -5 +    0 = -inf
         5/   5 =    1,    0         1 *    5 +    0 =    5
        -5/  -5 =    1,    0         1 *   -5 +    0 =   -5
       inf/ inf =    1,    0         1 *  inf +    0 =  inf
      -inf/-inf =    1,    0         1 * -inf +    0 = -inf
       inf/-inf =   -1,    0        -1 * -inf +    0 =  inf
      -inf/ inf =   -1,    0         1 * -inf +    0 = -inf
         8/   0 =  inf,    8       inf *    0 +    8 =    8
       inf/   0 =  inf,  inf       inf *    0 +  inf =  inf
         0/   0 =  NaN

        A /  B  =   C,     R so that C *    B +    R =    A
     ========================================================
      -inf/   0 = -inf, -inf      -inf *    0 +  inf = -inf
        -8/   0 = -inf,   -8      -inf *    0 +    8 = -8

        $x = Math::BigFloat->new(5);
        $y = $x;

$x
$y
$x
$y
"="
        $x->bmul(2);
        print "$x, $y\n";       # prints '10, 10'

$x
        $y = $x->copy();

        $y = $x->copy()->bmul(2);

"="
"bpow()"
"badd()"
$x
        print bpow($x,$i),"\n";         # modify $x
        print $x->bpow($i),"\n";        # ditto
        print $x **= $i,"\n";           # the same
        print $x ** $i,"\n";            # leave $x alone

"$x **= $y"
"$x = $x ** $y;"
        $x = -$x;

        $x->bneg();

"sub($x,0,1);"
"neg($x)"
$x
$x
$x
        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)

        $float = Math::BigFloat->new($mbi2) / $mbi;     # = 2.5

        $float = Math::BigFloat->new($mbi2 / $mbi);     # = 2

        $integer = ($mbi2 + $mbi) / $mbf;               # int / float => int
        $integer = $mbi2 / Math::BigFloat->new($mbi);   # ditto

        $float = 2 + $mbf;
        $float = $mbf + 2;

"bsqrt()"
        $x = Math::BigFloat->new(12);
        Math::BigFloat->precision(0);
        Math::BigFloat->round_mode('even');
        print $x->copy->bsqrt(),"\n";           # 4
        Math::BigFloat->precision(2);
        print $x->bsqrt(),"\n";                 # 3.46
        print $x->bsqrt(3),"\n";                # 3.464

"bug-math-bigint at rt.cpan.org"
    perldoc Math::BigInt

"bignum at lists.scsys.co.uk"

SYNOPSIS

DESCRIPTION

Input

Output

METHODS

ACCURACY and PRECISION

Precision P

Accuracy A

Fallback F

Rounding mode R

Infinity and Not a Number

INTERNALS

MATH LIBRARY

SIGN

mantissa(), exponent() and parts()

EXAMPLES

Autocreating constants

PERFORMANCE

Alternative math libraries

SUBCLASSING

Subclassing Math::BigInt

UPGRADING

Auto-upgrade

EXPORTS

CAVEATS

BUGS

SUPPORT

LICENSE

AUTHORS

LAST SEARCHED