This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Rebreak lines to achieve <80 recommended line length.
[perl5.git] / dist / Math-BigInt / lib / Math / BigInt.pm
1 package Math::BigInt;
2
3 #
4 # "Mike had an infinite amount to do and a negative amount of time in which
5 # to do it." - Before and After
6 #
7
8 # The following hash values are used:
9 #   value: unsigned int with actual value (as a Math::BigInt::Calc or similar)
10 #   sign : +,-,NaN,+inf,-inf
11 #   _a   : accuracy
12 #   _p   : precision
13 #   _f   : flags, used by MBF to flag parts of a float as untouchable
14
15 # Remember not to take shortcuts ala $xs = $x->{value}; $CALC->foo($xs); since
16 # underlying lib might change the reference!
17
18 my $class = "Math::BigInt";
19 use 5.006002;
20
21 $VERSION = '1.9995';
22
23 @ISA = qw(Exporter);
24 @EXPORT_OK = qw(objectify bgcd blcm); 
25
26 # _trap_inf and _trap_nan are internal and should never be accessed from the
27 # outside
28 use vars qw/$round_mode $accuracy $precision $div_scale $rnd_mode 
29             $upgrade $downgrade $_trap_nan $_trap_inf/;
30 use strict;
31
32 # Inside overload, the first arg is always an object. If the original code had
33 # it reversed (like $x = 2 * $y), then the third parameter is true.
34 # In some cases (like add, $x = $x + 2 is the same as $x = 2 + $x) this makes
35 # no difference, but in some cases it does.
36
37 # For overloaded ops with only one argument we simple use $_[0]->copy() to
38 # preserve the argument.
39
40 # Thus inheritance of overload operators becomes possible and transparent for
41 # our subclasses without the need to repeat the entire overload section there.
42
43 # We register ops that are not registerable yet, so suppress warnings
44 { no warnings;
45 use overload
46 '='     =>      sub { $_[0]->copy(); },
47
48 # some shortcuts for speed (assumes that reversed order of arguments is routed
49 # to normal '+' and we thus can always modify first arg. If this is changed,
50 # this breaks and must be adjusted.)
51 '+='    =>      sub { $_[0]->badd($_[1]); },
52 '-='    =>      sub { $_[0]->bsub($_[1]); },
53 '*='    =>      sub { $_[0]->bmul($_[1]); },
54 '/='    =>      sub { scalar $_[0]->bdiv($_[1]); },
55 '%='    =>      sub { $_[0]->bmod($_[1]); },
56 '^='    =>      sub { $_[0]->bxor($_[1]); },
57 '&='    =>      sub { $_[0]->band($_[1]); },
58 '|='    =>      sub { $_[0]->bior($_[1]); },
59
60 '**='   =>      sub { $_[0]->bpow($_[1]); },
61 '<<='   =>      sub { $_[0]->blsft($_[1]); },
62 '>>='   =>      sub { $_[0]->brsft($_[1]); },
63
64 # not supported by Perl yet
65 '..'    =>      \&_pointpoint,
66
67 '<=>'   =>      sub { my $rc = $_[2] ?
68                       ref($_[0])->bcmp($_[1],$_[0]) : 
69                       $_[0]->bcmp($_[1]); 
70                       $rc = 1 unless defined $rc;
71                       $rc <=> 0;
72                 },
73 # we need '>=' to get things like "1 >= NaN" right:
74 '>='    =>      sub { my $rc = $_[2] ?
75                       ref($_[0])->bcmp($_[1],$_[0]) : 
76                       $_[0]->bcmp($_[1]);
77                       # if there was a NaN involved, return false
78                       return '' unless defined $rc;
79                       $rc >= 0;
80                 },
81 'cmp'   =>      sub {
82          $_[2] ? 
83                "$_[1]" cmp $_[0]->bstr() :
84                $_[0]->bstr() cmp "$_[1]" },
85
86 'cos'   =>      sub { $_[0]->copy->bcos(); }, 
87 'sin'   =>      sub { $_[0]->copy->bsin(); }, 
88 'atan2' =>      sub { $_[2] ?
89                         ref($_[0])->new($_[1])->batan2($_[0]) :
90                         $_[0]->copy()->batan2($_[1]) },
91
92 # are not yet overloadable
93 #'hex'  =>      sub { print "hex"; $_[0]; }, 
94 #'oct'  =>      sub { print "oct"; $_[0]; }, 
95
96 # log(N) is log(N, e), where e is Euler's number
97 'log'   =>      sub { $_[0]->copy()->blog($_[1], undef); }, 
98 'exp'   =>      sub { $_[0]->copy()->bexp($_[1]); }, 
99 'int'   =>      sub { $_[0]->copy(); }, 
100 'neg'   =>      sub { $_[0]->copy()->bneg(); }, 
101 'abs'   =>      sub { $_[0]->copy()->babs(); },
102 'sqrt'  =>      sub { $_[0]->copy()->bsqrt(); },
103 '~'     =>      sub { $_[0]->copy()->bnot(); },
104
105 # for subtract it's a bit tricky to not modify b: b-a => -a+b
106 '-'     =>      sub { my $c = $_[0]->copy; $_[2] ?
107                         $c->bneg()->badd( $_[1]) :
108                         $c->bsub( $_[1]) },
109 '+'     =>      sub { $_[0]->copy()->badd($_[1]); },
110 '*'     =>      sub { $_[0]->copy()->bmul($_[1]); },
111
112 '/'     =>      sub { 
113    $_[2] ? ref($_[0])->new($_[1])->bdiv($_[0]) : $_[0]->copy->bdiv($_[1]);
114   }, 
115 '%'     =>      sub { 
116    $_[2] ? ref($_[0])->new($_[1])->bmod($_[0]) : $_[0]->copy->bmod($_[1]);
117   }, 
118 '**'    =>      sub { 
119    $_[2] ? ref($_[0])->new($_[1])->bpow($_[0]) : $_[0]->copy->bpow($_[1]);
120   }, 
121 '<<'    =>      sub { 
122    $_[2] ? ref($_[0])->new($_[1])->blsft($_[0]) : $_[0]->copy->blsft($_[1]);
123   }, 
124 '>>'    =>      sub { 
125    $_[2] ? ref($_[0])->new($_[1])->brsft($_[0]) : $_[0]->copy->brsft($_[1]);
126   }, 
127 '&'     =>      sub { 
128    $_[2] ? ref($_[0])->new($_[1])->band($_[0]) : $_[0]->copy->band($_[1]);
129   }, 
130 '|'     =>      sub { 
131    $_[2] ? ref($_[0])->new($_[1])->bior($_[0]) : $_[0]->copy->bior($_[1]);
132   }, 
133 '^'     =>      sub { 
134    $_[2] ? ref($_[0])->new($_[1])->bxor($_[0]) : $_[0]->copy->bxor($_[1]);
135   }, 
136
137 # can modify arg of ++ and --, so avoid a copy() for speed, but don't
138 # use $_[0]->bone(), it would modify $_[0] to be 1!
139 '++'    =>      sub { $_[0]->binc() },
140 '--'    =>      sub { $_[0]->bdec() },
141
142 # if overloaded, O(1) instead of O(N) and twice as fast for small numbers
143 'bool'  =>      sub {
144   # this kludge is needed for perl prior 5.6.0 since returning 0 here fails :-/
145   # v5.6.1 dumps on this: return !$_[0]->is_zero() || undef;                :-(
146   my $t = undef;
147   $t = 1 if !$_[0]->is_zero();
148   $t;
149   },
150
151 # the original qw() does not work with the TIESCALAR below, why?
152 # Order of arguments insignificant
153 '""' => sub { $_[0]->bstr(); },
154 '0+' => sub { $_[0]->numify(); }
155 ;
156 } # no warnings scope
157
158 ##############################################################################
159 # global constants, flags and accessory
160
161 # These vars are public, but their direct usage is not recommended, use the
162 # accessor methods instead
163
164 $round_mode = 'even'; # one of 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
165 $accuracy   = undef;
166 $precision  = undef;
167 $div_scale  = 40;
168
169 $upgrade = undef;                       # default is no upgrade
170 $downgrade = undef;                     # default is no downgrade
171
172 # These are internally, and not to be used from the outside at all
173
174 $_trap_nan = 0;                         # are NaNs ok? set w/ config()
175 $_trap_inf = 0;                         # are infs ok? set w/ config()
176 my $nan = 'NaN';                        # constants for easier life
177
178 my $CALC = 'Math::BigInt::Calc';        # module to do the low level math
179                                         # default is Calc.pm
180 my $IMPORT = 0;                         # was import() called yet?
181                                         # used to make require work
182 my %WARN;                               # warn only once for low-level libs
183 my %CAN;                                # cache for $CALC->can(...)
184 my %CALLBACKS;                          # callbacks to notify on lib loads
185 my $EMU_LIB = 'Math/BigInt/CalcEmu.pm'; # emulate low-level math
186
187 ##############################################################################
188 # the old code had $rnd_mode, so we need to support it, too
189
190 $rnd_mode   = 'even';
191 sub TIESCALAR  { my ($class) = @_; bless \$round_mode, $class; }
192 sub FETCH      { return $round_mode; }
193 sub STORE      { $rnd_mode = $_[0]->round_mode($_[1]); }
194
195 BEGIN
196   { 
197   # tie to enable $rnd_mode to work transparently
198   tie $rnd_mode, 'Math::BigInt'; 
199
200   # set up some handy alias names
201   *as_int = \&as_number;
202   *is_pos = \&is_positive;
203   *is_neg = \&is_negative;
204   }
205
206 ############################################################################## 
207
208 sub round_mode
209   {
210   no strict 'refs';
211   # make Class->round_mode() work
212   my $self = shift;
213   my $class = ref($self) || $self || __PACKAGE__;
214   if (defined $_[0])
215     {
216     my $m = shift;
217     if ($m !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
218       {
219       require Carp; Carp::croak ("Unknown round mode '$m'");
220       }
221     return ${"${class}::round_mode"} = $m;
222     }
223   ${"${class}::round_mode"};
224   }
225
226 sub upgrade
227   {
228   no strict 'refs';
229   # make Class->upgrade() work
230   my $self = shift;
231   my $class = ref($self) || $self || __PACKAGE__;
232   # need to set new value?
233   if (@_ > 0)
234     {
235     return ${"${class}::upgrade"} = $_[0];
236     }
237   ${"${class}::upgrade"};
238   }
239
240 sub downgrade
241   {
242   no strict 'refs';
243   # make Class->downgrade() work
244   my $self = shift;
245   my $class = ref($self) || $self || __PACKAGE__;
246   # need to set new value?
247   if (@_ > 0)
248     {
249     return ${"${class}::downgrade"} = $_[0];
250     }
251   ${"${class}::downgrade"};
252   }
253
254 sub div_scale
255   {
256   no strict 'refs';
257   # make Class->div_scale() work
258   my $self = shift;
259   my $class = ref($self) || $self || __PACKAGE__;
260   if (defined $_[0])
261     {
262     if ($_[0] < 0)
263       {
264       require Carp; Carp::croak ('div_scale must be greater than zero');
265       }
266     ${"${class}::div_scale"} = $_[0];
267     }
268   ${"${class}::div_scale"};
269   }
270
271 sub accuracy
272   {
273   # $x->accuracy($a);           ref($x) $a
274   # $x->accuracy();             ref($x)
275   # Class->accuracy();          class
276   # Class->accuracy($a);        class $a
277
278   my $x = shift;
279   my $class = ref($x) || $x || __PACKAGE__;
280
281   no strict 'refs';
282   # need to set new value?
283   if (@_ > 0)
284     {
285     my $a = shift;
286     # convert objects to scalars to avoid deep recursion. If object doesn't
287     # have numify(), then hopefully it will have overloading for int() and
288     # boolean test without wandering into a deep recursion path...
289     $a = $a->numify() if ref($a) && $a->can('numify');
290
291     if (defined $a)
292       {
293       # also croak on non-numerical
294       if (!$a || $a <= 0)
295         {
296         require Carp;
297         Carp::croak ('Argument to accuracy must be greater than zero');
298         }
299       if (int($a) != $a)
300         {
301         require Carp;
302         Carp::croak ('Argument to accuracy must be an integer');
303         }
304       }
305     if (ref($x))
306       {
307       # $object->accuracy() or fallback to global
308       $x->bround($a) if $a;             # not for undef, 0
309       $x->{_a} = $a;                    # set/overwrite, even if not rounded
310       delete $x->{_p};                  # clear P
311       $a = ${"${class}::accuracy"} unless defined $a;   # proper return value
312       }
313     else
314       {
315       ${"${class}::accuracy"} = $a;     # set global A
316       ${"${class}::precision"} = undef; # clear global P
317       }
318     return $a;                          # shortcut
319     }
320
321   my $a;
322   # $object->accuracy() or fallback to global
323   $a = $x->{_a} if ref($x);
324   # but don't return global undef, when $x's accuracy is 0!
325   $a = ${"${class}::accuracy"} if !defined $a;
326   $a;
327   }
328
329 sub precision
330   {
331   # $x->precision($p);          ref($x) $p
332   # $x->precision();            ref($x)
333   # Class->precision();         class
334   # Class->precision($p);       class $p
335
336   my $x = shift;
337   my $class = ref($x) || $x || __PACKAGE__;
338
339   no strict 'refs';
340   if (@_ > 0)
341     {
342     my $p = shift;
343     # convert objects to scalars to avoid deep recursion. If object doesn't
344     # have numify(), then hopefully it will have overloading for int() and
345     # boolean test without wandering into a deep recursion path...
346     $p = $p->numify() if ref($p) && $p->can('numify');
347     if ((defined $p) && (int($p) != $p))
348       {
349       require Carp; Carp::croak ('Argument to precision must be an integer');
350       }
351     if (ref($x))
352       {
353       # $object->precision() or fallback to global
354       $x->bfround($p) if $p;            # not for undef, 0
355       $x->{_p} = $p;                    # set/overwrite, even if not rounded
356       delete $x->{_a};                  # clear A
357       $p = ${"${class}::precision"} unless defined $p;  # proper return value
358       }
359     else
360       {
361       ${"${class}::precision"} = $p;    # set global P
362       ${"${class}::accuracy"} = undef;  # clear global A
363       }
364     return $p;                          # shortcut
365     }
366
367   my $p;
368   # $object->precision() or fallback to global
369   $p = $x->{_p} if ref($x);
370   # but don't return global undef, when $x's precision is 0!
371   $p = ${"${class}::precision"} if !defined $p;
372   $p;
373   }
374
375 sub config
376   {
377   # return (or set) configuration data as hash ref
378   my $class = shift || 'Math::BigInt';
379
380   no strict 'refs';
381   if (@_ > 1 || (@_ == 1 && (ref($_[0]) eq 'HASH')))
382     {
383     # try to set given options as arguments from hash
384
385     my $args = $_[0];
386     if (ref($args) ne 'HASH')
387       {
388       $args = { @_ };
389       }
390     # these values can be "set"
391     my $set_args = {};
392     foreach my $key (
393      qw/trap_inf trap_nan
394         upgrade downgrade precision accuracy round_mode div_scale/
395      )
396       {
397       $set_args->{$key} = $args->{$key} if exists $args->{$key};
398       delete $args->{$key};
399       }
400     if (keys %$args > 0)
401       {
402       require Carp;
403       Carp::croak ("Illegal key(s) '",
404        join("','",keys %$args),"' passed to $class\->config()");
405       }
406     foreach my $key (keys %$set_args)
407       {
408       if ($key =~ /^trap_(inf|nan)\z/)
409         {
410         ${"${class}::_trap_$1"} = ($set_args->{"trap_$1"} ? 1 : 0);
411         next;
412         }
413       # use a call instead of just setting the $variable to check argument
414       $class->$key($set_args->{$key});
415       }
416     }
417
418   # now return actual configuration
419
420   my $cfg = {
421     lib => $CALC,
422     lib_version => ${"${CALC}::VERSION"},
423     class => $class,
424     trap_nan => ${"${class}::_trap_nan"},
425     trap_inf => ${"${class}::_trap_inf"},
426     version => ${"${class}::VERSION"},
427     };
428   foreach my $key (qw/
429      upgrade downgrade precision accuracy round_mode div_scale
430      /)
431     {
432     $cfg->{$key} = ${"${class}::$key"};
433     };
434   if (@_ == 1 && (ref($_[0]) ne 'HASH'))
435     {
436     # calls of the style config('lib') return just this value
437     return $cfg->{$_[0]};
438     }
439   $cfg;
440   }
441
442 sub _scale_a
443   { 
444   # select accuracy parameter based on precedence,
445   # used by bround() and bfround(), may return undef for scale (means no op)
446   my ($x,$scale,$mode) = @_;
447
448   $scale = $x->{_a} unless defined $scale;
449
450   no strict 'refs';
451   my $class = ref($x);
452
453   $scale = ${ $class . '::accuracy' } unless defined $scale;
454   $mode = ${ $class . '::round_mode' } unless defined $mode;
455
456   if (defined $scale)
457     {
458     $scale = $scale->can('numify') ? $scale->numify()
459                                    : "$scale" if ref($scale);
460     $scale = int($scale);
461     }
462
463   ($scale,$mode);
464   }
465
466 sub _scale_p
467   { 
468   # select precision parameter based on precedence,
469   # used by bround() and bfround(), may return undef for scale (means no op)
470   my ($x,$scale,$mode) = @_;
471
472   $scale = $x->{_p} unless defined $scale;
473
474   no strict 'refs';
475   my $class = ref($x);
476
477   $scale = ${ $class . '::precision' } unless defined $scale;
478   $mode = ${ $class . '::round_mode' } unless defined $mode;
479
480   if (defined $scale)
481     {
482     $scale = $scale->can('numify') ? $scale->numify()
483                                    : "$scale" if ref($scale);
484     $scale = int($scale);
485     }
486
487   ($scale,$mode);
488   }
489
490 ##############################################################################
491 # constructors
492
493 sub copy
494   {
495   # if two arguments, the first one is the class to "swallow" subclasses
496   if (@_ > 1)
497     {
498     my  $self = bless {
499         sign => $_[1]->{sign}, 
500         value => $CALC->_copy($_[1]->{value}),
501     }, $_[0] if @_ > 1;
502
503     $self->{_a} = $_[1]->{_a} if defined $_[1]->{_a};
504     $self->{_p} = $_[1]->{_p} if defined $_[1]->{_p};
505     return $self;
506     }
507
508   my $self = bless {
509         sign => $_[0]->{sign}, 
510         value => $CALC->_copy($_[0]->{value}),
511         }, ref($_[0]);
512
513   $self->{_a} = $_[0]->{_a} if defined $_[0]->{_a};
514   $self->{_p} = $_[0]->{_p} if defined $_[0]->{_p};
515   $self;
516   }
517
518 sub new 
519   {
520   # create a new BigInt object from a string or another BigInt object. 
521   # see hash keys documented at top
522
523   # the argument could be an object, so avoid ||, && etc on it, this would
524   # cause costly overloaded code to be called. The only allowed ops are
525   # ref() and defined.
526
527   my ($class,$wanted,$a,$p,$r) = @_;
528
529   # avoid numify-calls by not using || on $wanted!
530   return $class->bzero($a,$p) if !defined $wanted;      # default to 0
531   return $class->copy($wanted,$a,$p,$r)
532    if ref($wanted) && $wanted->isa($class);             # MBI or subclass
533
534   $class->import() if $IMPORT == 0;             # make require work
535
536   my $self = bless {}, $class;
537
538   # shortcut for "normal" numbers
539   if ((!ref $wanted) && ($wanted =~ /^([+-]?)[1-9][0-9]*\z/))
540     {
541     $self->{sign} = $1 || '+';
542
543     if ($wanted =~ /^[+-]/)
544      {
545       # remove sign without touching wanted to make it work with constants
546       my $t = $wanted; $t =~ s/^[+-]//;
547       $self->{value} = $CALC->_new($t);
548       }
549     else
550       {
551       $self->{value} = $CALC->_new($wanted);
552       }
553     no strict 'refs';
554     if ( (defined $a) || (defined $p) 
555         || (defined ${"${class}::precision"})
556         || (defined ${"${class}::accuracy"}) 
557        )
558       {
559       $self->round($a,$p,$r) unless (@_ == 4 && !defined $a && !defined $p);
560       }
561     return $self;
562     }
563
564   # handle '+inf', '-inf' first
565   if ($wanted =~ /^[+-]?inf\z/)
566     {
567     $self->{sign} = $wanted;            # set a default sign for bstr()
568     return $self->binf($wanted);
569     }
570   # split str in m mantissa, e exponent, i integer, f fraction, v value, s sign
571   my ($mis,$miv,$mfv,$es,$ev) = _split($wanted);
572   if (!ref $mis)
573     {
574     if ($_trap_nan)
575       {
576       require Carp; Carp::croak("$wanted is not a number in $class");
577       }
578     $self->{value} = $CALC->_zero();
579     $self->{sign} = $nan;
580     return $self;
581     }
582   if (!ref $miv)
583     {
584     # _from_hex or _from_bin
585     $self->{value} = $mis->{value};
586     $self->{sign} = $mis->{sign};
587     return $self;       # throw away $mis
588     }
589   # make integer from mantissa by adjusting exp, then convert to bigint
590   $self->{sign} = $$mis;                        # store sign
591   $self->{value} = $CALC->_zero();              # for all the NaN cases
592   my $e = int("$$es$$ev");                      # exponent (avoid recursion)
593   if ($e > 0)
594     {
595     my $diff = $e - CORE::length($$mfv);
596     if ($diff < 0)                              # Not integer
597       {
598       if ($_trap_nan)
599         {
600         require Carp; Carp::croak("$wanted not an integer in $class");
601         }
602       #print "NOI 1\n";
603       return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
604       $self->{sign} = $nan;
605       }
606     else                                        # diff >= 0
607       {
608       # adjust fraction and add it to value
609       #print "diff > 0 $$miv\n";
610       $$miv = $$miv . ($$mfv . '0' x $diff);
611       }
612     }
613   else
614     {
615     if ($$mfv ne '')                            # e <= 0
616       {
617       # fraction and negative/zero E => NOI
618       if ($_trap_nan)
619         {
620         require Carp; Carp::croak("$wanted not an integer in $class");
621         }
622       #print "NOI 2 \$\$mfv '$$mfv'\n";
623       return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
624       $self->{sign} = $nan;
625       }
626     elsif ($e < 0)
627       {
628       # xE-y, and empty mfv
629       #print "xE-y\n";
630       $e = abs($e);
631       if ($$miv !~ s/0{$e}$//)          # can strip so many zero's?
632         {
633         if ($_trap_nan)
634           {
635           require Carp; Carp::croak("$wanted not an integer in $class");
636           }
637         #print "NOI 3\n";
638         return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
639         $self->{sign} = $nan;
640         }
641       }
642     }
643   $self->{sign} = '+' if $$miv eq '0';                  # normalize -0 => +0
644   $self->{value} = $CALC->_new($$miv) if $self->{sign} =~ /^[+-]$/;
645   # if any of the globals is set, use them to round and store them inside $self
646   # do not round for new($x,undef,undef) since that is used by MBF to signal
647   # no rounding
648   $self->round($a,$p,$r) unless @_ == 4 && !defined $a && !defined $p;
649   $self;
650   }
651
652 sub bnan
653   {
654   # create a bigint 'NaN', if given a BigInt, set it to 'NaN'
655   my $self = shift;
656   $self = $class if !defined $self;
657   if (!ref($self))
658     {
659     my $c = $self; $self = {}; bless $self, $c;
660     }
661   no strict 'refs';
662   if (${"${class}::_trap_nan"})
663     {
664     require Carp;
665     Carp::croak ("Tried to set $self to NaN in $class\::bnan()");
666     }
667   $self->import() if $IMPORT == 0;              # make require work
668   return if $self->modify('bnan');
669   if ($self->can('_bnan'))
670     {
671     # use subclass to initialize
672     $self->_bnan();
673     }
674   else
675     {
676     # otherwise do our own thing
677     $self->{value} = $CALC->_zero();
678     }
679   $self->{sign} = $nan;
680   delete $self->{_a}; delete $self->{_p};       # rounding NaN is silly
681   $self;
682   }
683
684 sub binf
685   {
686   # create a bigint '+-inf', if given a BigInt, set it to '+-inf'
687   # the sign is either '+', or if given, used from there
688   my $self = shift;
689   my $sign = shift; $sign = '+' if !defined $sign || $sign !~ /^-(inf)?$/;
690   $self = $class if !defined $self;
691   if (!ref($self))
692     {
693     my $c = $self; $self = {}; bless $self, $c;
694     }
695   no strict 'refs';
696   if (${"${class}::_trap_inf"})
697     {
698     require Carp;
699     Carp::croak ("Tried to set $self to +-inf in $class\::binf()");
700     }
701   $self->import() if $IMPORT == 0;              # make require work
702   return if $self->modify('binf');
703   if ($self->can('_binf'))
704     {
705     # use subclass to initialize
706     $self->_binf();
707     }
708   else
709     {
710     # otherwise do our own thing
711     $self->{value} = $CALC->_zero();
712     }
713   $sign = $sign . 'inf' if $sign !~ /inf$/;     # - => -inf
714   $self->{sign} = $sign;
715   ($self->{_a},$self->{_p}) = @_;               # take over requested rounding
716   $self;
717   }
718
719 sub bzero
720   {
721   # create a bigint '+0', if given a BigInt, set it to 0
722   my $self = shift;
723   $self = __PACKAGE__ if !defined $self;
724
725   if (!ref($self))
726     {
727     my $c = $self; $self = {}; bless $self, $c;
728     }
729   $self->import() if $IMPORT == 0;              # make require work
730   return if $self->modify('bzero');
731
732   if ($self->can('_bzero'))
733     {
734     # use subclass to initialize
735     $self->_bzero();
736     }
737   else
738     {
739     # otherwise do our own thing
740     $self->{value} = $CALC->_zero();
741     }
742   $self->{sign} = '+';
743   if (@_ > 0)
744     {
745     if (@_ > 3)
746       {
747       # call like: $x->bzero($a,$p,$r,$y);
748       ($self,$self->{_a},$self->{_p}) = $self->_find_round_parameters(@_);
749       }
750     else
751       {
752       $self->{_a} = $_[0]
753        if ( (!defined $self->{_a}) || (defined $_[0] && $_[0] > $self->{_a}));
754       $self->{_p} = $_[1]
755        if ( (!defined $self->{_p}) || (defined $_[1] && $_[1] > $self->{_p}));
756       }
757     }
758   $self;
759   }
760
761 sub bone
762   {
763   # create a bigint '+1' (or -1 if given sign '-'),
764   # if given a BigInt, set it to +1 or -1, respectively
765   my $self = shift;
766   my $sign = shift; $sign = '+' if !defined $sign || $sign ne '-';
767   $self = $class if !defined $self;
768
769   if (!ref($self))
770     {
771     my $c = $self; $self = {}; bless $self, $c;
772     }
773   $self->import() if $IMPORT == 0;              # make require work
774   return if $self->modify('bone');
775
776   if ($self->can('_bone'))
777     {
778     # use subclass to initialize
779     $self->_bone();
780     }
781   else
782     {
783     # otherwise do our own thing
784     $self->{value} = $CALC->_one();
785     }
786   $self->{sign} = $sign;
787   if (@_ > 0)
788     {
789     if (@_ > 3)
790       {
791       # call like: $x->bone($sign,$a,$p,$r,$y);
792       ($self,$self->{_a},$self->{_p}) = $self->_find_round_parameters(@_);
793       }
794     else
795       {
796       # call like: $x->bone($sign,$a,$p,$r);
797       $self->{_a} = $_[0]
798        if ( (!defined $self->{_a}) || (defined $_[0] && $_[0] > $self->{_a}));
799       $self->{_p} = $_[1]
800        if ( (!defined $self->{_p}) || (defined $_[1] && $_[1] > $self->{_p}));
801       }
802     }
803   $self;
804   }
805
806 ##############################################################################
807 # string conversion
808
809 sub bsstr
810   {
811   # (ref to BFLOAT or num_str ) return num_str
812   # Convert number from internal format to scientific string format.
813   # internal format is always normalized (no leading zeros, "-0E0" => "+0E0")
814   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_); 
815
816   if ($x->{sign} !~ /^[+-]$/)
817     {
818     return $x->{sign} unless $x->{sign} eq '+inf';      # -inf, NaN
819     return 'inf';                                       # +inf
820     }
821   my ($m,$e) = $x->parts();
822   #$m->bstr() . 'e+' . $e->bstr();      # e can only be positive in BigInt
823   # 'e+' because E can only be positive in BigInt
824   $m->bstr() . 'e+' . $CALC->_str($e->{value}); 
825   }
826
827 sub bstr 
828   {
829   # make a string from bigint object
830   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_); 
831
832   if ($x->{sign} !~ /^[+-]$/)
833     {
834     return $x->{sign} unless $x->{sign} eq '+inf';      # -inf, NaN
835     return 'inf';                                       # +inf
836     }
837   my $es = ''; $es = $x->{sign} if $x->{sign} eq '-';
838   $es.$CALC->_str($x->{value});
839   }
840
841 sub numify 
842   {
843   # Make a "normal" scalar from a BigInt object
844   my $x = shift; $x = $class->new($x) unless ref $x;
845
846   return $x->bstr() if $x->{sign} !~ /^[+-]$/;
847   my $num = $CALC->_num($x->{value});
848   return -$num if $x->{sign} eq '-';
849   $num;
850   }
851
852 ##############################################################################
853 # public stuff (usually prefixed with "b")
854
855 sub sign
856   {
857   # return the sign of the number: +/-/-inf/+inf/NaN
858   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_); 
859
860   $x->{sign};
861   }
862
863 sub _find_round_parameters
864   {
865   # After any operation or when calling round(), the result is rounded by
866   # regarding the A & P from arguments, local parameters, or globals.
867
868   # !!!!!!! If you change this, remember to change round(), too! !!!!!!!!!!
869
870   # This procedure finds the round parameters, but it is for speed reasons
871   # duplicated in round. Otherwise, it is tested by the testsuite and used
872   # by fdiv().
873
874   # returns ($self) or ($self,$a,$p,$r) - sets $self to NaN of both A and P
875   # were requested/defined (locally or globally or both)
876
877   my ($self,$a,$p,$r,@args) = @_;
878   # $a accuracy, if given by caller
879   # $p precision, if given by caller
880   # $r round_mode, if given by caller
881   # @args all 'other' arguments (0 for unary, 1 for binary ops)
882
883   my $c = ref($self);                           # find out class of argument(s)
884   no strict 'refs';
885
886   # convert to normal scalar for speed and correctness in inner parts
887   $a = $a->can('numify') ? $a->numify() : "$a" if defined $a && ref($a);
888   $p = $p->can('numify') ? $p->numify() : "$p" if defined $p && ref($p);
889
890   # now pick $a or $p, but only if we have got "arguments"
891   if (!defined $a)
892     {
893     foreach ($self,@args)
894       {
895       # take the defined one, or if both defined, the one that is smaller
896       $a = $_->{_a} if (defined $_->{_a}) && (!defined $a || $_->{_a} < $a);
897       }
898     }
899   if (!defined $p)
900     {
901     # even if $a is defined, take $p, to signal error for both defined
902     foreach ($self,@args)
903       {
904       # take the defined one, or if both defined, the one that is bigger
905       # -2 > -3, and 3 > 2
906       $p = $_->{_p} if (defined $_->{_p}) && (!defined $p || $_->{_p} > $p);
907       }
908     }
909   # if still none defined, use globals (#2)
910   $a = ${"$c\::accuracy"} unless defined $a;
911   $p = ${"$c\::precision"} unless defined $p;
912
913   # A == 0 is useless, so undef it to signal no rounding
914   $a = undef if defined $a && $a == 0;
915
916   # no rounding today? 
917   return ($self) unless defined $a || defined $p;               # early out
918
919   # set A and set P is an fatal error
920   return ($self->bnan()) if defined $a && defined $p;           # error
921
922   $r = ${"$c\::round_mode"} unless defined $r;
923   if ($r !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
924     {
925     require Carp; Carp::croak ("Unknown round mode '$r'");
926     }
927
928   $a = int($a) if defined $a;
929   $p = int($p) if defined $p;
930
931   ($self,$a,$p,$r);
932   }
933
934 sub round
935   {
936   # Round $self according to given parameters, or given second argument's
937   # parameters or global defaults 
938
939   # for speed reasons, _find_round_parameters is embedded here:
940
941   my ($self,$a,$p,$r,@args) = @_;
942   # $a accuracy, if given by caller
943   # $p precision, if given by caller
944   # $r round_mode, if given by caller
945   # @args all 'other' arguments (0 for unary, 1 for binary ops)
946
947   my $c = ref($self);                           # find out class of argument(s)
948   no strict 'refs';
949
950   # now pick $a or $p, but only if we have got "arguments"
951   if (!defined $a)
952     {
953     foreach ($self,@args)
954       {
955       # take the defined one, or if both defined, the one that is smaller
956       $a = $_->{_a} if (defined $_->{_a}) && (!defined $a || $_->{_a} < $a);
957       }
958     }
959   if (!defined $p)
960     {
961     # even if $a is defined, take $p, to signal error for both defined
962     foreach ($self,@args)
963       {
964       # take the defined one, or if both defined, the one that is bigger
965       # -2 > -3, and 3 > 2
966       $p = $_->{_p} if (defined $_->{_p}) && (!defined $p || $_->{_p} > $p);
967       }
968     }
969   # if still none defined, use globals (#2)
970   $a = ${"$c\::accuracy"} unless defined $a;
971   $p = ${"$c\::precision"} unless defined $p;
972
973   # A == 0 is useless, so undef it to signal no rounding
974   $a = undef if defined $a && $a == 0;
975
976   # no rounding today? 
977   return $self unless defined $a || defined $p;         # early out
978
979   # set A and set P is an fatal error
980   return $self->bnan() if defined $a && defined $p;
981
982   $r = ${"$c\::round_mode"} unless defined $r;
983   if ($r !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
984     {
985     require Carp; Carp::croak ("Unknown round mode '$r'");
986     }
987
988   # now round, by calling either fround or ffround:
989   if (defined $a)
990     {
991     $self->bround(int($a),$r) if !defined $self->{_a} || $self->{_a} >= $a;
992     }
993   else # both can't be undefined due to early out
994     {
995     $self->bfround(int($p),$r) if !defined $self->{_p} || $self->{_p} <= $p;
996     }
997   # bround() or bfround() already called bnorm() if nec.
998   $self;
999   }
1000
1001 sub bnorm
1002   { 
1003   # (numstr or BINT) return BINT
1004   # Normalize number -- no-op here
1005   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1006   $x;
1007   }
1008
1009 sub babs 
1010   {
1011   # (BINT or num_str) return BINT
1012   # make number absolute, or return absolute BINT from string
1013   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1014
1015   return $x if $x->modify('babs');
1016   # post-normalized abs for internal use (does nothing for NaN)
1017   $x->{sign} =~ s/^-/+/;
1018   $x;
1019   }
1020
1021 sub bsgn {
1022     # Signum function.
1023
1024     my $self = shift;
1025
1026     return $self if $self->modify('bsgn');
1027
1028     return $self -> bone("+") if $self -> is_pos();
1029     return $self -> bone("-") if $self -> is_neg();
1030     return $self;               # zero or NaN
1031 }
1032
1033 sub bneg 
1034   { 
1035   # (BINT or num_str) return BINT
1036   # negate number or make a negated number from string
1037   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1038
1039   return $x if $x->modify('bneg');
1040
1041   # for +0 do not negate (to have always normalized +0). Does nothing for 'NaN'
1042   $x->{sign} =~ tr/+-/-+/ unless ($x->{sign} eq '+' && $CALC->_is_zero($x->{value}));
1043   $x;
1044   }
1045
1046 sub bcmp 
1047   {
1048   # Compares 2 values.  Returns one of undef, <0, =0, >0. (suitable for sort)
1049   # (BINT or num_str, BINT or num_str) return cond_code
1050
1051   # set up parameters
1052   my ($self,$x,$y) = (ref($_[0]),@_);
1053
1054   # objectify is costly, so avoid it 
1055   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1056     {
1057     ($self,$x,$y) = objectify(2,@_);
1058     }
1059
1060   return $upgrade->bcmp($x,$y) if defined $upgrade &&
1061     ((!$x->isa($self)) || (!$y->isa($self)));
1062
1063   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1064     {
1065     # handle +-inf and NaN
1066     return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1067     return 0 if $x->{sign} eq $y->{sign} && $x->{sign} =~ /^[+-]inf$/;
1068     return +1 if $x->{sign} eq '+inf';
1069     return -1 if $x->{sign} eq '-inf';
1070     return -1 if $y->{sign} eq '+inf';
1071     return +1;
1072     }
1073   # check sign for speed first
1074   return 1 if $x->{sign} eq '+' && $y->{sign} eq '-';   # does also 0 <=> -y
1075   return -1 if $x->{sign} eq '-' && $y->{sign} eq '+';  # does also -x <=> 0 
1076
1077   # have same sign, so compare absolute values.  Don't make tests for zero
1078   # here because it's actually slower than testing in Calc (especially w/ Pari
1079   # et al)
1080
1081   # post-normalized compare for internal use (honors signs)
1082   if ($x->{sign} eq '+') 
1083     {
1084     # $x and $y both > 0
1085     return $CALC->_acmp($x->{value},$y->{value});
1086     }
1087
1088   # $x && $y both < 0
1089   $CALC->_acmp($y->{value},$x->{value});        # swapped acmp (lib returns 0,1,-1)
1090   }
1091
1092 sub bacmp 
1093   {
1094   # Compares 2 values, ignoring their signs. 
1095   # Returns one of undef, <0, =0, >0. (suitable for sort)
1096   # (BINT, BINT) return cond_code
1097
1098   # set up parameters
1099   my ($self,$x,$y) = (ref($_[0]),@_);
1100   # objectify is costly, so avoid it 
1101   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1102     {
1103     ($self,$x,$y) = objectify(2,@_);
1104     }
1105
1106   return $upgrade->bacmp($x,$y) if defined $upgrade &&
1107     ((!$x->isa($self)) || (!$y->isa($self)));
1108
1109   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1110     {
1111     # handle +-inf and NaN
1112     return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1113     return 0 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} =~ /^[+-]inf$/;
1114     return 1 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} !~ /^[+-]inf$/;
1115     return -1;
1116     }
1117   $CALC->_acmp($x->{value},$y->{value});        # lib does only 0,1,-1
1118   }
1119
1120 sub badd 
1121   {
1122   # add second arg (BINT or string) to first (BINT) (modifies first)
1123   # return result as BINT
1124
1125   # set up parameters
1126   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1127   # objectify is costly, so avoid it 
1128   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1129     {
1130     ($self,$x,$y,@r) = objectify(2,@_);
1131     }
1132
1133   return $x if $x->modify('badd');
1134   return $upgrade->badd($upgrade->new($x),$upgrade->new($y),@r) if defined $upgrade &&
1135     ((!$x->isa($self)) || (!$y->isa($self)));
1136
1137   $r[3] = $y;                           # no push!
1138   # inf and NaN handling
1139   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1140     {
1141     # NaN first
1142     return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1143     # inf handling
1144     if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1145       {
1146       # +inf++inf or -inf+-inf => same, rest is NaN
1147       return $x if $x->{sign} eq $y->{sign};
1148       return $x->bnan();
1149       }
1150     # +-inf + something => +inf
1151     # something +-inf => +-inf
1152     $x->{sign} = $y->{sign}, return $x if $y->{sign} =~ /^[+-]inf$/;
1153     return $x;
1154     }
1155
1156   my ($sx, $sy) = ( $x->{sign}, $y->{sign} );           # get signs
1157
1158   if ($sx eq $sy)  
1159     {
1160     $x->{value} = $CALC->_add($x->{value},$y->{value}); # same sign, abs add
1161     }
1162   else 
1163     {
1164     my $a = $CALC->_acmp ($y->{value},$x->{value});     # absolute compare
1165     if ($a > 0)                           
1166       {
1167       $x->{value} = $CALC->_sub($y->{value},$x->{value},1); # abs sub w/ swap
1168       $x->{sign} = $sy;
1169       } 
1170     elsif ($a == 0)
1171       {
1172       # speedup, if equal, set result to 0
1173       $x->{value} = $CALC->_zero();
1174       $x->{sign} = '+';
1175       }
1176     else # a < 0
1177       {
1178       $x->{value} = $CALC->_sub($x->{value}, $y->{value}); # abs sub
1179       }
1180     }
1181   $x->round(@r);
1182   }
1183
1184 sub bsub 
1185   {
1186   # (BINT or num_str, BINT or num_str) return BINT
1187   # subtract second arg from first, modify first
1188
1189   # set up parameters
1190   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1191
1192   # objectify is costly, so avoid it
1193   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1194     {
1195     ($self,$x,$y,@r) = objectify(2,@_);
1196     }
1197
1198   return $x if $x->modify('bsub');
1199
1200   return $upgrade->new($x)->bsub($upgrade->new($y),@r) if defined $upgrade &&
1201    ((!$x->isa($self)) || (!$y->isa($self)));
1202
1203   return $x->round(@r) if $y->is_zero();
1204
1205   # To correctly handle the lone special case $x->bsub($x), we note the sign
1206   # of $x, then flip the sign from $y, and if the sign of $x did change, too,
1207   # then we caught the special case:
1208   my $xsign = $x->{sign};
1209   $y->{sign} =~ tr/+\-/-+/;     # does nothing for NaN
1210   if ($xsign ne $x->{sign})
1211     {
1212     # special case of $x->bsub($x) results in 0
1213     return $x->bzero(@r) if $xsign =~ /^[+-]$/;
1214     return $x->bnan();          # NaN, -inf, +inf
1215     }
1216   $x->badd($y,@r);              # badd does not leave internal zeros
1217   $y->{sign} =~ tr/+\-/-+/;     # refix $y (does nothing for NaN)
1218   $x;                           # already rounded by badd() or no round nec.
1219   }
1220
1221 sub binc
1222   {
1223   # increment arg by one
1224   my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1225   return $x if $x->modify('binc');
1226
1227   if ($x->{sign} eq '+')
1228     {
1229     $x->{value} = $CALC->_inc($x->{value});
1230     return $x->round($a,$p,$r);
1231     }
1232   elsif ($x->{sign} eq '-')
1233     {
1234     $x->{value} = $CALC->_dec($x->{value});
1235     $x->{sign} = '+' if $CALC->_is_zero($x->{value}); # -1 +1 => -0 => +0
1236     return $x->round($a,$p,$r);
1237     }
1238   # inf, nan handling etc
1239   $x->badd($self->bone(),$a,$p,$r);             # badd does round
1240   }
1241
1242 sub bdec
1243   {
1244   # decrement arg by one
1245   my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1246   return $x if $x->modify('bdec');
1247
1248   if ($x->{sign} eq '-')
1249     {
1250     # x already < 0
1251     $x->{value} = $CALC->_inc($x->{value});
1252     } 
1253   else
1254     {
1255     return $x->badd($self->bone('-'),@r)
1256         unless $x->{sign} eq '+'; # inf or NaN
1257     # >= 0
1258     if ($CALC->_is_zero($x->{value}))
1259       {
1260       # == 0
1261       $x->{value} = $CALC->_one(); $x->{sign} = '-';            # 0 => -1
1262       }
1263     else
1264       {
1265       # > 0
1266       $x->{value} = $CALC->_dec($x->{value});
1267       }
1268     }
1269   $x->round(@r);
1270   }
1271
1272 sub blog
1273   {
1274   # calculate $x = $a ** $base + $b and return $a (e.g. the log() to base
1275   # $base of $x)
1276
1277   # set up parameters
1278   my ($self,$x,$base,@r) = (undef,@_);
1279   # objectify is costly, so avoid it
1280   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1281     {
1282     ($self,$x,$base,@r) = objectify(2,@_);
1283     }
1284
1285   return $x if $x->modify('blog');
1286
1287   $base = $self->new($base) if defined $base && !ref $base;
1288
1289   # inf, -inf, NaN, <0 => NaN
1290   return $x->bnan()
1291    if $x->{sign} ne '+' || (defined $base && $base->{sign} ne '+');
1292
1293   return $upgrade->blog($upgrade->new($x),$base,@r) if 
1294     defined $upgrade;
1295
1296   # fix for bug #24969:
1297   # the default base is e (Euler's number) which is not an integer
1298   if (!defined $base)
1299     {
1300     require Math::BigFloat;
1301     my $u = Math::BigFloat->blog(Math::BigFloat->new($x))->as_int();
1302     # modify $x in place
1303     $x->{value} = $u->{value};
1304     $x->{sign} = $u->{sign};
1305     return $x;
1306     }
1307
1308   my ($rc,$exact) = $CALC->_log_int($x->{value},$base->{value});
1309   return $x->bnan() unless defined $rc;         # not possible to take log?
1310   $x->{value} = $rc;
1311   $x->round(@r);
1312   }
1313
1314 sub bnok
1315   {
1316   # Calculate n over k (binomial coefficient or "choose" function) as integer.
1317   # set up parameters
1318   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1319
1320   # objectify is costly, so avoid it
1321   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1322     {
1323     ($self,$x,$y,@r) = objectify(2,@_);
1324     }
1325
1326   return $x if $x->modify('bnok');
1327   return $x->bnan() if $x->{sign} eq 'NaN' || $y->{sign} eq 'NaN';
1328   return $x->binf() if $x->{sign} eq '+inf';
1329
1330   # k > n or k < 0 => 0
1331   my $cmp = $x->bacmp($y);
1332   return $x->bzero() if $cmp < 0 || $y->{sign} =~ /^-/;
1333   # k == n => 1
1334   return $x->bone(@r) if $cmp == 0;
1335
1336   if ($CALC->can('_nok'))
1337     {
1338     $x->{value} = $CALC->_nok($x->{value},$y->{value});
1339     }
1340   else
1341     {
1342     # ( 7 )       7!       1*2*3*4 * 5*6*7   5 * 6 * 7       6   7
1343     # ( - ) = --------- =  --------------- = --------- = 5 * - * -
1344     # ( 3 )   (7-3)! 3!    1*2*3*4 * 1*2*3   1 * 2 * 3       2   3
1345
1346     if (!$y->is_zero())
1347       {
1348       my $z = $x - $y;
1349       $z->binc();
1350       my $r = $z->copy(); $z->binc();
1351       my $d = $self->new(2);
1352       while ($z->bacmp($x) <= 0)                # f <= x ?
1353         {
1354         $r->bmul($z); $r->bdiv($d);
1355         $z->binc(); $d->binc();
1356         }
1357       $x->{value} = $r->{value}; $x->{sign} = '+';
1358       }
1359     else { $x->bone(); }
1360     }
1361   $x->round(@r);
1362   }
1363
1364 sub bexp
1365   {
1366   # Calculate e ** $x (Euler's number to the power of X), truncated to
1367   # an integer value.
1368   my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1369   return $x if $x->modify('bexp');
1370
1371   # inf, -inf, NaN, <0 => NaN
1372   return $x->bnan() if $x->{sign} eq 'NaN';
1373   return $x->bone() if $x->is_zero();
1374   return $x if $x->{sign} eq '+inf';
1375   return $x->bzero() if $x->{sign} eq '-inf';
1376
1377   my $u;
1378   {
1379     # run through Math::BigFloat unless told otherwise
1380     require Math::BigFloat unless defined $upgrade;
1381     local $upgrade = 'Math::BigFloat' unless defined $upgrade;
1382     # calculate result, truncate it to integer
1383     $u = $upgrade->bexp($upgrade->new($x),@r);
1384   }
1385
1386   if (!defined $upgrade)
1387     {
1388     $u = $u->as_int();
1389     # modify $x in place
1390     $x->{value} = $u->{value};
1391     $x->round(@r);
1392     }
1393   else { $x = $u; }
1394   }
1395
1396 sub blcm
1397   {
1398   # (BINT or num_str, BINT or num_str) return BINT
1399   # does not modify arguments, but returns new object
1400   # Lowest Common Multiple
1401
1402   my $y = shift; my ($x);
1403   if (ref($y))
1404     {
1405     $x = $y->copy();
1406     }
1407   else
1408     {
1409     $x = $class->new($y);
1410     }
1411   my $self = ref($x);
1412   while (@_) 
1413     {
1414     my $y = shift; $y = $self->new($y) if !ref ($y);
1415     $x = __lcm($x,$y);
1416     } 
1417   $x;
1418   }
1419
1420 sub bgcd 
1421   { 
1422   # (BINT or num_str, BINT or num_str) return BINT
1423   # does not modify arguments, but returns new object
1424   # GCD -- Euclid's algorithm, variant C (Knuth Vol 3, pg 341 ff)
1425
1426   my $y = shift;
1427   $y = $class->new($y) if !ref($y);
1428   my $self = ref($y);
1429   my $x = $y->copy()->babs();                   # keep arguments
1430   return $x->bnan() if $x->{sign} !~ /^[+-]$/;  # x NaN?
1431
1432   while (@_)
1433     {
1434     $y = shift; $y = $self->new($y) if !ref($y);
1435     return $x->bnan() if $y->{sign} !~ /^[+-]$/;        # y NaN?
1436     $x->{value} = $CALC->_gcd($x->{value},$y->{value});
1437     last if $CALC->_is_one($x->{value});
1438     }
1439   $x;
1440   }
1441
1442 sub bnot 
1443   {
1444   # (num_str or BINT) return BINT
1445   # represent ~x as twos-complement number
1446   # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1447   my ($self,$x,$a,$p,$r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1448
1449   return $x if $x->modify('bnot');
1450   $x->binc()->bneg();                   # binc already does round
1451   }
1452
1453 ##############################################################################
1454 # is_foo test routines
1455 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1456
1457 sub is_zero
1458   {
1459   # return true if arg (BINT or num_str) is zero (array '+', '0')
1460   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1461
1462   return 0 if $x->{sign} !~ /^\+$/;                     # -, NaN & +-inf aren't
1463   $CALC->_is_zero($x->{value});
1464   }
1465
1466 sub is_nan
1467   {
1468   # return true if arg (BINT or num_str) is NaN
1469   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1470
1471   $x->{sign} eq $nan ? 1 : 0;
1472   }
1473
1474 sub is_inf
1475   {
1476   # return true if arg (BINT or num_str) is +-inf
1477   my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1478
1479   if (defined $sign)
1480     {
1481     $sign = '[+-]inf' if $sign eq '';   # +- doesn't matter, only that's inf
1482     $sign = "[$1]inf" if $sign =~ /^([+-])(inf)?$/;     # extract '+' or '-'
1483     return $x->{sign} =~ /^$sign$/ ? 1 : 0;
1484     }
1485   $x->{sign} =~ /^[+-]inf$/ ? 1 : 0;            # only +-inf is infinity
1486   }
1487
1488 sub is_one
1489   {
1490   # return true if arg (BINT or num_str) is +1, or -1 if sign is given
1491   my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1492
1493   $sign = '+' if !defined $sign || $sign ne '-';
1494
1495   return 0 if $x->{sign} ne $sign;      # -1 != +1, NaN, +-inf aren't either
1496   $CALC->_is_one($x->{value});
1497   }
1498
1499 sub is_odd
1500   {
1501   # return true when arg (BINT or num_str) is odd, false for even
1502   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1503
1504   return 0 if $x->{sign} !~ /^[+-]$/;                   # NaN & +-inf aren't
1505   $CALC->_is_odd($x->{value});
1506   }
1507
1508 sub is_even
1509   {
1510   # return true when arg (BINT or num_str) is even, false for odd
1511   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1512
1513   return 0 if $x->{sign} !~ /^[+-]$/;                   # NaN & +-inf aren't
1514   $CALC->_is_even($x->{value});
1515   }
1516
1517 sub is_positive
1518   {
1519   # return true when arg (BINT or num_str) is positive (> 0)
1520   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1521
1522   return 1 if $x->{sign} eq '+inf';                     # +inf is positive
1523
1524   # 0+ is neither positive nor negative
1525   ($x->{sign} eq '+' && !$x->is_zero()) ? 1 : 0;
1526   }
1527
1528 sub is_negative
1529   {
1530   # return true when arg (BINT or num_str) is negative (< 0)
1531   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1532
1533   $x->{sign} =~ /^-/ ? 1 : 0;           # -inf is negative, but NaN is not
1534   }
1535
1536 sub is_int
1537   {
1538   # return true when arg (BINT or num_str) is an integer
1539   # always true for BigInt, but different for BigFloats
1540   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1541
1542   $x->{sign} =~ /^[+-]$/ ? 1 : 0;               # inf/-inf/NaN aren't
1543   }
1544
1545 ###############################################################################
1546
1547 sub bmul 
1548   { 
1549   # multiply the first number by the second number
1550   # (BINT or num_str, BINT or num_str) return BINT
1551
1552   # set up parameters
1553   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1554   # objectify is costly, so avoid it
1555   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1556     {
1557     ($self,$x,$y,@r) = objectify(2,@_);
1558     }
1559
1560   return $x if $x->modify('bmul');
1561
1562   return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1563
1564   # inf handling
1565   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1566     {
1567     return $x->bnan() if $x->is_zero() || $y->is_zero();
1568     # result will always be +-inf:
1569     # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1570     # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1571     return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/); 
1572     return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/); 
1573     return $x->binf('-');
1574     }
1575
1576   return $upgrade->bmul($x,$upgrade->new($y),@r)
1577    if defined $upgrade && !$y->isa($self);
1578
1579   $r[3] = $y;                           # no push here
1580
1581   $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1582
1583   $x->{value} = $CALC->_mul($x->{value},$y->{value});   # do actual math
1584   $x->{sign} = '+' if $CALC->_is_zero($x->{value});     # no -0
1585
1586   $x->round(@r);
1587   }
1588
1589 sub bmuladd
1590   { 
1591   # multiply two numbers and then add the third to the result
1592   # (BINT or num_str, BINT or num_str, BINT or num_str) return BINT
1593
1594   # set up parameters
1595   my ($self,$x,$y,$z,@r) = objectify(3,@_);
1596
1597   return $x if $x->modify('bmuladd');
1598
1599   return $x->bnan() if  ($x->{sign} eq $nan) ||
1600                         ($y->{sign} eq $nan) ||
1601                         ($z->{sign} eq $nan);
1602
1603   # inf handling of x and y
1604   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1605     {
1606     return $x->bnan() if $x->is_zero() || $y->is_zero();
1607     # result will always be +-inf:
1608     # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1609     # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1610     return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/); 
1611     return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/); 
1612     return $x->binf('-');
1613     }
1614   # inf handling x*y and z
1615   if (($z->{sign} =~ /^[+-]inf$/))
1616     {
1617     # something +-inf => +-inf
1618     $x->{sign} = $z->{sign}, return $x if $z->{sign} =~ /^[+-]inf$/;
1619     }
1620
1621   return $upgrade->bmuladd($x,$upgrade->new($y),$upgrade->new($z),@r)
1622    if defined $upgrade && (!$y->isa($self) || !$z->isa($self) || !$x->isa($self));
1623
1624   # TODO: what if $y and $z have A or P set?
1625   $r[3] = $z;                           # no push here
1626
1627   $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1628
1629   $x->{value} = $CALC->_mul($x->{value},$y->{value});   # do actual math
1630   $x->{sign} = '+' if $CALC->_is_zero($x->{value});     # no -0
1631
1632   my ($sx, $sz) = ( $x->{sign}, $z->{sign} );           # get signs
1633
1634   if ($sx eq $sz)  
1635     {
1636     $x->{value} = $CALC->_add($x->{value},$z->{value}); # same sign, abs add
1637     }
1638   else 
1639     {
1640     my $a = $CALC->_acmp ($z->{value},$x->{value});     # absolute compare
1641     if ($a > 0)                           
1642       {
1643       $x->{value} = $CALC->_sub($z->{value},$x->{value},1); # abs sub w/ swap
1644       $x->{sign} = $sz;
1645       } 
1646     elsif ($a == 0)
1647       {
1648       # speedup, if equal, set result to 0
1649       $x->{value} = $CALC->_zero();
1650       $x->{sign} = '+';
1651       }
1652     else # a < 0
1653       {
1654       $x->{value} = $CALC->_sub($x->{value}, $z->{value}); # abs sub
1655       }
1656     }
1657   $x->round(@r);
1658   }
1659
1660 sub _div_inf
1661   {
1662   # helper function that handles +-inf cases for bdiv()/bmod() to reuse code
1663   my ($self,$x,$y) = @_;
1664
1665   # NaN if x == NaN or y == NaN or x==y==0
1666   return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan()
1667    if (($x->is_nan() || $y->is_nan())   ||
1668        ($x->is_zero() && $y->is_zero()));
1669
1670   # +-inf / +-inf == NaN, remainder also NaN
1671   if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1672     {
1673     return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan();
1674     }
1675   # x / +-inf => 0, remainder x (works even if x == 0)
1676   if ($y->{sign} =~ /^[+-]inf$/)
1677     {
1678     my $t = $x->copy();         # bzero clobbers up $x
1679     return wantarray ? ($x->bzero(),$t) : $x->bzero()
1680     }
1681
1682   # 5 / 0 => +inf, -6 / 0 => -inf
1683   # +inf / 0 = inf, inf,  and -inf / 0 => -inf, -inf 
1684   # exception:   -8 / 0 has remainder -8, not 8
1685   # exception: -inf / 0 has remainder -inf, not inf
1686   if ($y->is_zero())
1687     {
1688     # +-inf / 0 => special case for -inf
1689     return wantarray ?  ($x,$x->copy()) : $x if $x->is_inf();
1690     if (!$x->is_zero() && !$x->is_inf())
1691       {
1692       my $t = $x->copy();               # binf clobbers up $x
1693       return wantarray ?
1694        ($x->binf($x->{sign}),$t) : $x->binf($x->{sign})
1695       }
1696     }
1697
1698   # last case: +-inf / ordinary number
1699   my $sign = '+inf';
1700   $sign = '-inf' if substr($x->{sign},0,1) ne $y->{sign};
1701   $x->{sign} = $sign;
1702   return wantarray ? ($x,$self->bzero()) : $x;
1703   }
1704
1705 sub bdiv 
1706   {
1707   # (dividend: BINT or num_str, divisor: BINT or num_str) return 
1708   # (BINT,BINT) (quo,rem) or BINT (only rem)
1709
1710   # set up parameters
1711   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1712   # objectify is costly, so avoid it 
1713   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1714     {
1715     ($self,$x,$y,@r) = objectify(2,@_);
1716     } 
1717
1718   return $x if $x->modify('bdiv');
1719
1720   return $self->_div_inf($x,$y)
1721    if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero());
1722
1723   return $upgrade->bdiv($upgrade->new($x),$upgrade->new($y),@r)
1724    if defined $upgrade;
1725
1726   $r[3] = $y;                                   # no push!
1727
1728   # calc new sign and in case $y == +/- 1, return $x
1729   my $xsign = $x->{sign};                               # keep
1730   $x->{sign} = ($x->{sign} ne $y->{sign} ? '-' : '+'); 
1731
1732   if (wantarray)
1733     {
1734     my $rem = $self->bzero(); 
1735     ($x->{value},$rem->{value}) = $CALC->_div($x->{value},$y->{value});
1736     $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1737     $rem->{_a} = $x->{_a};
1738     $rem->{_p} = $x->{_p};
1739     $x->round(@r);
1740     if (! $CALC->_is_zero($rem->{value}))
1741       {
1742       $rem->{sign} = $y->{sign};
1743       $rem = $y->copy()->bsub($rem) if $xsign ne $y->{sign}; # one of them '-'
1744       }
1745     else
1746       {
1747       $rem->{sign} = '+';                       # do not leave -0
1748       }
1749     $rem->round(@r);
1750     return ($x,$rem);
1751     }
1752
1753   $x->{value} = $CALC->_div($x->{value},$y->{value});
1754   $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1755
1756   $x->round(@r);
1757   }
1758
1759 ###############################################################################
1760 # modulus functions
1761
1762 sub bmod 
1763   {
1764   # modulus (or remainder)
1765   # (BINT or num_str, BINT or num_str) return BINT
1766
1767   # set up parameters
1768   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1769   # objectify is costly, so avoid it
1770   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1771     {
1772     ($self,$x,$y,@r) = objectify(2,@_);
1773     }
1774
1775   return $x if $x->modify('bmod');
1776   $r[3] = $y;                                   # no push!
1777   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero())
1778     {
1779     my ($d,$r) = $self->_div_inf($x,$y);
1780     $x->{sign} = $r->{sign};
1781     $x->{value} = $r->{value};
1782     return $x->round(@r);
1783     }
1784
1785   # calc new sign and in case $y == +/- 1, return $x
1786   $x->{value} = $CALC->_mod($x->{value},$y->{value});
1787   if (!$CALC->_is_zero($x->{value}))
1788     {
1789     $x->{value} = $CALC->_sub($y->{value},$x->{value},1)        # $y-$x
1790       if ($x->{sign} ne $y->{sign});
1791     $x->{sign} = $y->{sign};
1792     }
1793    else
1794     {
1795     $x->{sign} = '+';                           # do not leave -0
1796     }
1797   $x->round(@r);
1798   }
1799
1800 sub bmodinv
1801   {
1802   # Return modular multiplicative inverse: z is the modular inverse of x (mod
1803   # y) if and only if x*z (mod y) = 1 (mod y). If the modulus y is larger than
1804   # one, x and z are relative primes (i.e., their greatest common divisor is
1805   # one).
1806   #
1807   # If no modular multiplicative inverse exists, NaN is returned.
1808
1809   # set up parameters
1810   my ($self,$x,$y,@r) = (undef,@_);
1811   # objectify is costly, so avoid it
1812   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1813     {
1814     ($self,$x,$y,@r) = objectify(2,@_);
1815     }
1816
1817   return $x if $x->modify('bmodinv');
1818
1819   # Return NaN if one or both arguments is +inf, -inf, or nan.
1820
1821   return $x->bnan() if ($y->{sign} !~ /^[+-]$/ ||
1822                         $x->{sign} !~ /^[+-]$/);
1823
1824   # Return NaN if $y is zero; 1 % 0 makes no sense.
1825
1826   return $x->bnan() if $y->is_zero();
1827
1828   # Return 0 in the trivial case. $x % 1 or $x % -1 is zero for all finite
1829   # integers $x.
1830
1831   return $x->bzero() if ($y->is_one() ||
1832                          $y->is_one('-'));
1833
1834   # Return NaN if $x = 0, or $x modulo $y is zero. The only valid case when
1835   # $x = 0 is when $y = 1 or $y = -1, but that was covered above.
1836   #
1837   # Note that computing $x modulo $y here affects the value we'll feed to
1838   # $CALC->_modinv() below when $x and $y have opposite signs. E.g., if $x =
1839   # 5 and $y = 7, those two values are fed to _modinv(), but if $x = -5 and
1840   # $y = 7, the values fed to _modinv() are $x = 2 (= -5 % 7) and $y = 7.
1841   # The value if $x is affected only when $x and $y have opposite signs.
1842
1843   $x->bmod($y);
1844   return $x->bnan() if $x->is_zero();
1845
1846   # Compute the modular multiplicative inverse of the absolute values. We'll
1847   # correct for the signs of $x and $y later. Return NaN if no GCD is found.
1848
1849   ($x->{value}, $x->{sign}) = $CALC->_modinv($x->{value}, $y->{value});
1850   return $x->bnan() if !defined $x->{value};
1851
1852   # Library inconsistency workaround: _modinv() in Math::BigInt::GMP versions
1853   # <= 1.32 return undef rather than a "+" for the sign.
1854
1855   $x->{sign} = '+' unless defined $x->{sign};
1856
1857   # When one or both arguments are negative, we have the following
1858   # relations.  If x and y are positive:
1859   #
1860   #   modinv(-x, -y) = -modinv(x, y)
1861   #   modinv(-x,  y) = y - modinv(x, y)  = -modinv(x, y) (mod y)
1862   #   modinv( x, -y) = modinv(x, y) - y  =  modinv(x, y) (mod -y)
1863
1864   # We must swap the sign of the result if the original $x is negative.
1865   # However, we must compensate for ignoring the signs when computing the
1866   # inverse modulo. The net effect is that we must swap the sign of the
1867   # result if $y is negative.
1868
1869   $x -> bneg() if $y->{sign} eq '-';
1870
1871   # Compute $x modulo $y again after correcting the sign.
1872
1873   $x -> bmod($y) if $x->{sign} ne $y->{sign};
1874
1875   return $x;
1876   }
1877
1878 sub bmodpow
1879   {
1880   # Modular exponentiation. Raises a very large number to a very large exponent
1881   # in a given very large modulus quickly, thanks to binary exponentiation.
1882   # Supports negative exponents.
1883   my ($self,$num,$exp,$mod,@r) = objectify(3,@_);
1884
1885   return $num if $num->modify('bmodpow');
1886
1887   # When the exponent 'e' is negative, use the following relation, which is
1888   # based on finding the multiplicative inverse 'd' of 'b' modulo 'm':
1889   #
1890   #    b^(-e) (mod m) = d^e (mod m) where b*d = 1 (mod m)
1891
1892   $num->bmodinv($mod) if ($exp->{sign} eq '-');
1893
1894   # Check for valid input. All operands must be finite, and the modulus must be
1895   # non-zero.
1896
1897   return $num->bnan() if ($num->{sign} =~ /NaN|inf/ ||  # NaN, -inf, +inf
1898                           $exp->{sign} =~ /NaN|inf/ ||  # NaN, -inf, +inf
1899                           $mod->{sign} =~ /NaN|inf/ ||  # NaN, -inf, +inf
1900                           $mod->is_zero());
1901
1902   # Compute 'a (mod m)', ignoring the signs on 'a' and 'm'. If the resulting
1903   # value is zero, the output is also zero, regardless of the signs on 'a' and
1904   # 'm'.
1905
1906   my $value = $CALC->_modpow($num->{value}, $exp->{value}, $mod->{value});
1907   my $sign  = '+';
1908
1909   # If the resulting value is non-zero, we have four special cases, depending
1910   # on the signs on 'a' and 'm'.
1911
1912   unless ($CALC->_is_zero($value)) {
1913
1914       # There is a negative sign on 'a' (= $num**$exp) only if the number we
1915       # are exponentiating ($num) is negative and the exponent ($exp) is odd.
1916
1917       if ($num->{sign} eq '-' && $exp->is_odd()) {
1918
1919           # When both the number 'a' and the modulus 'm' have a negative sign,
1920           # use this relation:
1921           #
1922           #    -a (mod -m) = -(a (mod m))
1923
1924           if ($mod->{sign} eq '-') {
1925               $sign = '-';
1926           }
1927
1928           # When only the number 'a' has a negative sign, use this relation:
1929           #
1930           #    -a (mod m) = m - (a (mod m))
1931
1932           else {
1933               # Use copy of $mod since _sub() modifies the first argument.
1934               my $mod = $CALC->_copy($mod->{value});
1935               $value = $CALC->_sub($mod, $value);
1936               $sign  = '+';
1937           }
1938
1939       } else {
1940
1941           # When only the modulus 'm' has a negative sign, use this relation:
1942           #
1943           #    a (mod -m) = (a (mod m)) - m
1944           #               = -(m - (a (mod m)))
1945
1946           if ($mod->{sign} eq '-') {
1947               # Use copy of $mod since _sub() modifies the first argument.
1948               my $mod = $CALC->_copy($mod->{value});
1949               $value = $CALC->_sub($mod, $value);
1950               $sign  = '-';
1951           }
1952
1953           # When neither the number 'a' nor the modulus 'm' have a negative
1954           # sign, directly return the already computed value.
1955           #
1956           #    (a (mod m))
1957
1958       }
1959
1960   }
1961
1962   $num->{value} = $value;
1963   $num->{sign}  = $sign;
1964
1965   return $num;
1966   }
1967
1968 ###############################################################################
1969
1970 sub bfac
1971   {
1972   # (BINT or num_str, BINT or num_str) return BINT
1973   # compute factorial number from $x, modify $x in place
1974   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1975
1976   return $x if $x->modify('bfac') || $x->{sign} eq '+inf';      # inf => inf
1977   return $x->bnan() if $x->{sign} ne '+';                       # NaN, <0 etc => NaN
1978
1979   $x->{value} = $CALC->_fac($x->{value});
1980   $x->round(@r);
1981   }
1982
1983 sub bpow 
1984   {
1985   # (BINT or num_str, BINT or num_str) return BINT
1986   # compute power of two numbers -- stolen from Knuth Vol 2 pg 233
1987   # modifies first argument
1988
1989   # set up parameters
1990   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1991   # objectify is costly, so avoid it
1992   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1993     {
1994     ($self,$x,$y,@r) = objectify(2,@_);
1995     }
1996
1997   return $x if $x->modify('bpow');
1998
1999   return $x->bnan() if $x->{sign} eq $nan || $y->{sign} eq $nan;
2000
2001   # inf handling
2002   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
2003     {
2004     if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
2005       {
2006       # +-inf ** +-inf
2007       return $x->bnan();
2008       }
2009     # +-inf ** Y
2010     if ($x->{sign} =~ /^[+-]inf/)
2011       {
2012       # +inf ** 0 => NaN
2013       return $x->bnan() if $y->is_zero();
2014       # -inf ** -1 => 1/inf => 0
2015       return $x->bzero() if $y->is_one('-') && $x->is_negative();
2016
2017       # +inf ** Y => inf
2018       return $x if $x->{sign} eq '+inf';
2019
2020       # -inf ** Y => -inf if Y is odd
2021       return $x if $y->is_odd();
2022       return $x->babs();
2023       }
2024     # X ** +-inf
2025
2026     # 1 ** +inf => 1
2027     return $x if $x->is_one();
2028
2029     # 0 ** inf => 0
2030     return $x if $x->is_zero() && $y->{sign} =~ /^[+]/;
2031
2032     # 0 ** -inf => inf
2033     return $x->binf() if $x->is_zero();
2034
2035     # -1 ** -inf => NaN
2036     return $x->bnan() if $x->is_one('-') && $y->{sign} =~ /^[-]/;
2037
2038     # -X ** -inf => 0
2039     return $x->bzero() if $x->{sign} eq '-' && $y->{sign} =~ /^[-]/;
2040
2041     # -1 ** inf => NaN
2042     return $x->bnan() if $x->{sign} eq '-';
2043
2044     # X ** inf => inf
2045     return $x->binf() if $y->{sign} =~ /^[+]/;
2046     # X ** -inf => 0
2047     return $x->bzero();
2048     }
2049
2050   return $upgrade->bpow($upgrade->new($x),$y,@r)
2051    if defined $upgrade && (!$y->isa($self) || $y->{sign} eq '-');
2052
2053   $r[3] = $y;                                   # no push!
2054
2055   # cases 0 ** Y, X ** 0, X ** 1, 1 ** Y are handled by Calc or Emu
2056
2057   my $new_sign = '+';
2058   $new_sign = $y->is_odd() ? '-' : '+' if ($x->{sign} ne '+'); 
2059
2060   # 0 ** -7 => ( 1 / (0 ** 7)) => 1 / 0 => +inf 
2061   return $x->binf() 
2062     if $y->{sign} eq '-' && $x->{sign} eq '+' && $CALC->_is_zero($x->{value});
2063   # 1 ** -y => 1 / (1 ** |y|)
2064   # so do test for negative $y after above's clause
2065   return $x->bnan() if $y->{sign} eq '-' && !$CALC->_is_one($x->{value});
2066
2067   $x->{value} = $CALC->_pow($x->{value},$y->{value});
2068   $x->{sign} = $new_sign;
2069   $x->{sign} = '+' if $CALC->_is_zero($y->{value});
2070   $x->round(@r);
2071   }
2072
2073 sub blsft 
2074   {
2075   # (BINT or num_str, BINT or num_str) return BINT
2076   # compute x << y, base n, y >= 0
2077
2078   # set up parameters
2079   my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
2080   # objectify is costly, so avoid it
2081   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2082     {
2083     ($self,$x,$y,$n,@r) = objectify(2,@_);
2084     }
2085
2086   return $x if $x->modify('blsft');
2087   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2088   return $x->round(@r) if $y->is_zero();
2089
2090   $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
2091
2092   $x->{value} = $CALC->_lsft($x->{value},$y->{value},$n);
2093   $x->round(@r);
2094   }
2095
2096 sub brsft 
2097   {
2098   # (BINT or num_str, BINT or num_str) return BINT
2099   # compute x >> y, base n, y >= 0
2100
2101   # set up parameters
2102   my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
2103   # objectify is costly, so avoid it
2104   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2105     {
2106     ($self,$x,$y,$n,@r) = objectify(2,@_);
2107     }
2108
2109   return $x if $x->modify('brsft');
2110   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2111   return $x->round(@r) if $y->is_zero();
2112   return $x->bzero(@r) if $x->is_zero();                # 0 => 0
2113
2114   $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
2115
2116    # this only works for negative numbers when shifting in base 2
2117   if (($x->{sign} eq '-') && ($n == 2))
2118     {
2119     return $x->round(@r) if $x->is_one('-');    # -1 => -1
2120     if (!$y->is_one())
2121       {
2122       # although this is O(N*N) in calc (as_bin!) it is O(N) in Pari et al
2123       # but perhaps there is a better emulation for two's complement shift...
2124       # if $y != 1, we must simulate it by doing:
2125       # convert to bin, flip all bits, shift, and be done
2126       $x->binc();                       # -3 => -2
2127       my $bin = $x->as_bin();
2128       $bin =~ s/^-0b//;                 # strip '-0b' prefix
2129       $bin =~ tr/10/01/;                # flip bits
2130       # now shift
2131       if ($y >= CORE::length($bin))
2132         {
2133         $bin = '0';                     # shifting to far right creates -1
2134                                         # 0, because later increment makes 
2135                                         # that 1, attached '-' makes it '-1'
2136                                         # because -1 >> x == -1 !
2137         } 
2138       else
2139         {
2140         $bin =~ s/.{$y}$//;             # cut off at the right side
2141         $bin = '1' . $bin;              # extend left side by one dummy '1'
2142         $bin =~ tr/10/01/;              # flip bits back
2143         }
2144       my $res = $self->new('0b'.$bin);  # add prefix and convert back
2145       $res->binc();                     # remember to increment
2146       $x->{value} = $res->{value};      # take over value
2147       return $x->round(@r);             # we are done now, magic, isn't?
2148       }
2149     # x < 0, n == 2, y == 1
2150     $x->bdec();                         # n == 2, but $y == 1: this fixes it
2151     }
2152
2153   $x->{value} = $CALC->_rsft($x->{value},$y->{value},$n);
2154   $x->round(@r);
2155   }
2156
2157 sub band 
2158   {
2159   #(BINT or num_str, BINT or num_str) return BINT
2160   # compute x & y
2161
2162   # set up parameters
2163   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2164   # objectify is costly, so avoid it
2165   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2166     {
2167     ($self,$x,$y,@r) = objectify(2,@_);
2168     }
2169
2170   return $x if $x->modify('band');
2171
2172   $r[3] = $y;                           # no push!
2173
2174   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2175
2176   my $sx = $x->{sign} eq '+' ? 1 : -1;
2177   my $sy = $y->{sign} eq '+' ? 1 : -1;
2178
2179   if ($sx == 1 && $sy == 1)
2180     {
2181     $x->{value} = $CALC->_and($x->{value},$y->{value});
2182     return $x->round(@r);
2183     }
2184
2185   if ($CAN{signed_and})
2186     {
2187     $x->{value} = $CALC->_signed_and($x->{value},$y->{value},$sx,$sy);
2188     return $x->round(@r);
2189     }
2190
2191   require $EMU_LIB;
2192   __emu_band($self,$x,$y,$sx,$sy,@r);
2193   }
2194
2195 sub bior 
2196   {
2197   #(BINT or num_str, BINT or num_str) return BINT
2198   # compute x | y
2199
2200   # set up parameters
2201   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2202   # objectify is costly, so avoid it
2203   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2204     {
2205     ($self,$x,$y,@r) = objectify(2,@_);
2206     }
2207
2208   return $x if $x->modify('bior');
2209   $r[3] = $y;                           # no push!
2210
2211   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2212
2213   my $sx = $x->{sign} eq '+' ? 1 : -1;
2214   my $sy = $y->{sign} eq '+' ? 1 : -1;
2215
2216   # the sign of X follows the sign of X, e.g. sign of Y irrelevant for bior()
2217
2218   # don't use lib for negative values
2219   if ($sx == 1 && $sy == 1)
2220     {
2221     $x->{value} = $CALC->_or($x->{value},$y->{value});
2222     return $x->round(@r);
2223     }
2224
2225   # if lib can do negative values, let it handle this
2226   if ($CAN{signed_or})
2227     {
2228     $x->{value} = $CALC->_signed_or($x->{value},$y->{value},$sx,$sy);
2229     return $x->round(@r);
2230     }
2231
2232   require $EMU_LIB;
2233   __emu_bior($self,$x,$y,$sx,$sy,@r);
2234   }
2235
2236 sub bxor 
2237   {
2238   #(BINT or num_str, BINT or num_str) return BINT
2239   # compute x ^ y
2240
2241   # set up parameters
2242   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2243   # objectify is costly, so avoid it
2244   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2245     {
2246     ($self,$x,$y,@r) = objectify(2,@_);
2247     }
2248
2249   return $x if $x->modify('bxor');
2250   $r[3] = $y;                           # no push!
2251
2252   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2253
2254   my $sx = $x->{sign} eq '+' ? 1 : -1;
2255   my $sy = $y->{sign} eq '+' ? 1 : -1;
2256
2257   # don't use lib for negative values
2258   if ($sx == 1 && $sy == 1)
2259     {
2260     $x->{value} = $CALC->_xor($x->{value},$y->{value});
2261     return $x->round(@r);
2262     }
2263
2264   # if lib can do negative values, let it handle this
2265   if ($CAN{signed_xor})
2266     {
2267     $x->{value} = $CALC->_signed_xor($x->{value},$y->{value},$sx,$sy);
2268     return $x->round(@r);
2269     }
2270
2271   require $EMU_LIB;
2272   __emu_bxor($self,$x,$y,$sx,$sy,@r);
2273   }
2274
2275 sub length
2276   {
2277   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2278
2279   my $e = $CALC->_len($x->{value}); 
2280   wantarray ? ($e,0) : $e;
2281   }
2282
2283 sub digit
2284   {
2285   # return the nth decimal digit, negative values count backward, 0 is right
2286   my ($self,$x,$n) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2287
2288   $n = $n->numify() if ref($n);
2289   $CALC->_digit($x->{value},$n||0);
2290   }
2291
2292 sub _trailing_zeros
2293   {
2294   # return the amount of trailing zeros in $x (as scalar)
2295   my $x = shift;
2296   $x = $class->new($x) unless ref $x;
2297
2298   return 0 if $x->{sign} !~ /^[+-]$/;   # NaN, inf, -inf etc
2299
2300   $CALC->_zeros($x->{value});           # must handle odd values, 0 etc
2301   }
2302
2303 sub bsqrt
2304   {
2305   # calculate square root of $x
2306   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2307
2308   return $x if $x->modify('bsqrt');
2309
2310   return $x->bnan() if $x->{sign} !~ /^\+/;     # -x or -inf or NaN => NaN
2311   return $x if $x->{sign} eq '+inf';            # sqrt(+inf) == inf
2312
2313   return $upgrade->bsqrt($x,@r) if defined $upgrade;
2314
2315   $x->{value} = $CALC->_sqrt($x->{value});
2316   $x->round(@r);
2317   }
2318
2319 sub broot
2320   {
2321   # calculate $y'th root of $x
2322
2323   # set up parameters
2324   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2325
2326   $y = $self->new(2) unless defined $y;
2327
2328   # objectify is costly, so avoid it
2329   if ((!ref($x)) || (ref($x) ne ref($y)))
2330     {
2331     ($self,$x,$y,@r) = objectify(2,$self || $class,@_);
2332     }
2333
2334   return $x if $x->modify('broot');
2335
2336   # NaN handling: $x ** 1/0, x or y NaN, or y inf/-inf or y == 0
2337   return $x->bnan() if $x->{sign} !~ /^\+/ || $y->is_zero() ||
2338          $y->{sign} !~ /^\+$/;
2339
2340   return $x->round(@r)
2341     if $x->is_zero() || $x->is_one() || $x->is_inf() || $y->is_one();
2342
2343   return $upgrade->new($x)->broot($upgrade->new($y),@r) if defined $upgrade;
2344
2345   $x->{value} = $CALC->_root($x->{value},$y->{value});
2346   $x->round(@r);
2347   }
2348
2349 sub exponent
2350   {
2351   # return a copy of the exponent (here always 0, NaN or 1 for $m == 0)
2352   my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2353
2354   if ($x->{sign} !~ /^[+-]$/)
2355     {
2356     my $s = $x->{sign}; $s =~ s/^[+-]//;  # NaN, -inf,+inf => NaN or inf
2357     return $self->new($s);
2358     }
2359   return $self->bone() if $x->is_zero();
2360
2361   # 12300 => 2 trailing zeros => exponent is 2
2362   $self->new( $CALC->_zeros($x->{value}) );
2363   }
2364
2365 sub mantissa
2366   {
2367   # return the mantissa (compatible to Math::BigFloat, e.g. reduced)
2368   my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2369
2370   if ($x->{sign} !~ /^[+-]$/)
2371     {
2372     # for NaN, +inf, -inf: keep the sign
2373     return $self->new($x->{sign});
2374     }
2375   my $m = $x->copy(); delete $m->{_p}; delete $m->{_a};
2376
2377   # that's a bit inefficient:
2378   my $zeros = $CALC->_zeros($m->{value});
2379   $m->brsft($zeros,10) if $zeros != 0;
2380   $m;
2381   }
2382
2383 sub parts
2384   {
2385   # return a copy of both the exponent and the mantissa
2386   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2387
2388   ($x->mantissa(),$x->exponent());
2389   }
2390
2391 ##############################################################################
2392 # rounding functions
2393
2394 sub bfround
2395   {
2396   # precision: round to the $Nth digit left (+$n) or right (-$n) from the '.'
2397   # $n == 0 || $n == 1 => round to integer
2398   my $x = shift; my $self = ref($x) || $x; $x = $self->new($x) unless ref $x;
2399
2400   my ($scale,$mode) = $x->_scale_p(@_);
2401
2402   return $x if !defined $scale || $x->modify('bfround');        # no-op
2403
2404   # no-op for BigInts if $n <= 0
2405   $x->bround( $x->length()-$scale, $mode) if $scale > 0;
2406
2407   delete $x->{_a};      # delete to save memory
2408   $x->{_p} = $scale;    # store new _p
2409   $x;
2410   }
2411
2412 sub _scan_for_nonzero
2413   {
2414   # internal, used by bround() to scan for non-zeros after a '5'
2415   my ($x,$pad,$xs,$len) = @_;
2416
2417   return 0 if $len == 1;                # "5" is trailed by invisible zeros
2418   my $follow = $pad - 1;
2419   return 0 if $follow > $len || $follow < 1;
2420
2421   # use the string form to check whether only '0's follow or not
2422   substr ($xs,-$follow) =~ /[^0]/ ? 1 : 0;
2423   }
2424
2425 sub fround
2426   {
2427   # Exists to make life easier for switch between MBF and MBI (should we
2428   # autoload fxxx() like MBF does for bxxx()?)
2429   my $x = shift; $x = $class->new($x) unless ref $x;
2430   $x->bround(@_);
2431   }
2432
2433 sub bround
2434   {
2435   # accuracy: +$n preserve $n digits from left,
2436   #           -$n preserve $n digits from right (f.i. for 0.1234 style in MBF)
2437   # no-op for $n == 0
2438   # and overwrite the rest with 0's, return normalized number
2439   # do not return $x->bnorm(), but $x
2440
2441   my $x = shift; $x = $class->new($x) unless ref $x;
2442   my ($scale,$mode) = $x->_scale_a(@_);
2443   return $x if !defined $scale || $x->modify('bround'); # no-op
2444
2445   if ($x->is_zero() || $scale == 0)
2446     {
2447     $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2448     return $x;
2449     }
2450   return $x if $x->{sign} !~ /^[+-]$/;          # inf, NaN
2451
2452   # we have fewer digits than we want to scale to
2453   my $len = $x->length();
2454   # convert $scale to a scalar in case it is an object (put's a limit on the
2455   # number length, but this would already limited by memory constraints), makes
2456   # it faster
2457   $scale = $scale->numify() if ref ($scale);
2458
2459   # scale < 0, but > -len (not >=!)
2460   if (($scale < 0 && $scale < -$len-1) || ($scale >= $len))
2461     {
2462     $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2463     return $x; 
2464     }
2465
2466   # count of 0's to pad, from left (+) or right (-): 9 - +6 => 3, or |-6| => 6
2467   my ($pad,$digit_round,$digit_after);
2468   $pad = $len - $scale;
2469   $pad = abs($scale-1) if $scale < 0;
2470
2471   # do not use digit(), it is very costly for binary => decimal
2472   # getting the entire string is also costly, but we need to do it only once
2473   my $xs = $CALC->_str($x->{value});
2474   my $pl = -$pad-1;
2475
2476   # pad:   123: 0 => -1, at 1 => -2, at 2 => -3, at 3 => -4
2477   # pad+1: 123: 0 => 0,  at 1 => -1, at 2 => -2, at 3 => -3
2478   $digit_round = '0'; $digit_round = substr($xs,$pl,1) if $pad <= $len;
2479   $pl++; $pl ++ if $pad >= $len;
2480   $digit_after = '0'; $digit_after = substr($xs,$pl,1) if $pad > 0;
2481
2482   # in case of 01234 we round down, for 6789 up, and only in case 5 we look
2483   # closer at the remaining digits of the original $x, remember decision
2484   my $round_up = 1;                                     # default round up
2485   $round_up -- if
2486     ($mode eq 'trunc')                          ||      # trunc by round down
2487     ($digit_after =~ /[01234]/)                 ||      # round down anyway,
2488                                                         # 6789 => round up
2489     ($digit_after eq '5')                       &&      # not 5000...0000
2490     ($x->_scan_for_nonzero($pad,$xs,$len) == 0)         &&
2491     (
2492      ($mode eq 'even') && ($digit_round =~ /[24680]/) ||
2493      ($mode eq 'odd')  && ($digit_round =~ /[13579]/) ||
2494      ($mode eq '+inf') && ($x->{sign} eq '-')   ||
2495      ($mode eq '-inf') && ($x->{sign} eq '+')   ||
2496      ($mode eq 'zero')          # round down if zero, sign adjusted below
2497     );
2498   my $put_back = 0;                                     # not yet modified
2499         
2500   if (($pad > 0) && ($pad <= $len))
2501     {
2502     substr($xs,-$pad,$pad) = '0' x $pad;                # replace with '00...'
2503     $put_back = 1;                                      # need to put back
2504     }
2505   elsif ($pad > $len)
2506     {
2507     $x->bzero();                                        # round to '0'
2508     }
2509
2510   if ($round_up)                                        # what gave test above?
2511     {
2512     $put_back = 1;                                      # need to put back
2513     $pad = $len, $xs = '0' x $pad if $scale < 0;        # tlr: whack 0.51=>1.0  
2514
2515     # we modify directly the string variant instead of creating a number and
2516     # adding it, since that is faster (we already have the string)
2517     my $c = 0; $pad ++;                         # for $pad == $len case
2518     while ($pad <= $len)
2519       {
2520       $c = substr($xs,-$pad,1) + 1; $c = '0' if $c eq '10';
2521       substr($xs,-$pad,1) = $c; $pad++;
2522       last if $c != 0;                          # no overflow => early out
2523       }
2524     $xs = '1'.$xs if $c == 0;
2525
2526     }
2527   $x->{value} = $CALC->_new($xs) if $put_back == 1;     # put back, if needed
2528
2529   $x->{_a} = $scale if $scale >= 0;
2530   if ($scale < 0)
2531     {
2532     $x->{_a} = $len+$scale;
2533     $x->{_a} = 0 if $scale < -$len;
2534     }
2535   $x;
2536   }
2537
2538 sub bfloor
2539   {
2540   # round towards minus infinity; no-op since it's already integer
2541   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2542
2543   $x->round(@r);
2544   }
2545
2546 sub bceil
2547   {
2548   # round towards plus infinity; no-op since it's already int
2549   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2550
2551   $x->round(@r);
2552   }
2553
2554 sub bint {
2555     # round towards zero; no-op since it's already integer
2556     my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2557
2558     $x->round(@r);
2559 }
2560
2561 sub as_number
2562   {
2563   # An object might be asked to return itself as bigint on certain overloaded
2564   # operations. This does exactly this, so that sub classes can simple inherit
2565   # it or override with their own integer conversion routine.
2566   $_[0]->copy();
2567   }
2568
2569 sub as_hex
2570   {
2571   # return as hex string, with prefixed 0x
2572   my $x = shift; $x = $class->new($x) if !ref($x);
2573
2574   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2575
2576   my $s = '';
2577   $s = $x->{sign} if $x->{sign} eq '-';
2578   $s . $CALC->_as_hex($x->{value});
2579   }
2580
2581 sub as_bin
2582   {
2583   # return as binary string, with prefixed 0b
2584   my $x = shift; $x = $class->new($x) if !ref($x);
2585
2586   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2587
2588   my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2589   return $s . $CALC->_as_bin($x->{value});
2590   }
2591
2592 sub as_oct
2593   {
2594   # return as octal string, with prefixed 0
2595   my $x = shift; $x = $class->new($x) if !ref($x);
2596
2597   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2598
2599   my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2600   return $s . $CALC->_as_oct($x->{value});
2601   }
2602
2603 ##############################################################################
2604 # private stuff (internal use only)
2605
2606 sub objectify {
2607     # Convert strings and "foreign objects" to the objects we want.
2608
2609     # The first argument, $count, is the number of following arguments that
2610     # objectify() looks at and converts to objects. The first is a classname.
2611     # If the given count is 0, all arguments will be used.
2612
2613     # After the count is read, objectify obtains the name of the class to which
2614     # the following arguments are converted. If the second argument is a
2615     # reference, use the reference type as the class name. Otherwise, if it is
2616     # a string that looks like a class name, use that. Otherwise, use $class.
2617
2618     # Caller:                        Gives us:
2619     #
2620     # $x->badd(1);                => ref x, scalar y
2621     # Class->badd(1,2);           => classname x (scalar), scalar x, scalar y
2622     # Class->badd(Class->(1),2);  => classname x (scalar), ref x, scalar y
2623     # Math::BigInt::badd(1,2);    => scalar x, scalar y
2624
2625     # A shortcut for the common case $x->unary_op():
2626
2627     return (ref($_[1]), $_[1]) if (@_ == 2) && ($_[0]||0 == 1) && ref($_[1]);
2628
2629     # Check the context.
2630
2631     unless (wantarray) {
2632         require Carp;
2633         Carp::croak ("${class}::objectify() needs list context");
2634     }
2635
2636     # Get the number of arguments to objectify.
2637
2638     my $count = shift;
2639     $count ||= @_;
2640
2641     # Initialize the output array.
2642
2643     my @a = @_;
2644
2645     # If the first argument is a reference, use that reference type as our
2646     # class name. Otherwise, if the first argument looks like a class name,
2647     # then use that as our class name. Otherwise, use the default class name.
2648
2649     {
2650         if (ref($a[0])) {               # reference?
2651             unshift @a, ref($a[0]);
2652             last;
2653         }
2654         if ($a[0] =~ /^[A-Z].*::/) {    # string with class name?
2655             last;
2656         }
2657         unshift @a, $class;             # default class name
2658     }
2659
2660     no strict 'refs';
2661
2662     # What we upgrade to, if anything.
2663
2664     my $up = ${"$a[0]::upgrade"};
2665
2666     # Disable downgrading, because Math::BigFloat -> foo('1.0','2.0') needs
2667     # floats.
2668
2669     my $down;
2670     if (defined ${"$a[0]::downgrade"}) {
2671         $down = ${"$a[0]::downgrade"};
2672         ${"$a[0]::downgrade"} = undef;
2673     }
2674
2675     for my $i (1 .. $count) {
2676         my $ref = ref $a[$i];
2677
2678         # If it is an object of the right class, all is fine.
2679
2680         if ($ref eq $a[0]) {
2681             next;
2682         }
2683
2684         # Don't do anything with undefs.
2685
2686         unless (defined($a[$i])) {
2687             next;
2688         }
2689
2690         # Perl scalars are fed to the appropriate constructor.
2691
2692         unless ($ref) {
2693             $a[$i] = $a[0] -> new($a[$i]);
2694             next;
2695         }
2696
2697         # Upgrading is OK, so skip further tests if the argument is upgraded.
2698
2699         if (defined $up && $ref eq $up) {
2700             next;
2701         }
2702
2703         # If we want a Math::BigInt, see if the object can become one.
2704         # Support the old misnomer as_number().
2705
2706         if ($a[0] eq 'Math::BigInt') {
2707             if ($a[$i] -> can('as_int')) {
2708                 $a[$i] = $a[$i] -> as_int();
2709                 next;
2710             }
2711             if ($a[$i] -> can('as_number')) {
2712                 $a[$i] = $a[$i] -> as_number();
2713                 next;
2714             }
2715         }
2716
2717         # If we want a Math::BigFloat, see if the object can become one.
2718
2719         if ($a[0] eq 'Math::BigFloat') {
2720             if ($a[$i] -> can('as_float')) {
2721                 $a[$i] = $a[$i] -> as_float();
2722                 next;
2723             }
2724         }
2725
2726         # Last resort.
2727
2728         $a[$i] = $a[0] -> new($a[$i]);
2729     }
2730
2731     # Reset the downgrading.
2732
2733     ${"$a[0]::downgrade"} = $down;
2734
2735     return @a;
2736 }
2737
2738 sub _register_callback
2739   {
2740   my ($class,$callback) = @_;
2741
2742   if (ref($callback) ne 'CODE')
2743     { 
2744     require Carp;
2745     Carp::croak ("$callback is not a coderef");
2746     }
2747   $CALLBACKS{$class} = $callback;
2748   }
2749
2750 sub import 
2751   {
2752   my $self = shift;
2753
2754   $IMPORT++;                            # remember we did import()
2755   my @a; my $l = scalar @_;
2756   my $warn_or_die = 0;                  # 0 - no warn, 1 - warn, 2 - die
2757   for ( my $i = 0; $i < $l ; $i++ )
2758     {
2759     if ($_[$i] eq ':constant')
2760       {
2761       # this causes overlord er load to step in
2762       overload::constant 
2763         integer => sub { $self->new(shift) },
2764         binary => sub { $self->new(shift) };
2765       }
2766     elsif ($_[$i] eq 'upgrade')
2767       {
2768       # this causes upgrading
2769       $upgrade = $_[$i+1];              # or undef to disable
2770       $i++;
2771       }
2772     elsif ($_[$i] =~ /^(lib|try|only)\z/)
2773       {
2774       # this causes a different low lib to take care...
2775       $CALC = $_[$i+1] || '';
2776       # lib => 1 (warn on fallback), try => 0 (no warn), only => 2 (die on fallback)
2777       $warn_or_die = 1 if $_[$i] eq 'lib';
2778       $warn_or_die = 2 if $_[$i] eq 'only';
2779       $i++;
2780       }
2781     else
2782       {
2783       push @a, $_[$i];
2784       }
2785     }
2786   # any non :constant stuff is handled by our parent, Exporter
2787   if (@a > 0)
2788     {
2789     require Exporter;
2790
2791     $self->SUPER::import(@a);                   # need it for subclasses
2792     $self->export_to_level(1,$self,@a);         # need it for MBF
2793     }
2794
2795   # try to load core math lib
2796   my @c = split /\s*,\s*/,$CALC;
2797   foreach (@c)
2798     {
2799     $_ =~ tr/a-zA-Z0-9://cd;                    # limit to sane characters
2800     }
2801   push @c, \'Calc'                              # if all fail, try these
2802     if $warn_or_die < 2;                        # but not for "only"
2803   $CALC = '';                                   # signal error
2804   foreach my $l (@c)
2805     {
2806     # fallback libraries are "marked" as \'string', extract string if nec.
2807     my $lib = $l; $lib = $$l if ref($l);
2808
2809     next if ($lib || '') eq '';
2810     $lib = 'Math::BigInt::'.$lib if $lib !~ /^Math::BigInt/i;
2811     $lib =~ s/\.pm$//;
2812     if ($] < 5.006)
2813       {
2814       # Perl < 5.6.0 dies with "out of memory!" when eval("") and ':constant' is
2815       # used in the same script, or eval("") inside import().
2816       my @parts = split /::/, $lib;             # Math::BigInt => Math BigInt
2817       my $file = pop @parts; $file .= '.pm';    # BigInt => BigInt.pm
2818       require File::Spec;
2819       $file = File::Spec->catfile (@parts, $file);
2820       eval { require "$file"; $lib->import( @c ); }
2821       }
2822     else
2823       {
2824       eval "use $lib qw/@c/;";
2825       }
2826     if ($@ eq '')
2827       {
2828       my $ok = 1;
2829       # loaded it ok, see if the api_version() is high enough
2830       if ($lib->can('api_version') && $lib->api_version() >= 1.0)
2831         {
2832         $ok = 0;
2833         # api_version matches, check if it really provides anything we need
2834         for my $method (qw/
2835                 one two ten
2836                 str num
2837                 add mul div sub dec inc
2838                 acmp len digit is_one is_zero is_even is_odd
2839                 is_two is_ten
2840                 zeros new copy check
2841                 from_hex from_oct from_bin as_hex as_bin as_oct
2842                 rsft lsft xor and or
2843                 mod sqrt root fac pow modinv modpow log_int gcd
2844          /)
2845           {
2846           if (!$lib->can("_$method"))
2847             {
2848             if (($WARN{$lib}||0) < 2)
2849               {
2850               require Carp;
2851               Carp::carp ("$lib is missing method '_$method'");
2852               $WARN{$lib} = 1;          # still warn about the lib
2853               }
2854             $ok++; last; 
2855             }
2856           }
2857         }
2858       if ($ok == 0)
2859         {
2860         $CALC = $lib;
2861         if ($warn_or_die > 0 && ref($l))
2862           {
2863           require Carp;
2864           my $msg =
2865         "Math::BigInt: couldn't load specified math lib(s), fallback to $lib";
2866           Carp::carp ($msg) if $warn_or_die == 1;
2867           Carp::croak ($msg) if $warn_or_die == 2;
2868           }
2869         last;                   # found a usable one, break
2870         }
2871       else
2872         {
2873         if (($WARN{$lib}||0) < 2)
2874           {
2875           my $ver = eval "\$$lib\::VERSION" || 'unknown';
2876           require Carp;
2877           Carp::carp ("Cannot load outdated $lib v$ver, please upgrade");
2878           $WARN{$lib} = 2;              # never warn again
2879           }
2880         }
2881       }
2882     }
2883   if ($CALC eq '')
2884     {
2885     require Carp;
2886     if ($warn_or_die == 2)
2887       {
2888       Carp::croak(
2889           "Couldn't load specified math lib(s) and fallback disallowed");
2890       }
2891     else
2892       {
2893       Carp::croak(
2894           "Couldn't load any math lib(s), not even fallback to Calc.pm");
2895       }
2896     }
2897
2898   # notify callbacks
2899   foreach my $class (keys %CALLBACKS)
2900     {
2901     &{$CALLBACKS{$class}}($CALC);
2902     }
2903
2904   # Fill $CAN with the results of $CALC->can(...) for emulating lower math lib
2905   # functions
2906
2907   %CAN = ();
2908   for my $method (qw/ signed_and signed_or signed_xor /)
2909     {
2910     $CAN{$method} = $CALC->can("_$method") ? 1 : 0;
2911     }
2912
2913   # import done
2914   }
2915
2916 sub from_hex {
2917     # Create a bigint from a hexadecimal string.
2918
2919     my ($self, $str) = @_;
2920
2921     if ($str =~ s/
2922                      ^
2923                      ( [+-]? )
2924                      (0?x)?
2925                      (
2926                          [0-9a-fA-F]*
2927                          ( _ [0-9a-fA-F]+ )*
2928                      )
2929                      $
2930                  //x)
2931     {
2932         # Get a "clean" version of the string, i.e., non-emtpy and with no
2933         # underscores or invalid characters.
2934
2935         my $sign = $1;
2936         my $chrs = $3;
2937         $chrs =~ tr/_//d;
2938         $chrs = '0' unless CORE::length $chrs;
2939
2940         # Initialize output.
2941
2942         my $x = Math::BigInt->bzero();
2943
2944         # The library method requires a prefix.
2945
2946         $x->{value} = $CALC->_from_hex('0x' . $chrs);
2947
2948         # Place the sign.
2949
2950         if ($sign eq '-' && ! $CALC->_is_zero($x->{value})) {
2951             $x->{sign} = '-';
2952         }
2953
2954         return $x;
2955     }
2956
2957     # CORE::hex() parses as much as it can, and ignores any trailing garbage.
2958     # For backwards compatibility, we return NaN.
2959
2960     return $self->bnan();
2961 }
2962
2963 sub from_oct {
2964     # Create a bigint from an octal string.
2965
2966     my ($self, $str) = @_;
2967
2968     if ($str =~ s/
2969                      ^
2970                      ( [+-]? )
2971                      (
2972                          [0-7]*
2973                          ( _ [0-7]+ )*
2974                      )
2975                      $
2976                  //x)
2977     {
2978         # Get a "clean" version of the string, i.e., non-emtpy and with no
2979         # underscores or invalid characters.
2980
2981         my $sign = $1;
2982         my $chrs = $2;
2983         $chrs =~ tr/_//d;
2984         $chrs = '0' unless CORE::length $chrs;
2985
2986         # Initialize output.
2987
2988         my $x = Math::BigInt->bzero();
2989
2990         # The library method requires a prefix.
2991
2992         $x->{value} = $CALC->_from_oct('0' . $chrs);
2993
2994         # Place the sign.
2995
2996         if ($sign eq '-' && ! $CALC->_is_zero($x->{value})) {
2997             $x->{sign} = '-';
2998         }
2999
3000         return $x;
3001     }
3002
3003     # CORE::oct() parses as much as it can, and ignores any trailing garbage.
3004     # For backwards compatibility, we return NaN.
3005
3006     return $self->bnan();
3007 }
3008
3009 sub from_bin {
3010     # Create a bigint from a binary string.
3011
3012     my ($self, $str) = @_;
3013
3014     if ($str =~ s/
3015                      ^
3016                      ( [+-]? )
3017                      (0?b)?
3018                      (
3019                          [01]*
3020                          ( _ [01]+ )*
3021                      )
3022                      $
3023                  //x)
3024     {
3025         # Get a "clean" version of the string, i.e., non-emtpy and with no
3026         # underscores or invalid characters.
3027
3028         my $sign = $1;
3029         my $chrs = $3;
3030         $chrs =~ tr/_//d;
3031         $chrs = '0' unless CORE::length $chrs;
3032
3033         # Initialize output.
3034
3035         my $x = Math::BigInt->bzero();
3036
3037         # The library method requires a prefix.
3038
3039         $x->{value} = $CALC->_from_bin('0b' . $chrs);
3040
3041         # Place the sign.
3042
3043         if ($sign eq '-' && ! $CALC->_is_zero($x->{value})) {
3044             $x->{sign} = '-';
3045         }
3046
3047         return $x;
3048     }
3049
3050     # For consistency with from_hex() and from_oct(), we return NaN when the
3051     # input is invalid.
3052
3053     return $self->bnan();
3054 }
3055
3056 sub _split
3057   {
3058   # input: num_str; output: undef for invalid or
3059   # (\$mantissa_sign,\$mantissa_value,\$mantissa_fraction,
3060   # \$exp_sign,\$exp_value)
3061   # Internal, take apart a string and return the pieces.
3062   # Strip leading/trailing whitespace, leading zeros, underscore and reject
3063   # invalid input.
3064   my $x = shift;
3065
3066   # strip white space at front, also extraneous leading zeros
3067   $x =~ s/^\s*([-]?)0*([0-9])/$1$2/g;   # will not strip '  .2'
3068   $x =~ s/^\s+//;                       # but this will
3069   $x =~ s/\s+$//g;                      # strip white space at end
3070
3071   # shortcut, if nothing to split, return early
3072   if ($x =~ /^[+-]?[0-9]+\z/)
3073     {
3074     $x =~ s/^([+-])0*([0-9])/$2/; my $sign = $1 || '+';
3075     return (\$sign, \$x, \'', \'', \0);
3076     }
3077
3078   # invalid starting char?
3079   return if $x !~ /^[+-]?(\.?[0-9]|0b[0-1]|0x[0-9a-fA-F])/;
3080
3081   return Math::BigInt->from_hex($x) if $x =~ /^[+-]?0x/;        # hex string
3082   return Math::BigInt->from_bin($x) if $x =~ /^[+-]?0b/;        # binary string
3083
3084   # strip underscores between digits
3085   $x =~ s/([0-9])_([0-9])/$1$2/g;
3086   $x =~ s/([0-9])_([0-9])/$1$2/g;               # do twice for 1_2_3
3087
3088   # some possible inputs: 
3089   # 2.1234 # 0.12        # 1          # 1E1 # 2.134E1 # 434E-10 # 1.02009E-2 
3090   # .2     # 1_2_3.4_5_6 # 1.4E1_2_3  # 1e3 # +.2     # 0e999   
3091
3092   my ($m,$e,$last) = split /[Ee]/,$x;
3093   return if defined $last;              # last defined => 1e2E3 or others
3094   $e = '0' if !defined $e || $e eq "";
3095
3096   # sign,value for exponent,mantint,mantfrac
3097   my ($es,$ev,$mis,$miv,$mfv);
3098   # valid exponent?
3099   if ($e =~ /^([+-]?)0*([0-9]+)$/)      # strip leading zeros
3100     {
3101     $es = $1; $ev = $2;
3102     # valid mantissa?
3103     return if $m eq '.' || $m eq '';
3104     my ($mi,$mf,$lastf) = split /\./,$m;
3105     return if defined $lastf;           # lastf defined => 1.2.3 or others
3106     $mi = '0' if !defined $mi;
3107     $mi .= '0' if $mi =~ /^[\-\+]?$/;
3108     $mf = '0' if !defined $mf || $mf eq '';
3109     if ($mi =~ /^([+-]?)0*([0-9]+)$/)           # strip leading zeros
3110       {
3111       $mis = $1||'+'; $miv = $2;
3112       return unless ($mf =~ /^([0-9]*?)0*$/);   # strip trailing zeros
3113       $mfv = $1;
3114       # handle the 0e999 case here
3115       $ev = 0 if $miv eq '0' && $mfv eq '';
3116       return (\$mis,\$miv,\$mfv,\$es,\$ev);
3117       }
3118     }
3119   return; # NaN, not a number
3120   }
3121
3122 ##############################################################################
3123 # internal calculation routines (others are in Math::BigInt::Calc etc)
3124
3125 sub __lcm 
3126   { 
3127   # (BINT or num_str, BINT or num_str) return BINT
3128   # does modify first argument
3129   # LCM
3130
3131   my ($x,$ty) = @_;
3132   return $x->bnan() if ($x->{sign} eq $nan) || ($ty->{sign} eq $nan);
3133   my $method = ref($x) . '::bgcd';
3134   no strict 'refs';
3135   $x * $ty / &$method($x,$ty);
3136   }
3137
3138 ###############################################################################
3139 # trigonometric functions
3140
3141 sub bpi
3142   {
3143   # Calculate PI to N digits. Unless upgrading is in effect, returns the
3144   # result truncated to an integer, that is, always returns '3'.
3145   my ($self,$n) = @_;
3146   if (@_ == 1)
3147     {
3148     # called like Math::BigInt::bpi(10);
3149     $n = $self; $self = $class;
3150     }
3151   $self = ref($self) if ref($self);
3152
3153   return $upgrade->new($n) if defined $upgrade;
3154
3155   # hard-wired to "3"
3156   $self->new(3);
3157   }
3158
3159 sub bcos
3160   {
3161   # Calculate cosinus(x) to N digits. Unless upgrading is in effect, returns the
3162   # result truncated to an integer.
3163   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
3164
3165   return $x if $x->modify('bcos');
3166
3167   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
3168
3169   return $upgrade->new($x)->bcos(@r) if defined $upgrade;
3170
3171   require Math::BigFloat;
3172   # calculate the result and truncate it to integer
3173   my $t = Math::BigFloat->new($x)->bcos(@r)->as_int();
3174
3175   $x->bone() if $t->is_one();
3176   $x->bzero() if $t->is_zero();
3177   $x->round(@r);
3178   }
3179
3180 sub bsin
3181   {
3182   # Calculate sinus(x) to N digits. Unless upgrading is in effect, returns the
3183   # result truncated to an integer.
3184   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
3185
3186   return $x if $x->modify('bsin');
3187
3188   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
3189
3190   return $upgrade->new($x)->bsin(@r) if defined $upgrade;
3191
3192   require Math::BigFloat;
3193   # calculate the result and truncate it to integer
3194   my $t = Math::BigFloat->new($x)->bsin(@r)->as_int();
3195
3196   $x->bone() if $t->is_one();
3197   $x->bzero() if $t->is_zero();
3198   $x->round(@r);
3199   }
3200
3201 sub batan2
3202   { 
3203   # calculate arcus tangens of ($y/$x)
3204
3205   # set up parameters
3206   my ($self,$y,$x,@r) = (ref($_[0]),@_);
3207   # objectify is costly, so avoid it
3208   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
3209     {
3210     ($self,$y,$x,@r) = objectify(2,@_);
3211     }
3212
3213   return $y if $y->modify('batan2');
3214
3215   return $y->bnan() if ($y->{sign} eq $nan) || ($x->{sign} eq $nan);
3216
3217   # Y    X
3218   # != 0 -inf result is +- pi
3219   if ($x->is_inf() || $y->is_inf())
3220     {
3221     # upgrade to BigFloat etc.
3222     return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3223     if ($y->is_inf())
3224       {
3225       if ($x->{sign} eq '-inf')
3226         {
3227         # calculate 3 pi/4 => 2.3.. => 2
3228         $y->bone( substr($y->{sign},0,1) );
3229         $y->bmul($self->new(2));
3230         }
3231       elsif ($x->{sign} eq '+inf')
3232         {
3233         # calculate pi/4 => 0.7 => 0
3234         $y->bzero();
3235         }
3236       else
3237         {
3238         # calculate pi/2 => 1.5 => 1
3239         $y->bone( substr($y->{sign},0,1) );
3240         }
3241       }
3242     else
3243       {
3244       if ($x->{sign} eq '+inf')
3245         {
3246         # calculate pi/4 => 0.7 => 0
3247         $y->bzero();
3248         }
3249       else
3250         {
3251         # PI => 3.1415.. => 3
3252         $y->bone( substr($y->{sign},0,1) );
3253         $y->bmul($self->new(3));
3254         }
3255       }
3256     return $y;
3257     }
3258
3259   return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3260
3261   require Math::BigFloat;
3262   my $r = Math::BigFloat->new($y)
3263                         ->batan2(Math::BigFloat->new($x),@r)
3264                         ->as_int();
3265
3266   $x->{value} = $r->{value};
3267   $x->{sign} = $r->{sign};
3268
3269   $x;
3270   }
3271
3272 sub batan
3273   {
3274   # Calculate arcus tangens of x to N digits. Unless upgrading is in effect, returns the
3275   # result truncated to an integer.
3276   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
3277
3278   return $x if $x->modify('batan');
3279
3280   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
3281
3282   return $upgrade->new($x)->batan(@r) if defined $upgrade;
3283
3284   # calculate the result and truncate it to integer
3285   my $t = Math::BigFloat->new($x)->batan(@r);
3286
3287   $x->{value} = $CALC->_new( $x->as_int()->bstr() );
3288   $x->round(@r);
3289   }
3290
3291 ###############################################################################
3292 # this method returns 0 if the object can be modified, or 1 if not.
3293 # We use a fast constant sub() here, to avoid costly calls. Subclasses
3294 # may override it with special code (f.i. Math::BigInt::Constant does so)
3295
3296 sub modify () { 0; }
3297
3298 1;
3299 __END__
3300
3301 =pod
3302
3303 =head1 NAME
3304
3305 Math::BigInt - Arbitrary size integer/float math package
3306
3307 =head1 SYNOPSIS
3308
3309   use Math::BigInt;
3310
3311   # or make it faster with huge numbers: install (optional)
3312   # Math::BigInt::GMP and always use (it will fall back to
3313   # pure Perl if the GMP library is not installed):
3314   # (See also the L<MATH LIBRARY> section!)
3315
3316   # will warn if Math::BigInt::GMP cannot be found
3317   use Math::BigInt lib => 'GMP';
3318
3319   # to suppress the warning use this:
3320   # use Math::BigInt try => 'GMP';
3321
3322   # dies if GMP cannot be loaded:
3323   # use Math::BigInt only => 'GMP';
3324
3325   my $str = '1234567890';
3326   my @values = (64,74,18);
3327   my $n = 1; my $sign = '-';
3328
3329   # Number creation     
3330   my $x = Math::BigInt->new($str);      # defaults to 0
3331   my $y = $x->copy();                   # make a true copy
3332   my $nan  = Math::BigInt->bnan();      # create a NotANumber
3333   my $zero = Math::BigInt->bzero();     # create a +0
3334   my $inf = Math::BigInt->binf();       # create a +inf
3335   my $inf = Math::BigInt->binf('-');    # create a -inf
3336   my $one = Math::BigInt->bone();       # create a +1
3337   my $mone = Math::BigInt->bone('-');   # create a -1
3338
3339   my $pi = Math::BigInt->bpi();         # returns '3'
3340                                         # see Math::BigFloat::bpi()
3341
3342   $h = Math::BigInt->new('0x123');      # from hexadecimal
3343   $b = Math::BigInt->new('0b101');      # from binary
3344   $o = Math::BigInt->from_oct('0101');  # from octal
3345
3346   # Testing (don't modify their arguments)
3347   # (return true if the condition is met, otherwise false)
3348
3349   $x->is_zero();        # if $x is +0
3350   $x->is_nan();         # if $x is NaN
3351   $x->is_one();         # if $x is +1
3352   $x->is_one('-');      # if $x is -1
3353   $x->is_odd();         # if $x is odd
3354   $x->is_even();        # if $x is even
3355   $x->is_pos();         # if $x > 0
3356   $x->is_neg();         # if $x < 0
3357   $x->is_inf($sign);    # if $x is +inf, or -inf (sign is default '+')
3358   $x->is_int();         # if $x is an integer (not a float)
3359
3360   # comparing and digit/sign extraction
3361   $x->bcmp($y);         # compare numbers (undef,<0,=0,>0)
3362   $x->bacmp($y);        # compare absolutely (undef,<0,=0,>0)
3363   $x->sign();           # return the sign, either +,- or NaN
3364   $x->digit($n);        # return the nth digit, counting from right
3365   $x->digit(-$n);       # return the nth digit, counting from left
3366
3367   # The following all modify their first argument. If you want to pre-
3368   # serve $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for
3369   # why this is necessary when mixing $a = $b assignments with non-over-
3370   # loaded math.
3371
3372   $x->bzero();          # set $x to 0
3373   $x->bnan();           # set $x to NaN
3374   $x->bone();           # set $x to +1
3375   $x->bone('-');        # set $x to -1
3376   $x->binf();           # set $x to inf
3377   $x->binf('-');        # set $x to -inf
3378
3379   $x->bneg();           # negation
3380   $x->babs();           # absolute value
3381   $x->bsgn();           # sign function (-1, 0, 1, or NaN)
3382   $x->bnorm();          # normalize (no-op in BigInt)
3383   $x->bnot();           # two's complement (bit wise not)
3384   $x->binc();           # increment $x by 1
3385   $x->bdec();           # decrement $x by 1
3386
3387   $x->badd($y);         # addition (add $y to $x)
3388   $x->bsub($y);         # subtraction (subtract $y from $x)
3389   $x->bmul($y);         # multiplication (multiply $x by $y)
3390   $x->bdiv($y);         # divide, set $x to quotient
3391                         # return (quo,rem) or quo if scalar
3392
3393   $x->bmuladd($y,$z);   # $x = $x * $y + $z
3394
3395   $x->bmod($y);         # modulus (x % y)
3396   $x->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod)
3397   $x->bmodinv($mod);    # modular multiplicative inverse
3398   $x->bpow($y);         # power of arguments (x ** y)
3399   $x->blsft($y);        # left shift in base 2
3400   $x->brsft($y);        # right shift in base 2
3401                         # returns (quo,rem) or quo if in sca-
3402                         # lar context
3403   $x->blsft($y,$n);     # left shift by $y places in base $n
3404   $x->brsft($y,$n);     # right shift by $y places in base $n
3405                         # returns (quo,rem) or quo if in sca-
3406                         # lar context
3407
3408   $x->band($y);         # bitwise and
3409   $x->bior($y);         # bitwise inclusive or
3410   $x->bxor($y);         # bitwise exclusive or
3411   $x->bnot();           # bitwise not (two's complement)
3412
3413   $x->bsqrt();          # calculate square-root
3414   $x->broot($y);        # $y'th root of $x (e.g. $y == 3 => cubic root)
3415   $x->bfac();           # factorial of $x (1*2*3*4*..$x)
3416
3417   $x->bnok($y);         # x over y (binomial coefficient n over k)
3418
3419   $x->blog();           # logarithm of $x to base e (Euler's number)
3420   $x->blog($base);      # logarithm of $x to base $base (f.i. 2)
3421   $x->bexp();           # calculate e ** $x where e is Euler's number
3422
3423   $x->round($A,$P,$mode);  # round to accuracy or precision using
3424                            # mode $mode
3425   $x->bround($n);          # accuracy: preserve $n digits
3426   $x->bfround($n);         # $n > 0: round $nth digits,
3427                            # $n < 0: round to the $nth digit after the
3428                            # dot, no-op for BigInts
3429
3430   # The following do not modify their arguments in BigInt (are no-ops),
3431   # but do so in BigFloat:
3432
3433   $x->bfloor();            # round towards minus infinity
3434   $x->bceil();             # round towards plus infinity
3435   $x->bint();              # round towards zero
3436
3437   # The following do not modify their arguments:
3438
3439   # greatest common divisor (no OO style)
3440   my $gcd = Math::BigInt::bgcd(@values);
3441   # lowest common multiple (no OO style)
3442   my $lcm = Math::BigInt::blcm(@values);
3443
3444   $x->length();            # return number of digits in number
3445   ($xl,$f) = $x->length(); # length of number and length of fraction
3446                            # part, latter is always 0 digits long
3447                            # for BigInts
3448
3449   $x->exponent();         # return exponent as BigInt
3450   $x->mantissa();         # return (signed) mantissa as BigInt
3451   $x->parts();            # return (mantissa,exponent) as BigInt
3452   $x->copy();             # make a true copy of $x (unlike $y = $x;)
3453   $x->as_int();           # return as BigInt (in BigInt: same as copy())
3454   $x->numify();           # return as scalar (might overflow!)
3455
3456   # conversion to string (do not modify their argument)
3457   $x->bstr();         # normalized string (e.g. '3')
3458   $x->bsstr();        # norm. string in scientific notation (e.g. '3E0')
3459   $x->as_hex();       # as signed hexadecimal string with prefixed 0x
3460   $x->as_bin();       # as signed binary string with prefixed 0b
3461   $x->as_oct();       # as signed octal string with prefixed 0
3462
3463
3464   # precision and accuracy (see section about rounding for more)
3465   $x->precision();       # return P of $x (or global, if P of $x undef)
3466   $x->precision($n);     # set P of $x to $n
3467   $x->accuracy();        # return A of $x (or global, if A of $x undef)
3468   $x->accuracy($n);      # set A $x to $n
3469
3470   # Global methods
3471   Math::BigInt->precision();   # get/set global P for all BigInt objects
3472   Math::BigInt->accuracy();    # get/set global A for all BigInt objects
3473   Math::BigInt->round_mode();  # get/set global round mode, one of
3474                                # 'even', 'odd', '+inf', '-inf', 'zero',
3475                                # 'trunc' or 'common'
3476   Math::BigInt->config();      # return hash containing configuration
3477
3478 =head1 DESCRIPTION
3479
3480 All operators (including basic math operations) are overloaded if you
3481 declare your big integers as
3482
3483   $i = new Math::BigInt '123_456_789_123_456_789';
3484
3485 Operations with overloaded operators preserve the arguments which is
3486 exactly what you expect.
3487
3488 =head2 Input
3489
3490 Input values to these routines may be any string, that looks like a number
3491 and results in an integer, including hexadecimal and binary numbers.
3492
3493 Scalars holding numbers may also be passed, but note that non-integer numbers
3494 may already have lost precision due to the conversion to float. Quote
3495 your input if you want BigInt to see all the digits:
3496
3497         $x = Math::BigInt->new(12345678890123456789);   # bad
3498         $x = Math::BigInt->new('12345678901234567890'); # good
3499
3500 You can include one underscore between any two digits.
3501
3502 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3503 Non-integer values result in NaN.
3504
3505 Hexadecimal (prefixed with "0x") and binary numbers (prefixed with "0b")
3506 are accepted, too. Please note that octal numbers are not recognized
3507 by new(), so the following will print "123":
3508
3509         perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'
3510
3511 To convert an octal number, use from_oct();
3512
3513         perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'
3514
3515 Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('')
3516 results in 'NaN'. This might change in the future, so use always the following
3517 explicit forms to get a zero or NaN:
3518
3519         $zero = Math::BigInt->bzero();
3520         $nan = Math::BigInt->bnan();
3521
3522 C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers 
3523 are always stored in normalized form. If passed a string, creates a BigInt 
3524 object from the input.
3525
3526 =head2 Output
3527
3528 Output values are BigInt objects (normalized), except for the methods which
3529 return a string (see L</SYNOPSIS>).
3530
3531 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3532 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
3533 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
3534
3535 =head1 METHODS
3536
3537 Each of the methods below (except config(), accuracy() and precision())
3538 accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
3539 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
3540 L</ACCURACY and PRECISION> for more information.
3541
3542 =over
3543
3544 =item config()
3545
3546     use Data::Dumper;
3547
3548     print Dumper ( Math::BigInt->config() );
3549     print Math::BigInt->config()->{lib},"\n";
3550
3551 Returns a hash containing the configuration, e.g. the version number, lib
3552 loaded etc. The following hash keys are currently filled in with the
3553 appropriate information.
3554
3555     key           Description
3556                   Example
3557     ============================================================
3558     lib           Name of the low-level math library
3559                   Math::BigInt::Calc
3560     lib_version   Version of low-level math library (see 'lib')
3561                   0.30
3562     class         The class name of config() you just called
3563                   Math::BigInt
3564     upgrade       To which class math operations might be
3565                   upgraded Math::BigFloat
3566     downgrade     To which class math operations might be
3567                   downgraded undef
3568     precision     Global precision
3569                   undef
3570     accuracy      Global accuracy
3571                   undef
3572     round_mode    Global round mode
3573                   even
3574     version       version number of the class you used
3575                   1.61
3576     div_scale     Fallback accuracy for div
3577                   40
3578     trap_nan      If true, traps creation of NaN via croak()
3579                   1
3580     trap_inf      If true, traps creation of +inf/-inf via croak()
3581                   1
3582
3583 The following values can be set by passing C<config()> a reference to a hash:
3584
3585         trap_inf trap_nan
3586         upgrade downgrade precision accuracy round_mode div_scale
3587
3588 Example:
3589
3590         $new_cfg = Math::BigInt->config(
3591             { trap_inf => 1, precision => 5 }
3592         );
3593
3594 =item accuracy()
3595
3596     $x->accuracy(5);         # local for $x
3597     CLASS->accuracy(5);      # global for all members of CLASS
3598                              # Note: This also applies to new()!
3599
3600     $A = $x->accuracy();     # read out accuracy that affects $x
3601     $A = CLASS->accuracy();  # read out global accuracy
3602
3603 Set or get the global or local accuracy, aka how many significant digits the
3604 results have. If you set a global accuracy, then this also applies to new()!
3605
3606 Warning! The accuracy I<sticks>, e.g. once you created a number under the
3607 influence of C<< CLASS->accuracy($A) >>, all results from math operations with
3608 that number will also be rounded.
3609
3610 In most cases, you should probably round the results explicitly using one of
3611 L</round()>, L</bround()> or L</bfround()> or by passing the desired accuracy
3612 to the math operation as additional parameter:
3613
3614     my $x = Math::BigInt->new(30000);
3615     my $y = Math::BigInt->new(7);
3616     print scalar $x->copy()->bdiv($y, 2);               # print 4300
3617     print scalar $x->copy()->bdiv($y)->bround(2);       # print 4300
3618
3619 Please see the section about L</ACCURACY and PRECISION> for further details.
3620
3621 Value must be greater than zero. Pass an undef value to disable it:
3622
3623     $x->accuracy(undef);
3624     Math::BigInt->accuracy(undef);
3625
3626 Returns the current accuracy. For C<< $x->accuracy() >> it will return either
3627 the local accuracy, or if not defined, the global. This means the return value
3628 represents the accuracy that will be in effect for $x:
3629
3630     $y = Math::BigInt->new(1234567);       # unrounded
3631     print Math::BigInt->accuracy(4),"\n";  # set 4, print 4
3632     $x = Math::BigInt->new(123456);        # $x will be automatic-
3633                                            # ally rounded!
3634     print "$x $y\n";                       # '123500 1234567'
3635     print $x->accuracy(),"\n";             # will be 4
3636     print $y->accuracy(),"\n";             # also 4, since
3637                                            # global is 4
3638     print Math::BigInt->accuracy(5),"\n";  # set to 5, print 5
3639     print $x->accuracy(),"\n";             # still 4
3640     print $y->accuracy(),"\n";             # 5, since global is 5
3641
3642 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3643 globals separated from Math::BigInt, but it is possible to subclass
3644 Math::BigInt and make the globals of the subclass aliases to the ones from
3645 Math::BigInt.
3646
3647 =item precision()
3648
3649     $x->precision(-2);          # local for $x, round at the second
3650                                 # digit right of the dot
3651     $x->precision(2);           # ditto, round at the second digit
3652                                 # left of the dot
3653
3654     CLASS->precision(5);        # Global for all members of CLASS
3655                                 # This also applies to new()!
3656     CLASS->precision(-5);       # ditto
3657
3658     $P = CLASS->precision();    # read out global precision
3659     $P = $x->precision();       # read out precision that affects $x
3660
3661 Note: You probably want to use L</accuracy()> instead. With L</accuracy()> you
3662 set the number of digits each result should have, with L</precision()> you
3663 set the place where to round!
3664
3665 C<precision()> sets or gets the global or local precision, aka at which digit
3666 before or after the dot to round all results. A set global precision also
3667 applies to all newly created numbers!
3668
3669 In Math::BigInt, passing a negative number precision has no effect since no
3670 numbers have digits after the dot. In L<Math::BigFloat>, it will round all
3671 results to P digits after the dot.
3672
3673 Please see the section about L</ACCURACY and PRECISION> for further details.
3674
3675 Pass an undef value to disable it:
3676
3677     $x->precision(undef);
3678     Math::BigInt->precision(undef);
3679
3680 Returns the current precision. For C<< $x->precision() >> it will return either
3681 the local precision of $x, or if not defined, the global. This means the return
3682 value represents the prevision that will be in effect for $x:
3683
3684     $y = Math::BigInt->new(1234567);        # unrounded
3685     print Math::BigInt->precision(4),"\n";  # set 4, print 4
3686     $x = Math::BigInt->new(123456);  # will be automatically rounded
3687     print $x;                               # print "120000"!
3688
3689 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
3690 own globals separated from Math::BigInt, but it is possible to subclass
3691 Math::BigInt and make the globals of the subclass aliases to the ones from
3692 Math::BigInt.
3693
3694 =item brsft()
3695
3696     $x->brsft($y,$n);
3697
3698 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3699 2, but others work, too.
3700
3701 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3702 result:
3703
3704
3705     $x = Math::BigInt->new(10);
3706     $x->brsft(1);                       # same as $x >> 1: 5
3707     $x = Math::BigInt->new(1234);
3708     $x->brsft(2,10);                    # result 12
3709
3710 There is one exception, and that is base 2 with negative $x:
3711
3712
3713     $x = Math::BigInt->new(-5);
3714     print $x->brsft(1);
3715
3716 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3717 result).
3718
3719 =item new()
3720
3721     $x = Math::BigInt->new($str,$A,$P,$R);
3722
3723 Creates a new BigInt object from a scalar or another BigInt object. The
3724 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3725 '0b').
3726
3727 See L</Input> for more info on accepted input formats.
3728
3729 =item from_oct()
3730
3731     $x = Math::BigInt->from_oct("0775");      # input is octal
3732
3733 Interpret the input as an octal string and return the corresponding value. A
3734 "0" (zero) prefix is optional. A single underscore character may be placed
3735 right after the prefix, if present, or between any two digits. If the input is
3736 invalid, a NaN is returned.
3737
3738 =item from_hex()
3739
3740     $x = Math::BigInt->from_hex("0xcafe");    # input is hexadecimal
3741
3742 Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A
3743 single underscore character may be placed right after the prefix, if present,
3744 or between any two digits. If the input is invalid, a NaN is returned.
3745
3746 =item from_bin()
3747
3748     $x = Math::BigInt->from_bin("0b10011");   # input is binary
3749
3750 Interpret the input as a binary string. A "0b" or "b" prefix is optional. A
3751 single underscore character may be placed right after the prefix, if present,
3752 or between any two digits. If the input is invalid, a NaN is returned.
3753
3754 =item bnan()
3755
3756     $x = Math::BigInt->bnan();
3757
3758 Creates a new BigInt object representing NaN (Not A Number).
3759 If used on an object, it will set it to NaN:
3760
3761     $x->bnan();
3762
3763 =item bzero()
3764
3765     $x = Math::BigInt->bzero();
3766
3767 Creates a new BigInt object representing zero.
3768 If used on an object, it will set it to zero:
3769
3770     $x->bzero();
3771
3772 =item binf()
3773
3774     $x = Math::BigInt->binf($sign);
3775
3776 Creates a new BigInt object representing infinity. The optional argument is
3777 either '-' or '+', indicating whether you want infinity or minus infinity.
3778 If used on an object, it will set it to infinity:
3779
3780     $x->binf();
3781     $x->binf('-');
3782
3783 =item bone()
3784
3785     $x = Math::BigInt->binf($sign);
3786
3787 Creates a new BigInt object representing one. The optional argument is
3788 either '-' or '+', indicating whether you want one or minus one.
3789 If used on an object, it will set it to one:
3790
3791     $x->bone();         # +1
3792     $x->bone('-');              # -1
3793
3794 =item is_one()/is_zero()/is_nan()/is_inf()
3795
3796     $x->is_zero();              # true if arg is +0
3797     $x->is_nan();               # true if arg is NaN
3798     $x->is_one();               # true if arg is +1
3799     $x->is_one('-');            # true if arg is -1
3800     $x->is_inf();               # true if +inf
3801     $x->is_inf('-');            # true if -inf (sign is default '+')
3802
3803 These methods all test the BigInt for being one specific value and return
3804 true or false depending on the input. These are faster than doing something
3805 like:
3806
3807     if ($x == 0)
3808
3809 =item is_pos()/is_neg()/is_positive()/is_negative()
3810
3811     $x->is_pos();                       # true if > 0
3812     $x->is_neg();                       # true if < 0
3813
3814 The methods return true if the argument is positive or negative, respectively.
3815 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3816 C<-inf> is negative. A C<zero> is neither positive nor negative.
3817
3818 These methods are only testing the sign, and not the value.
3819
3820 C<is_positive()> and C<is_negative()> are aliases to C<is_pos()> and
3821 C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
3822 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
3823 in v1.68.
3824
3825 =item is_odd()/is_even()/is_int()
3826
3827     $x->is_odd();               # true if odd, false for even
3828     $x->is_even();              # true if even, false for odd
3829     $x->is_int();               # true if $x is an integer
3830
3831 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3832 C<-inf> are not integers and are neither odd nor even.
3833
3834 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
3835
3836 =item bcmp()
3837
3838     $x->bcmp($y);
3839
3840 Compares $x with $y and takes the sign into account.
3841 Returns -1, 0, 1 or undef.
3842
3843 =item bacmp()
3844
3845     $x->bacmp($y);
3846
3847 Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or undef.
3848
3849 =item sign()
3850
3851     $x->sign();
3852
3853 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3854
3855 If you want $x to have a certain sign, use one of the following methods:
3856
3857     $x->babs();                 # '+'
3858     $x->babs()->bneg();         # '-'
3859     $x->bnan();                 # 'NaN'
3860     $x->binf();                 # '+inf'
3861     $x->binf('-');              # '-inf'
3862
3863 =item digit()
3864
3865     $x->digit($n);       # return the nth digit, counting from right
3866
3867 If C<$n> is negative, returns the digit counting from left.
3868
3869 =item bneg()
3870
3871     $x->bneg();
3872
3873 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3874 and '-inf', respectively. Does nothing for NaN or zero.
3875
3876 =item babs()
3877
3878     $x->babs();
3879
3880 Set the number to its absolute value, e.g. change the sign from '-' to '+'
3881 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3882 numbers.
3883
3884 =item bsgn()
3885
3886     $x->bsgn();
3887
3888 Signum function. Set the number to -1, 0, or 1, depending on whether the
3889 number is negative, zero, or positive, respectively. Does not modify NaNs.
3890
3891 =item bnorm()
3892
3893     $x->bnorm();                        # normalize (no-op)
3894
3895 =item bnot()
3896
3897     $x->bnot();
3898
3899 Two's complement (bitwise not). This is equivalent to
3900
3901     $x->binc()->bneg();
3902
3903 but faster.
3904
3905 =item binc()
3906
3907     $x->binc();                 # increment x by 1
3908
3909 =item bdec()
3910
3911     $x->bdec();                 # decrement x by 1
3912
3913 =item badd()
3914
3915     $x->badd($y);               # addition (add $y to $x)
3916
3917 =item bsub()
3918
3919     $x->bsub($y);               # subtraction (subtract $y from $x)
3920
3921 =item bmul()
3922
3923     $x->bmul($y);               # multiplication (multiply $x by $y)
3924
3925 =item bmuladd()
3926
3927     $x->bmuladd($y,$z);
3928
3929 Multiply $x by $y, and then add $z to the result,
3930
3931 This method was added in v1.87 of Math::BigInt (June 2007).
3932
3933 =item bdiv()
3934
3935     $x->bdiv($y);               # divide, set $x to quotient
3936                                 # return (quo,rem) or quo if scalar
3937
3938 =item bmod()
3939
3940     $x->bmod($y);               # modulus (x % y)
3941
3942 =item bmodinv()
3943
3944     $x->bmodinv($mod);          # modular multiplicative inverse
3945
3946 Returns the multiplicative inverse of C<$x> modulo C<$mod>. If
3947
3948     $y = $x -> copy() -> bmodinv($mod)
3949
3950 then C<$y> is the number closest to zero, and with the same sign as C<$mod>,
3951 satisfying
3952
3953     ($x * $y) % $mod = 1 % $mod
3954
3955 If C<$x> and C<$y> are non-zero, they must be relative primes, i.e.,
3956 C<bgcd($y, $mod)==1>. 'C<NaN>' is returned when no modular multiplicative
3957 inverse exists.
3958
3959 =item bmodpow()
3960
3961     $num->bmodpow($exp,$mod);           # modular exponentiation
3962                                         # ($num**$exp % $mod)
3963
3964 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3965 C<$mod> using binary exponentiation.  C<bmodpow> is far superior to
3966 writing
3967
3968     $num ** $exp % $mod
3969
3970 because it is much faster - it reduces internal variables into
3971 the modulus whenever possible, so it operates on smaller numbers.
3972
3973 C<bmodpow> also supports negative exponents.
3974
3975     bmodpow($num, -1, $mod)
3976
3977 is exactly equivalent to
3978
3979     bmodinv($num, $mod)
3980
3981 =item bpow()
3982
3983     $x->bpow($y);                     # power of arguments (x ** y)
3984
3985 =item blog()
3986
3987     $x->blog($base, $accuracy);   # logarithm of x to the base $base
3988
3989 If C<$base> is not defined, Euler's number (e) is used:
3990
3991     print $x->blog(undef, 100);       # log(x) to 100 digits
3992
3993 =item bexp()
3994
3995     $x->bexp($accuracy);              # calculate e ** X
3996
3997 Calculates the expression C<e ** $x> where C<e> is Euler's number.
3998
3999 This method was added in v1.82 of Math::BigInt (April 2007).
4000
4001 See also L</blog()>.
4002
4003 =item bnok()
4004
4005     $x->bnok($y);         # x over y (binomial coefficient n over k)
4006
4007 Calculates the binomial coefficient n over k, also called the "choose"
4008 function. The result is equivalent to:
4009
4010         ( n )      n!
4011         | - |  = -------
4012         ( k )    k!(n-k)!
4013
4014 This method was added in v1.84 of Math::BigInt (April 2007).
4015
4016 =item bpi()
4017
4018     print Math::BigInt->bpi(100), "\n";         # 3
4019
4020 Returns PI truncated to an integer, with the argument being ignored. This means
4021 under BigInt this always returns C<3>.
4022
4023 If upgrading is in effect, returns PI, rounded to N digits with the
4024 current rounding mode:
4025
4026     use Math::BigFloat;
4027     use Math::BigInt upgrade => Math::BigFloat;
4028     print Math::BigInt->bpi(3), "\n";           # 3.14
4029     print Math::BigInt->bpi(100), "\n";         # 3.1415....
4030
4031 This method was added in v1.87 of Math::BigInt (June 2007).
4032
4033 =item bcos()
4034
4035     my $x = Math::BigInt->new(1);
4036     print $x->bcos(100), "\n";
4037
4038 Calculate the cosinus of $x, modifying $x in place.
4039
4040 In BigInt, unless upgrading is in effect, the result is truncated to an
4041 integer.
4042
4043 This method was added in v1.87 of Math::BigInt (June 2007).
4044
4045 =item bsin()
4046
4047     my $x = Math::BigInt->new(1);
4048     print $x->bsin(100), "\n";
4049
4050 Calculate the sinus of $x, modifying $x in place.
4051
4052 In BigInt, unless upgrading is in effect, the result is truncated to an
4053 integer.
4054
4055 This method was added in v1.87 of Math::BigInt (June 2007).
4056
4057 =item batan2()
4058
4059     my $x = Math::BigInt->new(1);
4060     my $y = Math::BigInt->new(1);
4061     print $y->batan2($x), "\n";
4062
4063 Calculate the arcus tangens of C<$y> divided by C<$x>, modifying $y in place.
4064
4065 In BigInt, unless upgrading is in effect, the result is truncated to an
4066 integer.
4067
4068 This method was added in v1.87 of Math::BigInt (June 2007).
4069
4070 =item batan()
4071
4072     my $x = Math::BigFloat->new(0.5);
4073     print $x->batan(100), "\n";
4074
4075 Calculate the arcus tangens of $x, modifying $x in place.
4076
4077 In BigInt, unless upgrading is in effect, the result is truncated to an
4078 integer.
4079
4080 This method was added in v1.87 of Math::BigInt (June 2007).
4081
4082 =item blsft()
4083
4084     $x->blsft($y);              # left shift in base 2
4085     $x->blsft($y,$n);           # left shift, in base $n (like 10)
4086
4087 =item brsft()
4088
4089     $x->brsft($y);              # right shift in base 2
4090     $x->brsft($y,$n);           # right shift, in base $n (like 10)
4091
4092 =item band()
4093
4094     $x->band($y);               # bitwise and
4095
4096 =item bior()
4097
4098     $x->bior($y);               # bitwise inclusive or
4099
4100 =item bxor()
4101
4102     $x->bxor($y);               # bitwise exclusive or
4103
4104 =item bnot()
4105
4106     $x->bnot();                 # bitwise not (two's complement)
4107
4108 =item bsqrt()
4109
4110     $x->bsqrt();                # calculate square-root
4111
4112 =item broot()
4113
4114     $x->broot($N);
4115
4116 Calculates the N'th root of C<$x>.
4117
4118 =item bfac()
4119
4120     $x->bfac();                 # factorial of $x (1*2*3*4*..$x)
4121
4122 =item round()
4123
4124     $x->round($A,$P,$round_mode);
4125
4126 Round $x to accuracy C<$A> or precision C<$P> using the round mode
4127 C<$round_mode>.
4128
4129 =item bround()
4130
4131     $x->bround($N);               # accuracy: preserve $N digits
4132
4133 =item bfround()
4134
4135     $x->bfround($N);
4136
4137 If N is > 0, rounds to the Nth digit from the left. If N < 0, rounds to
4138 the Nth digit after the dot. Since BigInts are integers, the case N < 0
4139 is a no-op for them.
4140
4141 Examples:
4142
4143         Input           N               Result
4144         ===================================================
4145         123456.123456   3               123500
4146         123456.123456   2               123450
4147         123456.123456   -2              123456.12
4148         123456.123456   -3              123456.123
4149
4150 =item bfloor()
4151
4152     $x->bfloor();
4153
4154 Round $x towards minus infinity (i.e., set $x to the largest integer less than
4155 or equal to $x). This is a no-op in BigInt, but changes $x in BigFloat, if $x
4156 is not an integer.
4157
4158 =item bceil()
4159
4160     $x->bceil();
4161
4162 Round $x towards plus infinity (i.e., set $x to the smallest integer greater
4163 than or equal to $x). This is a no-op in BigInt, but changes $x in BigFloat, if
4164 $x is not an integer.
4165
4166 =item bint()
4167
4168     $x->bint();
4169
4170 Round $x towards zero. This is a no-op in BigInt, but changes $x in BigFloat,
4171 if $x is not an integer.
4172
4173 =item bgcd()
4174
4175     bgcd(@values);           # greatest common divisor (no OO style)
4176
4177 =item blcm()
4178
4179     blcm(@values);           # lowest common multiple (no OO style)
4180
4181 =item length()
4182
4183     $x->length();
4184     ($xl,$fl) = $x->length();
4185
4186 Returns the number of digits in the decimal representation of the number.
4187 In list context, returns the length of the integer and fraction part. For
4188 BigInt's, the length of the fraction part will always be 0.
4189
4190 =item exponent()
4191
4192     $x->exponent();
4193
4194 Return the exponent of $x as BigInt.
4195
4196 =item mantissa()
4197
4198     $x->mantissa();
4199
4200 Return the signed mantissa of $x as BigInt.
4201
4202 =item parts()
4203
4204     $x->parts();        # return (mantissa,exponent) as BigInt
4205
4206 =item copy()
4207
4208     $x->copy();         # make a true copy of $x (unlike $y = $x;)
4209
4210 =item as_int()/as_number()
4211
4212     $x->as_int();
4213
4214 Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as
4215 C<copy()>.
4216
4217 C<as_number()> is an alias to this method. C<as_number> was introduced in
4218 v1.22, while C<as_int()> was only introduced in v1.68.
4219
4220 =item bstr()
4221
4222     $x->bstr();
4223
4224 Returns a normalized string representation of C<$x>.
4225
4226 =item bsstr()
4227
4228     $x->bsstr();     # normalized string in scientific notation
4229
4230 =item as_hex()
4231
4232     $x->as_hex();    # as signed hexadecimal string with prefixed 0x
4233
4234 =item as_bin()
4235
4236     $x->as_bin();    # as signed binary string with prefixed 0b
4237
4238 =item as_oct()
4239
4240     $x->as_oct();    # as signed octal string with prefixed 0
4241
4242 =item numify()
4243
4244         print $x->numify();
4245
4246 This returns a normal Perl scalar from $x. It is used automatically
4247 whenever a scalar is needed, for instance in array index operations.
4248
4249 This loses precision, to avoid this use L<as_int()|/"as_int()/as_number()"> instead.
4250
4251 =item modify()
4252
4253     $x->modify('bpowd');
4254
4255 This method returns 0 if the object can be modified with the given
4256 operation, or 1 if not.
4257
4258 This is used for instance by L<Math::BigInt::Constant>.
4259
4260 =item upgrade()/downgrade()
4261
4262 Set/get the class for downgrade/upgrade operations. Thuis is used
4263 for instance by L<bignum>. The defaults are '', thus the following
4264 operation will create a BigInt, not a BigFloat:
4265
4266         my $i = Math::BigInt->new(123);
4267         my $f = Math::BigFloat->new('123.1');
4268
4269         print $i + $f,"\n";                     # print 246
4270
4271 =item div_scale()
4272
4273 Set/get the number of digits for the default precision in divide
4274 operations.
4275
4276 =item round_mode()
4277
4278 Set/get the current round mode.
4279
4280 =back
4281
4282 =head1 ACCURACY and PRECISION
4283
4284 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
4285 accuracy and precision based rounding, both automatically after every
4286 operation, as well as manually.
4287
4288 This section describes the accuracy/precision handling in Math::Big* as it
4289 used to be and as it is now, complete with an explanation of all terms and
4290 abbreviations.
4291
4292 Not yet implemented things (but with correct description) are marked with '!',
4293 things that need to be answered are marked with '?'.
4294
4295 In the next paragraph follows a short description of terms used here (because
4296 these may differ from terms used by others people or documentation).
4297
4298 During the rest of this document, the shortcuts A (for accuracy), P (for
4299 precision), F (fallback) and R (rounding mode) will be used.
4300
4301 =head2 Precision P
4302
4303 A fixed number of digits before (positive) or after (negative)
4304 the decimal point. For example, 123.45 has a precision of -2. 0 means an
4305 integer like 123 (or 120). A precision of 2 means two digits to the left
4306 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
4307 numbers with zeros before the decimal point may have different precisions,
4308 because 1200 can have p = 0, 1 or 2 (depending on what the initial value
4309 was). It could also have p < 0, when the digits after the decimal point
4310 are zero.
4311
4312 The string output (of floating point numbers) will be padded with zeros:
4313
4314         Initial value   P       A       Result          String
4315         ------------------------------------------------------------
4316         1234.01         -3              1000            1000
4317         1234            -2              1200            1200
4318         1234.5          -1              1230            1230
4319         1234.001        1               1234            1234.0
4320         1234.01         0               1234            1234
4321         1234.01         2               1234.01         1234.01
4322         1234.01         5               1234.01         1234.01000
4323
4324 For BigInts, no padding occurs.
4325
4326 =head2 Accuracy A
4327
4328 Number of significant digits. Leading zeros are not counted. A
4329 number may have an accuracy greater than the non-zero digits
4330 when there are zeros in it or trailing zeros. For example, 123.456 has
4331 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
4332
4333 The string output (of floating point numbers) will be padded with zeros:
4334
4335         Initial value   P       A       Result          String
4336         ------------------------------------------------------------
4337         1234.01                 3       1230            1230
4338         1234.01                 6       1234.01         1234.01
4339         1234.1                  8       1234.1          1234.1000
4340
4341 For BigInts, no padding occurs.
4342
4343 =head2 Fallback F
4344
4345 When both A and P are undefined, this is used as a fallback accuracy when
4346 dividing numbers.
4347
4348 =head2 Rounding mode R
4349
4350 When rounding a number, different 'styles' or 'kinds'
4351 of rounding are possible. (Note that random rounding, as in
4352 Math::Round, is not implemented.)
4353
4354 =over
4355
4356 =item 'trunc'
4357
4358 truncation invariably removes all digits following the
4359 rounding place, replacing them with zeros. Thus, 987.65 rounded
4360 to tens (P=1) becomes 980, and rounded to the fourth sigdig
4361 becomes 987.6 (A=4). 123.456 rounded to the second place after the
4362 decimal point (P=-2) becomes 123.46.
4363
4364 All other implemented styles of rounding attempt to round to the
4365 "nearest digit." If the digit D immediately to the right of the
4366 rounding place (skipping the decimal point) is greater than 5, the
4367 number is incremented at the rounding place (possibly causing a
4368 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
4369 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
4370 truncated at the rounding place: e.g. when rounding to units, 0.4
4371 rounds to 0, and -19.4 rounds to -19.
4372
4373 However the results of other styles of rounding differ if the
4374 digit immediately to the right of the rounding place (skipping the
4375 decimal point) is 5 and if there are no digits, or no digits other
4376 than 0, after that 5. In such cases:
4377
4378 =item 'even'
4379
4380 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
4381 if it is not already. E.g., when rounding to the first sigdig, 0.45
4382 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
4383
4384 =item 'odd'
4385
4386 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
4387 it is not already. E.g., when rounding to the first sigdig, 0.45
4388 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
4389
4390 =item '+inf'
4391
4392 round to plus infinity, i.e. always round up. E.g., when
4393 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
4394 and 0.4501 also becomes 0.5.
4395
4396 =item '-inf'
4397
4398 round to minus infinity, i.e. always round down. E.g., when
4399 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
4400 but 0.4501 becomes 0.5.
4401
4402 =item 'zero'
4403
4404 round to zero, i.e. positive numbers down, negative ones up.
4405 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
4406 becomes -0.5, but 0.4501 becomes 0.5.
4407
4408 =item 'common'
4409
4410 round up if the digit immediately to the right of the rounding place
4411 is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
4412 0.149 becomes 0.1.