1Math::BigInt(3)       User Contributed Perl Documentation      Math::BigInt(3)
2
3
4

NAME

6       Math::BigInt - Arbitrary size integer/float math package
7

SYNOPSIS

9         use Math::BigInt;
10
11         # or make it faster with huge numbers: install (optional)
12         # Math::BigInt::GMP and always use (it falls back to
13         # pure Perl if the GMP library is not installed):
14         # (See also the L<MATH LIBRARY> section!)
15
16         # warns if Math::BigInt::GMP cannot be found
17         use Math::BigInt lib => 'GMP';
18
19         # to suppress the warning use this:
20         # use Math::BigInt try => 'GMP';
21
22         # dies if GMP cannot be loaded:
23         # use Math::BigInt only => 'GMP';
24
25         my $str = '1234567890';
26         my @values = (64, 74, 18);
27         my $n = 1; my $sign = '-';
28
29         # Configuration methods (may be used as class methods and instance methods)
30
31         Math::BigInt->accuracy();     # get class accuracy
32         Math::BigInt->accuracy($n);   # set class accuracy
33         Math::BigInt->precision();    # get class precision
34         Math::BigInt->precision($n);  # set class precision
35         Math::BigInt->round_mode();   # get class rounding mode
36         Math::BigInt->round_mode($m); # set global round mode, must be one of
37                                       # 'even', 'odd', '+inf', '-inf', 'zero',
38                                       # 'trunc', or 'common'
39         Math::BigInt->config();       # return hash with configuration
40
41         # Constructor methods (when the class methods below are used as instance
42         # methods, the value is assigned the invocand)
43
44         $x = Math::BigInt->new($str);             # defaults to 0
45         $x = Math::BigInt->new('0x123');          # from hexadecimal
46         $x = Math::BigInt->new('0b101');          # from binary
47         $x = Math::BigInt->from_hex('cafe');      # from hexadecimal
48         $x = Math::BigInt->from_oct('377');       # from octal
49         $x = Math::BigInt->from_bin('1101');      # from binary
50         $x = Math::BigInt->from_base('why', 36);  # from any base
51         $x = Math::BigInt->bzero();               # create a +0
52         $x = Math::BigInt->bone();                # create a +1
53         $x = Math::BigInt->bone('-');             # create a -1
54         $x = Math::BigInt->binf();                # create a +inf
55         $x = Math::BigInt->binf('-');             # create a -inf
56         $x = Math::BigInt->bnan();                # create a Not-A-Number
57         $x = Math::BigInt->bpi();                 # returns pi
58
59         $y = $x->copy();         # make a copy (unlike $y = $x)
60         $y = $x->as_int();       # return as a Math::BigInt
61
62         # Boolean methods (these don't modify the invocand)
63
64         $x->is_zero();          # if $x is 0
65         $x->is_one();           # if $x is +1
66         $x->is_one("+");        # ditto
67         $x->is_one("-");        # if $x is -1
68         $x->is_inf();           # if $x is +inf or -inf
69         $x->is_inf("+");        # if $x is +inf
70         $x->is_inf("-");        # if $x is -inf
71         $x->is_nan();           # if $x is NaN
72
73         $x->is_positive();      # if $x > 0
74         $x->is_pos();           # ditto
75         $x->is_negative();      # if $x < 0
76         $x->is_neg();           # ditto
77
78         $x->is_odd();           # if $x is odd
79         $x->is_even();          # if $x is even
80         $x->is_int();           # if $x is an integer
81
82         # Comparison methods
83
84         $x->bcmp($y);           # compare numbers (undef, < 0, == 0, > 0)
85         $x->bacmp($y);          # compare absolutely (undef, < 0, == 0, > 0)
86         $x->beq($y);            # true if and only if $x == $y
87         $x->bne($y);            # true if and only if $x != $y
88         $x->blt($y);            # true if and only if $x < $y
89         $x->ble($y);            # true if and only if $x <= $y
90         $x->bgt($y);            # true if and only if $x > $y
91         $x->bge($y);            # true if and only if $x >= $y
92
93         # Arithmetic methods
94
95         $x->bneg();             # negation
96         $x->babs();             # absolute value
97         $x->bsgn();             # sign function (-1, 0, 1, or NaN)
98         $x->bnorm();            # normalize (no-op)
99         $x->binc();             # increment $x by 1
100         $x->bdec();             # decrement $x by 1
101         $x->badd($y);           # addition (add $y to $x)
102         $x->bsub($y);           # subtraction (subtract $y from $x)
103         $x->bmul($y);           # multiplication (multiply $x by $y)
104         $x->bmuladd($y,$z);     # $x = $x * $y + $z
105         $x->bdiv($y);           # division (floored), set $x to quotient
106                                 # return (quo,rem) or quo if scalar
107         $x->btdiv($y);          # division (truncated), set $x to quotient
108                                 # return (quo,rem) or quo if scalar
109         $x->bmod($y);           # modulus (x % y)
110         $x->btmod($y);          # modulus (truncated)
111         $x->bmodinv($mod);      # modular multiplicative inverse
112         $x->bmodpow($y,$mod);   # modular exponentiation (($x ** $y) % $mod)
113         $x->bpow($y);           # power of arguments (x ** y)
114         $x->blog();             # logarithm of $x to base e (Euler's number)
115         $x->blog($base);        # logarithm of $x to base $base (e.g., base 2)
116         $x->bexp();             # calculate e ** $x where e is Euler's number
117         $x->bnok($y);           # x over y (binomial coefficient n over k)
118         $x->buparrow($n, $y);   # Knuth's up-arrow notation
119         $x->backermann($y);     # the Ackermann function
120         $x->bsin();             # sine
121         $x->bcos();             # cosine
122         $x->batan();            # inverse tangent
123         $x->batan2($y);         # two-argument inverse tangent
124         $x->bsqrt();            # calculate square root
125         $x->broot($y);          # $y'th root of $x (e.g. $y == 3 => cubic root)
126         $x->bfac();             # factorial of $x (1*2*3*4*..$x)
127
128         $x->blsft($n);          # left shift $n places in base 2
129         $x->blsft($n,$b);       # left shift $n places in base $b
130                                 # returns (quo,rem) or quo (scalar context)
131         $x->brsft($n);          # right shift $n places in base 2
132         $x->brsft($n,$b);       # right shift $n places in base $b
133                                 # returns (quo,rem) or quo (scalar context)
134
135         # Bitwise methods
136
137         $x->band($y);           # bitwise and
138         $x->bior($y);           # bitwise inclusive or
139         $x->bxor($y);           # bitwise exclusive or
140         $x->bnot();             # bitwise not (two's complement)
141
142         # Rounding methods
143         $x->round($A,$P,$mode); # round to accuracy or precision using
144                                 # rounding mode $mode
145         $x->bround($n);         # accuracy: preserve $n digits
146         $x->bfround($n);        # $n > 0: round to $nth digit left of dec. point
147                                 # $n < 0: round to $nth digit right of dec. point
148         $x->bfloor();           # round towards minus infinity
149         $x->bceil();            # round towards plus infinity
150         $x->bint();             # round towards zero
151
152         # Other mathematical methods
153
154         $x->bgcd($y);            # greatest common divisor
155         $x->blcm($y);            # least common multiple
156
157         # Object property methods (do not modify the invocand)
158
159         $x->sign();              # the sign, either +, - or NaN
160         $x->digit($n);           # the nth digit, counting from the right
161         $x->digit(-$n);          # the nth digit, counting from the left
162         $x->length();            # return number of digits in number
163         ($xl,$f) = $x->length(); # length of number and length of fraction
164                                  # part, latter is always 0 digits long
165                                  # for Math::BigInt objects
166         $x->mantissa();          # return (signed) mantissa as a Math::BigInt
167         $x->exponent();          # return exponent as a Math::BigInt
168         $x->parts();             # return (mantissa,exponent) as a Math::BigInt
169         $x->sparts();            # mantissa and exponent (as integers)
170         $x->nparts();            # mantissa and exponent (normalised)
171         $x->eparts();            # mantissa and exponent (engineering notation)
172         $x->dparts();            # integer and fraction part
173
174         # Conversion methods (do not modify the invocand)
175
176         $x->bstr();         # decimal notation, possibly zero padded
177         $x->bsstr();        # string in scientific notation with integers
178         $x->bnstr();        # string in normalized notation
179         $x->bestr();        # string in engineering notation
180         $x->bdstr();        # string in decimal notation
181
182         $x->to_hex();       # as signed hexadecimal string
183         $x->to_bin();       # as signed binary string
184         $x->to_oct();       # as signed octal string
185         $x->to_bytes();     # as byte string
186         $x->to_base($b);    # as string in any base
187
188         $x->as_hex();       # as signed hexadecimal string with prefixed 0x
189         $x->as_bin();       # as signed binary string with prefixed 0b
190         $x->as_oct();       # as signed octal string with prefixed 0
191
192         # Other conversion methods
193
194         $x->numify();           # return as scalar (might overflow or underflow)
195

DESCRIPTION

197       Math::BigInt provides support for arbitrary precision integers.
198       Overloading is also provided for Perl operators.
199
200   Input
201       Input values to these routines may be any scalar number or string that
202       looks like a number and represents an integer.
203
204       •   Leading and trailing whitespace is ignored.
205
206       •   Leading and trailing zeros are ignored.
207
208       •   If the string has a "0x" prefix, it is interpreted as a hexadecimal
209           number.
210
211       •   If the string has a "0b" prefix, it is interpreted as a binary
212           number.
213
214       •   One underline is allowed between any two digits.
215
216       •   If the string can not be interpreted, NaN is returned.
217
218       Octal numbers are typically prefixed by "0", but since leading zeros
219       are stripped, these methods can not automatically recognize octal
220       numbers, so use the constructor from_oct() to interpret octal strings.
221
222       Some examples of valid string input
223
224           Input string                Resulting value
225           123                         123
226           1.23e2                      123
227           12300e-2                    123
228           0xcafe                      51966
229           0b1101                      13
230           67_538_754                  67538754
231           -4_5_6.7_8_9e+0_1_0         -4567890000000
232
233       Input given as scalar numbers might lose precision. Quote your input to
234       ensure that no digits are lost:
235
236           $x = Math::BigInt->new( 56789012345678901234 );   # bad
237           $x = Math::BigInt->new('56789012345678901234');   # good
238
239       Currently, Math::BigInt->new() defaults to 0, while
240       Math::BigInt->new('') results in 'NaN'. This might change in the
241       future, so use always the following explicit forms to get a zero or
242       NaN:
243
244           $zero = Math::BigInt->bzero();
245           $nan  = Math::BigInt->bnan();
246
247   Output
248       Output values are usually Math::BigInt objects.
249
250       Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
251       or false.
252
253       Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
254

METHODS

