This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Rewrap some verbatim pod in Math::BigInt
[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.996';
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 pre-
3348   # serve $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for
3349   # why this is necessary when mixing $a = $b assignments with non-over-
3350   # loaded math.
3351
3352   $x->bzero();          # set $x to 0
3353   $x->bnan();           # set $x to NaN
3354   $x->bone();           # set $x to +1
3355   $x->bone('-');        # set $x to -1
3356   $x->binf();           # set $x to inf
3357   $x->binf('-');        # set $x to -inf
3358
3359   $x->bneg();           # negation
3360   $x->babs();           # absolute value
3361   $x->bsgn();           # sign function (-1, 0, 1, or NaN)
3362   $x->bnorm();          # normalize (no-op in BigInt)
3363   $x->bnot();           # two's complement (bit wise not)
3364   $x->binc();           # increment $x by 1
3365   $x->bdec();           # decrement $x by 1
3366
3367   $x->badd($y);         # addition (add $y to $x)
3368   $x->bsub($y);         # subtraction (subtract $y from $x)
3369   $x->bmul($y);         # multiplication (multiply $x by $y)
3370   $x->bdiv($y);         # divide, set $x to quotient
3371                         # return (quo,rem) or quo if scalar
3372
3373   $x->bmuladd($y,$z);   # $x = $x * $y + $z
3374
3375   $x->bmod($y);            # modulus (x % y)
3376   $x->bmodpow($y,$mod);    # modular exponentiation (($x ** $y) % $mod)
3377   $x->bmodinv($mod);       # modular multiplicative inverse
3378   $x->bpow($y);            # power of arguments (x ** y)
3379   $x->blsft($y);           # left shift in base 2
3380   $x->brsft($y);           # right shift in base 2
3381                            # returns (quo,rem) or quo if in sca-
3382                            # lar context
3383   $x->blsft($y,$n);        # left shift by $y places in base $n
3384   $x->brsft($y,$n);        # right shift by $y places in base $n
3385                            # returns (quo,rem) or quo if in sca-
3386                            # lar context
3387
3388   $x->band($y);            # bitwise and
3389   $x->bior($y);            # bitwise inclusive or
3390   $x->bxor($y);            # bitwise exclusive or
3391   $x->bnot();              # bitwise not (two's complement)
3392
3393   $x->bsqrt();             # calculate square-root
3394   $x->broot($y);           # $y'th root of $x (e.g. $y == 3 => cubic root)
3395   $x->bfac();              # factorial of $x (1*2*3*4*..$x)
3396
3397   $x->bnok($y);            # x over y (binomial coefficient n over k)
3398
3399   $x->blog();              # logarithm of $x to base e (Euler's number)
3400   $x->blog($base);         # logarithm of $x to base $base (f.i. 2)
3401   $x->bexp();              # calculate e ** $x where e is Euler's number
3402
3403   $x->round($A,$P,$mode);  # round to accuracy or precision using
3404                            # mode $mode
3405   $x->bround($n);          # accuracy: preserve $n digits
3406   $x->bfround($n);         # $n > 0: round $nth digits,
3407                            # $n < 0: round to the $nth digit after the
3408                            # dot, no-op for BigInts
3409
3410   # The following do not modify their arguments in BigInt (are no-ops),
3411   # but do so in BigFloat:
3412
3413   $x->bfloor();            # return integer less or equal than $x
3414   $x->bceil();             # return integer greater or equal than $x
3415
3416   # The following do not modify their arguments:
3417
3418   # greatest common divisor (no OO style)
3419   my $gcd = Math::BigInt::bgcd(@values);
3420   # lowest common multiple (no OO style)
3421   my $lcm = Math::BigInt::blcm(@values);
3422
3423   $x->length();            # return number of digits in number
3424   ($xl,$f) = $x->length(); # length of number and length of fraction
3425                            # part, latter is always 0 digits long
3426                            # for BigInts
3427
3428   $x->exponent();         # return exponent as BigInt
3429   $x->mantissa();         # return (signed) mantissa as BigInt
3430   $x->parts();            # return (mantissa,exponent) as BigInt
3431   $x->copy();             # make a true copy of $x (unlike $y = $x;)
3432   $x->as_int();           # return as BigInt (in BigInt: same as copy())
3433   $x->numify();           # return as scalar (might overflow!)
3434
3435   # conversion to string (do not modify their argument)
3436   $x->bstr();         # normalized string (e.g. '3')
3437   $x->bsstr();        # norm. string in scientific notation (e.g. '3E0')
3438   $x->as_hex();       # as signed hexadecimal string with prefixed 0x
3439   $x->as_bin();       # as signed binary string with prefixed 0b
3440   $x->as_oct();       # as signed octal string with prefixed 0
3441
3442
3443   # precision and accuracy (see section about rounding for more)
3444   $x->precision();       # return P of $x (or global, if P of $x undef)
3445   $x->precision($n);     # set P of $x to $n
3446   $x->accuracy();        # return A of $x (or global, if A of $x undef)
3447   $x->accuracy($n);      # set A $x to $n
3448
3449   # Global methods
3450   Math::BigInt->precision();   # get/set global P for all BigInt objects
3451   Math::BigInt->accuracy();    # get/set global A for all BigInt objects
3452   Math::BigInt->round_mode();  # get/set global round mode, one of
3453                                # 'even', 'odd', '+inf', '-inf', 'zero',
3454                                # 'trunc' or 'common'
3455   Math::BigInt->config();      # return hash containing configuration
3456
3457 =head1 DESCRIPTION
3458
3459 All operators (including basic math operations) are overloaded if you
3460 declare your big integers as
3461
3462   $i = new Math::BigInt '123_456_789_123_456_789';
3463
3464 Operations with overloaded operators preserve the arguments which is
3465 exactly what you expect.
3466
3467 =over 2
3468
3469 =item Input
3470
3471 Input values to these routines may be any string, that looks like a number
3472 and results in an integer, including hexadecimal and binary numbers.
3473
3474 Scalars holding numbers may also be passed, but note that non-integer numbers
3475 may already have lost precision due to the conversion to float. Quote
3476 your input if you want BigInt to see all the digits:
3477
3478         $x = Math::BigInt->new(12345678890123456789);   # bad
3479         $x = Math::BigInt->new('12345678901234567890'); # good
3480
3481 You can include one underscore between any two digits.
3482
3483 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3484 Non-integer values result in NaN.
3485
3486 Hexadecimal (prefixed with "0x") and binary numbers (prefixed with "0b")
3487 are accepted, too. Please note that octal numbers are not recognized
3488 by new(), so the following will print "123":
3489
3490         perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'
3491
3492 To convert an octal number, use from_oct();
3493
3494         perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'
3495
3496 Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('')
3497 results in 'NaN'. This might change in the future, so use always the following
3498 explicit forms to get a zero or NaN:
3499
3500         $zero = Math::BigInt->bzero();
3501         $nan = Math::BigInt->bnan();
3502
3503 C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers 
3504 are always stored in normalized form. If passed a string, creates a BigInt 
3505 object from the input.
3506
3507 =item Output
3508
3509 Output values are BigInt objects (normalized), except for the methods which
3510 return a string (see L<SYNOPSIS>).
3511
3512 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3513 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
3514 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
3515
3516 =back
3517
3518 =head1 METHODS
3519
3520 Each of the methods below (except config(), accuracy() and precision())
3521 accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
3522 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
3523 L<ACCURACY and PRECISION> for more information.
3524
3525 =head2 config()
3526
3527         use Data::Dumper;
3528
3529         print Dumper ( Math::BigInt->config() );
3530         print Math::BigInt->config()->{lib},"\n";
3531
3532 Returns a hash containing the configuration, e.g. the version number, lib
3533 loaded etc. The following hash keys are currently filled in with the
3534 appropriate information.
3535
3536         key           Description
3537                       Example
3538         ============================================================
3539         lib           Name of the low-level math library
3540                       Math::BigInt::Calc
3541         lib_version   Version of low-level math library (see 'lib')
3542                       0.30
3543         class         The class name of config() you just called
3544                       Math::BigInt
3545         upgrade       To which class math operations might be upgraded
3546                       Math::BigFloat
3547         downgrade     To which class math operations might be downgraded
3548                       undef
3549         precision     Global precision
3550                       undef
3551         accuracy      Global accuracy
3552                       undef
3553         round_mode    Global round mode
3554                       even
3555         version       version number of the class you used
3556                       1.61
3557         div_scale     Fallback accuracy for div
3558                       40
3559         trap_nan      If true, traps creation of NaN via croak()
3560                       1
3561         trap_inf      If true, traps creation of +inf/-inf via croak()
3562                       1
3563
3564 The following values can be set by passing C<config()> a reference to a hash:
3565
3566         trap_inf trap_nan
3567         upgrade downgrade precision accuracy round_mode div_scale
3568
3569 Example:
3570
3571         $new_cfg = Math::BigInt->config(
3572             { trap_inf => 1, precision => 5 }
3573         );
3574
3575 =head2 accuracy()
3576
3577     $x->accuracy(5);         # local for $x
3578     CLASS->accuracy(5);      # global for all members of CLASS
3579                              # Note: This also applies to new()!
3580
3581     $A = $x->accuracy();     # read out accuracy that affects $x
3582     $A = CLASS->accuracy();  # read out global accuracy
3583
3584 Set or get the global or local accuracy, aka how many significant digits the
3585 results have. If you set a global accuracy, then this also applies to new()!
3586
3587 Warning! The accuracy I<sticks>, e.g. once you created a number under the
3588 influence of C<< CLASS->accuracy($A) >>, all results from math operations with
3589 that number will also be rounded.
3590
3591 In most cases, you should probably round the results explicitly using one of
3592 L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy
3593 to the math operation as additional parameter:
3594
3595     my $x = Math::BigInt->new(30000);
3596     my $y = Math::BigInt->new(7);
3597     print scalar $x->copy()->bdiv($y, 2);               # print 4300
3598     print scalar $x->copy()->bdiv($y)->bround(2);       # print 4300
3599
3600 Please see the section about L<ACCURACY and PRECISION> for further details.
3601
3602 Value must be greater than zero. Pass an undef value to disable it:
3603
3604     $x->accuracy(undef);
3605     Math::BigInt->accuracy(undef);
3606
3607 Returns the current accuracy. For C<< $x->accuracy() >> it will return either
3608 the local accuracy, or if not defined, the global. This means the return value
3609 represents the accuracy that will be in effect for $x:
3610
3611     $y = Math::BigInt->new(1234567);       # unrounded
3612     print Math::BigInt->accuracy(4),"\n";  # set 4, print 4
3613     $x = Math::BigInt->new(123456);        # $x will be automatic-
3614                                            # ally rounded!
3615     print "$x $y\n";                       # '123500 1234567'
3616     print $x->accuracy(),"\n";             # will be 4
3617     print $y->accuracy(),"\n";             # also 4, since global is 4
3618     print Math::BigInt->accuracy(5),"\n";  # set to 5, print 5
3619     print $x->accuracy(),"\n";             # still 4
3620     print $y->accuracy(),"\n";             # 5, since global is 5
3621
3622 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3623 globals separated from Math::BigInt, but it is possible to subclass
3624 Math::BigInt and make the globals of the subclass aliases to the ones from
3625 Math::BigInt.
3626
3627 =head2 precision()
3628
3629     $x->precision(-2);          # local for $x, round at the second
3630                                 # digit right of the dot
3631     $x->precision(2);           # ditto, round at the second digit left
3632                                 # of the dot
3633
3634     CLASS->precision(5);        # Global for all members of CLASS
3635                                 # This also applies to new()!
3636     CLASS->precision(-5);       # ditto
3637
3638     $P = CLASS->precision();    # read out global precision
3639     $P = $x->precision();       # read out precision that affects $x
3640
3641 Note: You probably want to use L<accuracy()> instead. With L<accuracy> you
3642 set the number of digits each result should have, with L<precision> you
3643 set the place where to round!
3644
3645 C<precision()> sets or gets the global or local precision, aka at which digit
3646 before or after the dot to round all results. A set global precision also
3647 applies to all newly created numbers!
3648
3649 In Math::BigInt, passing a negative number precision has no effect since no
3650 numbers have digits after the dot. In L<Math::BigFloat>, it will round all
3651 results to P digits after the dot.
3652
3653 Please see the section about L<ACCURACY and PRECISION> for further details.
3654
3655 Pass an undef value to disable it:
3656
3657     $x->precision(undef);
3658     Math::BigInt->precision(undef);
3659
3660 Returns the current precision. For C<< $x->precision() >> it will return either
3661 the local precision of $x, or if not defined, the global. This means the return
3662 value represents the prevision that will be in effect for $x:
3663
3664     $y = Math::BigInt->new(1234567);        # unrounded
3665     print Math::BigInt->precision(4),"\n";  # set 4, print 4
3666     $x = Math::BigInt->new(123456);      # will be automatically rounded
3667     print $x;                               # print "120000"!
3668
3669 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
3670 own globals separated from Math::BigInt, but it is possible to subclass
3671 Math::BigInt and make the globals of the subclass aliases to the ones from
3672 Math::BigInt.
3673
3674 =head2 brsft()
3675
3676         $x->brsft($y,$n);
3677
3678 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3679 2, but others work, too.
3680
3681 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3682 result:
3683
3684
3685         $x = Math::BigInt->new(10);
3686         $x->brsft(1);                   # same as $x >> 1: 5
3687         $x = Math::BigInt->new(1234);
3688         $x->brsft(2,10);                # result 12
3689
3690 There is one exception, and that is base 2 with negative $x:
3691
3692
3693         $x = Math::BigInt->new(-5);
3694         print $x->brsft(1);
3695
3696 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3697 result).
3698
3699 =head2 new()
3700
3701         $x = Math::BigInt->new($str,$A,$P,$R);
3702
3703 Creates a new BigInt object from a scalar or another BigInt object. The
3704 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3705 '0b').
3706
3707 See L<Input> for more info on accepted input formats.
3708
3709 =head2 from_oct()
3710
3711         $x = Math::BigInt->from_oct("0775");    # input is octal
3712
3713 Interpret the input as an octal string and return the corresponding value. A
3714 "0" (zero) prefix is optional. A single underscore character may be placed
3715 right after the prefix, if present, or between any two digits. If the input is
3716 invalid, a NaN is returned.
3717
3718 =head2 from_hex()
3719
3720         $x = Math::BigInt->from_hex("0xcafe");  # input is hexadecimal
3721
3722 Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A
3723 single underscore character may be placed right after the prefix, if present,
3724 or between any two digits. If the input is invalid, a NaN is returned.
3725
3726 =head2 from_bin()
3727
3728         $x = Math::BigInt->from_bin("0b10011"); # input is binary
3729
3730 Interpret the input as a binary string. A "0b" or "b" prefix is optional. A
3731 single underscore character may be placed right after the prefix, if present,
3732 or between any two digits. If the input is invalid, a NaN is returned.
3733
3734 =head2 bnan()
3735
3736         $x = Math::BigInt->bnan();
3737
3738 Creates a new BigInt object representing NaN (Not A Number).
3739 If used on an object, it will set it to NaN:
3740
3741         $x->bnan();
3742
3743 =head2 bzero()
3744
3745         $x = Math::BigInt->bzero();
3746
3747 Creates a new BigInt object representing zero.
3748 If used on an object, it will set it to zero:
3749
3750         $x->bzero();
3751
3752 =head2 binf()
3753
3754         $x = Math::BigInt->binf($sign);
3755
3756 Creates a new BigInt object representing infinity. The optional argument is
3757 either '-' or '+', indicating whether you want infinity or minus infinity.
3758 If used on an object, it will set it to infinity:
3759
3760         $x->binf();
3761         $x->binf('-');
3762
3763 =head2 bone()
3764
3765         $x = Math::BigInt->binf($sign);
3766
3767 Creates a new BigInt object representing one. The optional argument is
3768 either '-' or '+', indicating whether you want one or minus one.
3769 If used on an object, it will set it to one:
3770
3771         $x->bone();             # +1
3772         $x->bone('-');          # -1
3773
3774 =head2 is_one()/is_zero()/is_nan()/is_inf()
3775
3776         $x->is_zero();          # true if arg is +0
3777         $x->is_nan();           # true if arg is NaN
3778         $x->is_one();           # true if arg is +1
3779         $x->is_one('-');        # true if arg is -1
3780         $x->is_inf();           # true if +inf
3781         $x->is_inf('-');        # true if -inf (sign is default '+')
3782
3783 These methods all test the BigInt for being one specific value and return
3784 true or false depending on the input. These are faster than doing something
3785 like:
3786
3787         if ($x == 0)
3788
3789 =head2 is_pos()/is_neg()/is_positive()/is_negative()
3790
3791         $x->is_pos();                   # true if > 0
3792         $x->is_neg();                   # true if < 0
3793
3794 The methods return true if the argument is positive or negative, respectively.
3795 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3796 C<-inf> is negative. A C<zero> is neither positive nor negative.
3797
3798 These methods are only testing the sign, and not the value.
3799
3800 C<is_positive()> and C<is_negative()> are aliases to C<is_pos()> and
3801 C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
3802 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
3803 in v1.68.
3804
3805 =head2 is_odd()/is_even()/is_int()
3806
3807         $x->is_odd();                   # true if odd, false for even
3808         $x->is_even();                  # true if even, false for odd
3809         $x->is_int();                   # true if $x is an integer
3810
3811 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3812 C<-inf> are not integers and are neither odd nor even.
3813
3814 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
3815
3816 =head2 bcmp()
3817
3818         $x->bcmp($y);
3819
3820 Compares $x with $y and takes the sign into account.
3821 Returns -1, 0, 1 or undef.
3822
3823 =head2 bacmp()
3824
3825         $x->bacmp($y);
3826
3827 Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or undef.
3828
3829 =head2 sign()
3830
3831         $x->sign();
3832
3833 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3834
3835 If you want $x to have a certain sign, use one of the following methods:
3836
3837         $x->babs();             # '+'
3838         $x->babs()->bneg();     # '-'
3839         $x->bnan();             # 'NaN'
3840         $x->binf();             # '+inf'
3841         $x->binf('-');          # '-inf'
3842
3843 =head2 digit()
3844
3845         $x->digit($n);       # return the nth digit, counting from right
3846
3847 If C<$n> is negative, returns the digit counting from left.
3848
3849 =head2 bneg()
3850
3851         $x->bneg();
3852
3853 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3854 and '-inf', respectively. Does nothing for NaN or zero.
3855
3856 =head2 babs()
3857
3858         $x->babs();
3859
3860 Set the number to its absolute value, e.g. change the sign from '-' to '+'
3861 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3862 numbers.
3863
3864 =head2 bnorm()
3865
3866         $x->bnorm();                    # normalize (no-op)
3867
3868 =head2 bnot()
3869
3870         $x->bnot();
3871
3872 Two's complement (bitwise not). This is equivalent to
3873
3874         $x->binc()->bneg();
3875
3876 but faster.
3877
3878 =head2 binc()
3879
3880         $x->binc();             # increment x by 1
3881
3882 =head2 bdec()
3883
3884         $x->bdec();             # decrement x by 1
3885
3886 =head2 badd()
3887
3888         $x->badd($y);           # addition (add $y to $x)
3889
3890 =head2 bsub()
3891
3892         $x->bsub($y);           # subtraction (subtract $y from $x)
3893
3894 =head2 bmul()
3895
3896         $x->bmul($y);           # multiplication (multiply $x by $y)
3897
3898 =head2 bmuladd()
3899
3900         $x->bmuladd($y,$z);
3901
3902 Multiply $x by $y, and then add $z to the result,
3903
3904 This method was added in v1.87 of Math::BigInt (June 2007).
3905
3906 =head2 bdiv()
3907
3908         $x->bdiv($y);           # divide, set $x to quotient
3909                                 # return (quo,rem) or quo if scalar
3910
3911 =head2 bmod()
3912
3913         $x->bmod($y);           # modulus (x % y)
3914
3915 =head2 bmodinv()
3916
3917         $x->bmodinv($mod);      # modular multiplicative inverse
3918
3919 Returns the multiplicative inverse of C<$x> modulo C<$mod>. If
3920
3921         $y = $x -> copy() -> bmodinv($mod)
3922
3923 then C<$y> is the number closest to zero, and with the same sign as C<$mod>,
3924 satisfying
3925
3926         ($x * $y) % $mod = 1 % $mod
3927
3928 If C<$x> and C<$y> are non-zero, they must be relative primes, i.e.,
3929 C<bgcd($y, $mod)==1>. 'C<NaN>' is returned when no modular multiplicative
3930 inverse exists.
3931
3932 =head2 bmodpow()
3933
3934         $num->bmodpow($exp,$mod);       # modular exponentiation
3935                                         # ($num**$exp % $mod)
3936
3937 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3938 C<$mod> using binary exponentiation.  C<bmodpow> is far superior to
3939 writing
3940
3941         $num ** $exp % $mod
3942
3943 because it is much faster - it reduces internal variables into
3944 the modulus whenever possible, so it operates on smaller numbers.
3945
3946 C<bmodpow> also supports negative exponents.
3947
3948         bmodpow($num, -1, $mod)
3949
3950 is exactly equivalent to
3951
3952         bmodinv($num, $mod)
3953
3954 =head2 bpow()
3955
3956         $x->bpow($y);                 # power of arguments (x ** y)
3957
3958 =head2 blog()
3959
3960         $x->blog($base, $accuracy);   # logarithm of x to the base $base
3961
3962 If C<$base> is not defined, Euler's number (e) is used:
3963
3964         print $x->blog(undef, 100);   # log(x) to 100 digits
3965
3966 =head2 bexp()
3967
3968         $x->bexp($accuracy);          # calculate e ** X
3969
3970 Calculates the expression C<e ** $x> where C<e> is Euler's number.
3971
3972 This method was added in v1.82 of Math::BigInt (April 2007).
3973
3974 See also L<blog()>.
3975
3976 =head2 bnok()
3977
3978         $x->bnok($y);        # x over y (binomial coefficient n over k)
3979
3980 Calculates the binomial coefficient n over k, also called the "choose"
3981 function. The result is equivalent to:
3982
3983         ( n )      n!
3984         | - |  = -------
3985         ( k )    k!(n-k)!
3986
3987 This method was added in v1.84 of Math::BigInt (April 2007).
3988
3989 =head2 bpi()
3990
3991         print Math::BigInt->bpi(100), "\n";             # 3
3992
3993 Returns PI truncated to an integer, with the argument being ignored. This means
3994 under BigInt this always returns C<3>.
3995
3996 If upgrading is in effect, returns PI, rounded to N digits with the
3997 current rounding mode:
3998
3999         use Math::BigFloat;
4000         use Math::BigInt upgrade => Math::BigFloat;
4001         print Math::BigInt->bpi(3), "\n";               # 3.14
4002         print Math::BigInt->bpi(100), "\n";             # 3.1415....
4003
4004 This method was added in v1.87 of Math::BigInt (June 2007).
4005
4006 =head2 bcos()
4007
4008         my $x = Math::BigInt->new(1);
4009         print $x->bcos(100), "\n";
4010
4011 Calculate the cosinus of $x, modifying $x in place.
4012
4013 In BigInt, unless upgrading is in effect, the result is truncated to an
4014 integer.
4015
4016 This method was added in v1.87 of Math::BigInt (June 2007).
4017
4018 =head2 bsin()
4019
4020         my $x = Math::BigInt->new(1);
4021         print $x->bsin(100), "\n";
4022
4023 Calculate the sinus of $x, modifying $x in place.
4024
4025 In BigInt, unless upgrading is in effect, the result is truncated to an
4026 integer.
4027
4028 This method was added in v1.87 of Math::BigInt (June 2007).
4029
4030 =head2 batan2()
4031
4032         my $x = Math::BigInt->new(1);
4033         my $y = Math::BigInt->new(1);
4034         print $y->batan2($x), "\n";
4035
4036 Calculate the arcus tangens of C<$y> divided by C<$x>, modifying $y in place.
4037
4038 In BigInt, unless upgrading is in effect, the result is truncated to an
4039 integer.
4040
4041 This method was added in v1.87 of Math::BigInt (June 2007).
4042
4043 =head2 batan()
4044
4045         my $x = Math::BigFloat->new(0.5);
4046         print $x->batan(100), "\n";
4047
4048 Calculate the arcus tangens of $x, modifying $x in place.
4049
4050 In BigInt, unless upgrading is in effect, the result is truncated to an
4051 integer.
4052
4053 This method was added in v1.87 of Math::BigInt (June 2007).
4054
4055 =head2 blsft()
4056
4057         $x->blsft($y);          # left shift in base 2
4058         $x->blsft($y,$n);       # left shift, in base $n (like 10)
4059
4060 =head2 brsft()
4061
4062         $x->brsft($y);          # right shift in base 2
4063         $x->brsft($y,$n);       # right shift, in base $n (like 10)
4064
4065 =head2 band()
4066
4067         $x->band($y);                   # bitwise and
4068
4069 =head2 bior()
4070
4071         $x->bior($y);                   # bitwise inclusive or
4072
4073 =head2 bxor()
4074
4075         $x->bxor($y);                   # bitwise exclusive or
4076
4077 =head2 bnot()
4078
4079         $x->bnot();                     # bitwise not (two's complement)
4080
4081 =head2 bsqrt()
4082
4083         $x->bsqrt();                    # calculate square-root
4084
4085 =head2 broot()
4086
4087         $x->broot($N);
4088
4089 Calculates the N'th root of C<$x>.
4090
4091 =head2 bfac()
4092
4093         $x->bfac();                     # factorial of $x (1*2*3*4*..$x)
4094
4095 =head2 round()
4096
4097         $x->round($A,$P,$round_mode);
4098
4099 Round $x to accuracy C<$A> or precision C<$P> using the round mode
4100 C<$round_mode>.
4101
4102 =head2 bround()
4103
4104         $x->bround($N);               # accuracy: preserve $N digits
4105
4106 =head2 bfround()
4107
4108         $x->bfround($N);
4109
4110 If N is > 0, rounds to the Nth digit from the left. If N < 0, rounds to
4111 the Nth digit after the dot. Since BigInts are integers, the case N < 0
4112 is a no-op for them.
4113
4114 Examples:
4115
4116         Input           N               Result
4117         ===================================================
4118         123456.123456   3               123500
4119         123456.123456   2               123450
4120         123456.123456   -2              123456.12
4121         123456.123456   -3              123456.123
4122
4123 =head2 bfloor()
4124
4125         $x->bfloor();
4126
4127 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
4128 does change $x in BigFloat.
4129
4130 =head2 bceil()
4131
4132         $x->bceil();
4133
4134 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
4135 does change $x in BigFloat.
4136
4137 =head2 bgcd()
4138
4139         bgcd(@values);          # greatest common divisor (no OO style)
4140
4141 =head2 blcm()
4142
4143         blcm(@values);          # lowest common multiple (no OO style)
4144
4145 head2 length()
4146
4147         $x->length();
4148         ($xl,$fl) = $x->length();
4149
4150 Returns the number of digits in the decimal representation of the number.
4151 In list context, returns the length of the integer and fraction part. For
4152 BigInt's, the length of the fraction part will always be 0.
4153
4154 =head2 exponent()
4155
4156         $x->exponent();
4157
4158 Return the exponent of $x as BigInt.
4159
4160 =head2 mantissa()
4161
4162         $x->mantissa();
4163
4164 Return the signed mantissa of $x as BigInt.
4165
4166 =head2 parts()
4167
4168         $x->parts();    # return (mantissa,exponent) as BigInt
4169
4170 =head2 copy()
4171
4172         $x->copy();     # make a true copy of $x (unlike $y = $x;)
4173
4174 =head2 as_int()/as_number()
4175
4176         $x->as_int();
4177
4178 Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as
4179 C<copy()>.
4180
4181 C<as_number()> is an alias to this method. C<as_number> was introduced in
4182 v1.22, while C<as_int()> was only introduced in v1.68.
4183
4184 =head2 bstr()
4185
4186         $x->bstr();
4187
4188 Returns a normalized string representation of C<$x>.
4189
4190 =head2 bsstr()
4191
4192         $x->bsstr();    # normalized string in scientific notation
4193
4194 =head2 as_hex()
4195
4196         $x->as_hex();   # as signed hexadecimal string with prefixed 0x
4197
4198 =head2 as_bin()
4199
4200         $x->as_bin();   # as signed binary string with prefixed 0b
4201
4202 =head2 as_oct()
4203
4204         $x->as_oct();   # as signed octal string with prefixed 0
4205
4206 =head2 numify()
4207
4208         print $x->numify();
4209
4210 This returns a normal Perl scalar from $x. It is used automatically
4211 whenever a scalar is needed, for instance in array index operations.
4212
4213 This loses precision, to avoid this use L<as_int()> instead.
4214
4215 =head2 modify()
4216
4217         $x->modify('bpowd');
4218
4219 This method returns 0 if the object can be modified with the given
4220 operation, or 1 if not.
4221
4222 This is used for instance by L<Math::BigInt::Constant>.
4223
4224 =head2 upgrade()/downgrade()
4225
4226 Set/get the class for downgrade/upgrade operations. Thuis is used
4227 for instance by L<bignum>. The defaults are '', thus the following
4228 operation will create a BigInt, not a BigFloat:
4229
4230         my $i = Math::BigInt->new(123);
4231         my $f = Math::BigFloat->new('123.1');
4232
4233         print $i + $f,"\n";                     # print 246
4234
4235 =head2 div_scale()
4236
4237 Set/get the number of digits for the default precision in divide
4238 operations.
4239
4240 =head2 round_mode()
4241
4242 Set/get the current round mode.
4243
4244 =head1 ACCURACY and PRECISION
4245
4246 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
4247 accuracy and precision based rounding, both automatically after every
4248 operation, as well as manually.
4249
4250 This section describes the accuracy/precision handling in Math::Big* as it
4251 used to be and as it is now, complete with an explanation of all terms and
4252 abbreviations.
4253
4254 Not yet implemented things (but with correct description) are marked with '!',
4255 things that need to be answered are marked with '?'.
4256
4257 In the next paragraph follows a short description of terms used here (because
4258 these may differ from terms used by others people or documentation).
4259
4260 During the rest of this document, the shortcuts A (for accuracy), P (for
4261 precision), F (fallback) and R (rounding mode) will be used.
4262
4263 =head2 Precision P
4264
4265 A fixed number of digits before (positive) or after (negative)
4266 the decimal point. For example, 123.45 has a precision of -2. 0 means an
4267 integer like 123 (or 120). A precision of 2 means two digits to the left
4268 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
4269 numbers with zeros before the decimal point may have different precisions,
4270 because 1200 can have p = 0, 1 or 2 (depending on what the initial value
4271 was). It could also have p < 0, when the digits after the decimal point
4272 are zero.
4273
4274 The string output (of floating point numbers) will be padded with zeros:
4275
4276         Initial value   P       A       Result          String
4277         ------------------------------------------------------------
4278         1234.01         -3              1000            1000
4279         1234            -2              1200            1200
4280         1234.5          -1              1230            1230
4281         1234.001        1               1234            1234.0
4282         1234.01         0               1234            1234
4283         1234.01         2               1234.01         1234.01
4284         1234.01         5               1234.01         1234.01000
4285
4286 For BigInts, no padding occurs.
4287
4288 =head2 Accuracy A
4289
4290 Number of significant digits. Leading zeros are not counted. A
4291 number may have an accuracy greater than the non-zero digits
4292 when there are zeros in it or trailing zeros. For example, 123.456 has
4293 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
4294
4295 The string output (of floating point numbers) will be padded with zeros:
4296
4297         Initial value   P       A       Result          String
4298         ------------------------------------------------------------
4299         1234.01                 3       1230            1230
4300         1234.01                 6       1234.01         1234.01
4301         1234.1                  8       1234.1          1234.1000
4302
4303 For BigInts, no padding occurs.
4304
4305 =head2 Fallback F
4306
4307 When both A and P are undefined, this is used as a fallback accuracy when
4308 dividing numbers.
4309
4310 =head2 Rounding mode R
4311
4312 When rounding a number, different 'styles' or 'kinds'
4313 of rounding are possible. (Note that random rounding, as in
4314 Math::Round, is not implemented.)
4315
4316 =over 2
4317
4318 =item 'trunc'
4319
4320 truncation invariably removes all digits following the
4321 rounding place, replacing them with zeros. Thus, 987.65 rounded
4322 to tens (P=1) becomes 980, and rounded to the fourth sigdig
4323 becomes 987.6 (A=4). 123.456 rounded to the second place after the
4324 decimal point (P=-2) becomes 123.46.
4325
4326 All other implemented styles of rounding attempt to round to the
4327 "nearest digit." If the digit D immediately to the right of the
4328 rounding place (skipping the decimal point) is greater than 5, the
4329 number is incremented at the rounding place (possibly causing a
4330 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
4331 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
4332 truncated at the rounding place: e.g. when rounding to units, 0.4
4333 rounds to 0, and -19.4 rounds to -19.
4334
4335 However the results of other styles of rounding differ if the
4336 digit immediately to the right of the rounding place (skipping the
4337 decimal point) is 5 and if there are no digits, or no digits other
4338 than 0, after that 5. In such cases:
4339
4340 =item 'even'
4341
4342 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
4343 if it is not already. E.g., when rounding to the first sigdig, 0.45
4344 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
4345
4346 =item 'odd'
4347
4348 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
4349 it is not already. E.g., when rounding to the first sigdig, 0.45
4350 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
4351
4352 =item '+inf'
4353
4354 round to plus infinity, i.e. always round up. E.g., when
4355 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
4356 and 0.4501 also becomes 0.5.
4357
4358 =item '-inf'
4359
4360 round to minus infinity, i.e. always round down. E.g., when
4361 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
4362 but 0.4501 becomes 0.5.
4363
4364 =item 'zero'
4365
4366 round to zero, i.e. positive numbers down, negative ones up.
4367 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
4368 becomes -0.5, but 0.4501 becomes 0.5.
4369
4370 =item 'common'
4371
4372 round up if the digit immediately to the right of the rounding place
4373 is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
4374 0.149 becomes 0.1.
4375
4376 =back
4377
4378 The handling of A & P in MBI/MBF (the old core code shipped with Perl
4379 versions <= 5.7.2) is like this:
4380
4381 =over 2
4382
4383 =item Precision
4384
4385   * ffround($p) is able to round to $p number of digits after the decimal
4386     point
4387   * otherwise P is unused
4388
4389 =item Accuracy (significant digits)
4390
4391   * fround($a) rounds to $a significant digits
4392   * only fdiv() and fsqrt() take A as (optional) parameter
4393     + other operations simply create the same number (fneg etc), or more (fmul)
4394       of digits
4395     + rounding/truncating is only done when explicitly calling one of fround
4396       or ffround, and never for BigInt (not implemented)
4397   * fsqrt() simply hands its accuracy argument over to fdiv.