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