256   Configuration methods
257       Each of the methods below (except config(), accuracy() and precision())
258       accepts three additional parameters. These arguments $A, $P and $R are
259       "accuracy", "precision" and "round_mode". Please see the section about
260       "ACCURACY and PRECISION" for more information.
261
262       Setting a class variable effects all object instance that are created
263       afterwards.
264
265       accuracy()
266               Math::BigInt->accuracy(5);      # set class accuracy
267               $x->accuracy(5);                # set instance accuracy
268
269               $A = Math::BigInt->accuracy();  # get class accuracy
270               $A = $x->accuracy();            # get instance accuracy
271
272           Set or get the accuracy, i.e., the number of significant digits.
273           The accuracy must be an integer. If the accuracy is set to "undef",
274           no rounding is done.
275
276           Alternatively, one can round the results explicitly using one of
277           "round()", "bround()" or "bfround()" or by passing the desired
278           accuracy to the method as an additional parameter:
279
280               my $x = Math::BigInt->new(30000);
281               my $y = Math::BigInt->new(7);
282               print scalar $x->copy()->bdiv($y, 2);               # prints 4300
283               print scalar $x->copy()->bdiv($y)->bround(2);       # prints 4300
284
285           Please see the section about "ACCURACY and PRECISION" for further
286           details.
287
288               $y = Math::BigInt->new(1234567);    # $y is not rounded
289               Math::BigInt->accuracy(4);          # set class accuracy to 4
290               $x = Math::BigInt->new(1234567);    # $x is rounded automatically
291               print "$x $y";                      # prints "1235000 1234567"
292
293               print $x->accuracy();       # prints "4"
294               print $y->accuracy();       # also prints "4", since
295                                           #   class accuracy is 4
296
297               Math::BigInt->accuracy(5);  # set class accuracy to 5
298               print $x->accuracy();       # prints "4", since instance
299                                           #   accuracy is 4
300               print $y->accuracy();       # prints "5", since no instance
301                                           #   accuracy, and class accuracy is 5
302
303           Note: Each class has it's own globals separated from Math::BigInt,
304           but it is possible to subclass Math::BigInt and make the globals of
305           the subclass aliases to the ones from Math::BigInt.
306
307       precision()
308               Math::BigInt->precision(-2);     # set class precision
309               $x->precision(-2);               # set instance precision
310
311               $P = Math::BigInt->precision();  # get class precision
312               $P = $x->precision();            # get instance precision
313
314           Set or get the precision, i.e., the place to round relative to the
315           decimal point. The precision must be a integer. Setting the
316           precision to $P means that each number is rounded up or down,
317           depending on the rounding mode, to the nearest multiple of 10**$P.
318           If the precision is set to "undef", no rounding is done.
319
320           You might want to use "accuracy()" instead. With "accuracy()" you
321           set the number of digits each result should have, with
322           "precision()" you set the place where to round.
323
324           Please see the section about "ACCURACY and PRECISION" for further
325           details.
326
327               $y = Math::BigInt->new(1234567);    # $y is not rounded
328               Math::BigInt->precision(4);         # set class precision to 4
329               $x = Math::BigInt->new(1234567);    # $x is rounded automatically
330               print $x;                           # prints "1230000"
331
332           Note: Each class has its own globals separated from Math::BigInt,
333           but it is possible to subclass Math::BigInt and make the globals of
334           the subclass aliases to the ones from Math::BigInt.
335
336       div_scale()
337           Set/get the fallback accuracy. This is the accuracy used when
338           neither accuracy nor precision is set explicitly. It is used when a
339           computation might otherwise attempt to return an infinite number of
340           digits.
341
342       round_mode()
343           Set/get the rounding mode.
344
345       upgrade()
346           Set/get the class for upgrading. When a computation might result in
347           a non-integer, the operands are upgraded to this class. This is
348           used for instance by bignum. The default is "undef", thus the
349           following operation creates a Math::BigInt, not a Math::BigFloat:
350
351               my $i = Math::BigInt->new(123);
352               my $f = Math::BigFloat->new('123.1');
353
354               print $i + $f, "\n";                # prints 246
355
356       downgrade()
357           Set/get the class for downgrading. The default is "undef".
358           Downgrading is not done by Math::BigInt.
359
360       modify()
361               $x->modify('bpowd');
362
363           This method returns 0 if the object can be modified with the given
364           operation, or 1 if not.
365
366           This is used for instance by Math::BigInt::Constant.
367
368       config()
369               Math::BigInt->config("trap_nan" => 1);      # set
370               $accu = Math::BigInt->config("accuracy");   # get
371
372           Set or get class variables. Read-only parameters are marked as RO.
373           Read-write parameters are marked as RW. The following parameters
374           are supported.
375
376               Parameter       RO/RW   Description
377                                       Example
378               ============================================================
379               lib             RO      Name of the math backend library
380                                       Math::BigInt::Calc
381               lib_version     RO      Version of the math backend library
382                                       0.30
383               class           RO      The class of config you just called
384                                       Math::BigRat
385               version         RO      version number of the class you used
386                                       0.10
387               upgrade         RW      To which class numbers are upgraded
388                                       undef
389               downgrade       RW      To which class numbers are downgraded
390                                       undef
391               precision       RW      Global precision
392                                       undef
393               accuracy        RW      Global accuracy
394                                       undef
395               round_mode      RW      Global round mode
396                                       even
397               div_scale       RW      Fallback accuracy for division etc.
398                                       40
399               trap_nan        RW      Trap NaNs
400                                       undef
401               trap_inf        RW      Trap +inf/-inf
402                                       undef
403
404   Constructor methods
405       new()
406               $x = Math::BigInt->new($str,$A,$P,$R);
407
408           Creates a new Math::BigInt object from a scalar or another
409           Math::BigInt object.  The input is accepted as decimal, hexadecimal
410           (with leading '0x') or binary (with leading '0b').
411
412           See "Input" for more info on accepted input formats.
413
414       from_hex()
415               $x = Math::BigInt->from_hex("0xcafe");    # input is hexadecimal
416
417           Interpret input as a hexadecimal string. A "0x" or "x" prefix is
418           optional. A single underscore character may be placed right after
419           the prefix, if present, or between any two digits. If the input is
420           invalid, a NaN is returned.
421
422       from_oct()
423               $x = Math::BigInt->from_oct("0775");      # input is octal
424
425           Interpret the input as an octal string and return the corresponding
426           value. A "0" (zero) prefix is optional. A single underscore
427           character may be placed right after the prefix, if present, or
428           between any two digits. If the input is invalid, a NaN is returned.
429
430       from_bin()
431               $x = Math::BigInt->from_bin("0b10011");   # input is binary
432
433           Interpret the input as a binary string. A "0b" or "b" prefix is
434           optional. A single underscore character may be placed right after
435           the prefix, if present, or between any two digits. If the input is
436           invalid, a NaN is returned.
437
438       from_bytes()
439               $x = Math::BigInt->from_bytes("\xf3\x6b");  # $x = 62315
440
441           Interpret the input as a byte string, assuming big endian byte
442           order. The output is always a non-negative, finite integer.
443
444           In some special cases, from_bytes() matches the conversion done by
445           unpack():
446
447               $b = "\x4e";                             # one char byte string
448               $x = Math::BigInt->from_bytes($b);       # = 78
449               $y = unpack "C", $b;                     # ditto, but scalar
450
451               $b = "\xf3\x6b";                         # two char byte string
452               $x = Math::BigInt->from_bytes($b);       # = 62315
453               $y = unpack "S>", $b;                    # ditto, but scalar
454
455               $b = "\x2d\xe0\x49\xad";                 # four char byte string
456               $x = Math::BigInt->from_bytes($b);       # = 769673645
457               $y = unpack "L>", $b;                    # ditto, but scalar
458
459               $b = "\x2d\xe0\x49\xad\x2d\xe0\x49\xad"; # eight char byte string
460               $x = Math::BigInt->from_bytes($b);       # = 3305723134637787565
461               $y = unpack "Q>", $b;                    # ditto, but scalar
462
463       from_base()
464           Given a string, a base, and an optional collation sequence,
465           interpret the string as a number in the given base. The collation
466           sequence describes the value of each character in the string.
467
468           If a collation sequence is not given, a default collation sequence
469           is used. If the base is less than or equal to 36, the collation
470           sequence is the string consisting of the 36 characters "0" to "9"
471           and "A" to "Z". In this case, the letter case in the input is
472           ignored. If the base is greater than 36, and smaller than or equal
473           to 62, the collation sequence is the string consisting of the 62
474           characters "0" to "9", "A" to "Z", and "a" to "z". A base larger
475           than 62 requires the collation sequence to be specified explicitly.
476
477           These examples show standard binary, octal, and hexadecimal
478           conversion. All cases return 250.
479
480               $x = Math::BigInt->from_base("11111010", 2);
481               $x = Math::BigInt->from_base("372", 8);
482               $x = Math::BigInt->from_base("fa", 16);
483
484           When the base is less than or equal to 36, and no collation
485           sequence is given, the letter case is ignored, so both of these
486           also return 250:
487
488               $x = Math::BigInt->from_base("6Y", 16);
489               $x = Math::BigInt->from_base("6y", 16);
490
491           When the base greater than 36, and no collation sequence is given,
492           the default collation sequence contains both uppercase and
493           lowercase letters, so the letter case in the input is not ignored:
494
495               $x = Math::BigInt->from_base("6S", 37);         # $x is 250
496               $x = Math::BigInt->from_base("6s", 37);         # $x is 276
497               $x = Math::BigInt->from_base("121", 3);         # $x is 16
498               $x = Math::BigInt->from_base("XYZ", 36);        # $x is 44027
499               $x = Math::BigInt->from_base("Why", 42);        # $x is 58314
500
501           The collation sequence can be any set of unique characters. These
502           two cases are equivalent
503
504               $x = Math::BigInt->from_base("100", 2, "01");   # $x is 4
505               $x = Math::BigInt->from_base("|--", 2, "-|");   # $x is 4
506
507       bzero()
508               $x = Math::BigInt->bzero();
509               $x->bzero();
510
511           Returns a new Math::BigInt object representing zero. If used as an
512           instance method, assigns the value to the invocand.
513
514       bone()
515               $x = Math::BigInt->bone();          # +1
516               $x = Math::BigInt->bone("+");       # +1
517               $x = Math::BigInt->bone("-");       # -1
518               $x->bone();                         # +1
519               $x->bone("+");                      # +1
520               $x->bone('-');                      # -1
521
522           Creates a new Math::BigInt object representing one. The optional
523           argument is either '-' or '+', indicating whether you want plus one
524           or minus one. If used as an instance method, assigns the value to
525           the invocand.
526
527       binf()
528               $x = Math::BigInt->binf($sign);
529
530           Creates a new Math::BigInt object representing infinity. The
531           optional argument is either '-' or '+', indicating whether you want
532           infinity or minus infinity.  If used as an instance method, assigns
533           the value to the invocand.
534
535               $x->binf();
536               $x->binf('-');
537
538       bnan()
539               $x = Math::BigInt->bnan();
540
541           Creates a new Math::BigInt object representing NaN (Not A Number).
542           If used as an instance method, assigns the value to the invocand.
543
544               $x->bnan();
545
546       bpi()
547               $x = Math::BigInt->bpi(100);        # 3
548               $x->bpi(100);                       # 3
549
550           Creates a new Math::BigInt object representing PI. If used as an
551           instance method, assigns the value to the invocand. With
552           Math::BigInt this always returns 3.
553
554           If upgrading is in effect, returns PI, rounded to N digits with the
555           current rounding mode:
556
557               use Math::BigFloat;
558               use Math::BigInt upgrade => "Math::BigFloat";
559               print Math::BigInt->bpi(3), "\n";           # 3.14
560               print Math::BigInt->bpi(100), "\n";         # 3.1415....
561
562       copy()
563               $x->copy();         # make a true copy of $x (unlike $y = $x)
564
565       as_int()
566       as_number()
567           These methods are called when Math::BigInt encounters an object it
568           doesn't know how to handle. For instance, assume $x is a
569           Math::BigInt, or subclass thereof, and $y is defined, but not a
570           Math::BigInt, or subclass thereof. If you do
571
572               $x -> badd($y);
573
574           $y needs to be converted into an object that $x can deal with. This
575           is done by first checking if $y is something that $x might be
576           upgraded to. If that is the case, no further attempts are made. The
577           next is to see if $y supports the method "as_int()". If it does,
578           "as_int()" is called, but if it doesn't, the next thing is to see
579           if $y supports the method "as_number()". If it does, "as_number()"
580           is called. The method "as_int()" (and "as_number()") is expected to
581           return either an object that has the same class as $x, a subclass
582           thereof, or a string that "ref($x)->new()" can parse to create an
583           object.
584
585           "as_number()" is an alias to "as_int()". "as_number" was introduced
586           in v1.22, while "as_int()" was introduced in v1.68.
587
588           In Math::BigInt, "as_int()" has the same effect as "copy()".
589
590   Boolean methods
591       None of these methods modify the invocand object.
592
593       is_zero()
594               $x->is_zero();              # true if $x is 0
595
596           Returns true if the invocand is zero and false otherwise.
597
598       is_one( [ SIGN ])
599               $x->is_one();               # true if $x is +1
600               $x->is_one("+");            # ditto
601               $x->is_one("-");            # true if $x is -1
602
603           Returns true if the invocand is one and false otherwise.
604
605       is_finite()
606               $x->is_finite();    # true if $x is not +inf, -inf or NaN
607
608           Returns true if the invocand is a finite number, i.e., it is
609           neither +inf, -inf, nor NaN.
610
611       is_inf( [ SIGN ] )
612               $x->is_inf();               # true if $x is +inf
613               $x->is_inf("+");            # ditto
614               $x->is_inf("-");            # true if $x is -inf
615
616           Returns true if the invocand is infinite and false otherwise.
617
618       is_nan()
619               $x->is_nan();               # true if $x is NaN
620
621       is_positive()
622       is_pos()
623               $x->is_positive();          # true if > 0
624               $x->is_pos();               # ditto
625
626           Returns true if the invocand is positive and false otherwise. A
627           "NaN" is neither positive nor negative.
628
629       is_negative()
630       is_neg()
631               $x->is_negative();          # true if < 0
632               $x->is_neg();               # ditto
633
634           Returns true if the invocand is negative and false otherwise. A
635           "NaN" is neither positive nor negative.
636
637       is_non_positive()
638               $x->is_non_positive();      # true if <= 0
639
640           Returns true if the invocand is negative or zero.
641
642       is_non_negative()
643               $x->is_non_negative();      # true if >= 0
644
645           Returns true if the invocand is positive or zero.
646
647       is_odd()
648               $x->is_odd();               # true if odd, false for even
649
650           Returns true if the invocand is odd and false otherwise. "NaN",
651           "+inf", and "-inf" are neither odd nor even.
652
653       is_even()
654               $x->is_even();              # true if $x is even
655
656           Returns true if the invocand is even and false otherwise. "NaN",
657           "+inf", "-inf" are not integers and are neither odd nor even.
658
659       is_int()
660               $x->is_int();               # true if $x is an integer
661
662           Returns true if the invocand is an integer and false otherwise.
663           "NaN", "+inf", "-inf" are not integers.
664
665   Comparison methods
666       None of these methods modify the invocand object. Note that a "NaN" is
667       neither less than, greater than, or equal to anything else, even a
668       "NaN".
669
670       bcmp()
671               $x->bcmp($y);
672
673           Returns -1, 0, 1 depending on whether $x is less than, equal to, or
674           grater than $y. Returns undef if any operand is a NaN.
675
676       bacmp()
677               $x->bacmp($y);
678
679           Returns -1, 0, 1 depending on whether the absolute value of $x is
680           less than, equal to, or grater than the absolute value of $y.
681           Returns undef if any operand is a NaN.
682
683       beq()
684               $x -> beq($y);
685
686           Returns true if and only if $x is equal to $y, and false otherwise.
687
688       bne()
689               $x -> bne($y);
690
691           Returns true if and only if $x is not equal to $y, and false
692           otherwise.
693
694       blt()
695               $x -> blt($y);
696
697           Returns true if and only if $x is equal to $y, and false otherwise.
698
699       ble()
700               $x -> ble($y);
701
702           Returns true if and only if $x is less than or equal to $y, and
703           false otherwise.
704
705       bgt()
706               $x -> bgt($y);
707
708           Returns true if and only if $x is greater than $y, and false
709           otherwise.
710
711       bge()
712               $x -> bge($y);
713
714           Returns true if and only if $x is greater than or equal to $y, and
715           false otherwise.
716
717   Arithmetic methods
718       These methods modify the invocand object and returns it.
719
720       bneg()
721               $x->bneg();
722
723           Negate the number, e.g. change the sign between '+' and '-', or
724           between '+inf' and '-inf', respectively. Does nothing for NaN or
725           zero.
726
727       babs()
728               $x->babs();
729
730           Set the number to its absolute value, e.g. change the sign from '-'
731           to '+' and from '-inf' to '+inf', respectively. Does nothing for
732           NaN or positive numbers.
733
734       bsgn()
735               $x->bsgn();
736
737           Signum function. Set the number to -1, 0, or 1, depending on
738           whether the number is negative, zero, or positive, respectively.
739           Does not modify NaNs.
740
741       bnorm()
742               $x->bnorm();                        # normalize (no-op)
743
744           Normalize the number. This is a no-op and is provided only for
745           backwards compatibility.
746
747       binc()
748               $x->binc();                 # increment x by 1
749
750       bdec()
751               $x->bdec();                 # decrement x by 1
752
753       badd()
754               $x->badd($y);               # addition (add $y to $x)
755
756       bsub()
757               $x->bsub($y);               # subtraction (subtract $y from $x)
758
759       bmul()
760               $x->bmul($y);               # multiplication (multiply $x by $y)
761
762       bmuladd()
763               $x->bmuladd($y,$z);
764
765           Multiply $x by $y, and then add $z to the result,
766
767           This method was added in v1.87 of Math::BigInt (June 2007).
768
769       bdiv()
770               $x->bdiv($y);               # divide, set $x to quotient
771
772           Divides $x by $y by doing floored division (F-division), where the
773           quotient is the floored (rounded towards negative infinity)
774           quotient of the two operands.  In list context, returns the
775           quotient and the remainder. The remainder is either zero or has the
776           same sign as the second operand. In scalar context, only the
777           quotient is returned.
778
779           The quotient is always the greatest integer less than or equal to
780           the real-valued quotient of the two operands, and the remainder
781           (when it is non-zero) always has the same sign as the second
782           operand; so, for example,
783
784                 1 /  4  => ( 0,  1)
785                 1 / -4  => (-1, -3)
786                -3 /  4  => (-1,  1)
787                -3 / -4  => ( 0, -3)
788               -11 /  2  => (-5,  1)
789                11 / -2  => (-5, -1)
790
791           The behavior of the overloaded operator % agrees with the behavior
792           of Perl's built-in % operator (as documented in the perlop
793           manpage), and the equation
794
795               $x == ($x / $y) * $y + ($x % $y)
796
797           holds true for any finite $x and finite, non-zero $y.
798
799           Perl's "use integer" might change the behaviour of % and / for
800           scalars. This is because under 'use integer' Perl does what the
801           underlying C library thinks is right, and this varies. However,
802           "use integer" does not change the way things are done with
803           Math::BigInt objects.
804
805       btdiv()
806               $x->btdiv($y);              # divide, set $x to quotient
807
808           Divides $x by $y by doing truncated division (T-division), where
809           quotient is the truncated (rouneded towards zero) quotient of the
810           two operands. In list context, returns the quotient and the
811           remainder. The remainder is either zero or has the same sign as the
812           first operand. In scalar context, only the quotient is returned.
813
814       bmod()
815               $x->bmod($y);               # modulus (x % y)
816
817           Returns $x modulo $y, i.e., the remainder after floored division
818           (F-division).  This method is like Perl's % operator. See "bdiv()".
819
820       btmod()
821               $x->btmod($y);              # modulus
822
823           Returns the remainer after truncated division (T-division). See
824           "btdiv()".
825
826       bmodinv()
827               $x->bmodinv($mod);          # modular multiplicative inverse
828
829           Returns the multiplicative inverse of $x modulo $mod. If
830
831               $y = $x -> copy() -> bmodinv($mod)
832
833           then $y is the number closest to zero, and with the same sign as
834           $mod, satisfying
835
836               ($x * $y) % $mod = 1 % $mod
837
838           If $x and $y are non-zero, they must be relative primes, i.e.,
839           "bgcd($y, $mod)==1". '"NaN"' is returned when no modular
840           multiplicative inverse exists.
841
842       bmodpow()
843               $num->bmodpow($exp,$mod);           # modular exponentiation
844                                                   # ($num**$exp % $mod)
845
846           Returns the value of $num taken to the power $exp in the modulus
847           $mod using binary exponentiation.  "bmodpow" is far superior to
848           writing
849
850               $num ** $exp % $mod
851
852           because it is much faster - it reduces internal variables into the
853           modulus whenever possible, so it operates on smaller numbers.
854
855           "bmodpow" also supports negative exponents.
856
857               bmodpow($num, -1, $mod)
858
859           is exactly equivalent to
860
861               bmodinv($num, $mod)
862
863       bpow()
864               $x->bpow($y);               # power of arguments (x ** y)
865
866           "bpow()" (and the rounding functions) now modifies the first
867           argument and returns it, unlike the old code which left it alone
868           and only returned the result. This is to be consistent with
869           "badd()" etc. The first three modifies $x, the last one won't:
870
871               print bpow($x,$i),"\n";         # modify $x
872               print $x->bpow($i),"\n";        # ditto
873               print $x **= $i,"\n";           # the same
874               print $x ** $i,"\n";            # leave $x alone
875
876           The form "$x **= $y" is faster than "$x = $x ** $y;", though.
877
878       blog()
879               $x->blog($base, $accuracy);         # logarithm of x to the base $base
880
881           If $base is not defined, Euler's number (e) is used:
882
883               print $x->blog(undef, 100);         # log(x) to 100 digits
884
885       bexp()
886               $x->bexp($accuracy);                # calculate e ** X
887
888           Calculates the expression "e ** $x" where "e" is Euler's number.
889
890           This method was added in v1.82 of Math::BigInt (April 2007).
891
892           See also "blog()".
893
894       bnok()
895               $x->bnok($y);               # x over y (binomial coefficient n over k)
896
897           Calculates the binomial coefficient n over k, also called the
898           "choose" function, which is
899
900               ( n )       n!
901               |   |  = --------
902               ( k )    k!(n-k)!
903
904           when n and k are non-negative. This method implements the full
905           Kronenburg extension (Kronenburg, M.J. "The Binomial Coefficient
906           for Negative Arguments."  18 May 2011.
907           http://arxiv.org/abs/1105.3689/) illustrated by the following
908           pseudo-code:
909
910               if n >= 0 and k >= 0:
911                   return binomial(n, k)
912               if k >= 0:
913                   return (-1)^k*binomial(-n+k-1, k)
914               if k <= n:
915                   return (-1)^(n-k)*binomial(-k-1, n-k)
916               else
917                   return 0
918
919           The behaviour is identical to the behaviour of the Maple and
920           Mathematica function for negative integers n, k.
921
922       buparrow()
923       uparrow()
924               $a -> buparrow($n, $b);         # modifies $a
925               $x = $a -> uparrow($n, $b);     # does not modify $a
926
927           This method implements Knuth's up-arrow notation, where $n is a
928           non-negative integer representing the number of up-arrows. $n = 0
929           gives multiplication, $n = 1 gives exponentiation, $n = 2 gives
930           tetration, $n = 3 gives hexation etc. The following illustrates the
931           relation between the first values of $n.
932
933           See <https://en.wikipedia.org/wiki/Knuth%27s_up-arrow_notation>.
934
935       backermann()
936       ackermann()
937               $m -> backermann($n);           # modifies $a
938               $x = $m -> ackermann($n);       # does not modify $a
939
940           This method implements the Ackermann function:
941
942                        / n + 1              if m = 0
943              A(m, n) = | A(m-1, 1)          if m > 0 and n = 0
944                        \ A(m-1, A(m, n-1))  if m > 0 and n > 0
945
946           Its value grows rapidly, even for small inputs. For example, A(4,
947           2) is an integer of 19729 decimal digits.
948
949           See https://en.wikipedia.org/wiki/Ackermann_function
950
951       bsin()
952               my $x = Math::BigInt->new(1);
953               print $x->bsin(100), "\n";
954
955           Calculate the sine of $x, modifying $x in place.
956
957           In Math::BigInt, unless upgrading is in effect, the result is
958           truncated to an integer.
959
960           This method was added in v1.87 of Math::BigInt (June 2007).
961
962       bcos()
963               my $x = Math::BigInt->new(1);
964               print $x->bcos(100), "\n";
965
966           Calculate the cosine of $x, modifying $x in place.
967
968           In Math::BigInt, unless upgrading is in effect, the result is
969           truncated to an integer.
970
971           This method was added in v1.87 of Math::BigInt (June 2007).
972
973       batan()
974               my $x = Math::BigFloat->new(0.5);
975               print $x->batan(100), "\n";
976
977           Calculate the arcus tangens of $x, modifying $x in place.
978
979           In Math::BigInt, unless upgrading is in effect, the result is
980           truncated to an integer.
981
982           This method was added in v1.87 of Math::BigInt (June 2007).
983
984       batan2()
985               my $x = Math::BigInt->new(1);
986               my $y = Math::BigInt->new(1);
987               print $y->batan2($x), "\n";
988
989           Calculate the arcus tangens of $y divided by $x, modifying $y in
990           place.
991
992           In Math::BigInt, unless upgrading is in effect, the result is
993           truncated to an integer.
994
995           This method was added in v1.87 of Math::BigInt (June 2007).
996
997       bsqrt()
998               $x->bsqrt();                # calculate square root
999
1000           "bsqrt()" returns the square root truncated to an integer.
1001
1002           If you want a better approximation of the square root, then use:
1003
1004               $x = Math::BigFloat->new(12);
1005               Math::BigFloat->precision(0);
1006               Math::BigFloat->round_mode('even');
1007               print $x->copy->bsqrt(),"\n";           # 4
1008
1009               Math::BigFloat->precision(2);
1010               print $x->bsqrt(),"\n";                 # 3.46
1011               print $x->bsqrt(3),"\n";                # 3.464
1012
1013       broot()
1014               $x->broot($N);
1015
1016           Calculates the N'th root of $x.
1017
1018       bfac()
1019               $x->bfac();                 # factorial of $x (1*2*3*4*..*$x)
1020
1021           Returns the factorial of $x, i.e., the product of all positive
1022           integers up to and including $x.
1023
1024       bdfac()
1025               $x->bdfac();                # double factorial of $x (1*2*3*4*..*$x)
1026
1027           Returns the double factorial of $x. If $x is an even integer,
1028           returns the product of all positive, even integers up to and
1029           including $x, i.e., 2*4*6*...*$x. If $x is an odd integer, returns
1030           the product of all positive, odd integers, i.e., 1*3*5*...*$x.
1031
1032       bfib()
1033               $F = $n->bfib();            # a single Fibonacci number
1034               @F = $n->bfib();            # a list of Fibonacci numbers
1035
1036           In scalar context, returns a single Fibonacci number. In list
1037           context, returns a list of Fibonacci numbers. The invocand is the
1038           last element in the output.
1039
1040           The Fibonacci sequence is defined by
1041
1042               F(0) = 0
1043               F(1) = 1
1044               F(n) = F(n-1) + F(n-2)
1045
1046           In list context, F(0) and F(n) is the first and last number in the
1047           output, respectively. For example, if $n is 12, then "@F =
1048           $n->bfib()" returns the following values, F(0) to F(12):
1049
1050               0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144
1051
1052           The sequence can also be extended to negative index n using the re-
1053           arranged recurrence relation
1054
1055               F(n-2) = F(n) - F(n-1)
1056
1057           giving the bidirectional sequence
1058
1059                  n  -7  -6  -5  -4  -3  -2  -1   0   1   2   3   4   5   6   7
1060               F(n)  13  -8   5  -3   2  -1   1   0   1   1   2   3   5   8  13
1061
1062           If $n is -12, the following values, F(0) to F(12), are returned:
1063
1064               0, 1, -1, 2, -3, 5, -8, 13, -21, 34, -55, 89, -144
1065
1066       blucas()
1067               $F = $n->blucas();          # a single Lucas number
1068               @F = $n->blucas();          # a list of Lucas numbers
1069
1070           In scalar context, returns a single Lucas number. In list context,
1071           returns a list of Lucas numbers. The invocand is the last element
1072           in the output.
1073
1074           The Lucas sequence is defined by
1075
1076               L(0) = 2
1077               L(1) = 1
1078               L(n) = L(n-1) + L(n-2)
1079
1080           In list context, L(0) and L(n) is the first and last number in the
1081           output, respectively. For example, if $n is 12, then "@L =
1082           $n->blucas()" returns the following values, L(0) to L(12):
1083
1084               2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322
1085
1086           The sequence can also be extended to negative index n using the re-
1087           arranged recurrence relation
1088
1089               L(n-2) = L(n) - L(n-1)
1090
1091           giving the bidirectional sequence
1092
1093                  n  -7  -6  -5  -4  -3  -2  -1   0   1   2   3   4   5   6   7
1094               L(n)  29 -18  11  -7   4  -3   1   2   1   3   4   7  11  18  29
1095
1096           If $n is -12, the following values, L(0) to L(-12), are returned:
1097
1098               2, 1, -3, 4, -7, 11, -18, 29, -47, 76, -123, 199, -322
1099
1100       brsft()
1101               $x->brsft($n);              # right shift $n places in base 2
1102               $x->brsft($n, $b);          # right shift $n places in base $b
1103
1104           The latter is equivalent to
1105
1106               $x -> bdiv($b -> copy() -> bpow($n))
1107
1108       blsft()
1109               $x->blsft($n);              # left shift $n places in base 2
1110               $x->blsft($n, $b);          # left shift $n places in base $b
1111
1112           The latter is equivalent to
1113
1114               $x -> bmul($b -> copy() -> bpow($n))
1115
1116   Bitwise methods
1117       band()
1118               $x->band($y);               # bitwise and
1119
1120       bior()
1121               $x->bior($y);               # bitwise inclusive or
1122
1123       bxor()
1124               $x->bxor($y);               # bitwise exclusive or
1125
1126       bnot()
1127               $x->bnot();                 # bitwise not (two's complement)
1128
1129           Two's complement (bitwise not). This is equivalent to, but faster
1130           than,
1131
1132               $x->binc()->bneg();
1133
1134   Rounding methods
1135       round()
1136               $x->round($A,$P,$round_mode);
1137
1138           Round $x to accuracy $A or precision $P using the round mode
1139           $round_mode.
1140
1141       bround()
1142               $x->bround($N);               # accuracy: preserve $N digits
1143
1144           Rounds $x to an accuracy of $N digits.
1145
1146       bfround()
1147               $x->bfround($N);
1148
1149           Rounds to a multiple of 10**$N. Examples:
1150
1151               Input            N          Result
1152
1153               123456.123456    3          123500
1154               123456.123456    2          123450
1155               123456.123456   -2          123456.12
1156               123456.123456   -3          123456.123
1157
1158       bfloor()
1159               $x->bfloor();
1160
1161           Round $x towards minus infinity, i.e., set $x to the largest
1162           integer less than or equal to $x.
1163
1164       bceil()
1165               $x->bceil();
1166
1167           Round $x towards plus infinity, i.e., set $x to the smallest
1168           integer greater than or equal to $x).
1169
1170       bint()
1171               $x->bint();
1172
1173           Round $x towards zero.
1174
1175   Other mathematical methods
1176       bgcd()
1177               $x -> bgcd($y);             # GCD of $x and $y
1178               $x -> bgcd($y, $z, ...);    # GCD of $x, $y, $z, ...
1179
1180           Returns the greatest common divisor (GCD).
1181
1182       blcm()
1183               $x -> blcm($y);             # LCM of $x and $y
1184               $x -> blcm($y, $z, ...);    # LCM of $x, $y, $z, ...
1185
1186           Returns the least common multiple (LCM).
1187
1188   Object property methods
1189       sign()
1190               $x->sign();
1191
1192           Return the sign, of $x, meaning either "+", "-", "-inf", "+inf" or
1193           NaN.
1194
1195           If you want $x to have a certain sign, use one of the following
1196           methods:
1197
1198               $x->babs();                 # '+'
1199               $x->babs()->bneg();         # '-'
1200               $x->bnan();                 # 'NaN'
1201               $x->binf();                 # '+inf'
1202               $x->binf('-');              # '-inf'
1203
1204       digit()
1205               $x->digit($n);       # return the nth digit, counting from right
1206
1207           If $n is negative, returns the digit counting from left.
1208
1209       digitsum()
1210               $x->digitsum();
1211
1212           Computes the sum of the base 10 digits and returns it.
1213
1214       bdigitsum()
1215               $x->bdigitsum();
1216
1217           Computes the sum of the base 10 digits and assigns the result to
1218           the invocand.
1219
1220       length()
1221               $x->length();
1222               ($xl, $fl) = $x->length();
1223
1224           Returns the number of digits in the decimal representation of the
1225           number. In list context, returns the length of the integer and
1226           fraction part. For Math::BigInt objects, the length of the fraction
1227           part is always 0.
1228
1229           The following probably doesn't do what you expect:
1230
1231               $c = Math::BigInt->new(123);
1232               print $c->length(),"\n";                # prints 30
1233
1234           It prints both the number of digits in the number and in the
1235           fraction part since print calls "length()" in list context. Use
1236           something like:
1237
1238               print scalar $c->length(),"\n";         # prints 3
1239
1240       mantissa()
1241               $x->mantissa();
1242
1243           Return the signed mantissa of $x as a Math::BigInt.
1244
1245       exponent()
1246               $x->exponent();
1247
1248           Return the exponent of $x as a Math::BigInt.
1249
1250       parts()
1251               $x->parts();
1252
1253           Returns the significand (mantissa) and the exponent as integers. In
1254           Math::BigFloat, both are returned as Math::BigInt objects.
1255
1256       sparts()
1257           Returns the significand (mantissa) and the exponent as integers. In
1258           scalar context, only the significand is returned. The significand
1259           is the integer with the smallest absolute value. The output of
1260           "sparts()" corresponds to the output from "bsstr()".
1261
1262           In Math::BigInt, this method is identical to "parts()".
1263
1264       nparts()
1265           Returns the significand (mantissa) and exponent corresponding to
1266           normalized notation. In scalar context, only the significand is
1267           returned. For finite non-zero numbers, the significand's absolute
1268           value is greater than or equal to 1 and less than 10. The output of
1269           "nparts()" corresponds to the output from "bnstr()". In
1270           Math::BigInt, if the significand can not be represented as an
1271           integer, upgrading is performed or NaN is returned.
1272
1273       eparts()
1274           Returns the significand (mantissa) and exponent corresponding to
1275           engineering notation. In scalar context, only the significand is
1276           returned. For finite non-zero numbers, the significand's absolute
1277           value is greater than or equal to 1 and less than 1000, and the
1278           exponent is a multiple of 3. The output of "eparts()" corresponds
1279           to the output from "bestr()". In Math::BigInt, if the significand
1280           can not be represented as an integer, upgrading is performed or NaN
1281           is returned.
1282
1283       dparts()
1284           Returns the integer part and the fraction part. If the fraction
1285           part can not be represented as an integer, upgrading is performed
1286           or NaN is returned. The output of "dparts()" corresponds to the
1287           output from "bdstr()".
1288
1289   String conversion methods
1290       bstr()
1291           Returns a string representing the number using decimal notation. In
1292           Math::BigFloat, the output is zero padded according to the current
1293           accuracy or precision, if any of those are defined.
1294
1295       bsstr()
1296           Returns a string representing the number using scientific notation
1297           where both the significand (mantissa) and the exponent are
1298           integers. The output corresponds to the output from "sparts()".
1299
1300                 123 is returned as "123e+0"
1301                1230 is returned as "123e+1"
1302               12300 is returned as "123e+2"
1303               12000 is returned as "12e+3"
1304               10000 is returned as "1e+4"
1305
1306       bnstr()
1307           Returns a string representing the number using normalized notation,
1308           the most common variant of scientific notation. For finite non-zero
1309           numbers, the absolute value of the significand is greater than or
1310           equal to 1 and less than 10. The output corresponds to the output
1311           from "nparts()".
1312
1313                 123 is returned as "1.23e+2"
1314                1230 is returned as "1.23e+3"
1315               12300 is returned as "1.23e+4"
1316               12000 is returned as "1.2e+4"
1317               10000 is returned as "1e+4"
1318
1319       bestr()
1320           Returns a string representing the number using engineering
1321           notation. For finite non-zero numbers, the absolute value of the
1322           significand is greater than or equal to 1 and less than 1000, and
1323           the exponent is a multiple of 3. The output corresponds to the
1324           output from "eparts()".
1325
1326                 123 is returned as "123e+0"
1327                1230 is returned as "1.23e+3"
1328               12300 is returned as "12.3e+3"
1329               12000 is returned as "12e+3"
1330               10000 is returned as "10e+3"
1331
1332       bdstr()
1333           Returns a string representing the number using decimal notation.
1334           The output corresponds to the output from "dparts()".
1335
1336                 123 is returned as "123"
1337                1230 is returned as "1230"
1338               12300 is returned as "12300"
1339               12000 is returned as "12000"
1340               10000 is returned as "10000"
1341
1342       to_hex()
1343               $x->to_hex();
1344
1345           Returns a hexadecimal string representation of the number. See also
1346           from_hex().
1347
1348       to_bin()
1349               $x->to_bin();
1350
1351           Returns a binary string representation of the number. See also
1352           from_bin().
1353
1354       to_oct()
1355               $x->to_oct();
1356
1357           Returns an octal string representation of the number. See also
1358           from_oct().
1359
1360       to_bytes()
1361               $x = Math::BigInt->new("1667327589");
1362               $s = $x->to_bytes();                    # $s = "cafe"
1363
1364           Returns a byte string representation of the number using big endian
1365           byte order. The invocand must be a non-negative, finite integer.
1366           See also from_bytes().
1367
1368       to_base()
1369               $x = Math::BigInt->new("250");
1370               $x->to_base(2);     # returns "11111010"
1371               $x->to_base(8);     # returns "372"
1372               $x->to_base(16);    # returns "fa"
1373
1374           Returns a string representation of the number in the given base. If
1375           a collation sequence is given, the collation sequence determines
1376           which characters are used in the output.
1377
1378           Here are some more examples
1379
1380               $x = Math::BigInt->new("16")->to_base(3);       # returns "121"
1381               $x = Math::BigInt->new("44027")->to_base(36);   # returns "XYZ"
1382               $x = Math::BigInt->new("58314")->to_base(42);   # returns "Why"
1383               $x = Math::BigInt->new("4")->to_base(2, "-|");  # returns "|--"
1384
1385           See from_base() for information and examples.
1386
1387       as_hex()
1388               $x->as_hex();
1389
1390           As, "to_hex()", but with a "0x" prefix.
1391
1392       as_bin()
1393               $x->as_bin();
1394
1395           As, "to_bin()", but with a "0b" prefix.
1396
1397       as_oct()
1398               $x->as_oct();
1399
1400           As, "to_oct()", but with a "0" prefix.
1401
1402       as_bytes()
1403           This is just an alias for "to_bytes()".
1404
1405   Other conversion methods
1406       numify()
1407               print $x->numify();
1408
1409           Returns a Perl scalar from $x. It is used automatically whenever a
1410           scalar is needed, for instance in array index operations.
1411

