[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/Math/ -> BigInt.pm (source)

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