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