ACCURACY and PRECISION

1413       Math::BigInt and Math::BigFloat have full support for accuracy and
1414       precision based rounding, both automatically after every operation, as
1415       well as manually.
1416
1417       This section describes the accuracy/precision handling in Math::BigInt
1418       and Math::BigFloat as it used to be and as it is now, complete with an
1419       explanation of all terms and abbreviations.
1420
1421       Not yet implemented things (but with correct description) are marked
1422       with '!', things that need to be answered are marked with '?'.
1423
1424       In the next paragraph follows a short description of terms used here
1425       (because these may differ from terms used by others people or
1426       documentation).
1427
1428       During the rest of this document, the shortcuts A (for accuracy), P
1429       (for precision), F (fallback) and R (rounding mode) are be used.
1430
1431   Precision P
1432       Precision is a fixed number of digits before (positive) or after
1433       (negative) the decimal point. For example, 123.45 has a precision of
1434       -2. 0 means an integer like 123 (or 120). A precision of 2 means at
1435       least two digits to the left of the decimal point are zero, so 123 with
1436       P = 1 becomes 120. Note that numbers with zeros before the decimal
1437       point may have different precisions, because 1200 can have P = 0, 1 or
1438       2 (depending on what the initial value was). It could also have p < 0,
1439       when the digits after the decimal point are zero.
1440
1441       The string output (of floating point numbers) is padded with zeros:
1442
1443           Initial value    P      A       Result          String
1444           ------------------------------------------------------------
1445           1234.01         -3              1000            1000
1446           1234            -2              1200            1200
1447           1234.5          -1              1230            1230
1448           1234.001         1              1234            1234.0
1449           1234.01          0              1234            1234
1450           1234.01          2              1234.01         1234.01
1451           1234.01          5              1234.01         1234.01000
1452
1453       For Math::BigInt objects, no padding occurs.
1454
1455   Accuracy A
1456       Number of significant digits. Leading zeros are not counted. A number
1457       may have an accuracy greater than the non-zero digits when there are
1458       zeros in it or trailing zeros. For example, 123.456 has A of 6, 10203
1459       has 5, 123.0506 has 7, 123.45000 has 8 and 0.000123 has 3.
1460
1461       The string output (of floating point numbers) is padded with zeros:
1462
1463           Initial value    P      A       Result          String
1464           ------------------------------------------------------------
1465           1234.01                 3       1230            1230
1466           1234.01                 6       1234.01         1234.01
1467           1234.1                  8       1234.1          1234.1000
1468
1469       For Math::BigInt objects, no padding occurs.
1470
1471   Fallback F
1472       When both A and P are undefined, this is used as a fallback accuracy
1473       when dividing numbers.
1474
1475   Rounding mode R
1476       When rounding a number, different 'styles' or 'kinds' of rounding are
1477       possible.  (Note that random rounding, as in Math::Round, is not
1478       implemented.)
1479
1480       Directed rounding
1481
1482       These round modes always round in the same direction.
1483
1484       'trunc'
1485           Round towards zero. Remove all digits following the rounding place,
1486           i.e., replace them with zeros. Thus, 987.65 rounded to tens (P=1)
1487           becomes 980, and rounded to the fourth significant digit becomes
1488           987.6 (A=4). 123.456 rounded to the second place after the decimal
1489           point (P=-2) becomes 123.46. This corresponds to the IEEE 754
1490           rounding mode 'roundTowardZero'.
1491
1492       Rounding to nearest
1493
1494       These rounding modes round to the nearest digit. They differ in how
1495       they determine which way to round in the ambiguous case when there is a
1496       tie.
1497
1498       'even'
1499           Round towards the nearest even digit, e.g., when rounding to
1500           nearest integer, -5.5 becomes -6, 4.5 becomes 4, but 4.501 becomes
1501           5. This corresponds to the IEEE 754 rounding mode
1502           'roundTiesToEven'.
1503
1504       'odd'
1505           Round towards the nearest odd digit, e.g., when rounding to nearest
1506           integer, 4.5 becomes 5, -5.5 becomes -5, but 5.501 becomes 6. This
1507           corresponds to the IEEE 754 rounding mode 'roundTiesToOdd'.
1508
1509       '+inf'
1510           Round towards plus infinity, i.e., always round up. E.g., when
1511           rounding to the nearest integer, 4.5 becomes 5, -5.5 becomes -5,
1512           and 4.501 also becomes 5. This corresponds to the IEEE 754 rounding
1513           mode 'roundTiesToPositive'.
1514
1515       '-inf'
1516           Round towards minus infinity, i.e., always round down. E.g., when
1517           rounding to the nearest integer, 4.5 becomes 4, -5.5 becomes -6,
1518           but 4.501 becomes 5. This corresponds to the IEEE 754 rounding mode
1519           'roundTiesToNegative'.
1520
1521       'zero'
1522           Round towards zero, i.e., round positive numbers down and negative
1523           numbers up.  E.g., when rounding to the nearest integer, 4.5
1524           becomes 4, -5.5 becomes -5, but 4.501 becomes 5. This corresponds
1525           to the IEEE 754 rounding mode 'roundTiesToZero'.
1526
1527       'common'
1528           Round away from zero, i.e., round to the number with the largest
1529           absolute value. E.g., when rounding to the nearest integer, -1.5
1530           becomes -2, 1.5 becomes 2 and 1.49 becomes 1. This corresponds to
1531           the IEEE 754 rounding mode 'roundTiesToAway'.
1532
1533       The handling of A & P in MBI/MBF (the old core code shipped with Perl
1534       versions <= 5.7.2) is like this:
1535
1536       Precision
1537             * bfround($p) is able to round to $p number of digits after the decimal
1538               point
1539             * otherwise P is unused
1540
1541       Accuracy (significant digits)
1542             * bround($a) rounds to $a significant digits
1543             * only bdiv() and bsqrt() take A as (optional) parameter
1544               + other operations simply create the same number (bneg etc), or
1545                 more (bmul) of digits
1546               + rounding/truncating is only done when explicitly calling one
1547                 of bround or bfround, and never for Math::BigInt (not implemented)
1548             * bsqrt() simply hands its accuracy argument over to bdiv.
1549             * the documentation and the comment in the code indicate two
1550               different ways on how bdiv() determines the maximum number
1551               of digits it should calculate, and the actual code does yet
1552               another thing
1553               POD:
1554                 max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
1555               Comment:
1556                 result has at most max(scale, length(dividend), length(divisor)) digits
1557               Actual code:
1558                 scale = max(scale, length(dividend)-1,length(divisor)-1);
1559                 scale += length(divisor) - length(dividend);
1560               So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10
1561               So for lx = 3, ly = 9, scale = 10, scale will actually be 16
1562               (10+9-3). Actually, the 'difference' added to the scale is cal-
1563               culated from the number of "significant digits" in dividend and
1564               divisor, which is derived by looking at the length of the man-
1565               tissa. Which is wrong, since it includes the + sign (oops) and
1566               actually gets 2 for '+100' and 4 for '+101'. Oops again. Thus
1567               124/3 with div_scale=1 will get you '41.3' based on the strange
1568               assumption that 124 has 3 significant digits, while 120/7 will
1569               get you '17', not '17.1' since 120 is thought to have 2 signif-
1570               icant digits. The rounding after the division then uses the
1571               remainder and $y to determine whether it must round up or down.
1572            ?  I have no idea which is the right way. That's why I used a slightly more
1573            ?  simple scheme and tweaked the few failing testcases to match it.
1574
1575       This is how it works now:
1576
1577       Setting/Accessing
1578             * You can set the A global via Math::BigInt->accuracy() or
1579               Math::BigFloat->accuracy() or whatever class you are using.
1580             * You can also set P globally by using Math::SomeClass->precision()
1581               likewise.
1582             * Globals are classwide, and not inherited by subclasses.
1583             * to undefine A, use Math::SomeCLass->accuracy(undef);
1584             * to undefine P, use Math::SomeClass->precision(undef);
1585             * Setting Math::SomeClass->accuracy() clears automatically
1586               Math::SomeClass->precision(), and vice versa.
1587             * To be valid, A must be > 0, P can have any value.
1588             * If P is negative, this means round to the P'th place to the right of the
1589               decimal point; positive values mean to the left of the decimal point.
1590               P of 0 means round to integer.
1591             * to find out the current global A, use Math::SomeClass->accuracy()
1592             * to find out the current global P, use Math::SomeClass->precision()
1593             * use $x->accuracy() respective $x->precision() for the local
1594               setting of $x.
1595             * Please note that $x->accuracy() respective $x->precision()
1596               return eventually defined global A or P, when $x's A or P is not
1597               set.
1598
1599       Creating numbers
1600             * When you create a number, you can give the desired A or P via:
1601               $x = Math::BigInt->new($number,$A,$P);
1602             * Only one of A or P can be defined, otherwise the result is NaN
1603             * If no A or P is give ($x = Math::BigInt->new($number) form), then the
1604               globals (if set) will be used. Thus changing the global defaults later on
1605               will not change the A or P of previously created numbers (i.e., A and P of
1606               $x will be what was in effect when $x was created)
1607             * If given undef for A and P, NO rounding will occur, and the globals will
1608               NOT be used. This is used by subclasses to create numbers without
1609               suffering rounding in the parent. Thus a subclass is able to have its own
1610               globals enforced upon creation of a number by using
1611               $x = Math::BigInt->new($number,undef,undef):
1612
1613                   use Math::BigInt::SomeSubclass;
1614                   use Math::BigInt;
1615
1616                   Math::BigInt->accuracy(2);
1617                   Math::BigInt::SomeSubClass->accuracy(3);
1618                   $x = Math::BigInt::SomeSubClass->new(1234);
1619
1620               $x is now 1230, and not 1200. A subclass might choose to implement
1621               this otherwise, e.g. falling back to the parent's A and P.
1622
1623       Usage
1624             * If A or P are enabled/defined, they are used to round the result of each
1625               operation according to the rules below
1626             * Negative P is ignored in Math::BigInt, since Math::BigInt objects never
1627               have digits after the decimal point
1628             * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
1629               Math::BigInt as globals does not tamper with the parts of a Math::BigFloat.
1630               A flag is used to mark all Math::BigFloat numbers as 'never round'.
1631
1632       Precedence
1633             * It only makes sense that a number has only one of A or P at a time.
1634               If you set either A or P on one object, or globally, the other one will
1635               be automatically cleared.
1636             * If two objects are involved in an operation, and one of them has A in
1637               effect, and the other P, this results in an error (NaN).
1638             * A takes precedence over P (Hint: A comes before P).
1639               If neither of them is defined, nothing is used, i.e. the result will have
1640               as many digits as it can (with an exception for bdiv/bsqrt) and will not
1641               be rounded.
1642             * There is another setting for bdiv() (and thus for bsqrt()). If neither of
1643               A or P is defined, bdiv() will use a fallback (F) of $div_scale digits.
1644               If either the dividend's or the divisor's mantissa has more digits than
1645               the value of F, the higher value will be used instead of F.
1646               This is to limit the digits (A) of the result (just consider what would
1647               happen with unlimited A and P in the case of 1/3 :-)
1648             * bdiv will calculate (at least) 4 more digits than required (determined by
1649               A, P or F), and, if F is not used, round the result
1650               (this will still fail in the case of a result like 0.12345000000001 with A
1651               or P of 5, but this can not be helped - or can it?)
1652             * Thus you can have the math done by on Math::Big* class in two modi:
1653               + never round (this is the default):
1654                 This is done by setting A and P to undef. No math operation
1655                 will round the result, with bdiv() and bsqrt() as exceptions to guard
1656                 against overflows. You must explicitly call bround(), bfround() or
1657                 round() (the latter with parameters).
1658                 Note: Once you have rounded a number, the settings will 'stick' on it
1659                 and 'infect' all other numbers engaged in math operations with it, since
1660                 local settings have the highest precedence. So, to get SaferRound[tm],
1661                 use a copy() before rounding like this:
1662
1663                   $x = Math::BigFloat->new(12.34);
1664                   $y = Math::BigFloat->new(98.76);
1665                   $z = $x * $y;                           # 1218.6984
1666                   print $x->copy()->bround(3);            # 12.3 (but A is now 3!)
1667                   $z = $x * $y;                           # still 1218.6984, without
1668                                                           # copy would have been 1210!
1669
1670               + round after each op:
1671                 After each single operation (except for testing like is_zero()), the
1672                 method round() is called and the result is rounded appropriately. By
1673                 setting proper values for A and P, you can have all-the-same-A or
1674                 all-the-same-P modes. For example, Math::Currency might set A to undef,
1675                 and P to -2, globally.
1676
1677            ?Maybe an extra option that forbids local A & P settings would be in order,
1678            ?so that intermediate rounding does not 'poison' further math?
1679
1680       Overriding globals
1681             * you will be able to give A, P and R as an argument to all the calculation
1682               routines; the second parameter is A, the third one is P, and the fourth is
1683               R (shift right by one for binary operations like badd). P is used only if
1684               the first parameter (A) is undefined. These three parameters override the
1685               globals in the order detailed as follows, i.e. the first defined value
1686               wins:
1687               (local: per object, global: global default, parameter: argument to sub)
1688                 + parameter A
1689                 + parameter P
1690                 + local A (if defined on both of the operands: smaller one is taken)
1691                 + local P (if defined on both of the operands: bigger one is taken)
1692                 + global A
1693                 + global P
1694                 + global F
1695             * bsqrt() will hand its arguments to bdiv(), as it used to, only now for two
1696               arguments (A and P) instead of one
1697
1698       Local settings
1699             * You can set A or P locally by using $x->accuracy() or
1700               $x->precision()
1701               and thus force different A and P for different objects/numbers.
1702             * Setting A or P this way immediately rounds $x to the new value.
1703             * $x->accuracy() clears $x->precision(), and vice versa.
1704
1705       Rounding
1706             * the rounding routines will use the respective global or local settings.
1707               bround() is for accuracy rounding, while bfround() is for precision
1708             * the two rounding functions take as the second parameter one of the
1709               following rounding modes (R):
1710               'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
1711             * you can set/get the global R by using Math::SomeClass->round_mode()
1712               or by setting $Math::SomeClass::round_mode
1713             * after each operation, $result->round() is called, and the result may
1714               eventually be rounded (that is, if A or P were set either locally,
1715               globally or as parameter to the operation)
1716             * to manually round a number, call $x->round($A,$P,$round_mode);
1717               this will round the number by using the appropriate rounding function
1718               and then normalize it.
1719             * rounding modifies the local settings of the number:
1720
1721                   $x = Math::BigFloat->new(123.456);
1722                   $x->accuracy(5);
1723                   $x->bround(4);
1724
1725               Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
1726               will be 4 from now on.
1727
1728       Default values
1729             * R: 'even'
1730             * F: 40
1731             * A: undef
1732             * P: undef
1733
1734       Remarks
1735             * The defaults are set up so that the new code gives the same results as
1736               the old code (except in a few cases on bdiv):
1737               + Both A and P are undefined and thus will not be used for rounding
1738                 after each operation.
1739               + round() is thus a no-op, unless given extra parameters A and P
1740

