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