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