Infinity and Not a Number

1742       While Math::BigInt has extensive handling of inf and NaN, certain
1743       quirks remain.
1744
1745       oct()/hex()
1746           These perl routines currently (as of Perl v.5.8.6) cannot handle
1747           passed inf.
1748
1749               te@linux:~> perl -wle 'print 2 ** 3333'
1750               Inf
1751               te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
1752               1
1753               te@linux:~> perl -wle 'print oct(2 ** 3333)'
1754               0
1755               te@linux:~> perl -wle 'print hex(2 ** 3333)'
1756               Illegal hexadecimal digit 'I' ignored at -e line 1.
1757               0
1758
1759           The same problems occur if you pass them Math::BigInt->binf()
1760           objects. Since overloading these routines is not possible, this
1761           cannot be fixed from Math::BigInt.
1762

INTERNALS

1764       You should neither care about nor depend on the internal
1765       representation; it might change without notice. Use ONLY method calls
1766       like "$x->sign();" instead relying on the internal representation.
1767
1768   MATH LIBRARY
1769       Math with the numbers is done (by default) by a module called
1770       "Math::BigInt::Calc". This is equivalent to saying:
1771
1772           use Math::BigInt try => 'Calc';
1773
1774       You can change this backend library by using:
1775
1776           use Math::BigInt try => 'GMP';
1777
1778       Note: General purpose packages should not be explicit about the library
1779       to use; let the script author decide which is best.
1780
1781       If your script works with huge numbers and Calc is too slow for them,
1782       you can also for the loading of one of these libraries and if none of
1783       them can be used, the code dies:
1784
1785           use Math::BigInt only => 'GMP,Pari';
1786
1787       The following would first try to find Math::BigInt::Foo, then
1788       Math::BigInt::Bar, and when this also fails, revert to
1789       Math::BigInt::Calc:
1790
1791           use Math::BigInt try => 'Foo,Math::BigInt::Bar';
1792
1793       The library that is loaded last is used. Note that this can be
1794       overwritten at any time by loading a different library, and numbers
1795       constructed with different libraries cannot be used in math operations
1796       together.
1797
1798       What library to use?
1799
1800       Note: General purpose packages should not be explicit about the library
1801       to use; let the script author decide which is best.
1802
1803       Math::BigInt::GMP and Math::BigInt::Pari are in cases involving big
1804       numbers much faster than Calc, however it is slower when dealing with
1805       very small numbers (less than about 20 digits) and when converting very
1806       large numbers to decimal (for instance for printing, rounding,
1807       calculating their length in decimal etc).
1808
1809       So please select carefully what library you want to use.
1810
1811       Different low-level libraries use different formats to store the
1812       numbers.  However, you should NOT depend on the number having a
1813       specific format internally.
1814
1815       See the respective math library module documentation for further
1816       details.
1817
1818   SIGN
1819       The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
1820
1821       A sign of 'NaN' is used to represent the result when input arguments
1822       are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
1823       respectively minus infinity. You get '+inf' when dividing a positive
1824       number by 0, and '-inf' when dividing any negative number by 0.
1825

