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.65';
  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
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       return (\$mis,\$miv,\$mfv,\$es,\$ev);
2772       }
2773     }
2774   return; # NaN, not a number
2775   }
2776
2777 sub as_number
2778   {
2779   # an object might be asked to return itself as bigint on certain overloaded
2780   # operations, this does exactly this, so that sub classes can simple inherit
2781   # it or override with their own integer conversion routine
2782   my $self = shift;
2783
2784   $self->copy();
2785   }
2786
2787 sub as_hex
2788   {
2789   # return as hex string, with prefixed 0x
2790   my $x = shift; $x = $class->new($x) if !ref($x);
2791
2792   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2793
2794   my $es = ''; my $s = '';
2795   $s = $x->{sign} if $x->{sign} eq '-';
2796   if ($CALC->can('_as_hex'))
2797     {
2798     $es = ${$CALC->_as_hex($x->{value})};
2799     }
2800   else
2801     {
2802     return '0x0' if $x->is_zero();
2803
2804     my $x1 = $x->copy()->babs(); my ($xr,$x10000,$h);
2805     if ($] >= 5.006)
2806       {
2807       $x10000 = Math::BigInt->new (0x10000); $h = 'h4';
2808       }
2809     else
2810       {
2811       $x10000 = Math::BigInt->new (0x1000); $h = 'h3';
2812       }
2813     while (!$x1->is_zero())
2814       {
2815       ($x1, $xr) = bdiv($x1,$x10000);
2816       $es .= unpack($h,pack('v',$xr->numify()));
2817       }
2818     $es = reverse $es;
2819     $es =~ s/^[0]+//;   # strip leading zeros
2820     $s .= '0x';
2821     }
2822   $s . $es;
2823   }
2824
2825 sub as_bin
2826   {
2827   # return as binary string, with prefixed 0b
2828   my $x = shift; $x = $class->new($x) if !ref($x);
2829
2830   return $x->bstr() if $x->{sign} !~ /^[+-]$/;  # inf, nan etc
2831
2832   my $es = ''; my $s = '';
2833   $s = $x->{sign} if $x->{sign} eq '-';
2834   if ($CALC->can('_as_bin'))
2835     {
2836     $es = ${$CALC->_as_bin($x->{value})};
2837     }
2838   else
2839     {
2840     return '0b0' if $x->is_zero();
2841     my $x1 = $x->copy()->babs(); my ($xr,$x10000,$b);
2842     if ($] >= 5.006)
2843       {
2844       $x10000 = Math::BigInt->new (0x10000); $b = 'b16';
2845       }
2846     else
2847       {
2848       $x10000 = Math::BigInt->new (0x1000); $b = 'b12';
2849       }
2850     while (!$x1->is_zero())
2851       {
2852       ($x1, $xr) = bdiv($x1,$x10000);
2853       $es .= unpack($b,pack('v',$xr->numify()));
2854       }
2855     $es = reverse $es;
2856     $es =~ s/^[0]+//;   # strip leading zeros
2857     $s .= '0b';
2858     }
2859   $s . $es;
2860   }
2861
2862 ##############################################################################
2863 # internal calculation routines (others are in Math::BigInt::Calc etc)
2864
2865 sub __lcm
2866   {
2867   # (BINT or num_str, BINT or num_str) return BINT
2868   # does modify first argument
2869   # LCM
2870
2871   my $x = shift; my $ty = shift;
2872   return $x->bnan() if ($x->{sign} eq $nan) || ($ty->{sign} eq $nan);
2873   return $x * $ty / bgcd($x,$ty);
2874   }
2875
2876 sub __gcd
2877   {
2878   # (BINT or num_str, BINT or num_str) return BINT
2879   # does modify both arguments
2880   # GCD -- Euclids algorithm E, Knuth Vol 2 pg 296
2881   my ($x,$ty) = @_;
2882
2883   return $x->bnan() if $x->{sign} !~ /^[+-]$/ || $ty->{sign} !~ /^[+-]$/;
2884
2885   while (!$ty->is_zero())
2886     {
2887     ($x, $ty) = ($ty,bmod($x,$ty));
2888     }
2889   $x;
2890   }
2891
2892 ###############################################################################
2893 # this method return 0 if the object can be modified, or 1 for not
2894 # We use a fast use constant statement here, to avoid costly calls. Subclasses
2895 # may override it with special code (f.i. Math::BigInt::Constant does so)
2896
2897 sub modify () { 0; }
2898
2899 1;
2900 __END__
2901
2902 =head1 NAME
2903
2904 Math::BigInt - Arbitrary size integer math package
2905
2906 =head1 SYNOPSIS
2907
2908   use Math::BigInt;
2909
2910   # or make it faster: install (optional) Math::BigInt::GMP
2911   # and always use (it will fall back to pure Perl if the
2912   # GMP library is not installed):
2913
2914   use Math::BigInt lib => 'GMP';
2915
2916   # Number creation
2917   $x = Math::BigInt->new($str);         # defaults to 0
2918   $nan  = Math::BigInt->bnan();         # create a NotANumber
2919   $zero = Math::BigInt->bzero();        # create a +0
2920   $inf = Math::BigInt->binf();          # create a +inf
2921   $inf = Math::BigInt->binf('-');       # create a -inf
2922   $one = Math::BigInt->bone();          # create a +1
2923   $one = Math::BigInt->bone('-');       # create a -1
2924
2925   # Testing (don't modify their arguments)
2926   # (return true if the condition is met, otherwise false)
2927
2928   $x->is_zero();        # if $x is +0
2929   $x->is_nan();         # if $x is NaN
2930   $x->is_one();         # if $x is +1
2931   $x->is_one('-');      # if $x is -1
2932   $x->is_odd();         # if $x is odd
2933   $x->is_even();        # if $x is even
2934   $x->is_positive();    # if $x >= 0
2935   $x->is_negative();    # if $x <  0
2936   $x->is_inf(sign);     # if $x is +inf, or -inf (sign is default '+')
2937   $x->is_int();         # if $x is an integer (not a float)
2938
2939   # comparing and digit/sign extration
2940   $x->bcmp($y);         # compare numbers (undef,<0,=0,>0)
2941   $x->bacmp($y);        # compare absolutely (undef,<0,=0,>0)
2942   $x->sign();           # return the sign, either +,- or NaN
2943   $x->digit($n);        # return the nth digit, counting from right
2944   $x->digit(-$n);       # return the nth digit, counting from left
2945
2946   # The following all modify their first argument. If you want to preserve
2947   # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
2948   # neccessary when mixing $a = $b assigments with non-overloaded math.
2949
2950   $x->bzero();          # set $x to 0
2951   $x->bnan();           # set $x to NaN
2952   $x->bone();           # set $x to +1
2953   $x->bone('-');        # set $x to -1
2954   $x->binf();           # set $x to inf
2955   $x->binf('-');        # set $x to -inf
2956
2957   $x->bneg();           # negation
2958   $x->babs();           # absolute value
2959   $x->bnorm();          # normalize (no-op in BigInt)
2960   $x->bnot();           # two's complement (bit wise not)
2961   $x->binc();           # increment $x by 1
2962   $x->bdec();           # decrement $x by 1
2963
2964   $x->badd($y);         # addition (add $y to $x)
2965   $x->bsub($y);         # subtraction (subtract $y from $x)
2966   $x->bmul($y);         # multiplication (multiply $x by $y)
2967   $x->bdiv($y);         # divide, set $x to quotient
2968                         # return (quo,rem) or quo if scalar
2969
2970   $x->bmod($y);            # modulus (x % y)
2971   $x->bmodpow($exp,$mod);  # modular exponentation (($num**$exp) % $mod))
2972   $x->bmodinv($mod);       # the inverse of $x in the given modulus $mod
2973
2974   $x->bpow($y);            # power of arguments (x ** y)
2975   $x->blsft($y);           # left shift
2976   $x->brsft($y);           # right shift
2977   $x->blsft($y,$n);        # left shift, by base $n (like 10)
2978   $x->brsft($y,$n);        # right shift, by base $n (like 10)
2979
2980   $x->band($y);            # bitwise and
2981   $x->bior($y);            # bitwise inclusive or
2982   $x->bxor($y);            # bitwise exclusive or
2983   $x->bnot();              # bitwise not (two's complement)
2984
2985   $x->bsqrt();             # calculate square-root
2986   $x->broot($y);           # $y'th root of $x (e.g. $y == 3 => cubic root)
2987   $x->bfac();              # factorial of $x (1*2*3*4*..$x)
2988
2989   $x->round($A,$P,$mode);  # round to accuracy or precision using mode $mode
2990   $x->bround($N);          # accuracy: preserve $N digits
2991   $x->bfround($N);         # round to $Nth digit, no-op for BigInts
2992
2993   # The following do not modify their arguments in BigInt (are no-ops),
2994   # but do so in BigFloat:
2995
2996   $x->bfloor();            # return integer less or equal than $x
2997   $x->bceil();             # return integer greater or equal than $x
2998
2999   # The following do not modify their arguments:
3000
3001   bgcd(@values);           # greatest common divisor (no OO style)
3002   blcm(@values);           # lowest common multiplicator (no OO style)
3003
3004   $x->length();            # return number of digits in number
3005   ($x,$f) = $x->length();  # length of number and length of fraction part,
3006                            # latter is always 0 digits long for BigInt's
3007
3008   $x->exponent();          # return exponent as BigInt
3009   $x->mantissa();          # return (signed) mantissa as BigInt
3010   $x->parts();             # return (mantissa,exponent) as BigInt
3011   $x->copy();              # make a true copy of $x (unlike $y = $x;)
3012   $x->as_number();         # return as BigInt (in BigInt: same as copy())
3013
3014   # conversation to string (do not modify their argument)
3015   $x->bstr();              # normalized string
3016   $x->bsstr();             # normalized string in scientific notation
3017   $x->as_hex();            # as signed hexadecimal string with prefixed 0x
3018   $x->as_bin();            # as signed binary string with prefixed 0b
3019
3020
3021   # precision and accuracy (see section about rounding for more)
3022   $x->precision();         # return P of $x (or global, if P of $x undef)
3023   $x->precision($n);       # set P of $x to $n
3024   $x->accuracy();          # return A of $x (or global, if A of $x undef)
3025   $x->accuracy($n);        # set A $x to $n
3026
3027   # Global methods
3028   Math::BigInt->precision(); # get/set global P for all BigInt objects
3029   Math::BigInt->accuracy();  # get/set global A for all BigInt objects
3030   Math::BigInt->config();    # return hash containing configuration
3031
3032 =head1 DESCRIPTION
3033
3034 All operators (inlcuding basic math operations) are overloaded if you
3035 declare your big integers as
3036
3037   $i = new Math::BigInt '123_456_789_123_456_789';
3038
3039 Operations with overloaded operators preserve the arguments which is
3040 exactly what you expect.
3041
3042 =over 2
3043
3044 =item Canonical notation
3045
3046 Big integer values are strings of the form C</^[+-]\d+$/> with leading
3047 zeros suppressed.
3048
3049    '-0'                            canonical value '-0', normalized '0'
3050    '   -123_123_123'               canonical value '-123123123'
3051    '1_23_456_7890'                 canonical value '1234567890'
3052
3053 =item Input
3054
3055 Input values to these routines may be either Math::BigInt objects or
3056 strings of the form C</^\s*[+-]?[\d]+\.?[\d]*E?[+-]?[\d]*$/>, or
3057 hexadecimal C</^\s*[+-]?[0-9a-f]+$/i>, or binary C</^\s*[+-]?[01]+$/>.
3058
3059 You can include one underscore between any two digits.
3060
3061 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3062 Non integer values result in NaN.
3063
3064 Math::BigInt::new() defaults to 0, while Math::BigInt::new('') results
3065 in 'NaN'.
3066
3067 bnorm() on a BigInt object is now effectively a no-op, since the numbers
3068 are always stored in normalized form. On a string, it creates a BigInt
3069 object.
3070
3071 =item Output
3072
3073 Output values are BigInt objects (normalized), except for bstr(), which
3074 returns a string in normalized form.
3075 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3076 C<is_nan()>) return true or false, while others (C<bcmp()>, C<bacmp()>)
3077 return either undef, <0, 0 or >0 and are suited for sort.
3078
3079 =back
3080
3081 =head1 METHODS
3082
3083 Each of the methods below (except config(), accuracy() and precision())
3084 accepts three additional parameters. These arguments $A, $P and $R are
3085 accuracy, precision and round_mode. Please see the section about
3086 L<ACCURACY and PRECISION> for more information.
3087
3088 =head2 config
3089
3090         use Data::Dumper;
3091
3092         print Dumper ( Math::BigInt->config() );
3093         print Math::BigInt->config()->{lib},"\n";
3094
3095 Returns a hash containing the configuration, e.g. the version number, lib
3096 loaded etc. The following hash keys are currently filled in with the
3097 appropriate information.
3098
3099         key             Description
3100                         Example
3101         ============================================================
3102         lib             Name of the Math library
3103                         Math::BigInt::Calc
3104         lib_version     Version of 'lib'
3105                         0.30
3106         class           The class of config you just called
3107                         Math::BigInt
3108         upgrade         To which class numbers are upgraded
3109                         Math::BigFloat
3110         downgrade       To which class numbers are downgraded
3111                         undef
3112         precision       Global precision
3113                         undef
3114         accuracy        Global accuracy
3115                         undef
3116         round_mode      Global round mode
3117                         even
3118         version         version number of the class you used
3119                         1.61
3120         div_scale       Fallback acccuracy for div
3121                         40
3122
3123 The following values can be set by passing config a reference to a hash:
3124
3125         trap_inf trap_nan
3126         upgrade downgrade precision accuracy round_mode div_scale
3127
3128 Example:
3129
3130         $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );
3131
3132 =head2 accuracy
3133
3134         $x->accuracy(5);                # local for $x
3135         CLASS->accuracy(5);             # global for all members of CLASS
3136         $A = $x->accuracy();            # read out
3137         $A = CLASS->accuracy();         # read out
3138
3139 Set or get the global or local accuracy, aka how many significant digits the
3140 results have.
3141
3142 Please see the section about L<ACCURACY AND PRECISION> for further details.
3143
3144 Value must be greater than zero. Pass an undef value to disable it:
3145
3146         $x->accuracy(undef);
3147         Math::BigInt->accuracy(undef);
3148
3149 Returns the current accuracy. For C<$x->accuracy()> it will return either the
3150 local accuracy, or if not defined, the global. This means the return value
3151 represents the accuracy that will be in effect for $x:
3152
3153         $y = Math::BigInt->new(1234567);        # unrounded
3154         print Math::BigInt->accuracy(4),"\n";   # set 4, print 4
3155         $x = Math::BigInt->new(123456);         # will be automatically rounded
3156         print "$x $y\n";                        # '123500 1234567'
3157         print $x->accuracy(),"\n";              # will be 4
3158         print $y->accuracy(),"\n";              # also 4, since global is 4
3159         print Math::BigInt->accuracy(5),"\n";   # set to 5, print 5
3160         print $x->accuracy(),"\n";              # still 4
3161         print $y->accuracy(),"\n";              # 5, since global is 5
3162
3163 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3164 globals separated from Math::BigInt, but it is possible to subclass
3165 Math::BigInt and make the globals of the subclass aliases to the ones from
3166 Math::BigInt.
3167
3168 =head2 precision
3169
3170         $x->precision(-2);              # local for $x, round right of the dot
3171         $x->precision(2);               # ditto, but round left of the dot
3172         CLASS->accuracy(5);             # global for all members of CLASS
3173         CLASS->precision(-5);           # ditto
3174         $P = CLASS->precision();        # read out
3175         $P = $x->precision();           # read out
3176
3177 Set or get the global or local precision, aka how many digits the result has
3178 after the dot (or where to round it when passing a positive number). In
3179 Math::BigInt, passing a negative number precision has no effect since no
3180 numbers have digits after the dot.
3181
3182 Please see the section about L<ACCURACY AND PRECISION> for further details.
3183
3184 Value must be greater than zero. Pass an undef value to disable it:
3185
3186         $x->precision(undef);
3187         Math::BigInt->precision(undef);
3188
3189 Returns the current precision. For C<$x->precision()> it will return either the
3190 local precision of $x, or if not defined, the global. This means the return
3191 value represents the accuracy that will be in effect for $x:
3192
3193         $y = Math::BigInt->new(1234567);        # unrounded
3194         print Math::BigInt->precision(4),"\n";  # set 4, print 4
3195         $x = Math::BigInt->new(123456);         # will be automatically rounded
3196
3197 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3198 globals separated from Math::BigInt, but it is possible to subclass
3199 Math::BigInt and make the globals of the subclass aliases to the ones from
3200 Math::BigInt.
3201
3202 =head2 brsft
3203
3204         $x->brsft($y,$n);
3205
3206 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3207 2, but others work, too.
3208
3209 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3210 result:
3211
3212
3213         $x = Math::BigInt->new(10);
3214         $x->brsft(1);                   # same as $x >> 1: 5
3215         $x = Math::BigInt->new(1234);
3216         $x->brsft(2,10);                # result 12
3217
3218 There is one exception, and that is base 2 with negative $x:
3219
3220
3221         $x = Math::BigInt->new(-5);
3222         print $x->brsft(1);
3223
3224 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3225 result).
3226
3227 =head2 new
3228
3229         $x = Math::BigInt->new($str,$A,$P,$R);
3230
3231 Creates a new BigInt object from a string or another BigInt object. The
3232 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3233 '0b').
3234
3235 =head2 bnan
3236
3237         $x = Math::BigInt->bnan();
3238
3239 Creates a new BigInt object representing NaN (Not A Number).
3240 If used on an object, it will set it to NaN:
3241
3242         $x->bnan();
3243
3244 =head2 bzero
3245
3246         $x = Math::BigInt->bzero();
3247
3248 Creates a new BigInt object representing zero.
3249 If used on an object, it will set it to zero:
3250
3251         $x->bzero();
3252
3253 =head2 binf
3254
3255         $x = Math::BigInt->binf($sign);
3256
3257 Creates a new BigInt object representing infinity. The optional argument is
3258 either '-' or '+', indicating whether you want infinity or minus infinity.
3259 If used on an object, it will set it to infinity:
3260
3261         $x->binf();
3262         $x->binf('-');
3263
3264 =head2 bone
3265
3266         $x = Math::BigInt->binf($sign);
3267
3268 Creates a new BigInt object representing one. The optional argument is
3269 either '-' or '+', indicating whether you want one or minus one.
3270 If used on an object, it will set it to one:
3271
3272         $x->bone();             # +1
3273         $x->bone('-');          # -1
3274
3275 =head2 is_one()/is_zero()/is_nan()/is_inf()
3276
3277
3278         $x->is_zero();                  # true if arg is +0
3279         $x->is_nan();                   # true if arg is NaN
3280         $x->is_one();                   # true if arg is +1
3281         $x->is_one('-');                # true if arg is -1
3282         $x->is_inf();                   # true if +inf
3283         $x->is_inf('-');                # true if -inf (sign is default '+')
3284
3285 These methods all test the BigInt for beeing one specific value and return
3286 true or false depending on the input. These are faster than doing something
3287 like:
3288
3289         if ($x == 0)
3290
3291 =head2 is_positive()/is_negative()
3292
3293         $x->is_positive();              # true if >= 0
3294         $x->is_negative();              # true if <  0
3295
3296 The methods return true if the argument is positive or negative, respectively.
3297 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3298 C<-inf> is negative. A C<zero> is positive.
3299
3300 These methods are only testing the sign, and not the value.
3301
3302 =head2 is_odd()/is_even()/is_int()
3303
3304         $x->is_odd();                   # true if odd, false for even
3305         $x->is_even();                  # true if even, false for odd
3306         $x->is_int();                   # true if $x is an integer
3307
3308 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3309 C<-inf> are not integers and are neither odd nor even.
3310
3311 =head2 bcmp
3312
3313         $x->bcmp($y);
3314
3315 Compares $x with $y and takes the sign into account.
3316 Returns -1, 0, 1 or undef.
3317
3318 =head2 bacmp
3319
3320         $x->bacmp($y);
3321
3322 Compares $x with $y while ignoring their. Returns -1, 0, 1 or undef.
3323
3324 =head2 sign
3325
3326         $x->sign();
3327
3328 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3329
3330 =head2 bcmp
3331
3332   $x->digit($n);                # return the nth digit, counting from right
3333
3334 =head2 bneg
3335
3336         $x->bneg();
3337
3338 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3339 and '-inf', respectively. Does nothing for NaN or zero.
3340
3341 =head2 babs
3342
3343         $x->babs();
3344
3345 Set the number to it's absolute value, e.g. change the sign from '-' to '+'
3346 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3347 numbers.
3348
3349 =head2 bnorm
3350
3351         $x->bnorm();                    # normalize (no-op)
3352
3353 =head2 bnot
3354
3355         $x->bnot();                     # two's complement (bit wise not)
3356
3357 =head2 binc
3358
3359         $x->binc();                     # increment x by 1
3360
3361 =head2 bdec
3362
3363         $x->bdec();                     # decrement x by 1
3364
3365 =head2 badd
3366
3367         $x->badd($y);                   # addition (add $y to $x)
3368
3369 =head2 bsub
3370
3371         $x->bsub($y);                   # subtraction (subtract $y from $x)
3372
3373 =head2 bmul
3374
3375         $x->bmul($y);                   # multiplication (multiply $x by $y)
3376
3377 =head2 bdiv
3378
3379         $x->bdiv($y);                   # divide, set $x to quotient
3380                                         # return (quo,rem) or quo if scalar
3381
3382 =head2 bmod
3383
3384         $x->bmod($y);                   # modulus (x % y)
3385
3386 =head2 bmodinv
3387
3388         num->bmodinv($mod);             # modular inverse
3389
3390 Returns the inverse of C<$num> in the given modulus C<$mod>.  'C<NaN>' is
3391 returned unless C<$num> is relatively prime to C<$mod>, i.e. unless
3392 C<bgcd($num, $mod)==1>.
3393
3394 =head2 bmodpow
3395
3396         $num->bmodpow($exp,$mod);       # modular exponentation
3397                                         # ($num**$exp % $mod)
3398
3399 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3400 C<$mod> using binary exponentation.  C<bmodpow> is far superior to
3401 writing
3402
3403         $num ** $exp % $mod
3404
3405 because C<bmodpow> is much faster--it reduces internal variables into
3406 the modulus whenever possible, so it operates on smaller numbers.
3407
3408 C<bmodpow> also supports negative exponents.
3409
3410         bmodpow($num, -1, $mod)
3411
3412 is exactly equivalent to
3413
3414         bmodinv($num, $mod)
3415
3416 =head2 bpow
3417
3418         $x->bpow($y);                   # power of arguments (x ** y)
3419
3420 =head2 blsft
3421
3422         $x->blsft($y);          # left shift
3423         $x->blsft($y,$n);       # left shift, in base $n (like 10)
3424
3425 =head2 brsft
3426
3427         $x->brsft($y);          # right shift
3428         $x->brsft($y,$n);       # right shift, in base $n (like 10)
3429
3430 =head2 band
3431
3432         $x->band($y);                   # bitwise and
3433
3434 =head2 bior
3435
3436         $x->bior($y);                   # bitwise inclusive or
3437
3438 =head2 bxor
3439
3440         $x->bxor($y);                   # bitwise exclusive or
3441
3442 =head2 bnot
3443
3444         $x->bnot();                     # bitwise not (two's complement)
3445
3446 =head2 bsqrt
3447
3448         $x->bsqrt();                    # calculate square-root
3449
3450 =head2 bfac
3451
3452         $x->bfac();                     # factorial of $x (1*2*3*4*..$x)
3453
3454 =head2 round
3455
3456         $x->round($A,$P,$round_mode);
3457
3458 Round $x to accuracy C<$A> or precision C<$P> using the round mode
3459 C<$round_mode>.
3460
3461 =head2 bround
3462
3463         $x->bround($N);               # accuracy: preserve $N digits
3464
3465 =head2 bfround
3466
3467         $x->bfround($N);              # round to $Nth digit, no-op for BigInts
3468
3469 =head2 bfloor
3470
3471         $x->bfloor();
3472
3473 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
3474 does change $x in BigFloat.
3475
3476 =head2 bceil
3477
3478         $x->bceil();
3479
3480 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
3481 does change $x in BigFloat.
3482
3483 =head2 bgcd
3484
3485         bgcd(@values);          # greatest common divisor (no OO style)
3486
3487 =head2 blcm
3488
3489         blcm(@values);          # lowest common multiplicator (no OO style)
3490
3491 head2 length
3492
3493         $x->length();
3494         ($xl,$fl) = $x->length();
3495
3496 Returns the number of digits in the decimal representation of the number.
3497 In list context, returns the length of the integer and fraction part. For
3498 BigInt's, the length of the fraction part will always be 0.
3499
3500 =head2 exponent
3501
3502         $x->exponent();
3503
3504 Return the exponent of $x as BigInt.
3505
3506 =head2 mantissa
3507
3508         $x->mantissa();
3509
3510 Return the signed mantissa of $x as BigInt.
3511
3512 =head2 parts
3513
3514         $x->parts();            # return (mantissa,exponent) as BigInt
3515
3516 =head2 copy
3517
3518         $x->copy();             # make a true copy of $x (unlike $y = $x;)
3519
3520 =head2 as_number
3521
3522         $x->as_number();        # return as BigInt (in BigInt: same as copy())
3523
3524 =head2 bsrt
3525
3526         $x->bstr();             # return normalized string
3527
3528 =head2 bsstr
3529
3530         $x->bsstr();            # normalized string in scientific notation
3531
3532 =head2 as_hex
3533
3534         $x->as_hex();           # as signed hexadecimal string with prefixed 0x
3535
3536 =head2 as_bin
3537
3538         $x->as_bin();           # as signed binary string with prefixed 0b
3539
3540 =head1 ACCURACY and PRECISION
3541
3542 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
3543 accuracy and precision based rounding, both automatically after every
3544 operation as well as manually.
3545
3546 This section describes the accuracy/precision handling in Math::Big* as it
3547 used to be and as it is now, complete with an explanation of all terms and
3548 abbreviations.
3549
3550 Not yet implemented things (but with correct description) are marked with '!',
3551 things that need to be answered are marked with '?'.
3552
3553 In the next paragraph follows a short description of terms used here (because
3554 these may differ from terms used by others people or documentation).
3555
3556 During the rest of this document, the shortcuts A (for accuracy), P (for
3557 precision), F (fallback) and R (rounding mode) will be used.
3558
3559 =head2 Precision P
3560
3561 A fixed number of digits before (positive) or after (negative)
3562 the decimal point. For example, 123.45 has a precision of -2. 0 means an
3563 integer like 123 (or 120). A precision of 2 means two digits to the left
3564 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
3565 numbers with zeros before the decimal point may have different precisions,
3566 because 1200 can have p = 0, 1 or 2 (depending on what the inital value
3567 was). It could also have p < 0, when the digits after the decimal point
3568 are zero.
3569
3570 The string output (of floating point numbers) will be padded with zeros:
3571
3572         Initial value   P       A       Result          String
3573         ------------------------------------------------------------
3574         1234.01         -3              1000            1000
3575         1234            -2              1200            1200
3576         1234.5          -1              1230            1230
3577         1234.001        1               1234            1234.0
3578         1234.01         0               1234            1234
3579         1234.01         2               1234.01         1234.01
3580         1234.01         5               1234.01         1234.01000
3581
3582 For BigInts, no padding occurs.
3583
3584 =head2 Accuracy A
3585
3586 Number of significant digits. Leading zeros are not counted. A
3587 number may have an accuracy greater than the non-zero digits
3588 when there are zeros in it or trailing zeros. For example, 123.456 has
3589 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
3590
3591 The string output (of floating point numbers) will be padded with zeros:
3592
3593         Initial value   P       A       Result          String
3594         ------------------------------------------------------------
3595         1234.01                 3       1230            1230
3596         1234.01                 6       1234.01         1234.01
3597         1234.1                  8       1234.1          1234.1000
3598
3599 For BigInts, no padding occurs.
3600
3601 =head2 Fallback F
3602
3603 When both A and P are undefined, this is used as a fallback accuracy when
3604 dividing numbers.
3605
3606 =head2 Rounding mode R
3607
3608 When rounding a number, different 'styles' or 'kinds'
3609 of rounding are possible. (Note that random rounding, as in
3610 Math::Round, is not implemented.)
3611
3612 =over 2
3613
3614 =item 'trunc'
3615
3616 truncation invariably removes all digits following the
3617 rounding place, replacing them with zeros. Thus, 987.65 rounded
3618 to tens (P=1) becomes 980, and rounded to the fourth sigdig
3619 becomes 987.6 (A=4). 123.456 rounded to the second place after the
3620 decimal point (P=-2) becomes 123.46.
3621
3622 All other implemented styles of rounding attempt to round to the
3623 "nearest digit." If the digit D immediately to the right of the
3624 rounding place (skipping the decimal point) is greater than 5, the
3625 number is incremented at the rounding place (possibly causing a
3626 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
3627 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
3628 truncated at the rounding place: e.g. when rounding to units, 0.4
3629 rounds to 0, and -19.4 rounds to -19.
3630
3631 However the results of other styles of rounding differ if the
3632 digit immediately to the right of the rounding place (skipping the
3633 decimal point) is 5 and if there are no digits, or no digits other
3634 than 0, after that 5. In such cases:
3635
3636 =item 'even'
3637
3638 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
3639 if it is not already. E.g., when rounding to the first sigdig, 0.45
3640 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
3641
3642 =item 'odd'
3643
3644 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
3645 it is not already. E.g., when rounding to the first sigdig, 0.45
3646 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
3647
3648 =item '+inf'
3649
3650 round to plus infinity, i.e. always round up. E.g., when
3651 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
3652 and 0.4501 also becomes 0.5.
3653
3654 =item '-inf'
3655
3656 round to minus infinity, i.e. always round down. E.g., when
3657 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
3658 but 0.4501 becomes 0.5.
3659
3660 =item 'zero'
3661
3662 round to zero, i.e. positive numbers down, negative ones up.
3663 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
3664 becomes -0.5, but 0.4501 becomes 0.5.
3665
3666 =back
3667
3668 The handling of A & P in MBI/MBF (the old core code shipped with Perl
3669 versions <= 5.7.2) is like this:
3670
3671 =over 2
3672
3673 =item Precision
3674
3675   * ffround($p) is able to round to $p number of digits after the decimal
3676     point
3677   * otherwise P is unused
3678
3679 =item Accuracy (significant digits)
3680
3681   * fround($a) rounds to $a significant digits
3682   * only fdiv() and fsqrt() take A as (optional) paramater
3683     + other operations simply create the same number (fneg etc), or more (fmul)
3684       of digits
3685     + rounding/truncating is only done when explicitly calling one of fround
3686       or ffround, and never for BigInt (not implemented)
3687   * fsqrt() simply hands its accuracy argument over to fdiv.
3688   * the documentation and the comment in the code indicate two different ways
3689     on how fdiv() determines the maximum number of digits it should calculate,
3690     and the actual code does yet another thing
3691     POD:
3692       max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
3693     Comment:
3694       result has at most max(scale, length(dividend), length(divisor)) digits
3695     Actual code:
3696       scale = max(scale, length(dividend)-1,length(divisor)-1);
3697       scale += length(divisior) - length(dividend);
3698     So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
3699     Actually, the 'difference' added to the scale is calculated from the
3700     number of "significant digits" in dividend and divisor, which is derived
3701     by looking at the length of the mantissa. Which is wrong, since it includes
3702     the + sign (oups) and actually gets 2 for '+100' and 4 for '+101'. Oups
3703     again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
3704     assumption that 124 has 3 significant digits, while 120/7 will get you
3705     '17', not '17.1' since 120 is thought to have 2 significant digits.
3706     The rounding after the division then uses the remainder and $y to determine
3707     wether it must round up or down.
3708  ?  I have no idea which is the right way. That's why I used a slightly more
3709  ?  simple scheme and tweaked the few failing testcases to match it.
3710
3711 =back
3712
3713 This is how it works now:
3714
3715 =over 2
3716
3717 =item Setting/Accessing
3718
3719   * You can set the A global via Math::BigInt->accuracy() or
3720     Math::BigFloat->accuracy() or whatever class you are using.
3721   * You can also set P globally by using Math::SomeClass->precision() likewise.
3722   * Globals are classwide, and not inherited by subclasses.
3723   * to undefine A, use Math::SomeCLass->accuracy(undef);
3724   * to undefine P, use Math::SomeClass->precision(undef);
3725   * Setting Math::SomeClass->accuracy() clears automatically
3726     Math::SomeClass->precision(), and vice versa.
3727   * To be valid, A must be > 0, P can have any value.
3728   * If P is negative, this means round to the P'th place to the right of the
3729     decimal point; positive values mean to the left of the decimal point.
3730     P of 0 means round to integer.
3731   * to find out the current global A, take Math::SomeClass->accuracy()
3732   * to find out the current global P, take Math::SomeClass->precision()
3733   * use $x->accuracy() respective $x->precision() for the local setting of $x.
3734   * Please note that $x->accuracy() respecive $x->precision() fall back to the
3735     defined globals, when $x's A or P is not set.
3736
3737 =item Creating numbers
3738
3739   * When you create a number, you can give it's desired A or P via:
3740     $x = Math::BigInt->new($number,$A,$P);
3741   * Only one of A or P can be defined, otherwise the result is NaN
3742   * If no A or P is give ($x = Math::BigInt->new($number) form), then the
3743     globals (if set) will be used. Thus changing the global defaults later on
3744     will not change the A or P of previously created numbers (i.e., A and P of
3745     $x will be what was in effect when $x was created)
3746   * If given undef for A and P, B<no> rounding will occur, and the globals will
3747     B<not> be used. This is used by subclasses to create numbers without
3748     suffering rounding in the parent. Thus a subclass is able to have it's own
3749     globals enforced upon creation of a number by using
3750     $x = Math::BigInt->new($number,undef,undef):
3751
3752         use Math::BigInt::SomeSubclass;
3753         use Math::BigInt;
3754
3755         Math::BigInt->accuracy(2);
3756         Math::BigInt::SomeSubClass->accuracy(3);
3757         $x = Math::BigInt::SomeSubClass->new(1234);
3758
3759     $x is now 1230, and not 1200. A subclass might choose to implement
3760     this otherwise, e.g. falling back to the parent's A and P.
3761
3762 =item Usage
3763
3764   * If A or P are enabled/defined, they are used to round the result of each
3765     operation according to the rules below
3766   * Negative P is ignored in Math::BigInt, since BigInts never have digits
3767     after the decimal point
3768   * Math::BigFloat uses Math::BigInts internally, but setting A or P inside
3769     Math::BigInt as globals should not tamper with the parts of a BigFloat.
3770     Thus a flag is used to mark all Math::BigFloat numbers as 'never round'
3771
3772 =item Precedence
3773
3774   * It only makes sense that a number has only one of A or P at a time.
3775     Since you can set/get both A and P, there is a rule that will practically
3776     enforce only A or P to be in effect at a time, even if both are set.
3777     This is called precedence.
3778   * If two objects are involved in an operation, and one of them has A in
3779     effect, and the other P, this results in an error (NaN).
3780   * A takes precendence over P (Hint: A comes before P). If A is defined, it
3781     is used, otherwise P is used. If neither of them is defined, nothing is
3782     used, i.e. the result will have as many digits as it can (with an
3783     exception for fdiv/fsqrt) and will not be rounded.
3784   * There is another setting for fdiv() (and thus for fsqrt()). If neither of
3785     A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
3786     If either the dividend's or the divisor's mantissa has more digits than
3787     the value of F, the higher value will be used instead of F.
3788     This is to limit the digits (A) of the result (just consider what would
3789     happen with unlimited A and P in the case of 1/3 :-)
3790   * fdiv will calculate (at least) 4 more digits than required (determined by
3791     A, P or F), and, if F is not used, round the result
3792     (this will still fail in the case of a result like 0.12345000000001 with A
3793     or P of 5, but this can not be helped - or can it?)
3794   * Thus you can have the math done by on Math::Big* class in three modes:
3795     + never round (this is the default):
3796       This is done by setting A and P to undef. No math operation
3797       will round the result, with fdiv() and fsqrt() as exceptions to guard
3798       against overflows. You must explicitely call bround(), bfround() or
3799       round() (the latter with parameters).
3800       Note: Once you have rounded a number, the settings will 'stick' on it
3801       and 'infect' all other numbers engaged in math operations with it, since
3802       local settings have the highest precedence. So, to get SaferRound[tm],
3803       use a copy() before rounding like this:
3804
3805         $x = Math::BigFloat->new(12.34);
3806         $y = Math::BigFloat->new(98.76);
3807         $z = $x * $y;                           # 1218.6984
3808         print $x->copy()->fround(3);            # 12.3 (but A is now 3!)
3809         $z = $x * $y;                           # still 1218.6984, without
3810                                                 # copy would have been 1210!
3811
3812     + round after each op:
3813       After each single operation (except for testing like is_zero()), the
3814       method round() is called and the result is rounded appropriately. By
3815       setting proper values for A and P, you can have all-the-same-A or
3816       all-the-same-P modes. For example, Math::Currency might set A to undef,
3817       and P to -2, globally.
3818
3819  ?Maybe an extra option that forbids local A & P settings would be in order,
3820  ?so that intermediate rounding does not 'poison' further math?
3821
3822 =item Overriding globals
3823
3824   * you will be able to give A, P and R as an argument to all the calculation
3825     routines; the second parameter is A, the third one is P, and the fourth is
3826     R (shift right by one for binary operations like badd). P is used only if
3827     the first parameter (A) is undefined. These three parameters override the
3828     globals in the order detailed as follows, i.e. the first defined value
3829     wins:
3830     (local: per object, global: global default, parameter: argument to sub)
3831       + parameter A
3832       + parameter P
3833       + local A (if defined on both of the operands: smaller one is taken)
3834       + local P (if defined on both of the operands: bigger one is taken)
3835       + global A
3836       + global P
3837       + global F
3838   * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
3839     arguments (A and P) instead of one
3840
3841 =item Local settings
3842
3843   * You can set A and P locally by using $x->accuracy() and $x->precision()
3844     and thus force different A and P for different objects/numbers.
3845   * Setting A or P this way immediately rounds $x to the new value.
3846   * $x->accuracy() clears $x->precision(), and vice versa.
3847
3848 =item Rounding
3849
3850   * the rounding routines will use the respective global or local settings.
3851     fround()/bround() is for accuracy rounding, while ffround()/bfround()
3852     is for precision
3853   * the two rounding functions take as the second parameter one of the
3854     following rounding modes (R):
3855     'even', 'odd', '+inf', '-inf', 'zero', 'trunc'
3856   * you can set and get the global R by using Math::SomeClass->round_mode()
3857     or by setting $Math::SomeClass::round_mode
3858   * after each operation, $result->round() is called, and the result may
3859     eventually be rounded (that is, if A or P were set either locally,
3860     globally or as parameter to the operation)
3861   * to manually round a number, call $x->round($A,$P,$round_mode);
3862     this will round the number by using the appropriate rounding function
3863     and then normalize it.
3864   * rounding modifies the local settings of the number:
3865
3866         $x = Math::BigFloat->new(123.456);
3867         $x->accuracy(5);
3868         $x->bround(4);
3869
3870     Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
3871     will be 4 from now on.
3872
3873 =item Default values
3874
3875   * R: 'even'
3876   * F: 40
3877   * A: undef
3878   * P: undef
3879
3880 =item Remarks
3881
3882   * The defaults are set up so that the new code gives the same results as
3883     the old code (except in a few cases on fdiv):
3884     + Both A and P are undefined and thus will not be used for rounding
3885       after each operation.
3886     + round() is thus a no-op, unless given extra parameters A and P
3887
3888 =back
3889
3890 =head1 INTERNALS
3891
3892 The actual numbers are stored as unsigned big integers (with seperate sign).
3893 You should neither care about nor depend on the internal representation; it
3894 might change without notice. Use only method calls like C<< $x->sign(); >>
3895 instead relying on the internal hash keys like in C<< $x->{sign}; >>.
3896
3897 =head2 MATH LIBRARY
3898
3899 Math with the numbers is done (by default) by a module called
3900 Math::BigInt::Calc. This is equivalent to saying:
3901
3902         use Math::BigInt lib => 'Calc';
3903
3904 You can change this by using:
3905
3906         use Math::BigInt lib => 'BitVect';
3907
3908 The following would first try to find Math::BigInt::Foo, then
3909 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
3910
3911         use Math::BigInt lib => 'Foo,Math::BigInt::Bar';
3912
3913 Calc.pm uses as internal format an array of elements of some decimal base
3914 (usually 1e5 or 1e7) with the least significant digit first, while BitVect.pm
3915 uses a bit vector of base 2, most significant bit first. Other modules might
3916 use even different means of representing the numbers. See the respective
3917 module documentation for further details.
3918
3919 =head2 SIGN
3920
3921 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
3922
3923 A sign of 'NaN' is used to represent the result when input arguments are not
3924 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
3925 minus infinity. You will get '+inf' when dividing a positive number by 0, and
3926 '-inf' when dividing any negative number by 0.
3927
3928 =head2 mantissa(), exponent() and parts()
3929
3930 C<mantissa()> and C<exponent()> return the said parts of the BigInt such
3931 that:
3932
3933         $m = $x->mantissa();
3934         $e = $x->exponent();
3935         $y = $m * ( 10 ** $e );
3936         print "ok\n" if $x == $y;
3937
3938 C<< ($m,$e) = $x->parts() >> is just a shortcut that gives you both of them
3939 in one go. Both the returned mantissa and exponent have a sign.
3940
3941 Currently, for BigInts C<$e> will be always 0, except for NaN, +inf and -inf,
3942 where it will be NaN; and for $x == 0, where it will be 1
3943 (to be compatible with Math::BigFloat's internal representation of a zero as
3944 C<0E1>).
3945
3946 C<$m> will always be a copy of the original number. The relation between $e
3947 and $m might change in the future, but will always be equivalent in a
3948 numerical sense, e.g. $m might get minimized.
3949
3950 =head1 EXAMPLES
3951
3952   use Math::BigInt;
3953
3954   sub bint { Math::BigInt->new(shift); }
3955
3956   $x = Math::BigInt->bstr("1234")       # string "1234"
3957   $x = "$x";                            # same as bstr()
3958   $x = Math::BigInt->bneg("1234");      # BigInt "-1234"
3959   $x = Math::BigInt->babs("-12345");    # BigInt "12345"
3960   $x = Math::BigInt->bnorm("-0 00");    # BigInt "0"
3961   $x = bint(1) + bint(2);               # BigInt "3"
3962   $x = bint(1) + "2";                   # ditto (auto-BigIntify of "2")
3963   $x = bint(1);                         # BigInt "1"
3964   $x = $x + 5 / 2;                      # BigInt "3"
3965   $x = $x ** 3;                         # BigInt "27"
3966   $x *= 2;                              # BigInt "54"
3967   $x = Math::BigInt->new(0);            # BigInt "0"
3968   $x--;                                 # BigInt "-1"
3969   $x = Math::BigInt->badd(4,5)          # BigInt "9"
3970   print $x->bsstr();                    # 9e+0
3971
3972 Examples for rounding:
3973
3974   use Math::BigFloat;
3975   use Test;
3976
3977   $x = Math::BigFloat->new(123.4567);
3978   $y = Math::BigFloat->new(123.456789);
3979   Math::BigFloat->accuracy(4);          # no more A than 4
3980
3981   ok ($x->copy()->fround(),123.4);      # even rounding
3982   print $x->copy()->fround(),"\n";      # 123.4
3983   Math::BigFloat->round_mode('odd');    # round to odd
3984   print $x->copy()->fround(),"\n";      # 123.5
3985   Math::BigFloat->accuracy(5);          # no more A than 5
3986   Math::BigFloat->round_mode('odd');    # round to odd
3987   print $x->copy()->fround(),"\n";      # 123.46
3988   $y = $x->copy()->fround(4),"\n";      # A = 4: 123.4
3989   print "$y, ",$y->accuracy(),"\n";     # 123.4, 4
3990
3991   Math::BigFloat->accuracy(undef);      # A not important now
3992   Math::BigFloat->precision(2);         # P important
3993   print $x->copy()->bnorm(),"\n";       # 123.46
3994   print $x->copy()->fround(),"\n";      # 123.46
3995
3996 Examples for converting:
3997
3998   my $x = Math::BigInt->new('0b1'.'01' x 123);
3999   print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
4000
4001 =head1 Autocreating constants
4002
4003 After C<use Math::BigInt ':constant'> all the B<integer> decimal, hexadecimal
4004 and binary constants in the given scope are converted to C<Math::BigInt>.
4005 This conversion happens at compile time.
4006
4007 In particular,
4008
4009   perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'
4010
4011 prints the integer value of C<2**100>. Note that without conversion of
4012 constants the expression 2**100 will be calculated as perl scalar.
4013
4014 Please note that strings and floating point constants are not affected,
4015 so that
4016
4017         use Math::BigInt qw/:constant/;
4018
4019         $x = 1234567890123456789012345678901234567890
4020                 + 123456789123456789;
4021         $y = '1234567890123456789012345678901234567890'
4022                 + '123456789123456789';
4023
4024 do not work. You need an explicit Math::BigInt->new() around one of the
4025 operands. You should also quote large constants to protect loss of precision:
4026
4027         use Math::BigInt;
4028
4029         $x = Math::BigInt->new('1234567889123456789123456789123456789');
4030
4031 Without the quotes Perl would convert the large number to a floating point
4032 constant at compile time and then hand the result to BigInt, which results in
4033 an truncated result or a NaN.
4034
4035 This also applies to integers that look like floating point constants:
4036
4037         use Math::BigInt ':constant';
4038
4039         print ref(123e2),"\n";
4040         print ref(123.2e2),"\n";
4041
4042 will print nothing but newlines. Use either L<bignum> or L<Math::BigFloat>
4043 to get this to work.
4044
4045 =head1 PERFORMANCE
4046
4047 Using the form $x += $y; etc over $x = $x + $y is faster, since a copy of $x
4048 must be made in the second case. For long numbers, the copy can eat up to 20%
4049 of the work (in the case of addition/subtraction, less for
4050 multiplication/division). If $y is very small compared to $x, the form
4051 $x += $y is MUCH faster than $x = $x + $y since making the copy of $x takes
4052 more time then the actual addition.
4053
4054 With a technique called copy-on-write, the cost of copying with overload could
4055 be minimized or even completely avoided. A test implementation of COW did show
4056 performance gains for overloaded math, but introduced a performance loss due
4057 to a constant overhead for all other operatons.
4058
4059 The rewritten version of this module is slower on certain operations, like
4060 new(), bstr() and numify(). The reason are that it does now more work and
4061 handles more cases. The time spent in these operations is usually gained in
4062 the other operations so that programs on the average should get faster. If
4063 they don't, please contect the author.
4064
4065 Some operations may be slower for small numbers, but are significantly faster
4066 for big numbers. Other operations are now constant (O(1), like bneg(), babs()
4067 etc), instead of O(N) and thus nearly always take much less time. These
4068 optimizations were done on purpose.
4069
4070 If you find the Calc module to slow, try to install any of the replacement
4071 modules and see if they help you.
4072
4073 =head2 Alternative math libraries
4074
4075 You can use an alternative library to drive Math::BigInt via:
4076
4077         use Math::BigInt lib => 'Module';
4078
4079 See L<MATH LIBRARY> for more information.
4080
4081 For more benchmark results see L<http://bloodgate.com/perl/benchmarks.html>.
4082
4083 =head2 SUBCLASSING
4084
4085 =head1 Subclassing Math::BigInt
4086
4087 The basic design of Math::BigInt allows simple subclasses with very little
4088 work, as long as a few simple rules are followed:
4089
4090 =over 2
4091
4092 =item *
4093
4094 The public API must remain consistent, i.e. if a sub-class is overloading
4095 addition, the sub-class must use the same name, in this case badd(). The
4096 reason for this is that Math::BigInt is optimized to call the object methods
4097 directly.
4098
4099 =item *
4100
4101 The private object hash keys like C<$x->{sign}> may not be changed, but
4102 additional keys can be added, like C<$x->{_custom}>.
4103
4104 =item *
4105
4106 Accessor functions are available for all existing object hash keys and should
4107 be used instead of directly accessing the internal hash keys. The reason for
4108 this is that Math::BigInt itself has a pluggable interface which permits it
4109 to support different storage methods.
4110
4111 =back
4112
4113 More complex sub-classes may have to replicate more of the logic internal of
4114 Math::BigInt if they need to change more basic behaviors. A subclass that
4115 needs to merely change the output only needs to overload C<bstr()>.
4116
4117 All other object methods and overloaded functions can be directly inherited
4118 from the parent class.
4119
4120 At the very minimum, any subclass will need to provide it's own C<new()> and can
4121 store additional hash keys in the object. There are also some package globals
4122 that must be defined, e.g.:
4123
4124   # Globals
4125   $accuracy = undef;
4126   $precision = -2;       # round to 2 decimal places
4127   $round_mode = 'even';
4128   $div_scale = 40;
4129
4130 Additionally, you might want to provide the following two globals to allow
4131 auto-upgrading and auto-downgrading to work correctly:
4132
4133   $upgrade = undef;
4134   $downgrade = undef;
4135
4136 This allows Math::BigInt to correctly retrieve package globals from the
4137 subclass, like C<$SubClass::precision>.  See t/Math/BigInt/Subclass.pm or
4138 t/Math/BigFloat/SubClass.pm completely functional subclass examples.
4139
4140 Don't forget to
4141
4142         use overload;
4143
4144 in your subclass to automatically inherit the overloading from the parent. If
4145 you like, you can change part of the overloading, look at Math::String for an
4146 example.
4147
4148 =head1 UPGRADING
4149
4150 When used like this:
4151
4152         use Math::BigInt upgrade => 'Foo::Bar';
4153
4154 certain operations will 'upgrade' their calculation and thus the result to
4155 the class Foo::Bar. Usually this is used in conjunction with Math::BigFloat:
4156
4157         use Math::BigInt upgrade => 'Math::BigFloat';
4158
4159 As a shortcut, you can use the module C<bignum>:
4160
4161         use bignum;
4162
4163 Also good for oneliners:
4164
4165         perl -Mbignum -le 'print 2 ** 255'
4166
4167 This makes it possible to mix arguments of different classes (as in 2.5 + 2)
4168 as well es preserve accuracy (as in sqrt(3)).
4169
4170 Beware: This feature is not fully implemented yet.
4171
4172 =head2 Auto-upgrade
4173
4174 The following methods upgrade themselves unconditionally; that is if upgrade
4175 is in effect, they will always hand up their work:
4176
4177 =over 2
4178
4179 =item bsqrt()
4180
4181 =item div()
4182
4183 =item blog()
4184
4185 =back
4186
4187 Beware: This list is not complete.
4188
4189 All other methods upgrade themselves only when one (or all) of their
4190 arguments are of the class mentioned in $upgrade (This might change in later
4191 versions to a more sophisticated scheme):
4192
4193 =head1 BUGS
4194
4195 =over 2
4196
4197 =item broot() does not work
4198
4199 The broot() function in BigInt may only work for small values. This will be
4200 fixed in a later version.
4201
4202 =item Out of Memory!
4203
4204 Under Perl prior to 5.6.0 having an C<use Math::BigInt ':constant';> and
4205 C<eval()> in your code will crash with "Out of memory". This is probably an
4206 overload/exporter bug. You can workaround by not having C<eval()>
4207 and ':constant' at the same time or upgrade your Perl to a newer version.
4208
4209 =item Fails to load Calc on Perl prior 5.6.0
4210
4211 Since eval(' use ...') can not be used in conjunction with ':constant', BigInt
4212 will fall back to eval { require ... } when loading the math lib on Perls
4213 prior to 5.6.0. This simple replaces '::' with '/' and thus might fail on
4214 filesystems using a different seperator.
4215
4216 =back
4217
4218 =head1 CAVEATS
4219
4220 Some things might not work as you expect them. Below is documented what is
4221 known to be troublesome:
4222
4223 =over 1
4224
4225 =item stringify, bstr(), bsstr() and 'cmp'
4226
4227 Both stringify and bstr() now drop the leading '+'. The old code would return
4228 '+3', the new returns '3'. This is to be consistent with Perl and to make
4229 cmp (especially with overloading) to work as you expect. It also solves
4230 problems with Test.pm, it's ok() uses 'eq' internally.
4231
4232 Mark said, when asked about to drop the '+' altogether, or make only cmp work:
4233
4234         I agree (with the first alternative), don't add the '+' on positive
4235         numbers.  It's not as important anymore with the new internal
4236         form for numbers.  It made doing things like abs and neg easier,
4237         but those have to be done differently now anyway.
4238
4239 So, the following examples will now work all as expected:
4240
4241         use Test;
4242         BEGIN { plan tests => 1 }
4243         use Math::BigInt;
4244
4245         my $x = new Math::BigInt 3*3;
4246         my $y = new Math::BigInt 3*3;
4247
4248         ok ($x,3*3);
4249         print "$x eq 9" if $x eq $y;
4250         print "$x eq 9" if $x eq '9';
4251         print "$x eq 9" if $x eq 3*3;
4252
4253 Additionally, the following still works:
4254
4255         print "$x == 9" if $x == $y;
4256         print "$x == 9" if $x == 9;
4257         print "$x == 9" if $x == 3*3;
4258
4259 There is now a C<bsstr()> method to get the string in scientific notation aka
4260 C<1e+2> instead of C<100>. Be advised that overloaded 'eq' always uses bstr()
4261 for comparisation, but Perl will represent some numbers as 100 and others
4262 as 1e+308. If in doubt, convert both arguments to Math::BigInt before doing eq:
4263
4264         use Test;
4265         BEGIN { plan tests => 3 }
4266         use Math::BigInt;
4267
4268         $x = Math::BigInt->new('1e56'); $y = 1e56;
4269         ok ($x,$y);                     # will fail
4270         ok ($x->bsstr(),$y);            # okay
4271         $y = Math::BigInt->new($y);
4272         ok ($x,$y);                     # okay
4273
4274 Alternatively, simple use <=> for comparisations, that will get it always
4275 right. There is not yet a way to get a number automatically represented as
4276 a string that matches exactly the way Perl represents it.
4277
4278 =item int()
4279
4280 C<int()> will return (at least for Perl v5.7.1 and up) another BigInt, not a
4281 Perl scalar:
4282
4283         $x = Math::BigInt->new(123);
4284         $y = int($x);                           # BigInt 123
4285         $x = Math::BigFloat->new(123.45);
4286         $y = int($x);                           # BigInt 123
4287
4288 In all Perl versions you can use C<as_number()> for the same effect:
4289
4290         $x = Math::BigFloat->new(123.45);
4291         $y = $x->as_number();                   # BigInt 123
4292
4293 This also works for other subclasses, like Math::String.
4294
4295 It is yet unlcear whether overloaded int() should return a scalar or a BigInt.
4296
4297 =item length
4298
4299 The following will probably not do what you expect:
4300
4301         $c = Math::BigInt->new(123);
4302         print $c->length(),"\n";                # prints 30
4303
4304 It prints both the number of digits in the number and in the fraction part
4305 since print calls C<length()> in list context. Use something like:
4306
4307         print scalar $c->length(),"\n";         # prints 3
4308
4309 =item bdiv
4310
4311 The following will probably not do what you expect:
4312
4313         print $c->bdiv(10000),"\n";
4314
4315 It prints both quotient and remainder since print calls C<bdiv()> in list
4316 context. Also, C<bdiv()> will modify $c, so be carefull. You probably want
4317 to use
4318
4319         print $c / 10000,"\n";
4320         print scalar $c->bdiv(10000),"\n";  # or if you want to modify $c
4321
4322 instead.
4323
4324 The quotient is always the greatest integer less than or equal to the
4325 real-valued quotient of the two operands, and the remainder (when it is
4326 nonzero) always has the same sign as the second operand; so, for
4327 example,
4328
4329           1 / 4  => ( 0, 1)
4330           1 / -4 => (-1,-3)
4331          -3 / 4  => (-1, 1)
4332          -3 / -4 => ( 0,-3)
4333         -11 / 2  => (-5,1)
4334          11 /-2  => (-5,-1)
4335
4336 As a consequence, the behavior of the operator % agrees with the
4337 behavior of Perl's built-in % operator (as documented in the perlop
4338 manpage), and the equation
4339
4340         $x == ($x / $y) * $y + ($x % $y)
4341
4342 holds true for any $x and $y, which justifies calling the two return
4343 values of bdiv() the quotient and remainder. The only exception to this rule
4344 are when $y == 0 and $x is negative, then the remainder will also be
4345 negative. See below under "infinity handling" for the reasoning behing this.
4346
4347 Perl's 'use integer;' changes the behaviour of % and / for scalars, but will
4348 not change BigInt's way to do things. This is because under 'use integer' Perl
4349 will do what the underlying C thinks is right and this is different for each
4350 system. If you need BigInt's behaving exactly like Perl's 'use integer', bug
4351 the author to implement it ;)
4352
4353 =item infinity handling
4354
4355 Here are some examples that explain the reasons why certain results occur while
4356 handling infinity:
4357
4358 The following table shows the result of the division and the remainder, so that
4359 the equation above holds true. Some "ordinary" cases are strewn in to show more
4360 clearly the reasoning:
4361
4362         A /  B  =   C,     R so that C *    B +    R =    A
4363      =========================================================
4364         5 /   8 =   0,     5         0 *    8 +    5 =    5
4365         0 /   8 =   0,     0         0 *    8 +    0 =    0
4366         0 / inf =   0,     0         0 *  inf +    0 =    0
4367         0 /-inf =   0,     0         0 * -inf +    0 =    0
4368         5 / inf =   0,     5         0 *  inf +    5 =    5
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        inf/   5 =  inf,    0       inf *    5 +    0 =  inf
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          5/   5 =    1,    0         1 *    5 +    0 =    5
4377         -5/  -5 =    1,    0         1 *   -5 +    0 =   -5
4378        inf/ inf =    1,    0         1 *  inf +    0 =  inf
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          8/   0 =  inf,    8       inf *    0 +    8 =    8
4383        inf/   0 =  inf,  inf       inf *    0 +  inf =  inf
4384          0/   0 =  NaN
4385
4386 These cases below violate the "remainder has the sign of the second of the two
4387 arguments", since they wouldn't match up otherwise.
4388
4389         A /  B  =   C,     R so that C *    B +    R =    A
4390      ========================================================
4391       -inf/   0 = -inf, -inf      -inf *    0 +  inf = -inf
4392         -8/   0 = -inf,   -8      -inf *    0 +    8 = -8
4393
4394 =item Modifying and =
4395
4396 Beware of:
4397
4398         $x = Math::BigFloat->new(5);
4399         $y = $x;
4400
4401 It will not do what you think, e.g. making a copy of $x. Instead it just makes
4402 a second reference to the B<same> object and stores it in $y. Thus anything
4403 that modifies $x (except overloaded operators) will modify $y, and vice versa.
4404 Or in other words, C<=> is only safe if you modify your BigInts only via
4405 overloaded math. As soon as you use a method call it breaks:
4406
4407         $x->bmul(2);
4408         print "$x, $y\n";       # prints '10, 10'
4409
4410 If you want a true copy of $x, use:
4411
4412         $y = $x->copy();
4413
4414 You can also chain the calls like this, this will make first a copy and then
4415 multiply it by 2:
4416
4417         $y = $x->copy()->bmul(2);
4418
4419 See also the documentation for overload.pm regarding C<=>.
4420
4421 =item bpow
4422
4423 C<bpow()> (and the rounding functions) now modifies the first argument and
4424 returns it, unlike the old code which left it alone and only returned the
4425 result. This is to be consistent with C<badd()> etc. The first three will
4426 modify $x, the last one won't:
4427
4428         print bpow($x,$i),"\n";         # modify $x
4429         print $x->bpow($i),"\n";        # ditto
4430         print $x **= $i,"\n";           # the same
4431         print $x ** $i,"\n";            # leave $x alone
4432
4433 The form C<$x **= $y> is faster than C<$x = $x ** $y;>, though.
4434
4435 =item Overloading -$x
4436
4437 The following:
4438
4439         $x = -$x;
4440
4441 is slower than
4442
4443         $x->bneg();
4444
4445 since overload calls C<sub($x,0,1);> instead of C<neg($x)>. The first variant
4446 needs to preserve $x since it does not know that it later will get overwritten.
4447 This makes a copy of $x and takes O(N), but $x->bneg() is O(1).
4448
4449 With Copy-On-Write, this issue would be gone, but C-o-W is not implemented
4450 since it is slower for all other things.
4451
4452 =item Mixing different object types
4453
4454 In Perl you will get a floating point value if you do one of the following:
4455
4456         $float = 5.0 + 2;
4457         $float = 2 + 5.0;
4458         $float = 5 / 2;
4459
4460 With overloaded math, only the first two variants will result in a BigFloat:
4461
4462         use Math::BigInt;
4463         use Math::BigFloat;
4464
4465         $mbf = Math::BigFloat->new(5);
4466         $mbi2 = Math::BigInteger->new(5);
4467         $mbi = Math::BigInteger->new(2);
4468
4469                                         # what actually gets called:
4470         $float = $mbf + $mbi;           # $mbf->badd()
4471         $float = $mbf / $mbi;           # $mbf->bdiv()
4472         $integer = $mbi + $mbf;         # $mbi->badd()
4473         $integer = $mbi2 / $mbi;        # $mbi2->bdiv()
4474         $integer = $mbi2 / $mbf;        # $mbi2->bdiv()
4475
4476 This is because math with overloaded operators follows the first (dominating)
4477 operand, and the operation of that is called and returns thus the result. So,
4478 Math::BigInt::bdiv() will always return a Math::BigInt, regardless whether
4479 the result should be a Math::BigFloat or the second operant is one.
4480
4481 To get a Math::BigFloat you either need to call the operation manually,
4482 make sure the operands are already of the proper type or casted to that type
4483 via Math::BigFloat->new():
4484
4485         $float = Math::BigFloat->new($mbi2) / $mbi;     # = 2.5
4486
4487 Beware of simple "casting" the entire expression, this would only convert
4488 the already computed result:
4489
4490         $float = Math::BigFloat->new($mbi2 / $mbi);     # = 2.0 thus wrong!
4491
4492 Beware also of the order of more complicated expressions like:
4493
4494         $integer = ($mbi2 + $mbi) / $mbf;               # int / float => int
4495         $integer = $mbi2 / Math::BigFloat->new($mbi);   # ditto
4496
4497 If in doubt, break the expression into simpler terms, or cast all operands
4498 to the desired resulting type.
4499
4500 Scalar values are a bit different, since:
4501
4502         $float = 2 + $mbf;
4503         $float = $mbf + 2;
4504
4505 will both result in the proper type due to the way the overloaded math works.
4506
4507 This section also applies to other overloaded math packages, like Math::String.
4508
4509 One solution to you problem might be autoupgrading|upgrading. See the
4510 pragmas L<bignum>, L<bigint> and L<bigrat> for an easy way to do this.
4511
4512 =item bsqrt()
4513
4514 C<bsqrt()> works only good if the result is a big integer, e.g. the square
4515 root of 144 is 12, but from 12 the square root is 3, regardless of rounding
4516 mode. The reason is that the result is always truncated to an integer.
4517
4518 If you want a better approximation of the square root, then use:
4519
4520         $x = Math::BigFloat->new(12);
4521         Math::BigFloat->precision(0);
4522         Math::BigFloat->round_mode('even');
4523         print $x->copy->bsqrt(),"\n";           # 4
4524
4525         Math::BigFloat->precision(2);
4526         print $x->bsqrt(),"\n";                 # 3.46
4527         print $x->bsqrt(3),"\n";                # 3.464
4528
4529 =item brsft()
4530
4531 For negative numbers in base see also L<brsft|brsft>.
4532
4533 =back
4534
4535 =head1 LICENSE
4536
4537 This program is free software; you may redistribute it and/or modify it under
4538 the same terms as Perl itself.
4539
4540 =head1 SEE ALSO
4541
4542 L<Math::BigFloat>, L<Math::BigRat> and L<Math::Big> as well as
4543 L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
4544
4545 The pragmas L<bignum>, L<bigint> and L<bigrat> also might be of interest
4546 because they solve the autoupgrading/downgrading issue, at least partly.
4547
4548 The package at
4549 L<http://search.cpan.org/search?mode=module&query=Math%3A%3ABigInt> contains
4550 more documentation including a full version history, testcases, empty
4551 subclass files and benchmarks.
4552
4553 =head1 AUTHORS
4554
4555 Original code by Mark Biggar, overloaded interface by Ilya Zakharevich.
4556 Completely rewritten by Tels http://bloodgate.com in late 2000, 2001, 2002
4557 and still at it in 2003.
4558
4559 Many people contributed in one or more ways to the final beast, see the file
4560 CREDITS for an (uncomplete) list. If you miss your name, please drop me a
4561 mail. Thank you!
4562
4563 =cut