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