EXAMPLES

1827         use Math::BigInt;
1828
1829         sub bigint { Math::BigInt->new(shift); }
1830
1831         $x = Math::BigInt->bstr("1234")       # string "1234"
1832         $x = "$x";                            # same as bstr()
1833         $x = Math::BigInt->bneg("1234");      # Math::BigInt "-1234"
1834         $x = Math::BigInt->babs("-12345");    # Math::BigInt "12345"
1835         $x = Math::BigInt->bnorm("-0.00");    # Math::BigInt "0"
1836         $x = bigint(1) + bigint(2);           # Math::BigInt "3"
1837         $x = bigint(1) + "2";                 # ditto (auto-Math::BigIntify of "2")
1838         $x = bigint(1);                       # Math::BigInt "1"
1839         $x = $x + 5 / 2;                      # Math::BigInt "3"
1840         $x = $x ** 3;                         # Math::BigInt "27"
1841         $x *= 2;                              # Math::BigInt "54"
1842         $x = Math::BigInt->new(0);            # Math::BigInt "0"
1843         $x--;                                 # Math::BigInt "-1"
1844         $x = Math::BigInt->badd(4,5)          # Math::BigInt "9"
1845         print $x->bsstr();                    # 9e+0
1846
1847       Examples for rounding:
1848
1849         use Math::BigFloat;
1850         use Test::More;
1851
1852         $x = Math::BigFloat->new(123.4567);
1853         $y = Math::BigFloat->new(123.456789);
1854         Math::BigFloat->accuracy(4);          # no more A than 4
1855
1856         is ($x->copy()->bround(),123.4);      # even rounding
1857         print $x->copy()->bround(),"\n";      # 123.4
1858         Math::BigFloat->round_mode('odd');    # round to odd
1859         print $x->copy()->bround(),"\n";      # 123.5
1860         Math::BigFloat->accuracy(5);          # no more A than 5
1861         Math::BigFloat->round_mode('odd');    # round to odd
1862         print $x->copy()->bround(),"\n";      # 123.46
1863         $y = $x->copy()->bround(4),"\n";      # A = 4: 123.4
1864         print "$y, ",$y->accuracy(),"\n";     # 123.4, 4
1865
1866         Math::BigFloat->accuracy(undef);      # A not important now
1867         Math::BigFloat->precision(2);         # P important
1868         print $x->copy()->bnorm(),"\n";       # 123.46
1869         print $x->copy()->bround(),"\n";      # 123.46
1870
1871       Examples for converting:
1872
1873         my $x = Math::BigInt->new('0b1'.'01' x 123);
1874         print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
1875

