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