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