Autocreating constants

1877       After "use Math::BigInt ':constant'" all the integer decimal,
1878       hexadecimal and binary constants in the given scope are converted to
1879       "Math::BigInt". This conversion happens at compile time.
1880
1881       In particular,
1882
1883         perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'
1884
1885       prints the integer value of "2**100". Note that without conversion of
1886       constants the expression 2**100 is calculated using Perl scalars.
1887
1888       Please note that strings and floating point constants are not affected,
1889       so that
1890
1891           use Math::BigInt qw/:constant/;
1892
1893           $x = 1234567890123456789012345678901234567890
1894                   + 123456789123456789;
1895           $y = '1234567890123456789012345678901234567890'
1896                   + '123456789123456789';
1897
1898       does not give you what you expect. You need an explicit
1899       Math::BigInt->new() around one of the operands. You should also quote
1900       large constants to protect loss of precision:
1901
1902           use Math::BigInt;
1903
1904           $x = Math::BigInt->new('1234567889123456789123456789123456789');
1905
1906       Without the quotes Perl would convert the large number to a floating
1907       point constant at compile time and then hand the result to
1908       Math::BigInt, which results in an truncated result or a NaN.
1909
1910       This also applies to integers that look like floating point constants:
1911
1912           use Math::BigInt ':constant';
1913
1914           print ref(123e2),"\n";
1915           print ref(123.2e2),"\n";
1916
1917       prints nothing but newlines. Use either bignum or Math::BigFloat to get
1918       this to work.
1919

