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 # trigonometric functions
2835
2836 sub bpi
2837   {
2838   # Calculate PI to N digits. Unless upgrading is in effect, returns the
2839   # result truncated to an integer, that is, always returns '3'.
2840   my ($self,$n) = @_;
2841   if (@_ == 1)
2842     {
2843     # called like Math::BigInt::bpi(10);
2844     $n = $self; $self = $class;
2845     }
2846   $self = ref($self) if ref($self);
2847
2848   return $upgrade->new($n) if defined $upgrade;
2849
2850   # hard-wired to "3"
2851   $self->new(3);
2852   }
2853
2854 ###############################################################################
2855 # this method returns 0 if the object can be modified, or 1 if not.
2856 # We use a fast constant sub() here, to avoid costly calls. Subclasses
2857 # may override it with special code (f.i. Math::BigInt::Constant does so)
2858
2859 sub modify () { 0; }
2860
2861 1;
2862 __END__
2863
2864 =pod
2865
2866 =head1 NAME
2867
2868 Math::BigInt - Arbitrary size integer/float math package
2869
2870 =head1 SYNOPSIS
2871
2872   use Math::BigInt;
2873
2874   # or make it faster: install (optional) Math::BigInt::GMP
2875   # and always use (it will fall back to pure Perl if the
2876   # GMP library is not installed):
2877
2878   # will warn if Math::BigInt::GMP cannot be found
2879   use Math::BigInt lib => 'GMP';
2880
2881   # to supress the warning use this:
2882   # use Math::BigInt try => 'GMP';
2883
2884   my $str = '1234567890';
2885   my @values = (64,74,18);
2886   my $n = 1; my $sign = '-';
2887
2888   # Number creation
2889   my $x = Math::BigInt->new($str);      # defaults to 0
2890   my $y = $x->copy();                   # make a true copy
2891   my $nan  = Math::BigInt->bnan();      # create a NotANumber
2892   my $zero = Math::BigInt->bzero();     # create a +0
2893   my $inf = Math::BigInt->binf();       # create a +inf
2894   my $inf = Math::BigInt->binf('-');    # create a -inf
2895   my $one = Math::BigInt->bone();       # create a +1
2896   my $mone = Math::BigInt->bone('-');   # create a -1
2897
2898   my $pi = Math::BigInt->bpi();         # returns '3'
2899                                         # see Math::BigFloat::bpi()
2900
2901   $h = Math::BigInt->new('0x123');      # from hexadecimal
2902   $b = Math::BigInt->new('0b101');      # from binary
2903   $o = Math::BigInt->from_oct('0101');  # from octal
2904
2905   # Testing (don't modify their arguments)
2906   # (return true if the condition is met, otherwise false)
2907
2908   $x->is_zero();        # if $x is +0
2909   $x->is_nan();         # if $x is NaN
2910   $x->is_one();         # if $x is +1
2911   $x->is_one('-');      # if $x is -1
2912   $x->is_odd();         # if $x is odd
2913   $x->is_even();        # if $x is even
2914   $x->is_pos();         # if $x >= 0
2915   $x->is_neg();         # if $x <  0
2916   $x->is_inf($sign);    # if $x is +inf, or -inf (sign is default '+')
2917   $x->is_int();         # if $x is an integer (not a float)
2918
2919   # comparing and digit/sign extraction
2920   $x->bcmp($y);         # compare numbers (undef,<0,=0,>0)
2921   $x->bacmp($y);        # compare absolutely (undef,<0,=0,>0)
2922   $x->sign();           # return the sign, either +,- or NaN
2923   $x->digit($n);        # return the nth digit, counting from right
2924   $x->digit(-$n);       # return the nth digit, counting from left
2925
2926   # The following all modify their first argument. If you want to preserve
2927   # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
2928   # necessary when mixing $a = $b assignments with non-overloaded math.
2929
2930   $x->bzero();          # set $x to 0
2931   $x->bnan();           # set $x to NaN
2932   $x->bone();           # set $x to +1
2933   $x->bone('-');        # set $x to -1
2934   $x->binf();           # set $x to inf
2935   $x->binf('-');        # set $x to -inf
2936
2937   $x->bneg();           # negation
2938   $x->babs();           # absolute value
2939   $x->bnorm();          # normalize (no-op in BigInt)
2940   $x->bnot();           # two's complement (bit wise not)
2941   $x->binc();           # increment $x by 1
2942   $x->bdec();           # decrement $x by 1
2943
2944   $x->badd($y);         # addition (add $y to $x)
2945   $x->bsub($y);         # subtraction (subtract $y from $x)
2946   $x->bmul($y);         # multiplication (multiply $x by $y)
2947   $x->bdiv($y);         # divide, set $x to quotient
2948                         # return (quo,rem) or quo if scalar
2949
2950   $x->bmod($y);            # modulus (x % y)
2951   $x->bmodpow($exp,$mod);  # modular exponentation (($num**$exp) % $mod))
2952   $x->bmodinv($mod);       # the inverse of $x in the given modulus $mod
2953
2954   $x->bpow($y);            # power of arguments (x ** y)
2955   $x->blsft($y);           # left shift in base 2
2956   $x->brsft($y);           # right shift in base 2
2957                            # returns (quo,rem) or quo if in scalar context
2958   $x->blsft($y,$n);        # left shift by $y places in base $n
2959   $x->brsft($y,$n);        # right shift by $y places in base $n
2960                            # returns (quo,rem) or quo if in scalar context
2961
2962   $x->band($y);            # bitwise and
2963   $x->bior($y);            # bitwise inclusive or
2964   $x->bxor($y);            # bitwise exclusive or
2965   $x->bnot();              # bitwise not (two's complement)
2966
2967   $x->bsqrt();             # calculate square-root
2968   $x->broot($y);           # $y'th root of $x (e.g. $y == 3 => cubic root)
2969   $x->bfac();              # factorial of $x (1*2*3*4*..$x)
2970
2971   $x->bnok($y);            # x over y (binomial coefficient n over k)
2972
2973   $x->blog();              # logarithm of $x to base e (Euler's number)
2974   $x->blog($base);         # logarithm of $x to base $base (f.i. 2)
2975   $x->bexp();              # calculate e ** $x where e is Euler's number
2976
2977   $x->round($A,$P,$mode);  # round to accuracy or precision using mode $mode
2978   $x->bround($n);          # accuracy: preserve $n digits
2979   $x->bfround($n);         # round to $nth digit, no-op for BigInts
2980
2981   # The following do not modify their arguments in BigInt (are no-ops),
2982   # but do so in BigFloat:
2983
2984   $x->bfloor();            # return integer less or equal than $x
2985   $x->bceil();             # return integer greater or equal than $x
2986
2987   # The following do not modify their arguments:
2988
2989   # greatest common divisor (no OO style)
2990   my $gcd = Math::BigInt::bgcd(@values);
2991   # lowest common multiplicator (no OO style)
2992   my $lcm = Math::BigInt::blcm(@values);
2993
2994   $x->length();            # return number of digits in number
2995   ($xl,$f) = $x->length(); # length of number and length of fraction part,
2996                            # latter is always 0 digits long for BigInts
2997
2998   $x->exponent();          # return exponent as BigInt
2999   $x->mantissa();          # return (signed) mantissa as BigInt
3000   $x->parts();             # return (mantissa,exponent) as BigInt
3001   $x->copy();              # make a true copy of $x (unlike $y = $x;)
3002   $x->as_int();            # return as BigInt (in BigInt: same as copy())
3003   $x->numify();            # return as scalar (might overflow!)
3004
3005   # conversation to string (do not modify their argument)
3006   $x->bstr();              # normalized string (e.g. '3')
3007   $x->bsstr();             # norm. string in scientific notation (e.g. '3E0')
3008   $x->as_hex();            # as signed hexadecimal string with prefixed 0x
3009   $x->as_bin();            # as signed binary string with prefixed 0b
3010   $x->as_oct();            # as signed octal string with prefixed 0
3011
3012
3013   # precision and accuracy (see section about rounding for more)
3014   $x->precision();         # return P of $x (or global, if P of $x undef)
3015   $x->precision($n);       # set P of $x to $n
3016   $x->accuracy();          # return A of $x (or global, if A of $x undef)
3017   $x->accuracy($n);        # set A $x to $n
3018
3019   # Global methods
3020   Math::BigInt->precision();    # get/set global P for all BigInt objects
3021   Math::BigInt->accuracy();     # get/set global A for all BigInt objects
3022   Math::BigInt->round_mode();   # get/set global round mode, one of
3023                                 # 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
3024   Math::BigInt->config();       # return hash containing configuration
3025
3026 =head1 DESCRIPTION
3027
3028 All operators (including basic math operations) are overloaded if you
3029 declare your big integers as
3030
3031   $i = new Math::BigInt '123_456_789_123_456_789';
3032
3033 Operations with overloaded operators preserve the arguments which is
3034 exactly what you expect.
3035
3036 =over 2
3037
3038 =item Input
3039
3040 Input values to these routines may be any string, that looks like a number
3041 and results in an integer, including hexadecimal and binary numbers.
3042
3043 Scalars holding numbers may also be passed, but note that non-integer numbers
3044 may already have lost precision due to the conversation to float. Quote
3045 your input if you want BigInt to see all the digits:
3046
3047         $x = Math::BigInt->new(12345678890123456789);   # bad
3048         $x = Math::BigInt->new('12345678901234567890'); # good
3049
3050 You can include one underscore between any two digits.
3051
3052 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3053 Non-integer values result in NaN.
3054
3055 Hexadecimal (prefixed with "0x") and binary numbers (prefixed with "0b")
3056 are accepted, too. Please note that octal numbers are not recognized
3057 by new(), so the following will print "123":
3058
3059         perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'
3060
3061 To convert an octal number, use from_oct();
3062
3063         perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'
3064
3065 Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('')
3066 results in 'NaN'. This might change in the future, so use always the following
3067 explicit forms to get a zero or NaN:
3068
3069         $zero = Math::BigInt->bzero();
3070         $nan = Math::BigInt->bnan();
3071
3072 C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers
3073 are always stored in normalized form. If passed a string, creates a BigInt
3074 object from the input.
3075
3076 =item Output
3077
3078 Output values are BigInt objects (normalized), except for the methods which
3079 return a string (see L<SYNOPSIS>).
3080
3081 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3082 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
3083 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
3084
3085 =back
3086
3087 =head1 METHODS
3088
3089 Each of the methods below (except config(), accuracy() and precision())
3090 accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
3091 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
3092 L<ACCURACY and PRECISION> for more information.
3093
3094 =head2 config()
3095
3096         use Data::Dumper;
3097
3098         print Dumper ( Math::BigInt->config() );
3099         print Math::BigInt->config()->{lib},"\n";
3100
3101 Returns a hash containing the configuration, e.g. the version number, lib
3102 loaded etc. The following hash keys are currently filled in with the
3103 appropriate information.
3104
3105         key             Description
3106                         Example
3107         ============================================================
3108         lib             Name of the low-level math library
3109                         Math::BigInt::Calc
3110         lib_version     Version of low-level math library (see 'lib')
3111                         0.30
3112         class           The class name of config() you just called
3113                         Math::BigInt
3114         upgrade         To which class math operations might be upgraded
3115                         Math::BigFloat
3116         downgrade       To which class math operations might be downgraded
3117                         undef
3118         precision       Global precision
3119                         undef
3120         accuracy        Global accuracy
3121                         undef
3122         round_mode      Global round mode
3123                         even
3124         version         version number of the class you used
3125                         1.61
3126         div_scale       Fallback accuracy for div
3127                         40
3128         trap_nan        If true, traps creation of NaN via croak()
3129                         1
3130         trap_inf        If true, traps creation of +inf/-inf via croak()
3131                         1
3132
3133 The following values can be set by passing C<config()> a reference to a hash:
3134
3135         trap_inf trap_nan
3136         upgrade downgrade precision accuracy round_mode div_scale
3137
3138 Example:
3139
3140         $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );
3141
3142 =head2 accuracy()
3143
3144         $x->accuracy(5);                # local for $x
3145         CLASS->accuracy(5);             # global for all members of CLASS
3146                                         # Note: This also applies to new()!
3147
3148         $A = $x->accuracy();            # read out accuracy that affects $x
3149         $A = CLASS->accuracy();         # read out global accuracy
3150
3151 Set or get the global or local accuracy, aka how many significant digits the
3152 results have. If you set a global accuracy, then this also applies to new()!
3153
3154 Warning! The accuracy I<sticks>, e.g. once you created a number under the
3155 influence of C<< CLASS->accuracy($A) >>, all results from math operations with
3156 that number will also be rounded.
3157
3158 In most cases, you should probably round the results explicitly using one of
3159 L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy
3160 to the math operation as additional parameter:
3161
3162         my $x = Math::BigInt->new(30000);
3163         my $y = Math::BigInt->new(7);
3164         print scalar $x->copy()->bdiv($y, 2);           # print 4300
3165         print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300
3166
3167 Please see the section about L<ACCURACY AND PRECISION> for further details.
3168
3169 Value must be greater than zero. Pass an undef value to disable it:
3170
3171         $x->accuracy(undef);
3172         Math::BigInt->accuracy(undef);
3173
3174 Returns the current accuracy. For C<$x->accuracy()> it will return either the
3175 local accuracy, or if not defined, the global. This means the return value
3176 represents the accuracy that will be in effect for $x:
3177
3178         $y = Math::BigInt->new(1234567);        # unrounded
3179         print Math::BigInt->accuracy(4),"\n";   # set 4, print 4
3180         $x = Math::BigInt->new(123456);         # $x will be automatically rounded!
3181         print "$x $y\n";                        # '123500 1234567'
3182         print $x->accuracy(),"\n";              # will be 4
3183         print $y->accuracy(),"\n";              # also 4, since global is 4
3184         print Math::BigInt->accuracy(5),"\n";   # set to 5, print 5
3185         print $x->accuracy(),"\n";              # still 4
3186         print $y->accuracy(),"\n";              # 5, since global is 5
3187
3188 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3189 globals separated from Math::BigInt, but it is possible to subclass
3190 Math::BigInt and make the globals of the subclass aliases to the ones from
3191 Math::BigInt.
3192
3193 =head2 precision()
3194
3195         $x->precision(-2);      # local for $x, round at the second digit right of the dot
3196         $x->precision(2);       # ditto, round at the second digit left of the dot
3197
3198         CLASS->precision(5);    # Global for all members of CLASS
3199                                 # This also applies to new()!
3200         CLASS->precision(-5);   # ditto
3201
3202         $P = CLASS->precision();        # read out global precision
3203         $P = $x->precision();           # read out precision that affects $x
3204
3205 Note: You probably want to use L<accuracy()> instead. With L<accuracy> you
3206 set the number of digits each result should have, with L<precision> you
3207 set the place where to round!
3208
3209 C<precision()> sets or gets the global or local precision, aka at which digit
3210 before or after the dot to round all results. A set global precision also
3211 applies to all newly created numbers!
3212
3213 In Math::BigInt, passing a negative number precision has no effect since no
3214 numbers have digits after the dot. In L<Math::BigFloat>, it will round all
3215 results to P digits after the dot.
3216
3217 Please see the section about L<ACCURACY AND PRECISION> for further details.
3218
3219 Pass an undef value to disable it:
3220
3221         $x->precision(undef);
3222         Math::BigInt->precision(undef);
3223
3224 Returns the current precision. For C<$x->precision()> it will return either the
3225 local precision of $x, or if not defined, the global. This means the return
3226 value represents the prevision that will be in effect for $x:
3227
3228         $y = Math::BigInt->new(1234567);        # unrounded
3229         print Math::BigInt->precision(4),"\n";  # set 4, print 4
3230         $x = Math::BigInt->new(123456);         # will be automatically rounded
3231         print $x;                               # print "120000"!
3232
3233 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
3234 own globals separated from Math::BigInt, but it is possible to subclass
3235 Math::BigInt and make the globals of the subclass aliases to the ones from
3236 Math::BigInt.
3237
3238 =head2 brsft()
3239
3240         $x->brsft($y,$n);
3241
3242 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3243 2, but others work, too.
3244
3245 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3246 result:
3247
3248
3249         $x = Math::BigInt->new(10);
3250         $x->brsft(1);                   # same as $x >> 1: 5
3251         $x = Math::BigInt->new(1234);
3252         $x->brsft(2,10);                # result 12
3253
3254 There is one exception, and that is base 2 with negative $x:
3255
3256
3257         $x = Math::BigInt->new(-5);
3258         print $x->brsft(1);
3259
3260 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3261 result).
3262
3263 =head2 new()
3264
3265         $x = Math::BigInt->new($str,$A,$P,$R);
3266
3267 Creates a new BigInt object from a scalar or another BigInt object. The
3268 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3269 '0b').
3270
3271 See L<Input> for more info on accepted input formats.
3272
3273 =head2 from_oct()
3274
3275         $x = Math::BigIn->from_oct("0775");     # input is octal
3276
3277 =head2 from_hex()
3278
3279         $x = Math::BigIn->from_hex("0xcafe");   # input is hexadecimal
3280
3281 =head2 from_bin()
3282
3283         $x = Math::BigIn->from_oct("0x10011");  # input is binary
3284
3285 =head2 bnan()
3286
3287         $x = Math::BigInt->bnan();
3288
3289 Creates a new BigInt object representing NaN (Not A Number).
3290 If used on an object, it will set it to NaN:
3291
3292         $x->bnan();
3293
3294 =head2 bzero()
3295
3296         $x = Math::BigInt->bzero();
3297
3298 Creates a new BigInt object representing zero.
3299 If used on an object, it will set it to zero:
3300
3301         $x->bzero();
3302
3303 =head2 binf()
3304
3305         $x = Math::BigInt->binf($sign);
3306
3307 Creates a new BigInt object representing infinity. The optional argument is
3308 either '-' or '+', indicating whether you want infinity or minus infinity.
3309 If used on an object, it will set it to infinity:
3310
3311         $x->binf();
3312         $x->binf('-');
3313
3314 =head2 bone()
3315
3316         $x = Math::BigInt->binf($sign);
3317
3318 Creates a new BigInt object representing one. The optional argument is
3319 either '-' or '+', indicating whether you want one or minus one.
3320 If used on an object, it will set it to one:
3321
3322         $x->bone();             # +1
3323         $x->bone('-');          # -1
3324
3325 =head2 is_one()/is_zero()/is_nan()/is_inf()
3326
3327
3328         $x->is_zero();                  # true if arg is +0
3329         $x->is_nan();                   # true if arg is NaN
3330         $x->is_one();                   # true if arg is +1
3331         $x->is_one('-');                # true if arg is -1
3332         $x->is_inf();                   # true if +inf
3333         $x->is_inf('-');                # true if -inf (sign is default '+')
3334
3335 These methods all test the BigInt for being one specific value and return
3336 true or false depending on the input. These are faster than doing something
3337 like:
3338
3339         if ($x == 0)
3340
3341 =head2 is_pos()/is_neg()/is_positive()/is_negative()
3342
3343         $x->is_pos();                   # true if > 0
3344         $x->is_neg();                   # true if < 0
3345
3346 The methods return true if the argument is positive or negative, respectively.
3347 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3348 C<-inf> is negative. A C<zero> is neither positive nor negative.
3349
3350 These methods are only testing the sign, and not the value.
3351
3352 C<is_positive()> and C<is_negative()> are aliases to C<is_pos()> and
3353 C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
3354 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
3355 in v1.68.
3356
3357 =head2 is_odd()/is_even()/is_int()
3358
3359         $x->is_odd();                   # true if odd, false for even
3360         $x->is_even();                  # true if even, false for odd
3361         $x->is_int();                   # true if $x is an integer
3362
3363 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3364 C<-inf> are not integers and are neither odd nor even.
3365
3366 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
3367
3368 =head2 bcmp()
3369
3370         $x->bcmp($y);
3371
3372 Compares $x with $y and takes the sign into account.
3373 Returns -1, 0, 1 or undef.
3374
3375 =head2 bacmp()
3376
3377         $x->bacmp($y);
3378
3379 Compares $x with $y while ignoring their. Returns -1, 0, 1 or undef.
3380
3381 =head2 sign()
3382
3383         $x->sign();
3384
3385 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3386
3387 If you want $x to have a certain sign, use one of the following methods:
3388
3389         $x->babs();             # '+'
3390         $x->babs()->bneg();     # '-'
3391         $x->bnan();             # 'NaN'
3392         $x->binf();             # '+inf'
3393         $x->binf('-');          # '-inf'
3394
3395 =head2 digit()
3396
3397         $x->digit($n);          # return the nth digit, counting from right
3398
3399 If C<$n> is negative, returns the digit counting from left.
3400
3401 =head2 bneg()
3402
3403         $x->bneg();
3404
3405 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3406 and '-inf', respectively. Does nothing for NaN or zero.
3407
3408 =head2 babs()
3409
3410         $x->babs();
3411
3412 Set the number to its absolute value, e.g. change the sign from '-' to '+'
3413 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3414 numbers.
3415
3416 =head2 bnorm()
3417
3418         $x->bnorm();                    # normalize (no-op)
3419
3420 =head2 bnot()
3421
3422         $x->bnot();
3423
3424 Two's complement (bitwise not). This is equivalent to
3425
3426         $x->binc()->bneg();
3427
3428 but faster.
3429
3430 =head2 binc()
3431
3432         $x->binc();                     # increment x by 1
3433
3434 =head2 bdec()
3435
3436         $x->bdec();                     # decrement x by 1
3437
3438 =head2 badd()
3439
3440         $x->badd($y);                   # addition (add $y to $x)
3441
3442 =head2 bsub()
3443
3444         $x->bsub($y);                   # subtraction (subtract $y from $x)
3445
3446 =head2 bmul()
3447
3448         $x->bmul($y);                   # multiplication (multiply $x by $y)
3449
3450 =head2 bdiv()
3451
3452         $x->bdiv($y);                   # divide, set $x to quotient
3453                                         # return (quo,rem) or quo if scalar
3454
3455 =head2 bmod()
3456
3457         $x->bmod($y);                   # modulus (x % y)
3458
3459 =head2 bmodinv()
3460
3461         num->bmodinv($mod);             # modular inverse
3462
3463 Returns the inverse of C<$num> in the given modulus C<$mod>.  'C<NaN>' is
3464 returned unless C<$num> is relatively prime to C<$mod>, i.e. unless
3465 C<bgcd($num, $mod)==1>.
3466
3467 =head2 bmodpow()
3468
3469         $num->bmodpow($exp,$mod);       # modular exponentation
3470                                         # ($num**$exp % $mod)
3471
3472 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3473 C<$mod> using binary exponentation.  C<bmodpow> is far superior to
3474 writing
3475
3476         $num ** $exp % $mod
3477
3478 because it is much faster - it reduces internal variables into
3479 the modulus whenever possible, so it operates on smaller numbers.
3480
3481 C<bmodpow> also supports negative exponents.
3482
3483         bmodpow($num, -1, $mod)
3484
3485 is exactly equivalent to
3486
3487         bmodinv($num, $mod)
3488
3489 =head2 bpow()
3490
3491         $x->bpow($y);                   # power of arguments (x ** y)
3492
3493 =head2 blog()
3494
3495         $x->blog($base, $accuracy);     # logarithm of x to the base $base
3496
3497 If C<$base> is not defined, Euler's number (e) is used:
3498
3499         print $x->blog(undef, 100);     # log(x) to 100 digits
3500
3501 =head2 bexp()
3502
3503         $x->bexp($accuracy);            # calculate e ** X
3504
3505 Calculates the expression C<e ** $x> where C<e> is Euler's number.
3506
3507 This method was added in v1.82 of Math::BigInt (April 2007).
3508
3509 See also L<blog()>.
3510
3511 =head2 bnok()
3512
3513         $x->bnok($y);              # x over y (binomial coefficient n over k)
3514
3515 Calculates the binomial coefficient n over k, also called the "choose"
3516 function. The result is equivalent to:
3517
3518         ( n )      n!
3519         | - |  = -------
3520         ( k )    k!(n-k)!
3521
3522 This method was added in v1.84 of Math::BigInt (April 2007).
3523
3524 =head2 bpi()
3525
3526         print Math::BigInt->bpi(100), "\n";             # 3
3527
3528 Returns PI truncated to an integer, with the argument being ignored. that
3529 is it always returns C<3>.
3530
3531 If upgrading is in effect, returns PI to N digits (including the "3"
3532 before the dot):
3533
3534         use Math::BigFloat;
3535         use Math::BigInt upgrade => Math::BigFloat;
3536         print Math::BigInt->bpi(3), "\n";               # 3.14
3537         print Math::BigInt->bpi(100), "\n";             # 3.1415....
3538
3539 This method was added in v1.87 of Math::BigInt (June 2007).
3540
3541 =head2 blsft()
3542
3543         $x->blsft($y);          # left shift in base 2
3544         $x->blsft($y,$n);       # left shift, in base $n (like 10)
3545
3546 =head2 brsft()
3547
3548         $x->brsft($y);          # right shift in base 2
3549         $x->brsft($y,$n);       # right shift, in base $n (like 10)
3550
3551 =head2 band()
3552
3553         $x->band($y);                   # bitwise and
3554
3555 =head2 bior()
3556
3557         $x->bior($y);                   # bitwise inclusive or
3558
3559 =head2 bxor()
3560
3561         $x->bxor($y);                   # bitwise exclusive or
3562
3563 =head2 bnot()
3564
3565         $x->bnot();                     # bitwise not (two's complement)
3566
3567 =head2 bsqrt()
3568
3569         $x->bsqrt();                    # calculate square-root
3570
3571 =head2 bfac()
3572
3573         $x->bfac();                     # factorial of $x (1*2*3*4*..$x)
3574
3575 =head2 round()
3576
3577         $x->round($A,$P,$round_mode);
3578
3579 Round $x to accuracy C<$A> or precision C<$P> using the round mode
3580 C<$round_mode>.
3581
3582 =head2 bround()
3583
3584         $x->bround($N);               # accuracy: preserve $N digits
3585
3586 =head2 bfround()
3587
3588         $x->bfround($N);              # round to $Nth digit, no-op for BigInts
3589
3590 =head2 bfloor()
3591
3592         $x->bfloor();
3593
3594 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
3595 does change $x in BigFloat.
3596
3597 =head2 bceil()
3598
3599         $x->bceil();
3600
3601 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
3602 does change $x in BigFloat.
3603
3604 =head2 bgcd()
3605
3606         bgcd(@values);          # greatest common divisor (no OO style)
3607
3608 =head2 blcm()
3609
3610         blcm(@values);          # lowest common multiplicator (no OO style)
3611
3612 head2 length()
3613
3614         $x->length();
3615         ($xl,$fl) = $x->length();
3616
3617 Returns the number of digits in the decimal representation of the number.
3618 In list context, returns the length of the integer and fraction part. For
3619 BigInt's, the length of the fraction part will always be 0.
3620
3621 =head2 exponent()
3622
3623         $x->exponent();
3624
3625 Return the exponent of $x as BigInt.
3626
3627 =head2 mantissa()
3628
3629         $x->mantissa();
3630
3631 Return the signed mantissa of $x as BigInt.
3632
3633 =head2 parts()
3634
3635         $x->parts();            # return (mantissa,exponent) as BigInt
3636
3637 =head2 copy()
3638
3639         $x->copy();             # make a true copy of $x (unlike $y = $x;)
3640
3641 =head2 as_int()/as_number()
3642
3643         $x->as_int();
3644
3645 Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as
3646 C<copy()>.
3647
3648 C<as_number()> is an alias to this method. C<as_number> was introduced in
3649 v1.22, while C<as_int()> was only introduced in v1.68.
3650
3651 =head2 bstr()
3652
3653         $x->bstr();
3654
3655 Returns a normalized string representation of C<$x>.
3656
3657 =head2 bsstr()
3658
3659         $x->bsstr();            # normalized string in scientific notation
3660
3661 =head2 as_hex()
3662
3663         $x->as_hex();           # as signed hexadecimal string with prefixed 0x
3664
3665 =head2 as_bin()
3666
3667         $x->as_bin();           # as signed binary string with prefixed 0b
3668
3669 =head2 as_oct()
3670
3671         $x->as_oct();           # as signed octal string with prefixed 0
3672
3673 =head2 numify()
3674
3675         print $x->numify();
3676
3677 This returns a normal Perl scalar from $x. It is used automatically
3678 whenever a scalar is needed, for instance in array index operations.
3679
3680 This loses precision, to avoid this use L<as_int()> instead.
3681
3682 =head2 modify()
3683
3684         $x->modify('bpowd');
3685
3686 This method returns 0 if the object can be modified with the given
3687 peration, or 1 if not.
3688
3689 This is used for instance by L<Math::BigInt::Constant>.
3690
3691 =head2 upgrade()/downgrade()
3692
3693 Set/get the class for downgrade/upgrade operations. Thuis is used
3694 for instance by L<bignum>. The defaults are '', thus the following
3695 operation will create a BigInt, not a BigFloat:
3696
3697         my $i = Math::BigInt->new(123);
3698         my $f = Math::BigFloat->new('123.1');
3699
3700         print $i + $f,"\n";                     # print 246
3701
3702 =head2 div_scale()
3703
3704 Set/get the number of digits for the default precision in divide
3705 operations.
3706
3707 =head2 round_mode()
3708
3709 Set/get the current round mode.
3710
3711 =head1 ACCURACY and PRECISION
3712
3713 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
3714 accuracy and precision based rounding, both automatically after every
3715 operation, as well as manually.
3716
3717 This section describes the accuracy/precision handling in Math::Big* as it
3718 used to be and as it is now, complete with an explanation of all terms and
3719 abbreviations.
3720
3721 Not yet implemented things (but with correct description) are marked with '!',
3722 things that need to be answered are marked with '?'.
3723
3724 In the next paragraph follows a short description of terms used here (because
3725 these may differ from terms used by others people or documentation).
3726
3727 During the rest of this document, the shortcuts A (for accuracy), P (for
3728 precision), F (fallback) and R (rounding mode) will be used.
3729
3730 =head2 Precision P
3731
3732 A fixed number of digits before (positive) or after (negative)
3733 the decimal point. For example, 123.45 has a precision of -2. 0 means an
3734 integer like 123 (or 120). A precision of 2 means two digits to the left
3735 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
3736 numbers with zeros before the decimal point may have different precisions,
3737 because 1200 can have p = 0, 1 or 2 (depending on what the inital value
3738 was). It could also have p < 0, when the digits after the decimal point
3739 are zero.
3740
3741 The string output (of floating point numbers) will be padded with zeros:
3742
3743         Initial value   P       A       Result          String
3744         ------------------------------------------------------------
3745         1234.01         -3              1000            1000
3746         1234            -2              1200            1200
3747         1234.5          -1              1230            1230
3748         1234.001        1               1234            1234.0
3749         1234.01         0               1234            1234
3750         1234.01         2               1234.01         1234.01
3751         1234.01         5               1234.01         1234.01000
3752
3753 For BigInts, no padding occurs.
3754
3755 =head2 Accuracy A
3756
3757 Number of significant digits. Leading zeros are not counted. A
3758 number may have an accuracy greater than the non-zero digits
3759 when there are zeros in it or trailing zeros. For example, 123.456 has
3760 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
3761
3762 The string output (of floating point numbers) will be padded with zeros:
3763
3764         Initial value   P       A       Result          String
3765         ------------------------------------------------------------
3766         1234.01                 3       1230            1230
3767         1234.01                 6       1234.01         1234.01
3768         1234.1                  8       1234.1          1234.1000
3769
3770 For BigInts, no padding occurs.
3771
3772 =head2 Fallback F
3773
3774 When both A and P are undefined, this is used as a fallback accuracy when
3775 dividing numbers.
3776
3777 =head2 Rounding mode R
3778
3779 When rounding a number, different 'styles' or 'kinds'
3780 of rounding are possible. (Note that random rounding, as in
3781 Math::Round, is not implemented.)
3782
3783 =over 2
3784
3785 =item 'trunc'
3786
3787 truncation invariably removes all digits following the
3788 rounding place, replacing them with zeros. Thus, 987.65 rounded
3789 to tens (P=1) becomes 980, and rounded to the fourth sigdig
3790 becomes 987.6 (A=4). 123.456 rounded to the second place after the
3791 decimal point (P=-2) becomes 123.46.
3792
3793 All other implemented styles of rounding attempt to round to the
3794 "nearest digit." If the digit D immediately to the right of the
3795 rounding place (skipping the decimal point) is greater than 5, the
3796 number is incremented at the rounding place (possibly causing a
3797 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
3798 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
3799 truncated at the rounding place: e.g. when rounding to units, 0.4
3800 rounds to 0, and -19.4 rounds to -19.
3801
3802 However the results of other styles of rounding differ if the
3803 digit immediately to the right of the rounding place (skipping the
3804 decimal point) is 5 and if there are no digits, or no digits other
3805 than 0, after that 5. In such cases:
3806
3807 =item 'even'
3808
3809 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
3810 if it is not already. E.g., when rounding to the first sigdig, 0.45
3811 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
3812
3813 =item 'odd'
3814
3815 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
3816 it is not already. E.g., when rounding to the first sigdig, 0.45
3817 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
3818
3819 =item '+inf'
3820
3821 round to plus infinity, i.e. always round up. E.g., when
3822 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
3823 and 0.4501 also becomes 0.5.
3824
3825 =item '-inf'
3826
3827 round to minus infinity, i.e. always round down. E.g., when
3828 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
3829 but 0.4501 becomes 0.5.
3830
3831 =item 'zero'
3832
3833 round to zero, i.e. positive numbers down, negative ones up.
3834 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
3835 becomes -0.5, but 0.4501 becomes 0.5.
3836
3837 =item 'common'
3838
3839 round up if the digit immediately to the right of the rounding place
3840 is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
3841 0.149 becomes 0.1.
3842
3843 =back
3844
3845 The handling of A & P in MBI/MBF (the old core code shipped with Perl
3846 versions <= 5.7.2) is like this:
3847
3848 =over 2
3849
3850 =item Precision
3851
3852   * ffround($p) is able to round to $p number of digits after the decimal
3853     point
3854   * otherwise P is unused
3855
3856 =item Accuracy (significant digits)
3857
3858   * fround($a) rounds to $a significant digits
3859   * only fdiv() and fsqrt() take A as (optional) paramater
3860     + other operations simply create the same number (fneg etc), or more (fmul)
3861       of digits
3862     + rounding/truncating is only done when explicitly calling one of fround
3863       or ffround, and never for BigInt (not implemented)
3864   * fsqrt() simply hands its accuracy argument over to fdiv.
3865   * the documentation and the comment in the code indicate two different ways
3866     on how fdiv() determines the maximum number of digits it should calculate,
3867     and the actual code does yet another thing
3868     POD:
3869       max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
3870     Comment:
3871       result has at most max(scale, length(dividend), length(divisor)) digits
3872     Actual code:
3873       scale = max(scale, length(dividend)-1,length(divisor)-1);
3874       scale += length(divisor) - length(dividend);
3875     So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
3876     Actually, the 'difference' added to the scale is calculated from the
3877     number of "significant digits" in dividend and divisor, which is derived
3878     by looking at the length of the mantissa. Which is wrong, since it includes
3879     the + sign (oops) and actually gets 2 for '+100' and 4 for '+101'. Oops
3880     again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
3881     assumption that 124 has 3 significant digits, while 120/7 will get you
3882     '17', not '17.1' since 120 is thought to have 2 significant digits.
3883     The rounding after the division then uses the remainder and $y to determine
3884     wether it must round up or down.
3885  ?  I have no idea which is the right way. That's why I used a slightly more
3886  ?  simple scheme and tweaked the few failing testcases to match it.
3887
3888 =back
3889
3890 This is how it works now:
3891
3892 =over 2
3893
3894 =item Setting/Accessing
3895
3896   * You can set the A global via C<< Math::BigInt->accuracy() >> or
3897     C<< Math::BigFloat->accuracy() >> or whatever class you are using.
3898   * You can also set P globally by using C<< Math::SomeClass->precision() >>
3899     likewise.
3900   * Globals are classwide, and not inherited by subclasses.
3901   * to undefine A, use C<< Math::SomeCLass->accuracy(undef); >>
3902   * to undefine P, use C<< Math::SomeClass->precision(undef); >>
3903   * Setting C<< Math::SomeClass->accuracy() >> clears automatically
3904     C<< Math::SomeClass->precision() >>, and vice versa.
3905   * To be valid, A must be > 0, P can have any value.
3906   * If P is negative, this means round to the P'th place to the right of the
3907     decimal point; positive values mean to the left of the decimal point.
3908     P of 0 means round to integer.
3909   * to find out the current global A, use C<< Math::SomeClass->accuracy() >>
3910   * to find out the current global P, use C<< Math::SomeClass->precision() >>
3911   * use C<< $x->accuracy() >> respective C<< $x->precision() >> for the local
3912     setting of C<< $x >>.
3913   * Please note that C<< $x->accuracy() >> respective C<< $x->precision() >>
3914     return eventually defined global A or P, when C<< $x >>'s A or P is not
3915     set.
3916
3917 =item Creating numbers
3918
3919   * When you create a number, you can give the desired A or P via:
3920     $x = Math::BigInt->new($number,$A,$P);
3921   * Only one of A or P can be defined, otherwise the result is NaN
3922   * If no A or P is give ($x = Math::BigInt->new($number) form), then the
3923     globals (if set) will be used. Thus changing the global defaults later on
3924     will not change the A or P of previously created numbers (i.e., A and P of
3925     $x will be what was in effect when $x was created)
3926   * If given undef for A and P, B<no> rounding will occur, and the globals will
3927     B<not> be used. This is used by subclasses to create numbers without
3928     suffering rounding in the parent. Thus a subclass is able to have its own
3929     globals enforced upon creation of a number by using
3930     C<< $x = Math::BigInt->new($number,undef,undef) >>:
3931
3932         use Math::BigInt::SomeSubclass;
3933         use Math::BigInt;
3934
3935         Math::BigInt->accuracy(2);
3936         Math::BigInt::SomeSubClass->accuracy(3);
3937         $x = Math::BigInt::SomeSubClass->new(1234);
3938
3939     $x is now 1230, and not 1200. A subclass might choose to implement
3940     this otherwise, e.g. falling back to the parent's A and P.
3941
3942 =item Usage
3943
3944   * If A or P are enabled/defined, they are used to round the result of each
3945     operation according to the rules below
3946   * Negative P is ignored in Math::BigInt, since BigInts never have digits
3947     after the decimal point
3948   * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
3949     Math::BigInt as globals does not tamper with the parts of a BigFloat.
3950     A flag is used to mark all Math::BigFloat numbers as 'never round'.
3951
3952 =item Precedence
3953
3954   * It only makes sense that a number has only one of A or P at a time.
3955     If you set either A or P on one object, or globally, the other one will
3956     be automatically cleared.
3957   * If two objects are involved in an operation, and one of them has A in
3958     effect, and the other P, this results in an error (NaN).
3959   * A takes precedence over P (Hint: A comes before P).
3960     If neither of them is defined, nothing is used, i.e. the result will have
3961     as many digits as it can (with an exception for fdiv/fsqrt) and will not
3962     be rounded.
3963   * There is another setting for fdiv() (and thus for fsqrt()). If neither of
3964     A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
3965     If either the dividend's or the divisor's mantissa has more digits than
3966     the value of F, the higher value will be used instead of F.
3967     This is to limit the digits (A) of the result (just consider what would
3968     happen with unlimited A and P in the case of 1/3 :-)
3969   * fdiv will calculate (at least) 4 more digits than required (determined by
3970     A, P or F), and, if F is not used, round the result
3971     (this will still fail in the case of a result like 0.12345000000001 with A
3972     or P of 5, but this can not be helped - or can it?)
3973   * Thus you can have the math done by on Math::Big* class in two modi:
3974     + never round (this is the default):
3975       This is done by setting A and P to undef. No math operation
3976       will round the result, with fdiv() and fsqrt() as exceptions to guard
3977       against overflows. You must explicitly call bround(), bfround() or
3978       round() (the latter with parameters).
3979       Note: Once you have rounded a number, the settings will 'stick' on it
3980       and 'infect' all other numbers engaged in math operations with it, since
3981       local settings have the highest precedence. So, to get SaferRound[tm],
3982       use a copy() before rounding like this:
3983
3984         $x = Math::BigFloat->new(12.34);
3985         $y = Math::BigFloat->new(98.76);
3986         $z = $x * $y;                           # 1218.6984
3987         print $x->copy()->fround(3);            # 12.3 (but A is now 3!)
3988         $z = $x * $y;                           # still 1218.6984, without
3989                                                 # copy would have been 1210!
3990
3991     + round after each op:
3992       After each single operation (except for testing like is_zero()), the
3993       method round() is called and the result is rounded appropriately. By
3994       setting proper values for A and P, you can have all-the-same-A or
3995       all-the-same-P modes. For example, Math::Currency might set A to undef,
3996       and P to -2, globally.
3997
3998  ?Maybe an extra option that forbids local A & P settings would be in order,
3999  ?so that intermediate rounding does not 'poison' further math?
4000
4001 =item Overriding globals
4002
4003   * you will be able to give A, P and R as an argument to all the calculation
4004     routines; the second parameter is A, the third one is P, and the fourth is
4005     R (shift right by one for binary operations like badd). P is used only if
4006     the first parameter (A) is undefined. These three parameters override the
4007     globals in the order detailed as follows, i.e. the first defined value
4008     wins:
4009     (local: per object, global: global default, parameter: argument to sub)
4010       + parameter A
4011       + parameter P
4012       + local A (if defined on both of the operands: smaller one is taken)
4013       + local P (if defined on both of the operands: bigger one is taken)
4014       + global A
4015       + global P
4016       + global F
4017   * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
4018     arguments (A and P) instead of one
4019
4020 =item Local settings
4021
4022   * You can set A or P locally by using C<< $x->accuracy() >> or
4023     C<< $x->precision() >>
4024     and thus force different A and P for different objects/numbers.
4025   * Setting A or P this way immediately rounds $x to the new value.
4026   * C<< $x->accuracy() >> clears C<< $x->precision() >>, and vice versa.
4027
4028 =item Rounding
4029
4030   * the rounding routines will use the respective global or local settings.
4031     fround()/bround() is for accuracy rounding, while ffround()/bfround()
4032     is for precision
4033   * the two rounding functions take as the second parameter one of the
4034     following rounding modes (R):
4035     'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
4036   * you can set/get the global R by using C<< Math::SomeClass->round_mode() >>
4037     or by setting C<< $Math::SomeClass::round_mode >>
4038   * after each operation, C<< $result->round() >> is called, and the result may
4039     eventually be rounded (that is, if A or P were set either locally,
4040     globally or as parameter to the operation)
4041   * to manually round a number, call C<< $x->round($A,$P,$round_mode); >>
4042     this will round the number by using the appropriate rounding function
4043     and then normalize it.
4044   * rounding modifies the local settings of the number:
4045
4046         $x = Math::BigFloat->new(123.456);
4047         $x->accuracy(5);
4048         $x->bround(4);
4049
4050     Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
4051     will be 4 from now on.
4052
4053 =item Default values
4054
4055   * R: 'even'
4056   * F: 40
4057   * A: undef
4058   * P: undef
4059
4060 =item Remarks
4061
4062   * The defaults are set up so that the new code gives the same results as
4063     the old code (except in a few cases on fdiv):
4064     + Both A and P are undefined and thus will not be used for rounding
4065       after each operation.
4066     + round() is thus a no-op, unless given extra parameters A and P
4067
4068 =back
4069
4070 =head1 Infinity and Not a Number
4071
4072 While BigInt has extensive handling of inf and NaN, certain quirks remain.
4073
4074 =over 2
4075
4076 =item oct()/hex()
4077
4078 These perl routines currently (as of Perl v.5.8.6) cannot handle passed
4079 inf.
4080
4081         te@linux:~> perl -wle 'print 2 ** 3333'
4082         inf
4083         te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
4084         1
4085         te@linux:~> perl -wle 'print oct(2 ** 3333)'
4086         0
4087         te@linux:~> perl -wle 'print hex(2 ** 3333)'
4088         Illegal hexadecimal digit 'i' ignored at -e line 1.
4089         0
4090
4091 The same problems occur if you pass them Math::BigInt->binf() objects. Since
4092 overloading these routines is not possible, this cannot be fixed from BigInt.
4093
4094 =item ==, !=, <, >, <=, >= with NaNs
4095
4096 BigInt's bcmp() routine currently returns undef to signal that a NaN was
4097 involved in a comparison. However, the overload code turns that into
4098 either 1 or '' and thus operations like C<< NaN != NaN >> might return
4099 wrong values.
4100
4101 =item log(-inf)
4102
4103 C<< log(-inf) >> is highly weird. Since log(-x)=pi*i+log(x), then
4104 log(-inf)=pi*i+inf. However, since the imaginary part is finite, the real
4105 infinity "overshadows" it, so the number might as well just be infinity.
4106 However, the result is a complex number, and since BigInt/BigFloat can only
4107 have real numbers as results, the result is NaN.
4108
4109 =item exp(), cos(), sin(), atan2()
4110
4111 These all might have problems handling infinity right.
4112
4113 =back
4114
4115 =head1 INTERNALS
4116
4117 The actual numbers are stored as unsigned big integers (with seperate sign).
4118
4119 You should neither care about nor depend on the internal representation; it
4120 might change without notice. Use B<ONLY> method calls like C<< $x->sign(); >>
4121 instead relying on the internal representation.
4122
4123 =head2 MATH LIBRARY
4124
4125 Math with the numbers is done (by default) by a module called
4126 C<Math::BigInt::Calc>. This is equivalent to saying:
4127
4128         use Math::BigInt lib => 'Calc';
4129
4130 You can change this by using:
4131
4132         use Math::BigInt lib => 'BitVect';
4133
4134 The following would first try to find Math::BigInt::Foo, then
4135 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
4136
4137         use Math::BigInt lib => 'Foo,Math::BigInt::Bar';
4138
4139 Since Math::BigInt::GMP is in almost all cases faster than Calc (especially in
4140 math involving really big numbers, where it is B<much> faster), and there is
4141 no penalty if Math::BigInt::GMP is not installed, it is a good idea to always
4142 use the following:
4143
4144         use Math::BigInt lib => 'GMP';
4145
4146 Different low-level libraries use different formats to store the
4147 numbers. You should B<NOT> depend on the number having a specific format
4148 internally.
4149
4150 See the respective math library module documentation for further details.
4151
4152 =head2 SIGN
4153
4154 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
4155
4156 A sign of 'NaN' is used to represent the result when input arguments are not
4157 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
4158 minus infinity. You will get '+inf' when dividing a positive number by 0, and
4159 '-inf' when dividing any negative number by 0.
4160
4161 =head2 mantissa(), exponent() and parts()
4162
4163 C<mantissa()> and C<exponent()> return the said parts of the BigInt such
4164 that:
4165
4166         $m = $x->mantissa();
4167         $e = $x->exponent();
4168         $y = $m * ( 10 ** $e );
4169         print "ok\n" if $x == $y;
4170
4171 C<< ($m,$e) = $x->parts() >> is just a shortcut that gives you both of them
4172 in one go. Both the returned mantissa and exponent have a sign.
4173
4174 Currently, for BigInts C<$e> is always 0, except +inf and -inf, where it is
4175 C<+inf>; and for NaN, where it is C<NaN>; and for C<$x == 0>, where it is C<1>
4176 (to be compatible with Math::BigFloat's internal representation of a zero as
4177 C<0E1>).
4178
4179 C<$m> is currently just a copy of the original number. The relation between
4180 C<$e> and C<$m> will stay always the same, though their real values might
4181 change.
4182
4183 =head1 EXAMPLES
4184
4185   use Math::BigInt;
4186
4187   sub bint { Math::BigInt->new(shift); }
4188
4189   $x = Math::BigInt->bstr("1234")       # string "1234"
4190   $x = "$x";                            # same as bstr()
4191   $x = Math::BigInt->bneg("1234");      # BigInt "-1234"
4192   $x = Math::BigInt->babs("-12345");    # BigInt "12345"
4193   $x = Math::BigInt->bnorm("-0.00");    # BigInt "0"
4194   $x = bint(1) + bint(2);               # BigInt "3"
4195   $x = bint(1) + "2";                   # ditto (auto-BigIntify of "2")
4196   $x = bint(1);                         # BigInt "1"
4197   $x = $x + 5 / 2;                      # BigInt "3"
4198   $x = $x ** 3;                         # BigInt "27"
4199   $x *= 2;                              # BigInt "54"
4200   $x = Math::BigInt->new(0);            # BigInt "0"
4201   $x--;                                 # BigInt "-1"
4202   $x = Math::BigInt->badd(4,5)          # BigInt "9"
4203   print $x->bsstr();                    # 9e+0
4204
4205 Examples for rounding:
4206
4207   use Math::BigFloat;
4208   use Test;
4209
4210   $x = Math::BigFloat->new(123.4567);
4211   $y = Math::BigFloat->new(123.456789);
4212   Math::BigFloat->accuracy(4);          # no more A than 4
4213
4214   ok ($x->copy()->fround(),123.4);      # even rounding
4215   print $x->copy()->fround(),"\n";      # 123.4
4216   Math::BigFloat->round_mode('odd');    # round to odd
4217   print $x->copy()->fround(),"\n";      # 123.5
4218   Math::BigFloat->accuracy(5);          # no more A than 5
4219   Math::BigFloat->round_mode('odd');    # round to odd
4220   print $x->copy()->fround(),"\n";      # 123.46
4221   $y = $x->copy()->fround(4),"\n";      # A = 4: 123.4
4222   print "$y, ",$y->accuracy(),"\n";     # 123.4, 4
4223
4224   Math::BigFloat->accuracy(undef);      # A not important now
4225   Math::BigFloat->precision(2);         # P important
4226   print $x->copy()->bnorm(),"\n";       # 123.46
4227   print $x->copy()->fround(),"\n";      # 123.46
4228
4229 Examples for converting:
4230
4231   my $x = Math::BigInt->new('0b1'.'01' x 123);
4232   print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
4233
4234 =head1 Autocreating constants
4235
4236 After C<use Math::BigInt ':constant'> all the B<integer> decimal, hexadecimal
4237 and binary constants in the given scope are converted to C<Math::BigInt>.
4238 This conversion happens at compile time.
4239
4240 In particular,
4241
4242   perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'
4243
4244 prints the integer value of C<2**100>. Note that without conversion of
4245 constants the expression 2**100 will be calculated as perl scalar.
4246
4247 Please note that strings and floating point constants are not affected,
4248 so that
4249
4250         use Math::BigInt qw/:constant/;
4251
4252         $x = 1234567890123456789012345678901234567890
4253                 + 123456789123456789;
4254         $y = '1234567890123456789012345678901234567890'
4255                 + '123456789123456789';
4256
4257 do not work. You need an explicit Math::BigInt->new() around one of the
4258 operands. You should also quote large constants to protect loss of precision:
4259
4260         use Math::BigInt;
4261
4262         $x = Math::BigInt->new('1234567889123456789123456789123456789');
4263
4264 Without the quotes Perl would convert the large number to a floating point
4265 constant at compile time and then hand the result to BigInt, which results in
4266 an truncated result or a NaN.
4267
4268 This also applies to integers that look like floating point constants:
4269
4270         use Math::BigInt ':constant';
4271
4272         print ref(123e2),"\n";
4273         print ref(123.2e2),"\n";
4274
4275 will print nothing but newlines. Use either L<bignum> or L<Math::BigFloat>
4276 to get this to work.
4277
4278 =head1 PERFORMANCE
4279
4280 Using the form $x += $y; etc over $x = $x + $y is faster, since a copy of $x
4281 must be made in the second case. For long numbers, the copy can eat up to 20%
4282 of the work (in the case of addition/subtraction, less for
4283 multiplication/division). If $y is very small compared to $x, the form
4284 $x += $y is MUCH faster than $x = $x + $y since making the copy of $x takes
4285 more time then the actual addition.
4286
4287 With a technique called copy-on-write, the cost of copying with overload could
4288 be minimized or even completely avoided. A test implementation of COW did show
4289 performance gains for overloaded math, but introduced a performance loss due
4290 to a constant overhead for all other operations. So Math::BigInt does currently
4291 not COW.
4292
4293 The rewritten version of this module (vs. v0.01) is slower on certain
4294 operations, like C<new()>, C<bstr()> and C<numify()>. The reason are that it
4295 does now more work and handles much more cases. The time spent in these
4296 operations is usually gained in the other math operations so that code on
4297 the average should get (much) faster. If they don't, please contact the author.
4298
4299 Some operations may be slower for small numbers, but are significantly faster
4300 for big numbers. Other operations are now constant (O(1), like C<bneg()>,
4301 C<babs()> etc), instead of O(N) and thus nearly always take much less time.
4302 These optimizations were done on purpose.
4303
4304 If you find the Calc module to slow, try to install any of the replacement
4305 modules and see if they help you.
4306
4307 =head2 Alternative math libraries
4308
4309 You can use an alternative library to drive Math::BigInt via:
4310
4311         use Math::BigInt lib => 'Module';
4312
4313 See L<MATH LIBRARY> for more information.
4314
4315 For more benchmark results see L<http://bloodgate.com/perl/benchmarks.html>.
4316
4317 =head2 SUBCLASSING
4318
4319 =head1 Subclassing Math::BigInt
4320
4321 The basic design of Math::BigInt allows simple subclasses with very little
4322 work, as long as a few simple rules are followed:
4323
4324 =over 2
4325
4326 =item *
4327
4328 The public API must remain consistent, i.e. if a sub-class is overloading
4329 addition, the sub-class must use the same name, in this case badd(). The
4330 reason for this is that Math::BigInt is optimized to call the object methods
4331 directly.
4332
4333 =item *
4334
4335 The private object hash keys like C<$x->{sign}> may not be changed, but
4336 additional keys can be added, like C<$x->{_custom}>.
4337
4338 =item *
4339
4340 Accessor functions are available for all existing object hash keys and should
4341 be used instead of directly accessing the internal hash keys. The reason for
4342 this is that Math::BigInt itself has a pluggable interface which permits it
4343 to support different storage methods.
4344
4345 =back
4346
4347 More complex sub-classes may have to replicate more of the logic internal of
4348 Math::BigInt if they need to change more basic behaviors. A subclass that
4349 needs to merely change the output only needs to overload C<bstr()>.
4350
4351 All other object methods and overloaded functions can be directly inherited
4352 from the parent class.
4353
4354 At the very minimum, any subclass will need to provide its own C<new()> and can
4355 store additional hash keys in the object. There are also some package globals
4356 that must be defined, e.g.:
4357
4358   # Globals
4359   $accuracy = undef;
4360   $precision = -2;       # round to 2 decimal places
4361   $round_mode = 'even';
4362   $div_scale = 40;
4363
4364 Additionally, you might want to provide the following two globals to allow
4365 auto-upgrading and auto-downgrading to work correctly:
4366
4367   $upgrade = undef;
4368   $downgrade = undef;
4369
4370 This allows Math::BigInt to correctly retrieve package globals from the
4371 subclass, like C<$SubClass::precision>.  See t/Math/BigInt/Subclass.pm or
4372 t/Math/BigFloat/SubClass.pm completely functional subclass examples.
4373
4374 Don't forget to
4375
4376         use overload;
4377
4378 in your subclass to automatically inherit the overloading from the parent. If
4379 you like, you can change part of the overloading, look at Math::String for an
4380 example.
4381
4382 =head1 UPGRADING
4383
4384 When used like this:
4385
4386         use Math::BigInt upgrade => 'Foo::Bar';
4387
4388 certain operations will 'upgrade' their calculation and thus the result to
4389 the class Foo::Bar. Usually this is used in conjunction with Math::BigFloat:
4390
4391         use Math::BigInt upgrade => 'Math::BigFloat';
4392
4393 As a shortcut, you can use the module C<bignum>:
4394
4395         use bignum;
4396
4397 Also good for oneliners:
4398
4399         perl -Mbignum -le 'print 2 ** 255'
4400
4401 This makes it possible to mix arguments of different classes (as in 2.5 + 2)
4402 as well es preserve accuracy (as in sqrt(3)).
4403
4404 Beware: This feature is not fully implemented yet.
4405
4406 =head2 Auto-upgrade
4407
4408 The following methods upgrade themselves unconditionally; that is if upgrade
4409 is in effect, they will always hand up their work:
4410
4411 =over 2
4412
4413 =item bsqrt()
4414
4415 =item div()
4416
4417 =item blog()
4418
4419 =item bexp()
4420
4421 =back
4422
4423 Beware: This list is not complete.
4424
4425 All other methods upgrade themselves only when one (or all) of their
4426 arguments are of the class mentioned in $upgrade (This might change in later
4427 versions to a more sophisticated scheme):
4428
4429 =head1 EXPORTS
4430
4431 C<Math::BigInt> exports nothing by default, but can export the following methods:
4432
4433         bgcd
4434         blcm
4435
4436 =head1 BUGS
4437
4438 =over 2
4439
4440 =item broot() does not work
4441
4442 The broot() function in BigInt may only work for small values. This will be
4443 fixed in a later version.
4444
4445 =item Out of Memory!
4446
4447 Under Perl prior to 5.6.0 having an C<use Math::BigInt ':constant';> and
4448 C<eval()> in your code will crash with "Out of memory". This is probably an
4449 overload/exporter bug. You can workaround by not having C<eval()>
4450 and ':constant' at the same time or upgrade your Perl to a newer version.
4451
4452 =item Fails to load Calc on Perl prior 5.6.0
4453
4454 Since eval(' use ...') can not be used in conjunction with ':constant', BigInt
4455 will fall back to eval { require ... } when loading the math lib on Perls
4456 prior to 5.6.0. This simple replaces '::' with '/' and thus might fail on
4457 filesystems using a different seperator.
4458
4459 =back
4460
4461 =head1 CAVEATS
4462
4463 Some things might not work as you expect them. Below is documented what is
4464 known to be troublesome:
4465
4466 =over 1
4467
4468 =item bstr(), bsstr() and 'cmp'
4469
4470 Both C<bstr()> and C<bsstr()> as well as automated stringify via overload now
4471 drop the leading '+'. The old code would return '+3', the new returns '3'.
4472 This is to be consistent with Perl and to make C<cmp> (especially with
4473 overloading) to work as you expect. It also solves problems with C<Test.pm>,
4474 because its C<ok()> uses 'eq' internally.
4475
4476 Mark Biggar said, when asked about to drop the '+' altogether, or make only
4477 C<cmp> work:
4478
4479         I agree (with the first alternative), don't add the '+' on positive
4480         numbers.  It's not as important anymore with the new internal
4481         form for numbers.  It made doing things like abs and neg easier,
4482         but those have to be done differently now anyway.
4483
4484 So, the following examples will now work all as expected:
4485
4486         use Test;
4487         BEGIN { plan tests => 1 }
4488         use Math::BigInt;
4489
4490         my $x = new Math::BigInt 3*3;
4491         my $y = new Math::BigInt 3*3;
4492
4493         ok ($x,3*3);
4494         print "$x eq 9" if $x eq $y;
4495         print "$x eq 9" if $x eq '9';
4496         print "$x eq 9" if $x eq 3*3;
4497
4498 Additionally, the following still works:
4499
4500         print "$x == 9" if $x == $y;
4501         print "$x == 9" if $x == 9;
4502         print "$x == 9" if $x == 3*3;
4503
4504 There is now a C<bsstr()> method to get the string in scientific notation aka
4505 C<1e+2> instead of C<100>. Be advised that overloaded 'eq' always uses bstr()
4506 for comparison, but Perl will represent some numbers as 100 and others
4507 as 1e+308. If in doubt, convert both arguments to Math::BigInt before
4508 comparing them as strings:
4509
4510         use Test;
4511         BEGIN { plan tests => 3 }
4512         use Math::BigInt;
4513
4514         $x = Math::BigInt->new('1e56'); $y = 1e56;
4515         ok ($x,$y);                     # will fail
4516         ok ($x->bsstr(),$y);            # okay
4517         $y = Math::BigInt->new($y);
4518         ok ($x,$y);                     # okay
4519
4520 Alternatively, simple use C<< <=> >> for comparisons, this will get it
4521 always right. There is not yet a way to get a number automatically represented
4522 as a string that matches exactly the way Perl represents it.
4523
4524 See also the section about L<Infinity and Not a Number> for problems in
4525 comparing NaNs.
4526
4527 =item int()
4528
4529 C<int()> will return (at least for Perl v5.7.1 and up) another BigInt, not a
4530 Perl scalar:
4531
4532         $x = Math::BigInt->new(123);
4533         $y = int($x);                           # BigInt 123
4534         $x = Math::BigFloat->new(123.45);
4535         $y = int($x);                           # BigInt 123
4536
4537 In all Perl versions you can use C<as_number()> or C<as_int> for the same
4538 effect:
4539
4540         $x = Math::BigFloat->new(123.45);
4541         $y = $x->as_number();                   # BigInt 123
4542         $y = $x->as_int();                      # ditto
4543
4544 This also works for other subclasses, like Math::String.
4545
4546 If you want a real Perl scalar, use C<numify()>:
4547
4548         $y = $x->numify();                      # 123 as scalar
4549
4550 This is seldom necessary, though, because this is done automatically, like
4551 when you access an array:
4552
4553         $z = $array[$x];                        # does work automatically
4554
4555 =item length
4556
4557 The following will probably not do what you expect:
4558
4559         $c = Math::BigInt->new(123);
4560         print $c->length(),"\n";                # prints 30
4561
4562 It prints both the number of digits in the number and in the fraction part
4563 since print calls C<length()> in list context. Use something like:
4564
4565         print scalar $c->length(),"\n";         # prints 3
4566
4567 =item bdiv
4568
4569 The following will probably not do what you expect:
4570
4571         print $c->bdiv(10000),"\n";
4572
4573 It prints both quotient and remainder since print calls C<bdiv()> in list
4574 context. Also, C<bdiv()> will modify $c, so be careful. You probably want
4575 to use
4576
4577         print $c / 10000,"\n";
4578         print scalar $c->bdiv(10000),"\n";  # or if you want to modify $c
4579
4580 instead.
4581
4582 The quotient is always the greatest integer less than or equal to the
4583 real-valued quotient of the two operands, and the remainder (when it is
4584 nonzero) always has the same sign as the second operand; so, for
4585 example,
4586
4587           1 / 4  => ( 0, 1)
4588           1 / -4 => (-1,-3)
4589          -3 / 4  => (-1, 1)
4590          -3 / -4 => ( 0,-3)
4591         -11 / 2  => (-5,1)
4592          11 /-2  => (-5,-1)
4593
4594 As a consequence, the behavior of the operator % agrees with the
4595 behavior of Perl's built-in % operator (as documented in the perlop
4596 manpage), and the equation
4597
4598         $x == ($x / $y) * $y + ($x % $y)
4599
4600 holds true for any $x and $y, which justifies calling the two return
4601 values of bdiv() the quotient and remainder. The only exception to this rule
4602 are when $y == 0 and $x is negative, then the remainder will also be
4603 negative. See below under "infinity handling" for the reasoning behind this.
4604
4605 Perl's 'use integer;' changes the behaviour of % and / for scalars, but will
4606 not change BigInt's way to do things. This is because under 'use integer' Perl
4607 will do what the underlying C thinks is right and this is different for each
4608 system. If you need BigInt's behaving exactly like Perl's 'use integer', bug
4609 the author to implement it ;)
4610
4611 =item infinity handling
4612
4613 Here are some examples that explain the reasons why certain results occur while
4614 handling infinity:
4615
4616 The following table shows the result of the division and the remainder, so that
4617 the equation above holds true. Some "ordinary" cases are strewn in to show more
4618 clearly the reasoning:
4619
4620         A /  B  =   C,     R so that C *    B +    R =    A
4621      =========================================================
4622         5 /   8 =   0,     5         0 *    8 +    5 =    5
4623         0 /   8 =   0,     0         0 *    8 +    0 =    0
4624         0 / inf =   0,     0         0 *  inf +    0 =    0
4625         0 /-inf =   0,     0         0 * -inf +    0 =    0
4626         5 / inf =   0,     5         0 *  inf +    5 =    5
4627         5 /-inf =   0,     5         0 * -inf +    5 =    5
4628         -5/ inf =   0,    -5         0 *  inf +   -5 =   -5
4629         -5/-inf =   0,    -5         0 * -inf +   -5 =   -5
4630        inf/   5 =  inf,    0       inf *    5 +    0 =  inf
4631       -inf/   5 = -inf,    0      -inf *    5 +    0 = -inf
4632        inf/  -5 = -inf,    0      -inf *   -5 +    0 =  inf
4633       -inf/  -5 =  inf,    0       inf *   -5 +    0 = -inf
4634          5/   5 =    1,    0         1 *    5 +    0 =    5
4635         -5/  -5 =    1,    0         1 *   -5 +    0 =   -5
4636        inf/ inf =    1,    0         1 *  inf +    0 =  inf
4637       -inf/-inf =    1,    0         1 * -inf +    0 = -inf
4638        inf/-inf =   -1,    0        -1 * -inf +    0 =  inf
4639       -inf/ inf =   -1,    0         1 * -inf +    0 = -inf
4640          8/   0 =  inf,    8       inf *    0 +    8 =    8
4641        inf/   0 =  inf,  inf       inf *    0 +  inf =  inf
4642          0/   0 =  NaN
4643
4644 These cases below violate the "remainder has the sign of the second of the two
4645 arguments", since they wouldn't match up otherwise.
4646
4647         A /  B  =   C,     R so that C *    B +    R =    A
4648      ========================================================
4649       -inf/   0 = -inf, -inf      -inf *    0 +  inf = -inf
4650         -8/   0 = -inf,   -8      -inf *    0 +    8 = -8
4651
4652 =item Modifying and =
4653
4654 Beware of:
4655
4656         $x = Math::BigFloat->new(5);
4657         $y = $x;
4658
4659 It will not do what you think, e.g. making a copy of $x. Instead it just makes
4660 a second reference to the B<same> object and stores it in $y. Thus anything
4661 that modifies $x (except overloaded operators) will modify $y, and vice versa.
4662 Or in other words, C<=> is only safe if you modify your BigInts only via
4663 overloaded math. As soon as you use a method call it breaks:
4664
4665         $x->bmul(2);
4666         print "$x, $y\n";       # prints '10, 10'
4667
4668 If you want a true copy of $x, use:
4669
4670         $y = $x->copy();
4671
4672 You can also chain the calls like this, this will make first a copy and then
4673 multiply it by 2:
4674
4675         $y = $x->copy()->bmul(2);
4676
4677 See also the documentation for overload.pm regarding C<=>.
4678
4679 =item bpow
4680
4681 C<bpow()> (and the rounding functions) now modifies the first argument and
4682 returns it, unlike the old code which left it alone and only returned the
4683 result. This is to be consistent with C<badd()> etc. The first three will
4684 modify $x, the last one won't:
4685
4686         print bpow($x,$i),"\n";         # modify $x
4687         print $x->bpow($i),"\n";        # ditto
4688         print $x **= $i,"\n";           # the same
4689         print $x ** $i,"\n";            # leave $x alone
4690
4691 The form C<$x **= $y> is faster than C<$x = $x ** $y;>, though.
4692
4693 =item Overloading -$x
4694
4695 The following:
4696
4697         $x = -$x;
4698
4699 is slower than
4700
4701         $x->bneg();
4702
4703 since overload calls C<sub($x,0,1);> instead of C<neg($x)>. The first variant
4704 needs to preserve $x since it does not know that it later will get overwritten.
4705 This makes a copy of $x and takes O(N), but $x->bneg() is O(1).
4706
4707 =item Mixing different object types
4708
4709 In Perl you will get a floating point value if you do one of the following:
4710
4711         $float = 5.0 + 2;
4712         $float = 2 + 5.0;
4713         $float = 5 / 2;
4714
4715 With overloaded math, only the first two variants will result in a BigFloat:
4716
4717         use Math::BigInt;
4718         use Math::BigFloat;
4719
4720         $mbf = Math::BigFloat->new(5);
4721         $mbi2 = Math::BigInteger->new(5);
4722         $mbi = Math::BigInteger->new(2);
4723
4724                                         # what actually gets called:
4725         $float = $mbf + $mbi;           # $mbf->badd()
4726         $float = $mbf / $mbi;           # $mbf->bdiv()
4727         $integer = $mbi + $mbf;         # $mbi->badd()
4728         $integer = $mbi2 / $mbi;        # $mbi2->bdiv()
4729         $integer = $mbi2 / $mbf;        # $mbi2->bdiv()
4730
4731 This is because math with overloaded operators follows the first (dominating)
4732 operand, and the operation of that is called and returns thus the result. So,
4733 Math::BigInt::bdiv() will always return a Math::BigInt, regardless whether
4734 the result should be a Math::BigFloat or the second operant is one.
4735
4736 To get a Math::BigFloat you either need to call the operation manually,
4737 make sure the operands are already of the proper type or casted to that type
4738 via Math::BigFloat->new():
4739
4740         $float = Math::BigFloat->new($mbi2) / $mbi;     # = 2.5
4741
4742 Beware of simple "casting" the entire expression, this would only convert
4743 the already computed result:
4744
4745         $float = Math::BigFloat->new($mbi2 / $mbi);     # = 2.0 thus wrong!
4746
4747 Beware also of the order of more complicated expressions like:
4748
4749         $integer = ($mbi2 + $mbi) / $mbf;               # int / float => int
4750         $integer = $mbi2 / Math::BigFloat->new($mbi);   # ditto
4751
4752 If in doubt, break the expression into simpler terms, or cast all operands
4753 to the desired resulting type.
4754
4755 Scalar values are a bit different, since:
4756
4757         $float = 2 + $mbf;
4758         $float = $mbf + 2;
4759
4760 will both result in the proper type due to the way the overloaded math works.
4761
4762 This section also applies to other overloaded math packages, like Math::String.
4763
4764 One solution to you problem might be autoupgrading|upgrading. See the
4765 pragmas L<bignum>, L<bigint> and L<bigrat> for an easy way to do this.
4766
4767 =item bsqrt()
4768
4769 C<bsqrt()> works only good if the result is a big integer, e.g. the square
4770 root of 144 is 12, but from 12 the square root is 3, regardless of rounding
4771 mode. The reason is that the result is always truncated to an integer.
4772
4773 If you want a better approximation of the square root, then use:
4774
4775         $x = Math::BigFloat->new(12);
4776         Math::BigFloat->precision(0);
4777         Math::BigFloat->round_mode('even');
4778         print $x->copy->bsqrt(),"\n";           # 4
4779
4780         Math::BigFloat->precision(2);
4781         print $x->bsqrt(),"\n";                 # 3.46
4782         print $x->bsqrt(3),"\n";                # 3.464
4783
4784 =item brsft()
4785
4786 For negative numbers in base see also L<brsft|brsft>.
4787
4788 =back
4789
4790 =head1 LICENSE
4791
4792 This program is free software; you may redistribute it and/or modify it under
4793 the same terms as Perl itself.
4794
4795 =head1 SEE ALSO
4796
4797 L<Math::BigFloat>, L<Math::BigRat> and L<Math::Big> as well as
4798 L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
4799
4800 The pragmas L<bignum>, L<bigint> and L<bigrat> also might be of interest
4801 because they solve the autoupgrading/downgrading issue, at least partly.
4802
4803 The package at
4804 L<http://search.cpan.org/search?mode=module&query=Math%3A%3ABigInt> contains
4805 more documentation including a full version history, testcases, empty
4806 subclass files and benchmarks.
4807
4808 =head1 AUTHORS
4809
4810 Original code by Mark Biggar, overloaded interface by Ilya Zakharevich.
4811 Completely rewritten by Tels http://bloodgate.com in late 2000, 2001 - 2006
4812 and still at it in 2007.
4813
4814 Many people contributed in one or more ways to the final beast, see the file
4815 CREDITS for an (incomplete) list. If you miss your name, please drop me a
4816 mail. Thank you!
4817
4818 =cut