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