PERFORMANCE

1921       Using the form $x += $y; etc over $x = $x + $y is faster, since a copy
1922       of $x must be made in the second case. For long numbers, the copy can
1923       eat up to 20% of the work (in the case of addition/subtraction, less
1924       for multiplication/division). If $y is very small compared to $x, the
1925       form $x += $y is MUCH faster than $x = $x + $y since making the copy of
1926       $x takes more time then the actual addition.
1927
1928       With a technique called copy-on-write, the cost of copying with
1929       overload could be minimized or even completely avoided. A test
1930       implementation of COW did show performance gains for overloaded math,
1931       but introduced a performance loss due to a constant overhead for all
1932       other operations. So Math::BigInt does currently not COW.
1933
1934       The rewritten version of this module (vs. v0.01) is slower on certain
1935       operations, like "new()", "bstr()" and "numify()". The reason are that
1936       it does now more work and handles much more cases. The time spent in
1937       these operations is usually gained in the other math operations so that
1938       code on the average should get (much) faster. If they don't, please
1939       contact the author.
1940
1941       Some operations may be slower for small numbers, but are significantly
1942       faster for big numbers. Other operations are now constant (O(1), like
1943       "bneg()", "babs()" etc), instead of O(N) and thus nearly always take
1944       much less time.  These optimizations were done on purpose.
1945
1946       If you find the Calc module to slow, try to install any of the
1947       replacement modules and see if they help you.
1948
1949   Alternative math libraries
1950       You can use an alternative library to drive Math::BigInt. See the
1951       section "MATH LIBRARY" for more information.
1952
1953       For more benchmark results see
1954       <http://bloodgate.com/perl/benchmarks.html>.
1955

SUBCLASSING

1957   Subclassing Math::BigInt
1958       The basic design of Math::BigInt allows simple subclasses with very
1959       little work, as long as a few simple rules are followed:
1960
1961       •   The public API must remain consistent, i.e. if a sub-class is
1962           overloading addition, the sub-class must use the same name, in this
1963           case badd(). The reason for this is that Math::BigInt is optimized
1964           to call the object methods directly.
1965
1966       •   The private object hash keys like "$x->{sign}" may not be changed,
1967           but additional keys can be added, like "$x->{_custom}".
1968
1969       •   Accessor functions are available for all existing object hash keys
1970           and should be used instead of directly accessing the internal hash
1971           keys. The reason for this is that Math::BigInt itself has a
1972           pluggable interface which permits it to support different storage
1973           methods.
1974
1975       More complex sub-classes may have to replicate more of the logic
1976       internal of Math::BigInt if they need to change more basic behaviors. A
1977       subclass that needs to merely change the output only needs to overload
1978       "bstr()".
1979
1980       All other object methods and overloaded functions can be directly
1981       inherited from the parent class.
1982
1983       At the very minimum, any subclass needs to provide its own "new()" and
1984       can store additional hash keys in the object. There are also some
1985       package globals that must be defined, e.g.:
1986
1987           # Globals
1988           $accuracy = undef;
1989           $precision = -2;       # round to 2 decimal places
1990           $round_mode = 'even';
1991           $div_scale = 40;
1992
1993       Additionally, you might want to provide the following two globals to
1994       allow auto-upgrading and auto-downgrading to work correctly:
1995
1996           $upgrade = undef;
1997           $downgrade = undef;
1998
1999       This allows Math::BigInt to correctly retrieve package globals from the
2000       subclass, like $SubClass::precision. See t/Math/BigInt/Subclass.pm or
2001       t/Math/BigFloat/SubClass.pm completely functional subclass examples.
2002
2003       Don't forget to
2004
2005           use overload;
2006
2007       in your subclass to automatically inherit the overloading from the
2008       parent. If you like, you can change part of the overloading, look at
2009       Math::String for an example.
2010

