lib/Math/BigInt.pm

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