This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
b34a43849399b42fc198fc70062339713f10b417
[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.98';
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::FastCalc';    # module to do the low level math
176                                         # default is FastCalc.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 embeded 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 callled 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 bneg 
1017   { 
1018   # (BINT or num_str) return BINT
1019   # negate number or make a negated number from string
1020   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1021   
1022   return $x if $x->modify('bneg');
1023
1024   # for +0 dont negate (to have always normalized +0). Does nothing for 'NaN'
1025   $x->{sign} =~ tr/+-/-+/ unless ($x->{sign} eq '+' && $CALC->_is_zero($x->{value}));
1026   $x;
1027   }
1028
1029 sub bcmp 
1030   {
1031   # Compares 2 values.  Returns one of undef, <0, =0, >0. (suitable for sort)
1032   # (BINT or num_str, BINT or num_str) return cond_code
1033   
1034   # set up parameters
1035   my ($self,$x,$y) = (ref($_[0]),@_);
1036
1037   # objectify is costly, so avoid it 
1038   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1039     {
1040     ($self,$x,$y) = objectify(2,@_);
1041     }
1042
1043   return $upgrade->bcmp($x,$y) if defined $upgrade &&
1044     ((!$x->isa($self)) || (!$y->isa($self)));
1045
1046   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1047     {
1048     # handle +-inf and NaN
1049     return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1050     return 0 if $x->{sign} eq $y->{sign} && $x->{sign} =~ /^[+-]inf$/;
1051     return +1 if $x->{sign} eq '+inf';
1052     return -1 if $x->{sign} eq '-inf';
1053     return -1 if $y->{sign} eq '+inf';
1054     return +1;
1055     }
1056   # check sign for speed first
1057   return 1 if $x->{sign} eq '+' && $y->{sign} eq '-';   # does also 0 <=> -y
1058   return -1 if $x->{sign} eq '-' && $y->{sign} eq '+';  # does also -x <=> 0 
1059
1060   # have same sign, so compare absolute values. Don't make tests for zero here
1061   # because it's actually slower than testin in Calc (especially w/ Pari et al)
1062
1063   # post-normalized compare for internal use (honors signs)
1064   if ($x->{sign} eq '+') 
1065     {
1066     # $x and $y both > 0
1067     return $CALC->_acmp($x->{value},$y->{value});
1068     }
1069
1070   # $x && $y both < 0
1071   $CALC->_acmp($y->{value},$x->{value});        # swaped acmp (lib returns 0,1,-1)
1072   }
1073
1074 sub bacmp 
1075   {
1076   # Compares 2 values, ignoring their signs. 
1077   # Returns one of undef, <0, =0, >0. (suitable for sort)
1078   # (BINT, BINT) return cond_code
1079   
1080   # set up parameters
1081   my ($self,$x,$y) = (ref($_[0]),@_);
1082   # objectify is costly, so avoid it 
1083   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1084     {
1085     ($self,$x,$y) = objectify(2,@_);
1086     }
1087
1088   return $upgrade->bacmp($x,$y) if defined $upgrade &&
1089     ((!$x->isa($self)) || (!$y->isa($self)));
1090
1091   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1092     {
1093     # handle +-inf and NaN
1094     return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1095     return 0 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} =~ /^[+-]inf$/;
1096     return 1 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} !~ /^[+-]inf$/;
1097     return -1;
1098     }
1099   $CALC->_acmp($x->{value},$y->{value});        # lib does only 0,1,-1
1100   }
1101
1102 sub badd 
1103   {
1104   # add second arg (BINT or string) to first (BINT) (modifies first)
1105   # return result as BINT
1106
1107   # set up parameters
1108   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1109   # objectify is costly, so avoid it 
1110   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1111     {
1112     ($self,$x,$y,@r) = objectify(2,@_);
1113     }
1114
1115   return $x if $x->modify('badd');
1116   return $upgrade->badd($upgrade->new($x),$upgrade->new($y),@r) if defined $upgrade &&
1117     ((!$x->isa($self)) || (!$y->isa($self)));
1118
1119   $r[3] = $y;                           # no push!
1120   # inf and NaN handling
1121   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1122     {
1123     # NaN first
1124     return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1125     # inf handling
1126     if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1127       {
1128       # +inf++inf or -inf+-inf => same, rest is NaN
1129       return $x if $x->{sign} eq $y->{sign};
1130       return $x->bnan();
1131       }
1132     # +-inf + something => +inf
1133     # something +-inf => +-inf
1134     $x->{sign} = $y->{sign}, return $x if $y->{sign} =~ /^[+-]inf$/;
1135     return $x;
1136     }
1137     
1138   my ($sx, $sy) = ( $x->{sign}, $y->{sign} );           # get signs
1139
1140   if ($sx eq $sy)  
1141     {
1142     $x->{value} = $CALC->_add($x->{value},$y->{value}); # same sign, abs add
1143     }
1144   else 
1145     {
1146     my $a = $CALC->_acmp ($y->{value},$x->{value});     # absolute compare
1147     if ($a > 0)                           
1148       {
1149       $x->{value} = $CALC->_sub($y->{value},$x->{value},1); # abs sub w/ swap
1150       $x->{sign} = $sy;
1151       } 
1152     elsif ($a == 0)
1153       {
1154       # speedup, if equal, set result to 0
1155       $x->{value} = $CALC->_zero();
1156       $x->{sign} = '+';
1157       }
1158     else # a < 0
1159       {
1160       $x->{value} = $CALC->_sub($x->{value}, $y->{value}); # abs sub
1161       }
1162     }
1163   $x->round(@r);
1164   }
1165
1166 sub bsub 
1167   {
1168   # (BINT or num_str, BINT or num_str) return BINT
1169   # subtract second arg from first, modify first
1170   
1171   # set up parameters
1172   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1173
1174   # objectify is costly, so avoid it
1175   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1176     {
1177     ($self,$x,$y,@r) = objectify(2,@_);
1178     }
1179
1180   return $x if $x->modify('bsub');
1181
1182   return $upgrade->new($x)->bsub($upgrade->new($y),@r) if defined $upgrade &&
1183    ((!$x->isa($self)) || (!$y->isa($self)));
1184
1185   return $x->round(@r) if $y->is_zero();
1186
1187   # To correctly handle the lone special case $x->bsub($x), we note the sign
1188   # of $x, then flip the sign from $y, and if the sign of $x did change, too,
1189   # then we caught the special case:
1190   my $xsign = $x->{sign};
1191   $y->{sign} =~ tr/+\-/-+/;     # does nothing for NaN
1192   if ($xsign ne $x->{sign})
1193     {
1194     # special case of $x->bsub($x) results in 0
1195     return $x->bzero(@r) if $xsign =~ /^[+-]$/;
1196     return $x->bnan();          # NaN, -inf, +inf
1197     }
1198   $x->badd($y,@r);              # badd does not leave internal zeros
1199   $y->{sign} =~ tr/+\-/-+/;     # refix $y (does nothing for NaN)
1200   $x;                           # already rounded by badd() or no round nec.
1201   }
1202
1203 sub binc
1204   {
1205   # increment arg by one
1206   my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1207   return $x if $x->modify('binc');
1208
1209   if ($x->{sign} eq '+')
1210     {
1211     $x->{value} = $CALC->_inc($x->{value});
1212     return $x->round($a,$p,$r);
1213     }
1214   elsif ($x->{sign} eq '-')
1215     {
1216     $x->{value} = $CALC->_dec($x->{value});
1217     $x->{sign} = '+' if $CALC->_is_zero($x->{value}); # -1 +1 => -0 => +0
1218     return $x->round($a,$p,$r);
1219     }
1220   # inf, nan handling etc
1221   $x->badd($self->bone(),$a,$p,$r);             # badd does round
1222   }
1223
1224 sub bdec
1225   {
1226   # decrement arg by one
1227   my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1228   return $x if $x->modify('bdec');
1229   
1230   if ($x->{sign} eq '-')
1231     {
1232     # x already < 0
1233     $x->{value} = $CALC->_inc($x->{value});
1234     } 
1235   else
1236     {
1237     return $x->badd($self->bone('-'),@r) unless $x->{sign} eq '+';      # inf or NaN
1238     # >= 0
1239     if ($CALC->_is_zero($x->{value}))
1240       {
1241       # == 0
1242       $x->{value} = $CALC->_one(); $x->{sign} = '-';            # 0 => -1
1243       }
1244     else
1245       {
1246       # > 0
1247       $x->{value} = $CALC->_dec($x->{value});
1248       }
1249     }
1250   $x->round(@r);
1251   }
1252
1253 sub blog
1254   {
1255   # calculate $x = $a ** $base + $b and return $a (e.g. the log() to base
1256   # $base of $x)
1257
1258   # set up parameters
1259   my ($self,$x,$base,@r) = (undef,@_);
1260   # objectify is costly, so avoid it
1261   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1262     {
1263     ($self,$x,$base,@r) = objectify(2,@_);
1264     }
1265
1266   return $x if $x->modify('blog');
1267
1268   $base = $self->new($base) if defined $base && !ref $base;
1269
1270   # inf, -inf, NaN, <0 => NaN
1271   return $x->bnan()
1272    if $x->{sign} ne '+' || (defined $base && $base->{sign} ne '+');
1273
1274   return $upgrade->blog($upgrade->new($x),$base,@r) if 
1275     defined $upgrade;
1276
1277   # fix for bug #24969:
1278   # the default base is e (Euler's number) which is not an integer
1279   if (!defined $base)
1280     {
1281     require Math::BigFloat;
1282     my $u = Math::BigFloat->blog(Math::BigFloat->new($x))->as_int();
1283     # modify $x in place
1284     $x->{value} = $u->{value};
1285     $x->{sign} = $u->{sign};
1286     return $x;
1287     }
1288   
1289   my ($rc,$exact) = $CALC->_log_int($x->{value},$base->{value});
1290   return $x->bnan() unless defined $rc;         # not possible to take log?
1291   $x->{value} = $rc;
1292   $x->round(@r);
1293   }
1294
1295 sub bnok
1296   {
1297   # Calculate n over k (binomial coefficient or "choose" function) as integer.
1298   # set up parameters
1299   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1300
1301   # objectify is costly, so avoid it
1302   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1303     {
1304     ($self,$x,$y,@r) = objectify(2,@_);
1305     }
1306
1307   return $x if $x->modify('bnok');
1308   return $x->bnan() if $x->{sign} eq 'NaN' || $y->{sign} eq 'NaN';
1309   return $x->binf() if $x->{sign} eq '+inf';
1310
1311   # k > n or k < 0 => 0
1312   my $cmp = $x->bacmp($y);
1313   return $x->bzero() if $cmp < 0 || $y->{sign} =~ /^-/;
1314   # k == n => 1
1315   return $x->bone(@r) if $cmp == 0;
1316
1317   if ($CALC->can('_nok'))
1318     {
1319     $x->{value} = $CALC->_nok($x->{value},$y->{value});
1320     }
1321   else
1322     {
1323     # ( 7 )       7!       1*2*3*4 * 5*6*7   5 * 6 * 7       6   7
1324     # ( - ) = --------- =  --------------- = --------- = 5 * - * -
1325     # ( 3 )   (7-3)! 3!    1*2*3*4 * 1*2*3   1 * 2 * 3       2   3
1326
1327     if (!$y->is_zero())
1328       {
1329       my $z = $x - $y;
1330       $z->binc();
1331       my $r = $z->copy(); $z->binc();
1332       my $d = $self->new(2);
1333       while ($z->bacmp($x) <= 0)                # f <= x ?
1334         {
1335         $r->bmul($z); $r->bdiv($d);
1336         $z->binc(); $d->binc();
1337         }
1338       $x->{value} = $r->{value}; $x->{sign} = '+';
1339       }
1340     else { $x->bone(); }
1341     }
1342   $x->round(@r);
1343   }
1344
1345 sub bexp
1346   {
1347   # Calculate e ** $x (Euler's number to the power of X), truncated to
1348   # an integer value.
1349   my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1350   return $x if $x->modify('bexp');
1351
1352   # inf, -inf, NaN, <0 => NaN
1353   return $x->bnan() if $x->{sign} eq 'NaN';
1354   return $x->bone() if $x->is_zero();
1355   return $x if $x->{sign} eq '+inf';
1356   return $x->bzero() if $x->{sign} eq '-inf';
1357
1358   my $u;
1359   {
1360     # run through Math::BigFloat unless told otherwise
1361     require Math::BigFloat unless defined $upgrade;
1362     local $upgrade = 'Math::BigFloat' unless defined $upgrade;
1363     # calculate result, truncate it to integer
1364     $u = $upgrade->bexp($upgrade->new($x),@r);
1365   }
1366
1367   if (!defined $upgrade)
1368     {
1369     $u = $u->as_int();
1370     # modify $x in place
1371     $x->{value} = $u->{value};
1372     $x->round(@r);
1373     }
1374   else { $x = $u; }
1375   }
1376
1377 sub blcm
1378   {
1379   # (BINT or num_str, BINT or num_str) return BINT
1380   # does not modify arguments, but returns new object
1381   # Lowest Common Multiple
1382
1383   my $y = shift; my ($x);
1384   if (ref($y))
1385     {
1386     $x = $y->copy();
1387     }
1388   else
1389     {
1390     $x = $class->new($y);
1391     }
1392   my $self = ref($x);
1393   while (@_) 
1394     {
1395     my $y = shift; $y = $self->new($y) if !ref ($y);
1396     $x = __lcm($x,$y);
1397     } 
1398   $x;
1399   }
1400
1401 sub bgcd 
1402   { 
1403   # (BINT or num_str, BINT or num_str) return BINT
1404   # does not modify arguments, but returns new object
1405   # GCD -- Euclids algorithm, variant C (Knuth Vol 3, pg 341 ff)
1406
1407   my $y = shift;
1408   $y = $class->new($y) if !ref($y);
1409   my $self = ref($y);
1410   my $x = $y->copy()->babs();                   # keep arguments
1411   return $x->bnan() if $x->{sign} !~ /^[+-]$/;  # x NaN?
1412
1413   while (@_)
1414     {
1415     $y = shift; $y = $self->new($y) if !ref($y);
1416     return $x->bnan() if $y->{sign} !~ /^[+-]$/;        # y NaN?
1417     $x->{value} = $CALC->_gcd($x->{value},$y->{value});
1418     last if $CALC->_is_one($x->{value});
1419     }
1420   $x;
1421   }
1422
1423 sub bnot 
1424   {
1425   # (num_str or BINT) return BINT
1426   # represent ~x as twos-complement number
1427   # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1428   my ($self,$x,$a,$p,$r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1429  
1430   return $x if $x->modify('bnot');
1431   $x->binc()->bneg();                   # binc already does round
1432   }
1433
1434 ##############################################################################
1435 # is_foo test routines
1436 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1437
1438 sub is_zero
1439   {
1440   # return true if arg (BINT or num_str) is zero (array '+', '0')
1441   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1442   
1443   return 0 if $x->{sign} !~ /^\+$/;                     # -, NaN & +-inf aren't
1444   $CALC->_is_zero($x->{value});
1445   }
1446
1447 sub is_nan
1448   {
1449   # return true if arg (BINT or num_str) is NaN
1450   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1451
1452   $x->{sign} eq $nan ? 1 : 0;
1453   }
1454
1455 sub is_inf
1456   {
1457   # return true if arg (BINT or num_str) is +-inf
1458   my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1459
1460   if (defined $sign)
1461     {
1462     $sign = '[+-]inf' if $sign eq '';   # +- doesn't matter, only that's inf
1463     $sign = "[$1]inf" if $sign =~ /^([+-])(inf)?$/;     # extract '+' or '-'
1464     return $x->{sign} =~ /^$sign$/ ? 1 : 0;
1465     }
1466   $x->{sign} =~ /^[+-]inf$/ ? 1 : 0;            # only +-inf is infinity
1467   }
1468
1469 sub is_one
1470   {
1471   # return true if arg (BINT or num_str) is +1, or -1 if sign is given
1472   my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1473     
1474   $sign = '+' if !defined $sign || $sign ne '-';
1475  
1476   return 0 if $x->{sign} ne $sign;      # -1 != +1, NaN, +-inf aren't either
1477   $CALC->_is_one($x->{value});
1478   }
1479
1480 sub is_odd
1481   {
1482   # return true when arg (BINT or num_str) is odd, false for even
1483   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1484
1485   return 0 if $x->{sign} !~ /^[+-]$/;                   # NaN & +-inf aren't
1486   $CALC->_is_odd($x->{value});
1487   }
1488
1489 sub is_even
1490   {
1491   # return true when arg (BINT or num_str) is even, false for odd
1492   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1493
1494   return 0 if $x->{sign} !~ /^[+-]$/;                   # NaN & +-inf aren't
1495   $CALC->_is_even($x->{value});
1496   }
1497
1498 sub is_positive
1499   {
1500   # return true when arg (BINT or num_str) is positive (> 0)
1501   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1502
1503   return 1 if $x->{sign} eq '+inf';                     # +inf is positive
1504
1505   # 0+ is neither positive nor negative
1506   ($x->{sign} eq '+' && !$x->is_zero()) ? 1 : 0;
1507   }
1508
1509 sub is_negative
1510   {
1511   # return true when arg (BINT or num_str) is negative (< 0)
1512   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1513   
1514   $x->{sign} =~ /^-/ ? 1 : 0;           # -inf is negative, but NaN is not
1515   }
1516
1517 sub is_int
1518   {
1519   # return true when arg (BINT or num_str) is an integer
1520   # always true for BigInt, but different for BigFloats
1521   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1522   
1523   $x->{sign} =~ /^[+-]$/ ? 1 : 0;               # inf/-inf/NaN aren't
1524   }
1525
1526 ###############################################################################
1527
1528 sub bmul 
1529   { 
1530   # multiply the first number by the second number
1531   # (BINT or num_str, BINT or num_str) return BINT
1532
1533   # set up parameters
1534   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1535   # objectify is costly, so avoid it
1536   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1537     {
1538     ($self,$x,$y,@r) = objectify(2,@_);
1539     }
1540
1541   return $x if $x->modify('bmul');
1542
1543   return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1544
1545   # inf handling
1546   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1547     {
1548     return $x->bnan() if $x->is_zero() || $y->is_zero();
1549     # result will always be +-inf:
1550     # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1551     # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1552     return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/); 
1553     return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/); 
1554     return $x->binf('-');
1555     }
1556
1557   return $upgrade->bmul($x,$upgrade->new($y),@r)
1558    if defined $upgrade && !$y->isa($self);
1559   
1560   $r[3] = $y;                           # no push here
1561
1562   $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1563
1564   $x->{value} = $CALC->_mul($x->{value},$y->{value});   # do actual math
1565   $x->{sign} = '+' if $CALC->_is_zero($x->{value});     # no -0
1566
1567   $x->round(@r);
1568   }
1569
1570 sub bmuladd
1571   { 
1572   # multiply two numbers and then add the third to the result
1573   # (BINT or num_str, BINT or num_str, BINT or num_str) return BINT
1574
1575   # set up parameters
1576   my ($self,$x,$y,$z,@r) = (ref($_[0]),@_);
1577   # objectify is costly, so avoid it
1578   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1579     {
1580     ($self,$x,$y,$z,@r) = objectify(3,@_);
1581     }
1582
1583   return $x if $x->modify('bmuladd');
1584
1585   return $x->bnan() if  ($x->{sign} eq $nan) ||
1586                         ($y->{sign} eq $nan) ||
1587                         ($z->{sign} eq $nan);
1588
1589   # inf handling of x and y
1590   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1591     {
1592     return $x->bnan() if $x->is_zero() || $y->is_zero();
1593     # result will always be +-inf:
1594     # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1595     # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1596     return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/); 
1597     return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/); 
1598     return $x->binf('-');
1599     }
1600   # inf handling x*y and z
1601   if (($z->{sign} =~ /^[+-]inf$/))
1602     {
1603     # something +-inf => +-inf
1604     $x->{sign} = $z->{sign}, return $x if $z->{sign} =~ /^[+-]inf$/;
1605     }
1606
1607   return $upgrade->bmuladd($x,$upgrade->new($y),$upgrade->new($z),@r)
1608    if defined $upgrade && (!$y->isa($self) || !$z->isa($self) || !$x->isa($self));
1609  
1610   # TODO: what if $y and $z have A or P set?
1611   $r[3] = $z;                           # no push here
1612
1613   $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1614
1615   $x->{value} = $CALC->_mul($x->{value},$y->{value});   # do actual math
1616   $x->{sign} = '+' if $CALC->_is_zero($x->{value});     # no -0
1617
1618   my ($sx, $sz) = ( $x->{sign}, $z->{sign} );           # get signs
1619
1620   if ($sx eq $sz)  
1621     {
1622     $x->{value} = $CALC->_add($x->{value},$z->{value}); # same sign, abs add
1623     }
1624   else 
1625     {
1626     my $a = $CALC->_acmp ($z->{value},$x->{value});     # absolute compare
1627     if ($a > 0)                           
1628       {
1629       $x->{value} = $CALC->_sub($z->{value},$x->{value},1); # abs sub w/ swap
1630       $x->{sign} = $sz;
1631       } 
1632     elsif ($a == 0)
1633       {
1634       # speedup, if equal, set result to 0
1635       $x->{value} = $CALC->_zero();
1636       $x->{sign} = '+';
1637       }
1638     else # a < 0
1639       {
1640       $x->{value} = $CALC->_sub($x->{value}, $z->{value}); # abs sub
1641       }
1642     }
1643   $x->round(@r);
1644   }
1645
1646 sub _div_inf
1647   {
1648   # helper function that handles +-inf cases for bdiv()/bmod() to reuse code
1649   my ($self,$x,$y) = @_;
1650
1651   # NaN if x == NaN or y == NaN or x==y==0
1652   return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan()
1653    if (($x->is_nan() || $y->is_nan())   ||
1654        ($x->is_zero() && $y->is_zero()));
1655  
1656   # +-inf / +-inf == NaN, reminder also NaN
1657   if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1658     {
1659     return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan();
1660     }
1661   # x / +-inf => 0, remainder x (works even if x == 0)
1662   if ($y->{sign} =~ /^[+-]inf$/)
1663     {
1664     my $t = $x->copy();         # bzero clobbers up $x
1665     return wantarray ? ($x->bzero(),$t) : $x->bzero()
1666     }
1667   
1668   # 5 / 0 => +inf, -6 / 0 => -inf
1669   # +inf / 0 = inf, inf,  and -inf / 0 => -inf, -inf 
1670   # exception:   -8 / 0 has remainder -8, not 8
1671   # exception: -inf / 0 has remainder -inf, not inf
1672   if ($y->is_zero())
1673     {
1674     # +-inf / 0 => special case for -inf
1675     return wantarray ?  ($x,$x->copy()) : $x if $x->is_inf();
1676     if (!$x->is_zero() && !$x->is_inf())
1677       {
1678       my $t = $x->copy();               # binf clobbers up $x
1679       return wantarray ?
1680        ($x->binf($x->{sign}),$t) : $x->binf($x->{sign})
1681       }
1682     }
1683   
1684   # last case: +-inf / ordinary number
1685   my $sign = '+inf';
1686   $sign = '-inf' if substr($x->{sign},0,1) ne $y->{sign};
1687   $x->{sign} = $sign;
1688   return wantarray ? ($x,$self->bzero()) : $x;
1689   }
1690
1691 sub bdiv 
1692   {
1693   # (dividend: BINT or num_str, divisor: BINT or num_str) return 
1694   # (BINT,BINT) (quo,rem) or BINT (only rem)
1695   
1696   # set up parameters
1697   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1698   # objectify is costly, so avoid it 
1699   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1700     {
1701     ($self,$x,$y,@r) = objectify(2,@_);
1702     } 
1703
1704   return $x if $x->modify('bdiv');
1705
1706   return $self->_div_inf($x,$y)
1707    if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero());
1708
1709   return $upgrade->bdiv($upgrade->new($x),$upgrade->new($y),@r)
1710    if defined $upgrade;
1711    
1712   $r[3] = $y;                                   # no push!
1713
1714   # calc new sign and in case $y == +/- 1, return $x
1715   my $xsign = $x->{sign};                               # keep
1716   $x->{sign} = ($x->{sign} ne $y->{sign} ? '-' : '+'); 
1717
1718   if (wantarray)
1719     {
1720     my $rem = $self->bzero(); 
1721     ($x->{value},$rem->{value}) = $CALC->_div($x->{value},$y->{value});
1722     $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1723     $rem->{_a} = $x->{_a};
1724     $rem->{_p} = $x->{_p};
1725     $x->round(@r);
1726     if (! $CALC->_is_zero($rem->{value}))
1727       {
1728       $rem->{sign} = $y->{sign};
1729       $rem = $y->copy()->bsub($rem) if $xsign ne $y->{sign}; # one of them '-'
1730       }
1731     else
1732       {
1733       $rem->{sign} = '+';                       # dont leave -0
1734       }
1735     $rem->round(@r);
1736     return ($x,$rem);
1737     }
1738
1739   $x->{value} = $CALC->_div($x->{value},$y->{value});
1740   $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1741
1742   $x->round(@r);
1743   }
1744
1745 ###############################################################################
1746 # modulus functions
1747
1748 sub bmod 
1749   {
1750   # modulus (or remainder)
1751   # (BINT or num_str, BINT or num_str) return BINT
1752   
1753   # set up parameters
1754   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1755   # objectify is costly, so avoid it
1756   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1757     {
1758     ($self,$x,$y,@r) = objectify(2,@_);
1759     }
1760
1761   return $x if $x->modify('bmod');
1762   $r[3] = $y;                                   # no push!
1763   if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero())
1764     {
1765     my ($d,$r) = $self->_div_inf($x,$y);
1766     $x->{sign} = $r->{sign};
1767     $x->{value} = $r->{value};
1768     return $x->round(@r);
1769     }
1770
1771   # calc new sign and in case $y == +/- 1, return $x
1772   $x->{value} = $CALC->_mod($x->{value},$y->{value});
1773   if (!$CALC->_is_zero($x->{value}))
1774     {
1775     $x->{value} = $CALC->_sub($y->{value},$x->{value},1)        # $y-$x
1776       if ($x->{sign} ne $y->{sign});
1777     $x->{sign} = $y->{sign};
1778     }
1779    else
1780     {
1781     $x->{sign} = '+';                           # dont leave -0
1782     }
1783   $x->round(@r);
1784   }
1785
1786 sub bmodinv
1787   {
1788   # Modular inverse.  given a number which is (hopefully) relatively
1789   # prime to the modulus, calculate its inverse using Euclid's
1790   # algorithm.  If the number is not relatively prime to the modulus
1791   # (i.e. their gcd is not one) then NaN is returned.
1792
1793   # set up parameters
1794   my ($self,$x,$y,@r) = (undef,@_);
1795   # objectify is costly, so avoid it
1796   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1797     {
1798     ($self,$x,$y,@r) = objectify(2,@_);
1799     }
1800
1801   return $x if $x->modify('bmodinv');
1802
1803   return $x->bnan()
1804         if ($y->{sign} ne '+'                           # -, NaN, +inf, -inf
1805          || $x->is_zero()                               # or num == 0
1806          || $x->{sign} !~ /^[+-]$/                      # or num NaN, inf, -inf
1807         );
1808
1809   # put least residue into $x if $x was negative, and thus make it positive
1810   $x->bmod($y) if $x->{sign} eq '-';
1811
1812   my $sign;
1813   ($x->{value},$sign) = $CALC->_modinv($x->{value},$y->{value});
1814   return $x->bnan() if !defined $x->{value};            # in case no GCD found
1815   return $x if !defined $sign;                  # already real result
1816   $x->{sign} = $sign;                           # flip/flop see below
1817   $x->bmod($y);                                 # calc real result
1818   $x;
1819   }
1820
1821 sub bmodpow
1822   {
1823   # takes a very large number to a very large exponent in a given very
1824   # large modulus, quickly, thanks to binary exponentation. Supports
1825   # negative exponents.
1826   my ($self,$num,$exp,$mod,@r) = objectify(3,@_);
1827
1828   return $num if $num->modify('bmodpow');
1829
1830   # check modulus for valid values
1831   return $num->bnan() if ($mod->{sign} ne '+'           # NaN, - , -inf, +inf
1832                        || $mod->is_zero());
1833
1834   # check exponent for valid values
1835   if ($exp->{sign} =~ /\w/) 
1836     {
1837     # i.e., if it's NaN, +inf, or -inf...
1838     return $num->bnan();
1839     }
1840
1841   $num->bmodinv ($mod) if ($exp->{sign} eq '-');
1842
1843   # check num for valid values (also NaN if there was no inverse but $exp < 0)
1844   return $num->bnan() if $num->{sign} !~ /^[+-]$/;
1845
1846   # $mod is positive, sign on $exp is ignored, result also positive
1847   $num->{value} = $CALC->_modpow($num->{value},$exp->{value},$mod->{value});
1848   $num;
1849   }
1850
1851 ###############################################################################
1852
1853 sub bfac
1854   {
1855   # (BINT or num_str, BINT or num_str) return BINT
1856   # compute factorial number from $x, modify $x in place
1857   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1858
1859   return $x if $x->modify('bfac') || $x->{sign} eq '+inf';      # inf => inf
1860   return $x->bnan() if $x->{sign} ne '+';                       # NaN, <0 etc => NaN
1861
1862   $x->{value} = $CALC->_fac($x->{value});
1863   $x->round(@r);
1864   }
1865  
1866 sub bpow 
1867   {
1868   # (BINT or num_str, BINT or num_str) return BINT
1869   # compute power of two numbers -- stolen from Knuth Vol 2 pg 233
1870   # modifies first argument
1871
1872   # set up parameters
1873   my ($self,$x,$y,@r) = (ref($_[0]),@_);
1874   # objectify is costly, so avoid it
1875   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1876     {
1877     ($self,$x,$y,@r) = objectify(2,@_);
1878     }
1879
1880   return $x if $x->modify('bpow');
1881
1882   return $x->bnan() if $x->{sign} eq $nan || $y->{sign} eq $nan;
1883
1884   # inf handling
1885   if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1886     {
1887     if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1888       {
1889       # +-inf ** +-inf
1890       return $x->bnan();
1891       }
1892     # +-inf ** Y
1893     if ($x->{sign} =~ /^[+-]inf/)
1894       {
1895       # +inf ** 0 => NaN
1896       return $x->bnan() if $y->is_zero();
1897       # -inf ** -1 => 1/inf => 0
1898       return $x->bzero() if $y->is_one('-') && $x->is_negative();
1899
1900       # +inf ** Y => inf
1901       return $x if $x->{sign} eq '+inf';
1902
1903       # -inf ** Y => -inf if Y is odd
1904       return $x if $y->is_odd();
1905       return $x->babs();
1906       }
1907     # X ** +-inf
1908
1909     # 1 ** +inf => 1
1910     return $x if $x->is_one();
1911     
1912     # 0 ** inf => 0
1913     return $x if $x->is_zero() && $y->{sign} =~ /^[+]/;
1914
1915     # 0 ** -inf => inf
1916     return $x->binf() if $x->is_zero();
1917
1918     # -1 ** -inf => NaN
1919     return $x->bnan() if $x->is_one('-') && $y->{sign} =~ /^[-]/;
1920
1921     # -X ** -inf => 0
1922     return $x->bzero() if $x->{sign} eq '-' && $y->{sign} =~ /^[-]/;
1923
1924     # -1 ** inf => NaN
1925     return $x->bnan() if $x->{sign} eq '-';
1926
1927     # X ** inf => inf
1928     return $x->binf() if $y->{sign} =~ /^[+]/;
1929     # X ** -inf => 0
1930     return $x->bzero();
1931     }
1932
1933   return $upgrade->bpow($upgrade->new($x),$y,@r)
1934    if defined $upgrade && (!$y->isa($self) || $y->{sign} eq '-');
1935
1936   $r[3] = $y;                                   # no push!
1937
1938   # cases 0 ** Y, X ** 0, X ** 1, 1 ** Y are handled by Calc or Emu
1939
1940   my $new_sign = '+';
1941   $new_sign = $y->is_odd() ? '-' : '+' if ($x->{sign} ne '+'); 
1942
1943   # 0 ** -7 => ( 1 / (0 ** 7)) => 1 / 0 => +inf 
1944   return $x->binf() 
1945     if $y->{sign} eq '-' && $x->{sign} eq '+' && $CALC->_is_zero($x->{value});
1946   # 1 ** -y => 1 / (1 ** |y|)
1947   # so do test for negative $y after above's clause
1948   return $x->bnan() if $y->{sign} eq '-' && !$CALC->_is_one($x->{value});
1949
1950   $x->{value} = $CALC->_pow($x->{value},$y->{value});
1951   $x->{sign} = $new_sign;
1952   $x->{sign} = '+' if $CALC->_is_zero($y->{value});
1953   $x->round(@r);
1954   }
1955
1956 sub blsft 
1957   {
1958   # (BINT or num_str, BINT or num_str) return BINT
1959   # compute x << y, base n, y >= 0
1960  
1961   # set up parameters
1962   my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
1963   # objectify is costly, so avoid it
1964   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1965     {
1966     ($self,$x,$y,$n,@r) = objectify(2,@_);
1967     }
1968
1969   return $x if $x->modify('blsft');
1970   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1971   return $x->round(@r) if $y->is_zero();
1972
1973   $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1974
1975   $x->{value} = $CALC->_lsft($x->{value},$y->{value},$n);
1976   $x->round(@r);
1977   }
1978
1979 sub brsft 
1980   {
1981   # (BINT or num_str, BINT or num_str) return BINT
1982   # compute x >> y, base n, y >= 0
1983   
1984   # set up parameters
1985   my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
1986   # objectify is costly, so avoid it
1987   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1988     {
1989     ($self,$x,$y,$n,@r) = objectify(2,@_);
1990     }
1991
1992   return $x if $x->modify('brsft');
1993   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1994   return $x->round(@r) if $y->is_zero();
1995   return $x->bzero(@r) if $x->is_zero();                # 0 => 0
1996
1997   $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1998
1999    # this only works for negative numbers when shifting in base 2
2000   if (($x->{sign} eq '-') && ($n == 2))
2001     {
2002     return $x->round(@r) if $x->is_one('-');    # -1 => -1
2003     if (!$y->is_one())
2004       {
2005       # although this is O(N*N) in calc (as_bin!) it is O(N) in Pari et al
2006       # but perhaps there is a better emulation for two's complement shift...
2007       # if $y != 1, we must simulate it by doing:
2008       # convert to bin, flip all bits, shift, and be done
2009       $x->binc();                       # -3 => -2
2010       my $bin = $x->as_bin();
2011       $bin =~ s/^-0b//;                 # strip '-0b' prefix
2012       $bin =~ tr/10/01/;                # flip bits
2013       # now shift
2014       if ($y >= CORE::length($bin))
2015         {
2016         $bin = '0';                     # shifting to far right creates -1
2017                                         # 0, because later increment makes 
2018                                         # that 1, attached '-' makes it '-1'
2019                                         # because -1 >> x == -1 !
2020         } 
2021       else
2022         {
2023         $bin =~ s/.{$y}$//;             # cut off at the right side
2024         $bin = '1' . $bin;              # extend left side by one dummy '1'
2025         $bin =~ tr/10/01/;              # flip bits back
2026         }
2027       my $res = $self->new('0b'.$bin);  # add prefix and convert back
2028       $res->binc();                     # remember to increment
2029       $x->{value} = $res->{value};      # take over value
2030       return $x->round(@r);             # we are done now, magic, isn't?
2031       }
2032     # x < 0, n == 2, y == 1
2033     $x->bdec();                         # n == 2, but $y == 1: this fixes it
2034     }
2035
2036   $x->{value} = $CALC->_rsft($x->{value},$y->{value},$n);
2037   $x->round(@r);
2038   }
2039
2040 sub band 
2041   {
2042   #(BINT or num_str, BINT or num_str) return BINT
2043   # compute x & y
2044  
2045   # set up parameters
2046   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2047   # objectify is costly, so avoid it
2048   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2049     {
2050     ($self,$x,$y,@r) = objectify(2,@_);
2051     }
2052   
2053   return $x if $x->modify('band');
2054
2055   $r[3] = $y;                           # no push!
2056
2057   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2058
2059   my $sx = $x->{sign} eq '+' ? 1 : -1;
2060   my $sy = $y->{sign} eq '+' ? 1 : -1;
2061   
2062   if ($sx == 1 && $sy == 1)
2063     {
2064     $x->{value} = $CALC->_and($x->{value},$y->{value});
2065     return $x->round(@r);
2066     }
2067   
2068   if ($CAN{signed_and})
2069     {
2070     $x->{value} = $CALC->_signed_and($x->{value},$y->{value},$sx,$sy);
2071     return $x->round(@r);
2072     }
2073  
2074   require $EMU_LIB;
2075   __emu_band($self,$x,$y,$sx,$sy,@r);
2076   }
2077
2078 sub bior 
2079   {
2080   #(BINT or num_str, BINT or num_str) return BINT
2081   # compute x | y
2082   
2083   # set up parameters
2084   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2085   # objectify is costly, so avoid it
2086   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2087     {
2088     ($self,$x,$y,@r) = objectify(2,@_);
2089     }
2090
2091   return $x if $x->modify('bior');
2092   $r[3] = $y;                           # no push!
2093
2094   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2095
2096   my $sx = $x->{sign} eq '+' ? 1 : -1;
2097   my $sy = $y->{sign} eq '+' ? 1 : -1;
2098
2099   # the sign of X follows the sign of X, e.g. sign of Y irrelevant for bior()
2100   
2101   # don't use lib for negative values
2102   if ($sx == 1 && $sy == 1)
2103     {
2104     $x->{value} = $CALC->_or($x->{value},$y->{value});
2105     return $x->round(@r);
2106     }
2107
2108   # if lib can do negative values, let it handle this
2109   if ($CAN{signed_or})
2110     {
2111     $x->{value} = $CALC->_signed_or($x->{value},$y->{value},$sx,$sy);
2112     return $x->round(@r);
2113     }
2114
2115   require $EMU_LIB;
2116   __emu_bior($self,$x,$y,$sx,$sy,@r);
2117   }
2118
2119 sub bxor 
2120   {
2121   #(BINT or num_str, BINT or num_str) return BINT
2122   # compute x ^ y
2123   
2124   # set up parameters
2125   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2126   # objectify is costly, so avoid it
2127   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2128     {
2129     ($self,$x,$y,@r) = objectify(2,@_);
2130     }
2131
2132   return $x if $x->modify('bxor');
2133   $r[3] = $y;                           # no push!
2134
2135   return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2136   
2137   my $sx = $x->{sign} eq '+' ? 1 : -1;
2138   my $sy = $y->{sign} eq '+' ? 1 : -1;
2139
2140   # don't use lib for negative values
2141   if ($sx == 1 && $sy == 1)
2142     {
2143     $x->{value} = $CALC->_xor($x->{value},$y->{value});
2144     return $x->round(@r);
2145     }
2146   
2147   # if lib can do negative values, let it handle this
2148   if ($CAN{signed_xor})
2149     {
2150     $x->{value} = $CALC->_signed_xor($x->{value},$y->{value},$sx,$sy);
2151     return $x->round(@r);
2152     }
2153
2154   require $EMU_LIB;
2155   __emu_bxor($self,$x,$y,$sx,$sy,@r);
2156   }
2157
2158 sub length
2159   {
2160   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2161
2162   my $e = $CALC->_len($x->{value}); 
2163   wantarray ? ($e,0) : $e;
2164   }
2165
2166 sub digit
2167   {
2168   # return the nth decimal digit, negative values count backward, 0 is right
2169   my ($self,$x,$n) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2170
2171   $n = $n->numify() if ref($n);
2172   $CALC->_digit($x->{value},$n||0);
2173   }
2174
2175 sub _trailing_zeros
2176   {
2177   # return the amount of trailing zeros in $x (as scalar)
2178   my $x = shift;
2179   $x = $class->new($x) unless ref $x;
2180
2181   return 0 if $x->{sign} !~ /^[+-]$/;   # NaN, inf, -inf etc
2182
2183   $CALC->_zeros($x->{value});           # must handle odd values, 0 etc
2184   }
2185
2186 sub bsqrt
2187   {
2188   # calculate square root of $x
2189   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2190
2191   return $x if $x->modify('bsqrt');
2192
2193   return $x->bnan() if $x->{sign} !~ /^\+/;     # -x or -inf or NaN => NaN
2194   return $x if $x->{sign} eq '+inf';            # sqrt(+inf) == inf
2195
2196   return $upgrade->bsqrt($x,@r) if defined $upgrade;
2197
2198   $x->{value} = $CALC->_sqrt($x->{value});
2199   $x->round(@r);
2200   }
2201
2202 sub broot
2203   {
2204   # calculate $y'th root of $x
2205  
2206   # set up parameters
2207   my ($self,$x,$y,@r) = (ref($_[0]),@_);
2208
2209   $y = $self->new(2) unless defined $y;
2210
2211   # objectify is costly, so avoid it
2212   if ((!ref($x)) || (ref($x) ne ref($y)))
2213     {
2214     ($self,$x,$y,@r) = objectify(2,$self || $class,@_);
2215     }
2216
2217   return $x if $x->modify('broot');
2218
2219   # NaN handling: $x ** 1/0, x or y NaN, or y inf/-inf or y == 0
2220   return $x->bnan() if $x->{sign} !~ /^\+/ || $y->is_zero() ||
2221          $y->{sign} !~ /^\+$/;
2222
2223   return $x->round(@r)
2224     if $x->is_zero() || $x->is_one() || $x->is_inf() || $y->is_one();
2225
2226   return $upgrade->new($x)->broot($upgrade->new($y),@r) if defined $upgrade;
2227
2228   $x->{value} = $CALC->_root($x->{value},$y->{value});
2229   $x->round(@r);
2230   }
2231
2232 sub exponent
2233   {
2234   # return a copy of the exponent (here always 0, NaN or 1 for $m == 0)
2235   my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2236  
2237   if ($x->{sign} !~ /^[+-]$/)
2238     {
2239     my $s = $x->{sign}; $s =~ s/^[+-]//;  # NaN, -inf,+inf => NaN or inf
2240     return $self->new($s);
2241     }
2242   return $self->bone() if $x->is_zero();
2243
2244   # 12300 => 2 trailing zeros => exponent is 2
2245   $self->new( $CALC->_zeros($x->{value}) );
2246   }
2247
2248 sub mantissa
2249   {
2250   # return the mantissa (compatible to Math::BigFloat, e.g. reduced)
2251   my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2252
2253   if ($x->{sign} !~ /^[+-]$/)
2254     {
2255     # for NaN, +inf, -inf: keep the sign
2256     return $self->new($x->{sign});
2257     }
2258   my $m = $x->copy(); delete $m->{_p}; delete $m->{_a};
2259
2260   # that's a bit inefficient:
2261   my $zeros = $CALC->_zeros($m->{value});
2262   $m->brsft($zeros,10) if $zeros != 0;
2263   $m;
2264   }
2265
2266 sub parts
2267   {
2268   # return a copy of both the exponent and the mantissa
2269   my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2270
2271   ($x->mantissa(),$x->exponent());
2272   }
2273    
2274 ##############################################################################
2275 # rounding functions
2276
2277 sub bfround
2278   {
2279   # precision: round to the $Nth digit left (+$n) or right (-$n) from the '.'
2280   # $n == 0 || $n == 1 => round to integer
2281   my $x = shift; my $self = ref($x) || $x; $x = $self->new($x) unless ref $x;
2282
2283   my ($scale,$mode) = $x->_scale_p(@_);
2284
2285   return $x if !defined $scale || $x->modify('bfround');        # no-op
2286
2287   # no-op for BigInts if $n <= 0
2288   $x->bround( $x->length()-$scale, $mode) if $scale > 0;
2289
2290   delete $x->{_a};      # delete to save memory
2291   $x->{_p} = $scale;    # store new _p
2292   $x;
2293   }
2294
2295 sub _scan_for_nonzero
2296   {
2297   # internal, used by bround() to scan for non-zeros after a '5'
2298   my ($x,$pad,$xs,$len) = @_;
2299  
2300   return 0 if $len == 1;                # "5" is trailed by invisible zeros
2301   my $follow = $pad - 1;
2302   return 0 if $follow > $len || $follow < 1;
2303
2304   # use the string form to check whether only '0's follow or not
2305   substr ($xs,-$follow) =~ /[^0]/ ? 1 : 0;
2306   }
2307
2308 sub fround
2309   {
2310   # Exists to make life easier for switch between MBF and MBI (should we
2311   # autoload fxxx() like MBF does for bxxx()?)
2312   my $x = shift; $x = $class->new($x) unless ref $x;
2313   $x->bround(@_);
2314   }
2315
2316 sub bround
2317   {
2318   # accuracy: +$n preserve $n digits from left,
2319   #           -$n preserve $n digits from right (f.i. for 0.1234 style in MBF)
2320   # no-op for $n == 0
2321   # and overwrite the rest with 0's, return normalized number
2322   # do not return $x->bnorm(), but $x
2323
2324   my $x = shift; $x = $class->new($x) unless ref $x;
2325   my ($scale,$mode) = $x->_scale_a(@_);
2326   return $x if !defined $scale || $x->modify('bround'); # no-op
2327   
2328   if ($x->is_zero() || $scale == 0)
2329     {
2330     $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2331     return $x;
2332     }
2333   return $x if $x->{sign} !~ /^[+-]$/;          # inf, NaN
2334
2335   # we have fewer digits than we want to scale to
2336   my $len = $x->length();
2337   # convert $scale to a scalar in case it is an object (put's a limit on the
2338   # number length, but this would already limited by memory constraints), makes
2339   # it faster
2340   $scale = $scale->numify() if ref ($scale);
2341
2342   # scale < 0, but > -len (not >=!)
2343   if (($scale < 0 && $scale < -$len-1) || ($scale >= $len))
2344     {
2345     $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2346     return $x; 
2347     }
2348    
2349   # count of 0's to pad, from left (+) or right (-): 9 - +6 => 3, or |-6| => 6
2350   my ($pad,$digit_round,$digit_after);
2351   $pad = $len - $scale;
2352   $pad = abs($scale-1) if $scale < 0;
2353
2354   # do not use digit(), it is very costly for binary => decimal
2355   # getting the entire string is also costly, but we need to do it only once
2356   my $xs = $CALC->_str($x->{value});
2357   my $pl = -$pad-1;
2358
2359   # pad:   123: 0 => -1, at 1 => -2, at 2 => -3, at 3 => -4
2360   # pad+1: 123: 0 => 0,  at 1 => -1, at 2 => -2, at 3 => -3
2361   $digit_round = '0'; $digit_round = substr($xs,$pl,1) if $pad <= $len;
2362   $pl++; $pl ++ if $pad >= $len;
2363   $digit_after = '0'; $digit_after = substr($xs,$pl,1) if $pad > 0;
2364
2365   # in case of 01234 we round down, for 6789 up, and only in case 5 we look
2366   # closer at the remaining digits of the original $x, remember decision
2367   my $round_up = 1;                                     # default round up
2368   $round_up -- if
2369     ($mode eq 'trunc')                          ||      # trunc by round down
2370     ($digit_after =~ /[01234]/)                 ||      # round down anyway,
2371                                                         # 6789 => round up
2372     ($digit_after eq '5')                       &&      # not 5000...0000
2373     ($x->_scan_for_nonzero($pad,$xs,$len) == 0)         &&
2374     (
2375      ($mode eq 'even') && ($digit_round =~ /[24680]/) ||
2376      ($mode eq 'odd')  && ($digit_round =~ /[13579]/) ||
2377      ($mode eq '+inf') && ($x->{sign} eq '-')   ||
2378      ($mode eq '-inf') && ($x->{sign} eq '+')   ||
2379      ($mode eq 'zero')          # round down if zero, sign adjusted below
2380     );
2381   my $put_back = 0;                                     # not yet modified
2382         
2383   if (($pad > 0) && ($pad <= $len))
2384     {
2385     substr($xs,-$pad,$pad) = '0' x $pad;                # replace with '00...'
2386     $put_back = 1;                                      # need to put back
2387     }
2388   elsif ($pad > $len)
2389     {
2390     $x->bzero();                                        # round to '0'
2391     }
2392
2393   if ($round_up)                                        # what gave test above?
2394     {
2395     $put_back = 1;                                      # need to put back
2396     $pad = $len, $xs = '0' x $pad if $scale < 0;        # tlr: whack 0.51=>1.0  
2397
2398     # we modify directly the string variant instead of creating a number and
2399     # adding it, since that is faster (we already have the string)
2400     my $c = 0; $pad ++;                         # for $pad == $len case
2401     while ($pad <= $len)
2402       {
2403       $c = substr($xs,-$pad,1) + 1; $c = '0' if $c eq '10';
2404       substr($xs,-$pad,1) = $c; $pad++;
2405       last if $c != 0;                          # no overflow => early out
2406       }
2407     $xs = '1'.$xs if $c == 0;
2408
2409     }
2410   $x->{value} = $CALC->_new($xs) if $put_back == 1;     # put back, if needed
2411
2412   $x->{_a} = $scale if $scale >= 0;
2413   if ($scale < 0)
2414     {
2415     $x->{_a} = $len+$scale;
2416     $x->{_a} = 0 if $scale < -$len;
2417     }
2418   $x;
2419   }
2420
2421 sub bfloor
2422   {
2423   # return integer less or equal then number; no-op since it's already integer
2424   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2425
2426   $x->round(@r);
2427   }
2428
2429 sub bceil
2430   {
2431   # return integer greater or equal then number; no-op since it's already int
2432   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2433
2434   $x->round(@r);
2435   }
2436
2437 sub as_number
2438   {
2439   # An object might be asked to return itself as bigint on certain overloaded
2440   # operations. This does exactly this, so that sub classes can simple inherit
2441   # it or override with their own integer conversion routine.
2442   $_[0]->copy();
2443   }
2444
2445 sub as_hex
2446   {
2447   # return as hex string, with prefixed 0x
2448   my $x = shift; $x = $class->new($x) if !ref($x);
2449
2450   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2451
2452   my $s = '';
2453   $s = $x->{sign} if $x->{sign} eq '-';
2454   $s . $CALC->_as_hex($x->{value});
2455   }
2456
2457 sub as_bin
2458   {
2459   # return as binary string, with prefixed 0b
2460   my $x = shift; $x = $class->new($x) if !ref($x);
2461
2462   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2463
2464   my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2465   return $s . $CALC->_as_bin($x->{value});
2466   }
2467
2468 sub as_oct
2469   {
2470   # return as octal string, with prefixed 0
2471   my $x = shift; $x = $class->new($x) if !ref($x);
2472
2473   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2474
2475   my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2476   return $s . $CALC->_as_oct($x->{value});
2477   }
2478
2479 ##############################################################################
2480 # private stuff (internal use only)
2481
2482 sub objectify
2483   {
2484   # check for strings, if yes, return objects instead
2485  
2486   # the first argument is number of args objectify() should look at it will
2487   # return $count+1 elements, the first will be a classname. This is because
2488   # overloaded '""' calls bstr($object,undef,undef) and this would result in
2489   # useless objects being created and thrown away. So we cannot simple loop
2490   # over @_. If the given count is 0, all arguments will be used.
2491  
2492   # If the second arg is a ref, use it as class.
2493   # If not, try to use it as classname, unless undef, then use $class 
2494   # (aka Math::BigInt). The latter shouldn't happen,though.
2495
2496   # caller:                        gives us:
2497   # $x->badd(1);                => ref x, scalar y
2498   # Class->badd(1,2);           => classname x (scalar), scalar x, scalar y
2499   # Class->badd( Class->(1),2); => classname x (scalar), ref x, scalar y
2500   # Math::BigInt::badd(1,2);    => scalar x, scalar y
2501   # In the last case we check number of arguments to turn it silently into
2502   # $class,1,2. (We can not take '1' as class ;o)
2503   # badd($class,1) is not supported (it should, eventually, try to add undef)
2504   # currently it tries 'Math::BigInt' + 1, which will not work.
2505
2506   # some shortcut for the common cases
2507   # $x->unary_op();
2508   return (ref($_[1]),$_[1]) if (@_ == 2) && ($_[0]||0 == 1) && ref($_[1]);
2509
2510   my $count = abs(shift || 0);
2511   
2512   my (@a,$k,$d);                # resulting array, temp, and downgrade 
2513   if (ref $_[0])
2514     {
2515     # okay, got object as first
2516     $a[0] = ref $_[0];
2517     }
2518   else
2519     {
2520     # nope, got 1,2 (Class->xxx(1) => Class,1 and not supported)
2521     $a[0] = $class;
2522     $a[0] = shift if $_[0] =~ /^[A-Z].*::/;     # classname as first?
2523     }
2524
2525   no strict 'refs';
2526   # disable downgrading, because Math::BigFLoat->foo('1.0','2.0') needs floats
2527   if (defined ${"$a[0]::downgrade"})
2528     {
2529     $d = ${"$a[0]::downgrade"};
2530     ${"$a[0]::downgrade"} = undef;
2531     }
2532
2533   my $up = ${"$a[0]::upgrade"};
2534   # print STDERR "# Now in objectify, my class is today $a[0], count = $count\n";
2535   if ($count == 0)
2536     {
2537     while (@_)
2538       {
2539       $k = shift;
2540       if (!ref($k))
2541         {
2542         $k = $a[0]->new($k);
2543         }
2544       elsif (!defined $up && ref($k) ne $a[0])
2545         {
2546         # foreign object, try to convert to integer
2547         $k->can('as_number') ?  $k = $k->as_number() : $k = $a[0]->new($k);
2548         }
2549       push @a,$k;
2550       }
2551     }
2552   else
2553     {
2554     while ($count > 0)
2555       {
2556       $count--; 
2557       $k = shift;
2558       if (!ref($k))
2559         {
2560         $k = $a[0]->new($k);
2561         }
2562       elsif (ref($k) ne $a[0] and !defined $up || ref $k ne $up)
2563         {
2564         # foreign object, try to convert to integer
2565         $k->can('as_number') ? $k = $k->as_number() : $k = $a[0]->new($k);
2566         }
2567       push @a,$k;
2568       }
2569     push @a,@_;         # return other params, too
2570     }
2571   if (! wantarray)
2572     {
2573     require Carp; Carp::croak ("$class objectify needs list context");
2574     }
2575   ${"$a[0]::downgrade"} = $d;
2576   @a;
2577   }
2578
2579 sub _register_callback
2580   {
2581   my ($class,$callback) = @_;
2582
2583   if (ref($callback) ne 'CODE')
2584     { 
2585     require Carp;
2586     Carp::croak ("$callback is not a coderef");
2587     }
2588   $CALLBACKS{$class} = $callback;
2589   }
2590
2591 sub import 
2592   {
2593   my $self = shift;
2594
2595   $IMPORT++;                            # remember we did import()
2596   my @a; my $l = scalar @_;
2597   my $warn_or_die = 0;                  # 0 - no warn, 1 - warn, 2 - die
2598   for ( my $i = 0; $i < $l ; $i++ )
2599     {
2600     if ($_[$i] eq ':constant')
2601       {
2602       # this causes overlord er load to step in
2603       overload::constant 
2604         integer => sub { $self->new(shift) },
2605         binary => sub { $self->new(shift) };
2606       }
2607     elsif ($_[$i] eq 'upgrade')
2608       {
2609       # this causes upgrading
2610       $upgrade = $_[$i+1];              # or undef to disable
2611       $i++;
2612       }
2613     elsif ($_[$i] =~ /^(lib|try|only)\z/)
2614       {
2615       # this causes a different low lib to take care...
2616       $CALC = $_[$i+1] || '';
2617       # lib => 1 (warn on fallback), try => 0 (no warn), only => 2 (die on fallback)
2618       $warn_or_die = 1 if $_[$i] eq 'lib';
2619       $warn_or_die = 2 if $_[$i] eq 'only';
2620       $i++;
2621       }
2622     else
2623       {
2624       push @a, $_[$i];
2625       }
2626     }
2627   # any non :constant stuff is handled by our parent, Exporter
2628   if (@a > 0)
2629     {
2630     require Exporter;
2631  
2632     $self->SUPER::import(@a);                   # need it for subclasses
2633     $self->export_to_level(1,$self,@a);         # need it for MBF
2634     }
2635
2636   # try to load core math lib
2637   my @c = split /\s*,\s*/,$CALC;
2638   foreach (@c)
2639     {
2640     $_ =~ tr/a-zA-Z0-9://cd;                    # limit to sane characters
2641     }
2642   push @c, \'FastCalc', \'Calc'                 # if all fail, try these
2643     if $warn_or_die < 2;                        # but not for "only"
2644   $CALC = '';                                   # signal error
2645   foreach my $l (@c)
2646     {
2647     # fallback libraries are "marked" as \'string', extract string if nec.
2648     my $lib = $l; $lib = $$l if ref($l);
2649
2650     next if ($lib || '') eq '';
2651     $lib = 'Math::BigInt::'.$lib if $lib !~ /^Math::BigInt/i;
2652     $lib =~ s/\.pm$//;
2653     if ($] < 5.006)
2654       {
2655       # Perl < 5.6.0 dies with "out of memory!" when eval("") and ':constant' is
2656       # used in the same script, or eval("") inside import().
2657       my @parts = split /::/, $lib;             # Math::BigInt => Math BigInt
2658       my $file = pop @parts; $file .= '.pm';    # BigInt => BigInt.pm
2659       require File::Spec;
2660       $file = File::Spec->catfile (@parts, $file);
2661       eval { require "$file"; $lib->import( @c ); }
2662       }
2663     else
2664       {
2665       eval "use $lib qw/@c/;";
2666       }
2667     if ($@ eq '')
2668       {
2669       my $ok = 1;
2670       # loaded it ok, see if the api_version() is high enough
2671       if ($lib->can('api_version') && $lib->api_version() >= 1.0)
2672         {
2673         $ok = 0;
2674         # api_version matches, check if it really provides anything we need
2675         for my $method (qw/
2676                 one two ten
2677                 str num
2678                 add mul div sub dec inc
2679                 acmp len digit is_one is_zero is_even is_odd
2680                 is_two is_ten
2681                 zeros new copy check
2682                 from_hex from_oct from_bin as_hex as_bin as_oct
2683                 rsft lsft xor and or
2684                 mod sqrt root fac pow modinv modpow log_int gcd
2685          /)
2686           {
2687           if (!$lib->can("_$method"))
2688             {
2689             if (($WARN{$lib}||0) < 2)
2690               {
2691               require Carp;
2692               Carp::carp ("$lib is missing method '_$method'");
2693               $WARN{$lib} = 1;          # still warn about the lib
2694               }
2695             $ok++; last; 
2696             }
2697           }
2698         }
2699       if ($ok == 0)
2700         {
2701         $CALC = $lib;
2702         if ($warn_or_die > 0 && ref($l))
2703           {
2704           require Carp;
2705           my $msg = "Math::BigInt: couldn't load specified math lib(s), fallback to $lib";
2706           Carp::carp ($msg) if $warn_or_die == 1;
2707           Carp::croak ($msg) if $warn_or_die == 2;
2708           }
2709         last;                   # found a usable one, break
2710         }
2711       else
2712         {
2713         if (($WARN{$lib}||0) < 2)
2714           {
2715           my $ver = eval "\$$lib\::VERSION" || 'unknown';
2716           require Carp;
2717           Carp::carp ("Cannot load outdated $lib v$ver, please upgrade");
2718           $WARN{$lib} = 2;              # never warn again
2719           }
2720         }
2721       }
2722     }
2723   if ($CALC eq '')
2724     {
2725     require Carp;
2726     if ($warn_or_die == 2)
2727       {
2728       Carp::croak ("Couldn't load specified math lib(s) and fallback disallowed");
2729       }
2730     else
2731       {
2732       Carp::croak ("Couldn't load any math lib(s), not even fallback to Calc.pm");
2733       }
2734     }
2735
2736   # notify callbacks
2737   foreach my $class (keys %CALLBACKS)
2738     {
2739     &{$CALLBACKS{$class}}($CALC);
2740     }
2741
2742   # Fill $CAN with the results of $CALC->can(...) for emulating lower math lib
2743   # functions
2744
2745   %CAN = ();
2746   for my $method (qw/ signed_and signed_or signed_xor /)
2747     {
2748     $CAN{$method} = $CALC->can("_$method") ? 1 : 0;
2749     }
2750
2751   # import done
2752   }
2753
2754 sub from_hex
2755   {
2756   # create a bigint from a hexadecimal string
2757   my ($self, $hs) = @_;
2758
2759   my $rc = __from_hex($hs);
2760
2761   return $self->bnan() unless defined $rc;
2762
2763   $rc;
2764   }  
2765
2766 sub from_bin
2767   {
2768   # create a bigint from a hexadecimal string
2769   my ($self, $bs) = @_;
2770
2771   my $rc = __from_bin($bs);
2772
2773   return $self->bnan() unless defined $rc;
2774
2775   $rc;
2776   }  
2777
2778 sub from_oct
2779   {
2780   # create a bigint from a hexadecimal string
2781   my ($self, $os) = @_;
2782
2783   my $x = $self->bzero();
2784   
2785   # strip underscores
2786   $os =~ s/([0-7])_([0-7])/$1$2/g;      
2787   $os =~ s/([0-7])_([0-7])/$1$2/g;      
2788   
2789   return $x->bnan() if $os !~ /^[\-\+]?0[0-7]+\z/;
2790
2791   my $sign = '+'; $sign = '-' if $os =~ /^-/;
2792
2793   $os =~ s/^[+-]//;                                             # strip sign
2794   $x->{value} = $CALC->_from_oct($os);
2795   $x->{sign} = $sign unless $CALC->_is_zero($x->{value});       # no '-0'
2796   $x;
2797   }
2798
2799 sub __from_hex
2800   {
2801   # internal
2802   # convert a (ref to) big hex string to BigInt, return undef for error
2803   my $hs = shift;
2804
2805   my $x = Math::BigInt->bzero();
2806   
2807   # strip underscores
2808   $hs =~ s/([0-9a-fA-F])_([0-9a-fA-F])/$1$2/g;  
2809   $hs =~ s/([0-9a-fA-F])_([0-9a-fA-F])/$1$2/g;  
2810   
2811   return $x->bnan() if $hs !~ /^[\-\+]?0x[0-9A-Fa-f]+$/;
2812
2813   my $sign = '+'; $sign = '-' if $hs =~ /^-/;
2814
2815   $hs =~ s/^[+-]//;                                             # strip sign
2816   $x->{value} = $CALC->_from_hex($hs);
2817   $x->{sign} = $sign unless $CALC->_is_zero($x->{value});       # no '-0'
2818   $x;
2819   }
2820
2821 sub __from_bin
2822   {
2823   # internal
2824   # convert a (ref to) big binary string to BigInt, return undef for error
2825   my $bs = shift;
2826
2827   my $x = Math::BigInt->bzero();
2828
2829   # strip underscores
2830   $bs =~ s/([01])_([01])/$1$2/g;        
2831   $bs =~ s/([01])_([01])/$1$2/g;        
2832   return $x->bnan() if $bs !~ /^[+-]?0b[01]+$/;
2833
2834   my $sign = '+'; $sign = '-' if $bs =~ /^\-/;
2835   $bs =~ s/^[+-]//;                                             # strip sign
2836
2837   $x->{value} = $CALC->_from_bin($bs);
2838   $x->{sign} = $sign unless $CALC->_is_zero($x->{value});       # no '-0'
2839   $x;
2840   }
2841
2842 sub _split
2843   {
2844   # input: num_str; output: undef for invalid or
2845   # (\$mantissa_sign,\$mantissa_value,\$mantissa_fraction,\$exp_sign,\$exp_value)
2846   # Internal, take apart a string and return the pieces.
2847   # Strip leading/trailing whitespace, leading zeros, underscore and reject
2848   # invalid input.
2849   my $x = shift;
2850
2851   # strip white space at front, also extranous leading zeros
2852   $x =~ s/^\s*([-]?)0*([0-9])/$1$2/g;   # will not strip '  .2'
2853   $x =~ s/^\s+//;                       # but this will
2854   $x =~ s/\s+$//g;                      # strip white space at end
2855
2856   # shortcut, if nothing to split, return early
2857   if ($x =~ /^[+-]?[0-9]+\z/)
2858     {
2859     $x =~ s/^([+-])0*([0-9])/$2/; my $sign = $1 || '+';
2860     return (\$sign, \$x, \'', \'', \0);
2861     }
2862
2863   # invalid starting char?
2864   return if $x !~ /^[+-]?(\.?[0-9]|0b[0-1]|0x[0-9a-fA-F])/;
2865
2866   return __from_hex($x) if $x =~ /^[\-\+]?0x/;          # hex string
2867   return __from_bin($x) if $x =~ /^[\-\+]?0b/;          # binary string
2868   
2869   # strip underscores between digits
2870   $x =~ s/([0-9])_([0-9])/$1$2/g;
2871   $x =~ s/([0-9])_([0-9])/$1$2/g;               # do twice for 1_2_3
2872
2873   # some possible inputs: 
2874   # 2.1234 # 0.12        # 1          # 1E1 # 2.134E1 # 434E-10 # 1.02009E-2 
2875   # .2     # 1_2_3.4_5_6 # 1.4E1_2_3  # 1e3 # +.2     # 0e999   
2876
2877   my ($m,$e,$last) = split /[Ee]/,$x;
2878   return if defined $last;              # last defined => 1e2E3 or others
2879   $e = '0' if !defined $e || $e eq "";
2880
2881   # sign,value for exponent,mantint,mantfrac
2882   my ($es,$ev,$mis,$miv,$mfv);
2883   # valid exponent?
2884   if ($e =~ /^([+-]?)0*([0-9]+)$/)      # strip leading zeros
2885     {
2886     $es = $1; $ev = $2;
2887     # valid mantissa?
2888     return if $m eq '.' || $m eq '';
2889     my ($mi,$mf,$lastf) = split /\./,$m;
2890     return if defined $lastf;           # lastf defined => 1.2.3 or others
2891     $mi = '0' if !defined $mi;
2892     $mi .= '0' if $mi =~ /^[\-\+]?$/;
2893     $mf = '0' if !defined $mf || $mf eq '';
2894     if ($mi =~ /^([+-]?)0*([0-9]+)$/)           # strip leading zeros
2895       {
2896       $mis = $1||'+'; $miv = $2;
2897       return unless ($mf =~ /^([0-9]*?)0*$/);   # strip trailing zeros
2898       $mfv = $1;
2899       # handle the 0e999 case here
2900       $ev = 0 if $miv eq '0' && $mfv eq '';
2901       return (\$mis,\$miv,\$mfv,\$es,\$ev);
2902       }
2903     }
2904   return; # NaN, not a number
2905   }
2906
2907 ##############################################################################
2908 # internal calculation routines (others are in Math::BigInt::Calc etc)
2909
2910 sub __lcm 
2911   { 
2912   # (BINT or num_str, BINT or num_str) return BINT
2913   # does modify first argument
2914   # LCM
2915  
2916   my ($x,$ty) = @_;
2917   return $x->bnan() if ($x->{sign} eq $nan) || ($ty->{sign} eq $nan);
2918   my $method = ref($x) . '::bgcd';
2919   no strict 'refs';
2920   $x * $ty / &$method($x,$ty);
2921   }
2922
2923 ###############################################################################
2924 # trigonometric functions
2925
2926 sub bpi
2927   {
2928   # Calculate PI to N digits. Unless upgrading is in effect, returns the
2929   # result truncated to an integer, that is, always returns '3'.
2930   my ($self,$n) = @_;
2931   if (@_ == 1)
2932     {
2933     # called like Math::BigInt::bpi(10);
2934     $n = $self; $self = $class;
2935     }
2936   $self = ref($self) if ref($self);
2937
2938   return $upgrade->new($n) if defined $upgrade;
2939
2940   # hard-wired to "3"
2941   $self->new(3);
2942   }
2943
2944 sub bcos
2945   {
2946   # Calculate cosinus(x) to N digits. Unless upgrading is in effect, returns the
2947   # result truncated to an integer.
2948   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2949
2950   return $x if $x->modify('bcos');
2951
2952   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
2953
2954   return $upgrade->new($x)->bcos(@r) if defined $upgrade;
2955
2956   require Math::BigFloat;
2957   # calculate the result and truncate it to integer
2958   my $t = Math::BigFloat->new($x)->bcos(@r)->as_int();
2959
2960   $x->bone() if $t->is_one();
2961   $x->bzero() if $t->is_zero();
2962   $x->round(@r);
2963   }
2964
2965 sub bsin
2966   {
2967   # Calculate sinus(x) to N digits. Unless upgrading is in effect, returns the
2968   # result truncated to an integer.
2969   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2970
2971   return $x if $x->modify('bsin');
2972
2973   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
2974
2975   return $upgrade->new($x)->bsin(@r) if defined $upgrade;
2976
2977   require Math::BigFloat;
2978   # calculate the result and truncate it to integer
2979   my $t = Math::BigFloat->new($x)->bsin(@r)->as_int();
2980
2981   $x->bone() if $t->is_one();
2982   $x->bzero() if $t->is_zero();
2983   $x->round(@r);
2984   }
2985
2986 sub batan2
2987   { 
2988   # calculate arcus tangens of ($y/$x)
2989  
2990   # set up parameters
2991   my ($self,$y,$x,@r) = (ref($_[0]),@_);
2992   # objectify is costly, so avoid it
2993   if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2994     {
2995     ($self,$y,$x,@r) = objectify(2,@_);
2996     }
2997
2998   return $y if $y->modify('batan2');
2999
3000   return $y->bnan() if ($y->{sign} eq $nan) || ($x->{sign} eq $nan);
3001
3002   # Y    X
3003   # != 0 -inf result is +- pi
3004   if ($x->is_inf() || $y->is_inf())
3005     {
3006     # upgrade to BigFloat etc.
3007     return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3008     if ($y->is_inf())
3009       {
3010       if ($x->{sign} eq '-inf')
3011         {
3012         # calculate 3 pi/4 => 2.3.. => 2
3013         $y->bone( substr($y->{sign},0,1) );
3014         $y->bmul($self->new(2));
3015         }
3016       elsif ($x->{sign} eq '+inf')
3017         {
3018         # calculate pi/4 => 0.7 => 0
3019         $y->bzero();
3020         }
3021       else
3022         {
3023         # calculate pi/2 => 1.5 => 1
3024         $y->bone( substr($y->{sign},0,1) );
3025         }
3026       }
3027     else
3028       {
3029       if ($x->{sign} eq '+inf')
3030         {
3031         # calculate pi/4 => 0.7 => 0
3032         $y->bzero();
3033         }
3034       else
3035         {
3036         # PI => 3.1415.. => 3
3037         $y->bone( substr($y->{sign},0,1) );
3038         $y->bmul($self->new(3));
3039         }
3040       }
3041     return $y;
3042     }
3043
3044   return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3045
3046   require Math::BigFloat;
3047   my $r = Math::BigFloat->new($y)->batan2(Math::BigFloat->new($x),@r)->as_int();
3048
3049   $x->{value} = $r->{value};
3050   $x->{sign} = $r->{sign};
3051
3052   $x;
3053   }
3054
3055 sub batan
3056   {
3057   # Calculate arcus tangens of x to N digits. Unless upgrading is in effect, returns the
3058   # result truncated to an integer.
3059   my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
3060
3061   return $x if $x->modify('batan');
3062
3063   return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
3064
3065   return $upgrade->new($x)->batan(@r) if defined $upgrade;
3066
3067   # calculate the result and truncate it to integer
3068   my $t = Math::BigFloat->new($x)->batan(@r);
3069
3070   $x->{value} = $CALC->_new( $x->as_int()->bstr() );
3071   $x->round(@r);
3072   }
3073
3074 ###############################################################################
3075 # this method returns 0 if the object can be modified, or 1 if not.
3076 # We use a fast constant sub() here, to avoid costly calls. Subclasses
3077 # may override it with special code (f.i. Math::BigInt::Constant does so)
3078
3079 sub modify () { 0; }
3080
3081 1;
3082 __END__
3083
3084 =pod
3085
3086 =head1 NAME
3087
3088 Math::BigInt - Arbitrary size integer/float math package
3089
3090 =head1 SYNOPSIS
3091
3092   use Math::BigInt;
3093
3094   # or make it faster with huge numbers: install (optional)
3095   # Math::BigInt::GMP and always use (it will fall back to
3096   # pure Perl if the GMP library is not installed):
3097   # (See also the L<MATH LIBRARY> section!)
3098
3099   # will warn if Math::BigInt::GMP cannot be found
3100   use Math::BigInt lib => 'GMP';
3101
3102   # to suppress the warning use this:
3103   # use Math::BigInt try => 'GMP';
3104
3105   # dies if GMP cannot be loaded:
3106   # use Math::BigInt only => 'GMP';
3107
3108   my $str = '1234567890';
3109   my @values = (64,74,18);
3110   my $n = 1; my $sign = '-';
3111
3112   # Number creation     
3113   my $x = Math::BigInt->new($str);      # defaults to 0
3114   my $y = $x->copy();                   # make a true copy
3115   my $nan  = Math::BigInt->bnan();      # create a NotANumber
3116   my $zero = Math::BigInt->bzero();     # create a +0
3117   my $inf = Math::BigInt->binf();       # create a +inf
3118   my $inf = Math::BigInt->binf('-');    # create a -inf
3119   my $one = Math::BigInt->bone();       # create a +1
3120   my $mone = Math::BigInt->bone('-');   # create a -1
3121
3122   my $pi = Math::BigInt->bpi();         # returns '3'
3123                                         # see Math::BigFloat::bpi()
3124
3125   $h = Math::BigInt->new('0x123');      # from hexadecimal
3126   $b = Math::BigInt->new('0b101');      # from binary
3127   $o = Math::BigInt->from_oct('0101');  # from octal
3128
3129   # Testing (don't modify their arguments)
3130   # (return true if the condition is met, otherwise false)
3131
3132   $x->is_zero();        # if $x is +0
3133   $x->is_nan();         # if $x is NaN
3134   $x->is_one();         # if $x is +1
3135   $x->is_one('-');      # if $x is -1
3136   $x->is_odd();         # if $x is odd
3137   $x->is_even();        # if $x is even
3138   $x->is_pos();         # if $x > 0
3139   $x->is_neg();         # if $x < 0
3140   $x->is_inf($sign);    # if $x is +inf, or -inf (sign is default '+')
3141   $x->is_int();         # if $x is an integer (not a float)
3142
3143   # comparing and digit/sign extraction
3144   $x->bcmp($y);         # compare numbers (undef,<0,=0,>0)
3145   $x->bacmp($y);        # compare absolutely (undef,<0,=0,>0)
3146   $x->sign();           # return the sign, either +,- or NaN
3147   $x->digit($n);        # return the nth digit, counting from right
3148   $x->digit(-$n);       # return the nth digit, counting from left
3149
3150   # The following all modify their first argument. If you want to preserve
3151   # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
3152   # necessary when mixing $a = $b assignments with non-overloaded math.
3153
3154   $x->bzero();          # set $x to 0
3155   $x->bnan();           # set $x to NaN
3156   $x->bone();           # set $x to +1
3157   $x->bone('-');        # set $x to -1
3158   $x->binf();           # set $x to inf
3159   $x->binf('-');        # set $x to -inf
3160
3161   $x->bneg();           # negation
3162   $x->babs();           # absolute value
3163   $x->bnorm();          # normalize (no-op in BigInt)
3164   $x->bnot();           # two's complement (bit wise not)
3165   $x->binc();           # increment $x by 1
3166   $x->bdec();           # decrement $x by 1
3167   
3168   $x->badd($y);         # addition (add $y to $x)
3169   $x->bsub($y);         # subtraction (subtract $y from $x)
3170   $x->bmul($y);         # multiplication (multiply $x by $y)
3171   $x->bdiv($y);         # divide, set $x to quotient
3172                         # return (quo,rem) or quo if scalar
3173
3174   $x->bmuladd($y,$z);   # $x = $x * $y + $z
3175
3176   $x->bmod($y);            # modulus (x % y)
3177   $x->bmodpow($exp,$mod);  # modular exponentation (($num**$exp) % $mod))
3178   $x->bmodinv($mod);       # the inverse of $x in the given modulus $mod
3179
3180   $x->bpow($y);            # power of arguments (x ** y)
3181   $x->blsft($y);           # left shift in base 2
3182   $x->brsft($y);           # right shift in base 2
3183                            # returns (quo,rem) or quo if in scalar context
3184   $x->blsft($y,$n);        # left shift by $y places in base $n
3185   $x->brsft($y,$n);        # right shift by $y places in base $n
3186                            # returns (quo,rem) or quo if in scalar context
3187   
3188   $x->band($y);            # bitwise and
3189   $x->bior($y);            # bitwise inclusive or
3190   $x->bxor($y);            # bitwise exclusive or
3191   $x->bnot();              # bitwise not (two's complement)
3192
3193   $x->bsqrt();             # calculate square-root
3194   $x->broot($y);           # $y'th root of $x (e.g. $y == 3 => cubic root)
3195   $x->bfac();              # factorial of $x (1*2*3*4*..$x)
3196
3197   $x->bnok($y);            # x over y (binomial coefficient n over k)
3198
3199   $x->blog();              # logarithm of $x to base e (Euler's number)
3200   $x->blog($base);         # logarithm of $x to base $base (f.i. 2)
3201   $x->bexp();              # calculate e ** $x where e is Euler's number
3202   
3203   $x->round($A,$P,$mode);  # round to accuracy or precision using mode $mode
3204   $x->bround($n);          # accuracy: preserve $n digits
3205   $x->bfround($n);         # $n > 0: round $nth digits,
3206                            # $n < 0: round to the $nth digit after the
3207                            # dot, no-op for BigInts
3208
3209   # The following do not modify their arguments in BigInt (are no-ops),
3210   # but do so in BigFloat:
3211
3212   $x->bfloor();            # return integer less or equal than $x
3213   $x->bceil();             # return integer greater or equal than $x
3214
3215   # The following do not modify their arguments:
3216
3217   # greatest common divisor (no OO style)
3218   my $gcd = Math::BigInt::bgcd(@values);
3219   # lowest common multiple (no OO style)
3220   my $lcm = Math::BigInt::blcm(@values);
3221
3222   $x->length();            # return number of digits in number
3223   ($xl,$f) = $x->length(); # length of number and length of fraction part,
3224                            # latter is always 0 digits long for BigInts
3225
3226   $x->exponent();          # return exponent as BigInt
3227   $x->mantissa();          # return (signed) mantissa as BigInt
3228   $x->parts();             # return (mantissa,exponent) as BigInt
3229   $x->copy();              # make a true copy of $x (unlike $y = $x;)
3230   $x->as_int();            # return as BigInt (in BigInt: same as copy())
3231   $x->numify();            # return as scalar (might overflow!)
3232   
3233   # conversion to string (do not modify their argument)
3234   $x->bstr();              # normalized string (e.g. '3')
3235   $x->bsstr();             # norm. string in scientific notation (e.g. '3E0')
3236   $x->as_hex();            # as signed hexadecimal string with prefixed 0x
3237   $x->as_bin();            # as signed binary string with prefixed 0b
3238   $x->as_oct();            # as signed octal string with prefixed 0
3239
3240
3241   # precision and accuracy (see section about rounding for more)
3242   $x->precision();         # return P of $x (or global, if P of $x undef)
3243   $x->precision($n);       # set P of $x to $n
3244   $x->accuracy();          # return A of $x (or global, if A of $x undef)
3245   $x->accuracy($n);        # set A $x to $n
3246
3247   # Global methods
3248   Math::BigInt->precision();    # get/set global P for all BigInt objects
3249   Math::BigInt->accuracy();     # get/set global A for all BigInt objects
3250   Math::BigInt->round_mode();   # get/set global round mode, one of
3251                                 # 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
3252   Math::BigInt->config();       # return hash containing configuration
3253
3254 =head1 DESCRIPTION
3255
3256 All operators (including basic math operations) are overloaded if you
3257 declare your big integers as
3258
3259   $i = new Math::BigInt '123_456_789_123_456_789';
3260
3261 Operations with overloaded operators preserve the arguments which is
3262 exactly what you expect.
3263
3264 =over 2
3265
3266 =item Input
3267
3268 Input values to these routines may be any string, that looks like a number
3269 and results in an integer, including hexadecimal and binary numbers.
3270
3271 Scalars holding numbers may also be passed, but note that non-integer numbers
3272 may already have lost precision due to the conversion to float. Quote
3273 your input if you want BigInt to see all the digits:
3274
3275         $x = Math::BigInt->new(12345678890123456789);   # bad
3276         $x = Math::BigInt->new('12345678901234567890'); # good
3277
3278 You can include one underscore between any two digits.
3279
3280 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3281 Non-integer values result in NaN.
3282
3283 Hexadecimal (prefixed with "0x") and binary numbers (prefixed with "0b")
3284 are accepted, too. Please note that octal numbers are not recognized
3285 by new(), so the following will print "123":
3286
3287         perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'
3288         
3289 To convert an octal number, use from_oct();
3290
3291         perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'
3292
3293 Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('')
3294 results in 'NaN'. This might change in the future, so use always the following
3295 explicit forms to get a zero or NaN:
3296
3297         $zero = Math::BigInt->bzero(); 
3298         $nan = Math::BigInt->bnan(); 
3299
3300 C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers 
3301 are always stored in normalized form. If passed a string, creates a BigInt 
3302 object from the input.
3303
3304 =item Output
3305
3306 Output values are BigInt objects (normalized), except for the methods which
3307 return a string (see L<SYNOPSIS>).
3308
3309 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3310 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
3311 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
3312
3313 =back
3314
3315 =head1 METHODS
3316
3317 Each of the methods below (except config(), accuracy() and precision())
3318 accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
3319 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
3320 L<ACCURACY and PRECISION> for more information.
3321
3322 =head2 config()
3323
3324         use Data::Dumper;
3325
3326         print Dumper ( Math::BigInt->config() );
3327         print Math::BigInt->config()->{lib},"\n";
3328
3329 Returns a hash containing the configuration, e.g. the version number, lib
3330 loaded etc. The following hash keys are currently filled in with the
3331 appropriate information.
3332
3333         key             Description
3334                         Example
3335         ============================================================
3336         lib             Name of the low-level math library
3337                         Math::BigInt::Calc
3338         lib_version     Version of low-level math library (see 'lib')
3339                         0.30
3340         class           The class name of config() you just called
3341                         Math::BigInt
3342         upgrade         To which class math operations might be upgraded
3343                         Math::BigFloat
3344         downgrade       To which class math operations might be downgraded
3345                         undef
3346         precision       Global precision
3347                         undef
3348         accuracy        Global accuracy
3349                         undef
3350         round_mode      Global round mode
3351                         even
3352         version         version number of the class you used
3353                         1.61
3354         div_scale       Fallback accuracy for div
3355                         40
3356         trap_nan        If true, traps creation of NaN via croak()
3357                         1
3358         trap_inf        If true, traps creation of +inf/-inf via croak()
3359                         1
3360
3361 The following values can be set by passing C<config()> a reference to a hash:
3362
3363         trap_inf trap_nan
3364         upgrade downgrade precision accuracy round_mode div_scale
3365
3366 Example:
3367         
3368         $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );
3369
3370 =head2 accuracy()
3371
3372         $x->accuracy(5);                # local for $x
3373         CLASS->accuracy(5);             # global for all members of CLASS
3374                                         # Note: This also applies to new()!
3375
3376         $A = $x->accuracy();            # read out accuracy that affects $x
3377         $A = CLASS->accuracy();         # read out global accuracy
3378
3379 Set or get the global or local accuracy, aka how many significant digits the
3380 results have. If you set a global accuracy, then this also applies to new()!
3381
3382 Warning! The accuracy I<sticks>, e.g. once you created a number under the
3383 influence of C<< CLASS->accuracy($A) >>, all results from math operations with
3384 that number will also be rounded. 
3385
3386 In most cases, you should probably round the results explicitly using one of
3387 L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy
3388 to the math operation as additional parameter:
3389
3390         my $x = Math::BigInt->new(30000);
3391         my $y = Math::BigInt->new(7);
3392         print scalar $x->copy()->bdiv($y, 2);           # print 4300
3393         print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300
3394
3395 Please see the section about L<ACCURACY and PRECISION> for further details.
3396
3397 Value must be greater than zero. Pass an undef value to disable it:
3398
3399         $x->accuracy(undef);
3400         Math::BigInt->accuracy(undef);
3401
3402 Returns the current accuracy. For C<< $x->accuracy() >> it will return either
3403 the local accuracy, or if not defined, the global. This means the return value
3404 represents the accuracy that will be in effect for $x:
3405
3406         $y = Math::BigInt->new(1234567);        # unrounded
3407         print Math::BigInt->accuracy(4),"\n";   # set 4, print 4
3408         $x = Math::BigInt->new(123456);         # $x will be automatically rounded!
3409         print "$x $y\n";                        # '123500 1234567'
3410         print $x->accuracy(),"\n";              # will be 4
3411         print $y->accuracy(),"\n";              # also 4, since global is 4
3412         print Math::BigInt->accuracy(5),"\n";   # set to 5, print 5
3413         print $x->accuracy(),"\n";              # still 4
3414         print $y->accuracy(),"\n";              # 5, since global is 5
3415
3416 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3417 globals separated from Math::BigInt, but it is possible to subclass
3418 Math::BigInt and make the globals of the subclass aliases to the ones from
3419 Math::BigInt.
3420
3421 =head2 precision()
3422
3423         $x->precision(-2);      # local for $x, round at the second digit right of the dot
3424         $x->precision(2);       # ditto, round at the second digit left of the dot
3425
3426         CLASS->precision(5);    # Global for all members of CLASS
3427                                 # This also applies to new()!
3428         CLASS->precision(-5);   # ditto
3429
3430         $P = CLASS->precision();        # read out global precision 
3431         $P = $x->precision();           # read out precision that affects $x
3432
3433 Note: You probably want to use L<accuracy()> instead. With L<accuracy> you
3434 set the number of digits each result should have, with L<precision> you
3435 set the place where to round!
3436
3437 C<precision()> sets or gets the global or local precision, aka at which digit
3438 before or after the dot to round all results. A set global precision also
3439 applies to all newly created numbers!
3440
3441 In Math::BigInt, passing a negative number precision has no effect since no
3442 numbers have digits after the dot. In L<Math::BigFloat>, it will round all
3443 results to P digits after the dot.
3444
3445 Please see the section about L<ACCURACY and PRECISION> for further details.
3446
3447 Pass an undef value to disable it:
3448
3449         $x->precision(undef);
3450         Math::BigInt->precision(undef);
3451
3452 Returns the current precision. For C<< $x->precision() >> it will return either
3453 the local precision of $x, or if not defined, the global. This means the return
3454 value represents the prevision that will be in effect for $x:
3455
3456         $y = Math::BigInt->new(1234567);        # unrounded
3457         print Math::BigInt->precision(4),"\n";  # set 4, print 4
3458         $x = Math::BigInt->new(123456);         # will be automatically rounded
3459         print $x;                               # print "120000"!
3460
3461 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
3462 own globals separated from Math::BigInt, but it is possible to subclass
3463 Math::BigInt and make the globals of the subclass aliases to the ones from
3464 Math::BigInt.
3465
3466 =head2 brsft()
3467
3468         $x->brsft($y,$n);               
3469
3470 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3471 2, but others work, too.
3472
3473 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3474 result:
3475
3476
3477         $x = Math::BigInt->new(10);
3478         $x->brsft(1);                   # same as $x >> 1: 5
3479         $x = Math::BigInt->new(1234);
3480         $x->brsft(2,10);                # result 12
3481
3482 There is one exception, and that is base 2 with negative $x:
3483
3484
3485         $x = Math::BigInt->new(-5);
3486         print $x->brsft(1);
3487
3488 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3489 result).
3490
3491 =head2 new()
3492
3493         $x = Math::BigInt->new($str,$A,$P,$R);
3494
3495 Creates a new BigInt object from a scalar or another BigInt object. The
3496 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3497 '0b').
3498
3499 See L<Input> for more info on accepted input formats.
3500
3501 =head2 from_oct()
3502
3503         $x = Math::BigInt->from_oct("0775");    # input is octal
3504
3505 =head2 from_hex()
3506
3507         $x = Math::BigInt->from_hex("0xcafe");  # input is hexadecimal
3508
3509 =head2 from_bin()
3510
3511         $x = Math::BigInt->from_bin("0b10011"); # input is binary
3512
3513 =head2 bnan()
3514
3515         $x = Math::BigInt->bnan();
3516
3517 Creates a new BigInt object representing NaN (Not A Number).
3518 If used on an object, it will set it to NaN:
3519
3520         $x->bnan();
3521
3522 =head2 bzero()
3523
3524         $x = Math::BigInt->bzero();
3525
3526 Creates a new BigInt object representing zero.
3527 If used on an object, it will set it to zero:
3528
3529         $x->bzero();
3530
3531 =head2 binf()
3532
3533         $x = Math::BigInt->binf($sign);
3534
3535 Creates a new BigInt object representing infinity. The optional argument is
3536 either '-' or '+', indicating whether you want infinity or minus infinity.
3537 If used on an object, it will set it to infinity:
3538
3539         $x->binf();
3540         $x->binf('-');
3541
3542 =head2 bone()
3543
3544         $x = Math::BigInt->binf($sign);
3545
3546 Creates a new BigInt object representing one. The optional argument is
3547 either '-' or '+', indicating whether you want one or minus one.
3548 If used on an object, it will set it to one:
3549
3550         $x->bone();             # +1
3551         $x->bone('-');          # -1
3552
3553 =head2 is_one()/is_zero()/is_nan()/is_inf()
3554
3555   
3556         $x->is_zero();                  # true if arg is +0
3557         $x->is_nan();                   # true if arg is NaN
3558         $x->is_one();                   # true if arg is +1
3559         $x->is_one('-');                # true if arg is -1
3560         $x->is_inf();                   # true if +inf
3561         $x->is_inf('-');                # true if -inf (sign is default '+')
3562
3563 These methods all test the BigInt for being one specific value and return
3564 true or false depending on the input. These are faster than doing something
3565 like:
3566
3567         if ($x == 0)
3568
3569 =head2 is_pos()/is_neg()/is_positive()/is_negative()
3570         
3571         $x->is_pos();                   # true if > 0
3572         $x->is_neg();                   # true if < 0
3573
3574 The methods return true if the argument is positive or negative, respectively.
3575 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3576 C<-inf> is negative. A C<zero> is neither positive nor negative.
3577
3578 These methods are only testing the sign, and not the value.
3579
3580 C<is_positive()> and C<is_negative()> are aliases to C<is_pos()> and
3581 C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
3582 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
3583 in v1.68.
3584
3585 =head2 is_odd()/is_even()/is_int()
3586
3587         $x->is_odd();                   # true if odd, false for even
3588         $x->is_even();                  # true if even, false for odd
3589         $x->is_int();                   # true if $x is an integer
3590
3591 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3592 C<-inf> are not integers and are neither odd nor even.
3593
3594 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
3595
3596 =head2 bcmp()
3597
3598         $x->bcmp($y);
3599
3600 Compares $x with $y and takes the sign into account.
3601 Returns -1, 0, 1 or undef.
3602
3603 =head2 bacmp()
3604
3605         $x->bacmp($y);
3606
3607 Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or undef.
3608
3609 =head2 sign()
3610
3611         $x->sign();
3612
3613 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3614
3615 If you want $x to have a certain sign, use one of the following methods:
3616
3617         $x->babs();             # '+'
3618         $x->babs()->bneg();     # '-'
3619         $x->bnan();             # 'NaN'
3620         $x->binf();             # '+inf'
3621         $x->binf('-');          # '-inf'
3622
3623 =head2 digit()
3624
3625         $x->digit($n);          # return the nth digit, counting from right
3626
3627 If C<$n> is negative, returns the digit counting from left.
3628
3629 =head2 bneg()
3630
3631         $x->bneg();
3632
3633 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3634 and '-inf', respectively. Does nothing for NaN or zero.
3635
3636 =head2 babs()
3637
3638         $x->babs();
3639
3640 Set the number to its absolute value, e.g. change the sign from '-' to '+'
3641 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3642 numbers.
3643
3644 =head2 bnorm()
3645
3646         $x->bnorm();                    # normalize (no-op)
3647
3648 =head2 bnot()
3649
3650         $x->bnot();                     
3651
3652 Two's complement (bitwise not). This is equivalent to
3653
3654         $x->binc()->bneg();
3655
3656 but faster.
3657
3658 =head2 binc()
3659
3660         $x->binc();                     # increment x by 1
3661
3662 =head2 bdec()
3663
3664         $x->bdec();                     # decrement x by 1
3665
3666 =head2 badd()
3667
3668         $x->badd($y);                   # addition (add $y to $x)
3669
3670 =head2 bsub()
3671
3672         $x->bsub($y);                   # subtraction (subtract $y from $x)
3673
3674 =head2 bmul()
3675
3676         $x->bmul($y);                   # multiplication (multiply $x by $y)
3677
3678 =head2 bmuladd()
3679
3680         $x->bmuladd($y,$z);
3681
3682 Multiply $x by $y, and then add $z to the result,
3683
3684 This method was added in v1.87 of Math::BigInt (June 2007).
3685
3686 =head2 bdiv()
3687
3688         $x->bdiv($y);                   # divide, set $x to quotient
3689                                         # return (quo,rem) or quo if scalar
3690
3691 =head2 bmod()
3692
3693         $x->bmod($y);                   # modulus (x % y)
3694
3695 =head2 bmodinv()
3696
3697         num->bmodinv($mod);             # modular inverse
3698
3699 Returns the inverse of C<$num> in the given modulus C<$mod>.  'C<NaN>' is
3700 returned unless C<$num> is relatively prime to C<$mod>, i.e. unless
3701 C<bgcd($num, $mod)==1>.
3702
3703 =head2 bmodpow()
3704
3705         $num->bmodpow($exp,$mod);       # modular exponentation
3706                                         # ($num**$exp % $mod)
3707
3708 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3709 C<$mod> using binary exponentation.  C<bmodpow> is far superior to
3710 writing
3711
3712         $num ** $exp % $mod
3713
3714 because it is much faster - it reduces internal variables into
3715 the modulus whenever possible, so it operates on smaller numbers.
3716
3717 C<bmodpow> also supports negative exponents.
3718
3719         bmodpow($num, -1, $mod)
3720
3721 is exactly equivalent to
3722
3723         bmodinv($num, $mod)
3724
3725 =head2 bpow()
3726
3727         $x->bpow($y);                   # power of arguments (x ** y)
3728
3729 =head2 blog()
3730
3731         $x->blog($base, $accuracy);     # logarithm of x to the base $base
3732
3733 If C<$base> is not defined, Euler's number (e) is used:
3734
3735         print $x->blog(undef, 100);     # log(x) to 100 digits
3736
3737 =head2 bexp()
3738
3739         $x->bexp($accuracy);            # calculate e ** X
3740
3741 Calculates the expression C<e ** $x> where C<e> is Euler's number.
3742
3743 This method was added in v1.82 of Math::BigInt (April 2007).
3744
3745 See also L<blog()>.
3746
3747 =head2 bnok()
3748
3749         $x->bnok($y);              # x over y (binomial coefficient n over k)
3750
3751 Calculates the binomial coefficient n over k, also called the "choose"
3752 function. The result is equivalent to:
3753
3754         ( n )      n!
3755         | - |  = -------
3756         ( k )    k!(n-k)!
3757
3758 This method was added in v1.84 of Math::BigInt (April 2007).
3759
3760 =head2 bpi()
3761
3762         print Math::BigInt->bpi(100), "\n";             # 3
3763
3764 Returns PI truncated to an integer, with the argument being ignored. This means
3765 under BigInt this always returns C<3>.
3766
3767 If upgrading is in effect, returns PI, rounded to N digits with the
3768 current rounding mode:
3769
3770         use Math::BigFloat;
3771         use Math::BigInt upgrade => Math::BigFloat;
3772         print Math::BigInt->bpi(3), "\n";               # 3.14
3773         print Math::BigInt->bpi(100), "\n";             # 3.1415....
3774
3775 This method was added in v1.87 of Math::BigInt (June 2007).
3776
3777 =head2 bcos()
3778
3779         my $x = Math::BigInt->new(1);
3780         print $x->bcos(100), "\n";
3781
3782 Calculate the cosinus of $x, modifying $x in place.
3783
3784 In BigInt, unless upgrading is in effect, the result is truncated to an
3785 integer.
3786
3787 This method was added in v1.87 of Math::BigInt (June 2007).
3788
3789 =head2 bsin()
3790
3791         my $x = Math::BigInt->new(1);
3792         print $x->bsin(100), "\n";
3793
3794 Calculate the sinus of $x, modifying $x in place.
3795
3796 In BigInt, unless upgrading is in effect, the result is truncated to an
3797 integer.
3798
3799 This method was added in v1.87 of Math::BigInt (June 2007).
3800
3801 =head2 batan2()
3802
3803         my $x = Math::BigInt->new(1);
3804         my $y = Math::BigInt->new(1);
3805         print $y->batan2($x), "\n";
3806
3807 Calculate the arcus tangens of C<$y> divided by C<$x>, modifying $y in place.
3808
3809 In BigInt, unless upgrading is in effect, the result is truncated to an
3810 integer.
3811
3812 This method was added in v1.87 of Math::BigInt (June 2007).
3813
3814 =head2 batan()
3815
3816         my $x = Math::BigFloat->new(0.5);
3817         print $x->batan(100), "\n";
3818
3819 Calculate the arcus tangens of $x, modifying $x in place.
3820
3821 In BigInt, unless upgrading is in effect, the result is truncated to an
3822 integer.
3823
3824 This method was added in v1.87 of Math::BigInt (June 2007).
3825
3826 =head2 blsft()
3827
3828         $x->blsft($y);          # left shift in base 2
3829         $x->blsft($y,$n);       # left shift, in base $n (like 10)
3830
3831 =head2 brsft()
3832
3833         $x->brsft($y);          # right shift in base 2
3834         $x->brsft($y,$n);       # right shift, in base $n (like 10)
3835
3836 =head2 band()
3837
3838         $x->band($y);                   # bitwise and
3839
3840 =head2 bior()
3841
3842         $x->bior($y);                   # bitwise inclusive or
3843
3844 =head2 bxor()
3845
3846         $x->bxor($y);                   # bitwise exclusive or
3847
3848 =head2 bnot()
3849
3850         $x->bnot();                     # bitwise not (two's complement)
3851
3852 =head2 bsqrt()
3853
3854         $x->bsqrt();                    # calculate square-root
3855
3856 =head2 broot()
3857
3858         $x->broot($N);
3859
3860 Calculates the N'th root of C<$x>.
3861
3862 =head2 bfac()
3863
3864         $x->bfac();                     # factorial of $x (1*2*3*4*..$x)
3865
3866 =head2 round()
3867
3868         $x->round($A,$P,$round_mode);
3869         
3870 Round $x to accuracy C<$A> or precision C<$P> using the round mode
3871 C<$round_mode>.
3872
3873 =head2 bround()
3874
3875         $x->bround($N);               # accuracy: preserve $N digits
3876
3877 =head2 bfround()
3878
3879         $x->bfround($N);
3880
3881 If N is > 0, rounds to the Nth digit from the left. If N < 0, rounds to
3882 the Nth digit after the dot. Since BigInts are integers, the case N < 0
3883 is a no-op for them.
3884
3885 Examples:
3886
3887         Input           N               Result
3888         ===================================================
3889         123456.123456   3               123500
3890         123456.123456   2               123450
3891         123456.123456   -2              123456.12
3892         123456.123456   -3              123456.123
3893
3894 =head2 bfloor()
3895
3896         $x->bfloor();                   
3897
3898 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
3899 does change $x in BigFloat.
3900
3901 =head2 bceil()
3902
3903         $x->bceil();
3904
3905 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
3906 does change $x in BigFloat.
3907
3908 =head2 bgcd()
3909
3910         bgcd(@values);          # greatest common divisor (no OO style)
3911
3912 =head2 blcm()
3913
3914         blcm(@values);          # lowest common multiple (no OO style)
3915
3916 head2 length()
3917
3918         $x->length();
3919         ($xl,$fl) = $x->length();
3920
3921 Returns the number of digits in the decimal representation of the number.
3922 In list context, returns the length of the integer and fraction part. For
3923 BigInt's, the length of the fraction part will always be 0.
3924
3925 =head2 exponent()
3926
3927         $x->exponent();
3928
3929 Return the exponent of $x as BigInt.
3930
3931 =head2 mantissa()
3932
3933         $x->mantissa();
3934
3935 Return the signed mantissa of $x as BigInt.
3936
3937 =head2 parts()
3938
3939         $x->parts();            # return (mantissa,exponent) as BigInt
3940
3941 =head2 copy()
3942
3943         $x->copy();             # make a true copy of $x (unlike $y = $x;)
3944
3945 =head2 as_int()/as_number()
3946
3947         $x->as_int();   
3948
3949 Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as
3950 C<copy()>. 
3951
3952 C<as_number()> is an alias to this method. C<as_number> was introduced in
3953 v1.22, while C<as_int()> was only introduced in v1.68.
3954   
3955 =head2 bstr()
3956
3957         $x->bstr();
3958
3959 Returns a normalized string representation of C<$x>.
3960
3961 =head2 bsstr()
3962
3963         $x->bsstr();            # normalized string in scientific notation
3964
3965 =head2 as_hex()
3966
3967         $x->as_hex();           # as signed hexadecimal string with prefixed 0x
3968
3969 =head2 as_bin()
3970
3971         $x->as_bin();           # as signed binary string with prefixed 0b
3972
3973 =head2 as_oct()
3974
3975         $x->as_oct();           # as signed octal string with prefixed 0
3976
3977 =head2 numify()
3978
3979         print $x->numify();
3980
3981 This returns a normal Perl scalar from $x. It is used automatically
3982 whenever a scalar is needed, for instance in array index operations.
3983
3984 This loses precision, to avoid this use L<as_int()> instead.
3985
3986 =head2 modify()
3987
3988         $x->modify('bpowd');
3989
3990 This method returns 0 if the object can be modified with the given
3991 operation, or 1 if not.
3992
3993 This is used for instance by L<Math::BigInt::Constant>.
3994
3995 =head2 upgrade()/downgrade()
3996
3997 Set/get the class for downgrade/upgrade operations. Thuis is used
3998 for instance by L<bignum>. The defaults are '', thus the following
3999 operation will create a BigInt, not a BigFloat:
4000
4001         my $i = Math::BigInt->new(123);
4002         my $f = Math::BigFloat->new('123.1');
4003
4004         print $i + $f,"\n";                     # print 246
4005
4006 =head2 div_scale()
4007
4008 Set/get the number of digits for the default precision in divide
4009 operations.
4010
4011 =head2 round_mode()
4012
4013 Set/get the current round mode.
4014
4015 =head1 ACCURACY and PRECISION
4016
4017 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
4018 accuracy and precision based rounding, both automatically after every
4019 operation, as well as manually.
4020
4021 This section describes the accuracy/precision handling in Math::Big* as it
4022 used to be and as it is now, complete with an explanation of all terms and
4023 abbreviations.
4024
4025 Not yet implemented things (but with correct description) are marked with '!',
4026 things that need to be answered are marked with '?'.
4027
4028 In the next paragraph follows a short description of terms used here (because
4029 these may differ from terms used by others people or documentation).
4030
4031 During the rest of this document, the shortcuts A (for accuracy), P (for
4032 precision), F (fallback) and R (rounding mode) will be used.
4033
4034 =head2 Precision P
4035
4036 A fixed number of digits before (positive) or after (negative)
4037 the decimal point. For example, 123.45 has a precision of -2. 0 means an
4038 integer like 123 (or 120). A precision of 2 means two digits to the left
4039 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
4040 numbers with zeros before the decimal point may have different precisions,
4041 because 1200 can have p = 0, 1 or 2 (depending on what the inital value
4042 was). It could also have p < 0, when the digits after the decimal point
4043 are zero.
4044
4045 The string output (of floating point numbers) will be padded with zeros:
4046  
4047         Initial value   P       A       Result          String
4048         ------------------------------------------------------------
4049         1234.01         -3              1000            1000
4050         1234            -2              1200            1200
4051         1234.5          -1              1230            1230
4052         1234.001        1               1234            1234.0
4053         1234.01         0               1234            1234
4054         1234.01         2               1234.01         1234.01
4055         1234.01         5               1234.01         1234.01000
4056
4057 For BigInts, no padding occurs.
4058
4059 =head2 Accuracy A
4060
4061 Number of significant digits. Leading zeros are not counted. A
4062 number may have an accuracy greater than the non-zero digits
4063 when there are zeros in it or trailing zeros. For example, 123.456 has
4064 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
4065
4066 The string output (of floating point numbers) will be padded with zeros:
4067
4068         Initial value   P       A       Result          String
4069         ------------------------------------------------------------
4070         1234.01                 3       1230            1230
4071         1234.01                 6       1234.01         1234.01
4072         1234.1                  8       1234.1          1234.1000
4073
4074 For BigInts, no padding occurs.
4075
4076 =head2 Fallback F
4077
4078 When both A and P are undefined, this is used as a fallback accuracy when
4079 dividing numbers.
4080
4081 =head2 Rounding mode R
4082
4083 When rounding a number, different 'styles' or 'kinds'
4084 of rounding are possible. (Note that random rounding, as in
4085 Math::Round, is not implemented.)
4086
4087 =over 2
4088
4089 =item 'trunc'
4090
4091 truncation invariably removes all digits following the
4092 rounding place, replacing them with zeros. Thus, 987.65 rounded
4093 to tens (P=1) becomes 980, and rounded to the fourth sigdig
4094 becomes 987.6 (A=4). 123.456 rounded to the second place after the
4095 decimal point (P=-2) becomes 123.46.
4096
4097 All other implemented styles of rounding attempt to round to the
4098 "nearest digit." If the digit D immediately to the right of the
4099 rounding place (skipping the decimal point) is greater than 5, the
4100 number is incremented at the rounding place (possibly causing a
4101 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
4102 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
4103 truncated at the rounding place: e.g. when rounding to units, 0.4
4104 rounds to 0, and -19.4 rounds to -19.
4105
4106 However the results of other styles of rounding differ if the
4107 digit immediately to the right of the rounding place (skipping the
4108 decimal point) is 5 and if there are no digits, or no digits other
4109 than 0, after that 5. In such cases:
4110
4111 =item 'even'
4112
4113 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
4114 if it is not already. E.g., when rounding to the first sigdig, 0.45
4115 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
4116
4117 =item 'odd'
4118
4119 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
4120 it is not already. E.g., when rounding to the first sigdig, 0.45
4121 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
4122
4123 =item '+inf'
4124
4125 round to plus infinity, i.e. always round up. E.g., when
4126 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
4127 and 0.4501 also becomes 0.5.
4128
4129 =item '-inf'
4130
4131 round to minus infinity, i.e. always round down. E.g., when
4132 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
4133 but 0.4501 becomes 0.5.
4134
4135 =item 'zero'
4136
4137 round to zero, i.e. positive numbers down, negative ones up.
4138 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
4139 becomes -0.5, but 0.4501 becomes 0.5.
4140
4141 =item 'common'
4142
4143 round up if the digit immediately to the right of the rounding place
4144 is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
4145 0.149 becomes 0.1.
4146
4147 =back
4148
4149 The handling of A & P in MBI/MBF (the old core code shipped with Perl
4150 versions <= 5.7.2) is like this:
4151
4152 =over 2
4153
4154 =item Precision
4155
4156   * ffround($p) is able to round to $p number of digits after the decimal
4157     point
4158   * otherwise P is unused
4159
4160 =item Accuracy (significant digits)
4161
4162   * fround($a) rounds to $a significant digits
4163   * only fdiv() and fsqrt() take A as (optional) parameter
4164     + other operations simply create the same number (fneg etc), or more (fmul)
4165       of digits
4166     + rounding/truncating is only done when explicitly calling one of fround
4167       or ffround, and never for BigInt (not implemented)
4168   * fsqrt() simply hands its accuracy argument over to fdiv.
4169   * the documentation and the comment in the code indicate two different ways
4170     on how fdiv() determines the maximum number of digits it should calculate,
4171     and the actual code does yet another thing
4172     POD:
4173       max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
4174     Comment:
4175       result has at most max(scale, length(dividend), length(divisor)) digits
4176     Actual code:
4177       scale = max(scale, length(dividend)-1,length(divisor)-1);
4178       scale += length(divisor) - length(dividend);
4179     So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
4180     Actually, the 'difference' added to the scale is calculated from the
4181     number of "significant digits" in dividend and divisor, which is derived
4182     by looking at the length of the mantissa. Which is wrong, since it includes
4183     the + sign (oops) and actually gets 2 for '+100' and 4 for '+101'. Oops
4184     again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
4185     assumption that 124 has 3 significant digits, while 120/7 will get you
4186     '17', not '17.1' since 120 is thought to have 2 significant digits.
4187     The rounding after the division then uses the remainder and $y to determine
4188     wether it must round up or down.
4189  ?  I have no idea which is the right way. That's why I used a slightly more
4190  ?  simple scheme and tweaked the few failing testcases to match it.
4191
4192 =back
4193
4194 This is how it works now:
4195
4196 =over 2
4197
4198 =item Setting/Accessing
4199
4200   * You can set the A global via C<< Math::BigInt->accuracy() >> or
4201     C<< Math::BigFloat->accuracy() >> or whatever class you are using.
4202   * You can also set P globally by using C<< Math::SomeClass->precision() >>
4203     likewise.
4204   * Globals are classwide, and not inherited by subclasses.
4205   * to undefine A, use C<< Math::SomeCLass->accuracy(undef); >>
4206   * to undefine P, use C<< Math::SomeClass->precision(undef); >>
4207   * Setting C<< Math::SomeClass->accuracy() >> clears automatically
4208     C<< Math::SomeClass->precision() >>, and vice versa.
4209   * To be valid, A must be > 0, P can have any value.
4210   * If P is negative, this means round to the P'th place to the right of the
4211     decimal point; positive values mean to the left of the decimal point.
4212     P of 0 means round to integer.
4213   * to find out the current global A, use C<< Math::SomeClass->accuracy() >>
4214   * to find out the current global P, use C<< Math::SomeClass->precision() >>
4215   * use C<< $x->accuracy() >> respective C<< $x->precision() >> for the local
4216     setting of C<< $x >>.
4217   * Please note that C<< $x->accuracy() >> respective C<< $x->precision() >>
4218     return eventually defined global A or P, when C<< $x >>'s A or P is not
4219     set.
4220
4221 =item Creating numbers
4222
4223   * When you create a number, you can give the desired A or P via:
4224     $x = Math::BigInt->new($number,$A,$P);
4225   * Only one of A or P can be defined, otherwise the result is NaN
4226   * If no A or P is give ($x = Math::BigInt->new($number) form), then the
4227     globals (if set) will be used. Thus changing the global defaults later on
4228     will not change the A or P of previously created numbers (i.e., A and P of
4229     $x will be what was in effect when $x was created)
4230   * If given undef for A and P, B<no> rounding will occur, and the globals will
4231     B<not> be used. This is used by subclasses to create numbers without
4232     suffering rounding in the parent. Thus a subclass is able to have its own
4233     globals enforced upon creation of a number by using
4234     C<< $x = Math::BigInt->new($number,undef,undef) >>:
4235
4236         use Math::BigInt::SomeSubclass;
4237         use Math::BigInt;
4238
4239         Math::BigInt->accuracy(2);
4240         Math::BigInt::SomeSubClass->accuracy(3);
4241         $x = Math::BigInt::SomeSubClass->new(1234);     
4242
4243     $x is now 1230, and not 1200. A subclass might choose to implement
4244     this otherwise, e.g. falling back to the parent's A and P.
4245
4246 =item Usage
4247
4248   * If A or P are enabled/defined, they are used to round the result of each
4249     operation according to the rules below
4250   * Negative P is ignored in Math::BigInt, since BigInts never have digits
4251     after the decimal point
4252   * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
4253     Math::BigInt as globals does not tamper with the parts of a BigFloat.
4254     A flag is used to mark all Math::BigFloat numbers as 'never round'.
4255
4256 =item Precedence
4257
4258   * It only makes sense that a number has only one of A or P at a time.
4259     If you set either A or P on one object, or globally, the other one will
4260     be automatically cleared.
4261   * If two objects are involved in an operation, and one of them has A in
4262     effect, and the other P, this results in an error (NaN).
4263   * A takes precedence over P (Hint: A comes before P).
4264     If neither of them is defined, nothing is used, i.e. the result will have
4265     as many digits as it can (with an exception for fdiv/fsqrt) and will not
4266     be rounded.
4267   * There is another setting for fdiv() (and thus for fsqrt()). If neither of
4268     A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
4269     If either the dividend's or the divisor's mantissa has more digits than
4270     the value of F, the higher value will be used instead of F.
4271     This is to limit the digits (A) of the result (just consider what would
4272     happen with unlimited A and P in the case of 1/3 :-)
4273   * fdiv will calculate (at least) 4 more digits than required (determined by
4274     A, P or F), and, if F is not used, round the result
4275     (this will still fail in the case of a result like 0.12345000000001 with A
4276     or P of 5, but this can not be helped - or can it?)
4277   * Thus you can have the math done by on Math::Big* class in two modi:
4278     + never round (this is the default):
4279       This is done by setting A and P to undef. No math operation
4280       will round the result, with fdiv() and fsqrt() as exceptions to guard
4281       against overflows. You must explicitly call bround(), bfround() or
4282       round() (the latter with parameters).
4283       Note: Once you have rounded a number, the settings will 'stick' on it
4284       and 'infect' all other numbers engaged in math operations with it, since
4285       local settings have the highest precedence. So, to get SaferRound[tm],
4286       use a copy() before rounding like this:
4287
4288         $x = Math::BigFloat->new(12.34);
4289         $y = Math::BigFloat->new(98.76);
4290         $z = $x * $y;                           # 1218.6984
4291         print $x->copy()->fround(3);            # 12.3 (but A is now 3!)
4292         $z = $x * $y;                           # still 1218.6984, without
4293                                                 # copy would have been 1210!
4294
4295     + round after each op:
4296       After each single operation (except for testing like is_zero()), the
4297       method round() is called and the result is rounded appropriately. By
4298       setting proper values for A and P, you can have all-the-same-A or
4299       all-the-same-P modes. For example, Math::Currency might set A to undef,
4300       and P to -2, globally.
4301
4302  ?Maybe an extra option that forbids local A & P settings would be in order,
4303  ?so that intermediate rounding does not 'poison' further math? 
4304
4305 =item Overriding globals
4306
4307   * you will be able to give A, P and R as an argument to all the calculation
4308     routines; the second parameter is A, the third one is P, and the fourth is
4309     R (shift right by one for binary operations like badd). P is used only if
4310     the first parameter (A) is undefined. These three parameters override the
4311     globals in the order detailed as follows, i.e. the first defined value
4312     wins:
4313     (local: per object, global: global default, parameter: argument to sub)
4314       + parameter A
4315       + parameter P
4316       + local A (if defined on both of the operands: smaller one is taken)
4317       + local P (if defined on both of the operands: bigger one is taken)
4318       + global A
4319       + global P
4320       + global F
4321   * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
4322     arguments (A and P) instead of one
4323
4324 =item Local settings
4325
4326   * You can set A or P locally by using C<< $x->accuracy() >> or
4327     C<< $x->precision() >>
4328     and thus force different A and P for different objects/numbers.
4329   * Setting A or P this way immediately rounds $x to the new value.
4330   * C<< $x->accuracy() >> clears C<< $x->precision() >>, and vice versa.
4331
4332 =item Rounding
4333
4334   * the rounding routines will use the respective global or local settings.
4335     fround()/bround() is for accuracy rounding, while ffround()/bfround()
4336     is for precision
4337   * the two rounding functions take as the second parameter one of the
4338     following rounding modes (R):
4339     'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
4340   * you can set/get the global R by using C<< Math::SomeClass->round_mode() >>
4341     or by setting C<< $Math::SomeClass::round_mode >>
4342   * after each operation, C<< $result->round() >> is called, and the result may
4343     eventually be rounded (that is, if A or P were set either locally,
4344     globally or as parameter to the operation)
4345   * to manually round a number, call C<< $x->round($A,$P,$round_mode); >>
4346     this will round the number by using the appropriate rounding function
4347     and then normalize it.
4348   * rounding modifies the local settings of the number:
4349
4350         $x = Math::BigFloat->new(123.456);
4351         $x->accuracy(5);
4352         $x->bround(4);
4353
4354     Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
4355     will be 4 from now on.
4356
4357