UPGRADING

2012       When used like this:
2013
2014           use Math::BigInt upgrade => 'Foo::Bar';
2015
2016       certain operations 'upgrade' their calculation and thus the result to
2017       the class Foo::Bar. Usually this is used in conjunction with
2018       Math::BigFloat:
2019
2020           use Math::BigInt upgrade => 'Math::BigFloat';
2021
2022       As a shortcut, you can use the module bignum:
2023
2024           use bignum;
2025
2026       Also good for one-liners:
2027
2028           perl -Mbignum -le 'print 2 ** 255'
2029
2030       This makes it possible to mix arguments of different classes (as in 2.5
2031       + 2) as well es preserve accuracy (as in sqrt(3)).
2032
2033       Beware: This feature is not fully implemented yet.
2034
2035   Auto-upgrade
2036       The following methods upgrade themselves unconditionally; that is if
2037       upgrade is in effect, they always hands up their work:
2038
2039           div bsqrt blog bexp bpi bsin bcos batan batan2
2040
2041       All other methods upgrade themselves only when one (or all) of their
2042       arguments are of the class mentioned in $upgrade.
2043

EXPORTS

2045       "Math::BigInt" exports nothing by default, but can export the following
2046       methods:
2047
2048           bgcd
2049           blcm
2050

CAVEATS

2052       Some things might not work as you expect them. Below is documented what
2053       is known to be troublesome:
2054
2055       Comparing numbers as strings
2056           Both "bstr()" and "bsstr()" as well as stringify via overload drop
2057           the leading '+'. This is to be consistent with Perl and to make
2058           "cmp" (especially with overloading) to work as you expect. It also
2059           solves problems with "Test.pm" and Test::More, which stringify
2060           arguments before comparing them.
2061
2062           Mark Biggar said, when asked about to drop the '+' altogether, or
2063           make only "cmp" work:
2064
2065               I agree (with the first alternative), don't add the '+' on positive
2066               numbers.  It's not as important anymore with the new internal form
2067               for numbers.  It made doing things like abs and neg easier, but
2068               those have to be done differently now anyway.
2069
2070           So, the following examples now works as expected:
2071
2072               use Test::More tests => 1;
2073               use Math::BigInt;
2074
2075               my $x = Math::BigInt -> new(3*3);
2076               my $y = Math::BigInt -> new(3*3);
2077
2078               is($x,3*3, 'multiplication');
2079               print "$x eq 9" if $x eq $y;
2080               print "$x eq 9" if $x eq '9';
2081               print "$x eq 9" if $x eq 3*3;
2082
2083           Additionally, the following still works:
2084
2085               print "$x == 9" if $x == $y;
2086               print "$x == 9" if $x == 9;
2087               print "$x == 9" if $x == 3*3;
2088
2089           There is now a "bsstr()" method to get the string in scientific
2090           notation aka 1e+2 instead of 100. Be advised that overloaded 'eq'
2091           always uses bstr() for comparison, but Perl represents some numbers
2092           as 100 and others as 1e+308.  If in doubt, convert both arguments
2093           to Math::BigInt before comparing them as strings:
2094
2095               use Test::More tests => 3;
2096               use Math::BigInt;
2097
2098               $x = Math::BigInt->new('1e56'); $y = 1e56;
2099               is($x,$y);                     # fails
2100               is($x->bsstr(),$y);            # okay
2101               $y = Math::BigInt->new($y);
2102               is($x,$y);                     # okay
2103
2104           Alternatively, simply use "<=>" for comparisons, this always gets
2105           it right. There is not yet a way to get a number automatically
2106           represented as a string that matches exactly the way Perl
2107           represents it.
2108
2109           See also the section about "Infinity and Not a Number" for problems
2110           in comparing NaNs.
2111
2112       int()
2113           "int()" returns (at least for Perl v5.7.1 and up) another
2114           Math::BigInt, not a Perl scalar:
2115
2116               $x = Math::BigInt->new(123);
2117               $y = int($x);                           # 123 as a Math::BigInt
2118               $x = Math::BigFloat->new(123.45);
2119               $y = int($x);                           # 123 as a Math::BigFloat
2120
2121           If you want a real Perl scalar, use "numify()":
2122
2123               $y = $x->numify();                      # 123 as a scalar
2124
2125           This is seldom necessary, though, because this is done
2126           automatically, like when you access an array:
2127
2128               $z = $array[$x];                        # does work automatically
2129
2130       Modifying and =
2131           Beware of:
2132
2133               $x = Math::BigFloat->new(5);
2134               $y = $x;
2135
2136           This makes a second reference to the same object and stores it in
2137           $y. Thus anything that modifies $x (except overloaded operators)
2138           also modifies $y, and vice versa. Or in other words, "=" is only
2139           safe if you modify your Math::BigInt objects only via overloaded
2140           math. As soon as you use a method call it breaks:
2141
2142               $x->bmul(2);
2143               print "$x, $y\n";       # prints '10, 10'
2144
2145           If you want a true copy of $x, use:
2146
2147               $y = $x->copy();
2148
2149           You can also chain the calls like this, this first makes a copy and
2150           then multiply it by 2:
2151
2152               $y = $x->copy()->bmul(2);
2153
2154           See also the documentation for overload.pm regarding "=".
2155
2156       Overloading -$x
2157           The following:
2158
2159               $x = -$x;
2160
2161           is slower than
2162
2163               $x->bneg();
2164
2165           since overload calls "sub($x,0,1);" instead of "neg($x)". The first
2166           variant needs to preserve $x since it does not know that it later
2167           gets overwritten.  This makes a copy of $x and takes O(N), but
2168           $x->bneg() is O(1).
2169
2170       Mixing different object types
2171           With overloaded operators, it is the first (dominating) operand
2172           that determines which method is called. Here are some examples
2173           showing what actually gets called in various cases.
2174
2175               use Math::BigInt;
2176               use Math::BigFloat;
2177
2178               $mbf  = Math::BigFloat->new(5);
2179               $mbi2 = Math::BigInt->new(5);
2180               $mbi  = Math::BigInt->new(2);
2181                                               # what actually gets called:
2182               $float = $mbf + $mbi;           # $mbf->badd($mbi)
2183               $float = $mbf / $mbi;           # $mbf->bdiv($mbi)
2184               $integer = $mbi + $mbf;         # $mbi->badd($mbf)
2185               $integer = $mbi2 / $mbi;        # $mbi2->bdiv($mbi)
2186               $integer = $mbi2 / $mbf;        # $mbi2->bdiv($mbf)
2187
2188           For instance, Math::BigInt->bdiv() always returns a Math::BigInt,
2189           regardless of whether the second operant is a Math::BigFloat. To
2190           get a Math::BigFloat you either need to call the operation
2191           manually, make sure each operand already is a Math::BigFloat, or
2192           cast to that type via Math::BigFloat->new():
2193
2194               $float = Math::BigFloat->new($mbi2) / $mbi;     # = 2.5
2195
2196           Beware of casting the entire expression, as this would cast the
2197           result, at which point it is too late:
2198
2199               $float = Math::BigFloat->new($mbi2 / $mbi);     # = 2
2200
2201           Beware also of the order of more complicated expressions like:
2202
2203               $integer = ($mbi2 + $mbi) / $mbf;               # int / float => int
2204               $integer = $mbi2 / Math::BigFloat->new($mbi);   # ditto
2205
2206           If in doubt, break the expression into simpler terms, or cast all
2207           operands to the desired resulting type.
2208
2209           Scalar values are a bit different, since:
2210
2211               $float = 2 + $mbf;
2212               $float = $mbf + 2;
2213
2214           both result in the proper type due to the way the overloaded math
2215           works.
2216
2217           This section also applies to other overloaded math packages, like
2218           Math::String.
2219
2220           One solution to you problem might be autoupgrading|upgrading. See
2221           the pragmas bignum, bigint and bigrat for an easy way to do this.
2222

BUGS

2224       Please report any bugs or feature requests to "bug-math-bigint at
2225       rt.cpan.org", or through the web interface at
2226       <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
2227       login).  We will be notified, and then you'll automatically be notified
2228       of progress on your bug as I make changes.
2229

SUPPORT

2231       You can find documentation for this module with the perldoc command.
2232
2233           perldoc Math::BigInt
2234
2235       You can also look for information at:
2236
2237       •   RT: CPAN's request tracker
2238
2239           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
2240
2241       •   AnnoCPAN: Annotated CPAN documentation
2242
2243           <http://annocpan.org/dist/Math-BigInt>
2244
2245       •   CPAN Ratings
2246
2247           <https://cpanratings.perl.org/dist/Math-BigInt>
2248
2249       •   MetaCPAN
2250
2251           <https://metacpan.org/release/Math-BigInt>
2252
2253       •   CPAN Testers Matrix
2254
2255           <http://matrix.cpantesters.org/?dist=Math-BigInt>
2256
2257       •   The Bignum mailing list
2258
2259           •   Post to mailing list
2260
2261               "bignum at lists.scsys.co.uk"
2262
2263           •   View mailing list
2264
2265               <http://lists.scsys.co.uk/pipermail/bignum/>
2266
2267           •   Subscribe/Unsubscribe
2268
2269               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
2270

LICENSE

2272       This program is free software; you may redistribute it and/or modify it
2273       under the same terms as Perl itself.
2274

SEE ALSO

2276       Math::BigFloat and Math::BigRat as well as the backends
2277       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
2278
2279       The pragmas bignum, bigint and bigrat also might be of interest because
2280       they solve the autoupgrading/downgrading issue, at least partly.
2281

AUTHORS

2283       •   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
2284
2285       •   Completely rewritten by Tels <http://bloodgate.com>, 2001-2008.
2286
2287       •   Florian Ragwitz <flora@cpan.org>, 2010.
2288
2289       •   Peter John Acklam <pjacklam@online.no>, 2011-.
2290
2291       Many people contributed in one or more ways to the final beast, see the
2292       file CREDITS for an (incomplete) list. If you miss your name, please
2293       drop me a mail. Thank you!
2294
2295
2296
2297perl v5.32.1                      2021-01-27                   Math::BigInt(3)
Impressum