3 # Qs: what exactly happens on numify of HUGE numbers? overflow?
4 # $a = -$a is much slower (making copy of $a) than $a->bneg(), hm!?
5 # (copy_on_write will help there, but that is not yet implemented)
7 # The following hash values are used:
8 # value: unsigned int with actual value (as a Math::BigInt::Calc or similiar)
9 # sign : +,-,NaN,+inf,-inf
12 # _f : flags, used by MBF to flag parts of a float as untouchable
13 # _cow : copy on write: number of objects that share the data (NRY)
15 # Remember not to take shortcuts ala $xs = $x->{value}; $CALC->foo($xs); since
16 # underlying lib might change the reference!
19 my $class = "Math::BigInt";
24 @ISA = qw( Exporter );
25 @EXPORT_OK = qw( bneg babs bcmp badd bmul bdiv bmod bnorm bsub
28 blsft brsft band bior bxor bnot bpow bnan bzero
29 bacmp bstr bsstr binc bdec binf bfloor bceil
30 is_odd is_even is_zero is_one is_nan is_inf sign
31 is_positive is_negative
36 use vars qw/$round_mode $accuracy $precision $div_scale/;
39 # Inside overload, the first arg is always an object. If the original code had
40 # it reversed (like $x = 2 * $y), then the third paramater indicates this
41 # swapping. To make it work, we use a helper routine which not only reswaps the
42 # params, but also makes a new object in this case. See _swap() for details,
43 # especially the cases of operators with different classes.
45 # For overloaded ops with only one argument we simple use $_[0]->copy() to
46 # preserve the argument.
48 # Thus inheritance of overload operators becomes possible and transparent for
49 # our subclasses without the need to repeat the entire overload section there.
52 '=' => sub { $_[0]->copy(); },
54 # '+' and '-' do not use _swap, since it is a triffle slower. If you want to
55 # override _swap (if ever), then override overload of '+' and '-', too!
56 # for sub it is a bit tricky to keep b: b-a => -a+b
57 '-' => sub { my $c = $_[0]->copy; $_[2] ?
58 $c->bneg()->badd($_[1]) :
60 '+' => sub { $_[0]->copy()->badd($_[1]); },
62 # some shortcuts for speed (assumes that reversed order of arguments is routed
63 # to normal '+' and we thus can always modify first arg. If this is changed,
64 # this breaks and must be adjusted.)
65 '+=' => sub { $_[0]->badd($_[1]); },
66 '-=' => sub { $_[0]->bsub($_[1]); },
67 '*=' => sub { $_[0]->bmul($_[1]); },
68 '/=' => sub { scalar $_[0]->bdiv($_[1]); },
69 '**=' => sub { $_[0]->bpow($_[1]); },
71 '<=>' => sub { $_[2] ?
72 ref($_[0])->bcmp($_[1],$_[0]) :
73 ref($_[0])->bcmp($_[0],$_[1])},
76 $_[1] cmp $_[0]->bstr() :
77 $_[0]->bstr() cmp $_[1] },
79 'int' => sub { $_[0]->copy(); },
80 'neg' => sub { $_[0]->copy()->bneg(); },
81 'abs' => sub { $_[0]->copy()->babs(); },
82 '~' => sub { $_[0]->copy()->bnot(); },
84 '*' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->bmul($a[1]); },
85 '/' => sub { my @a = ref($_[0])->_swap(@_);scalar $a[0]->bdiv($a[1]);},
86 '%' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->bmod($a[1]); },
87 '**' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->bpow($a[1]); },
88 '<<' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->blsft($a[1]); },
89 '>>' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->brsft($a[1]); },
91 '&' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->band($a[1]); },
92 '|' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->bior($a[1]); },
93 '^' => sub { my @a = ref($_[0])->_swap(@_); $a[0]->bxor($a[1]); },
95 # can modify arg of ++ and --, so avoid a new-copy for speed, but don't
96 # use $_[0]->__one(), it modifies $_[0] to be 1!
97 '++' => sub { $_[0]->binc() },
98 '--' => sub { $_[0]->bdec() },
100 # if overloaded, O(1) instead of O(N) and twice as fast for small numbers
102 # this kludge is needed for perl prior 5.6.0 since returning 0 here fails :-/
103 # v5.6.1 dumps on that: return !$_[0]->is_zero() || undef; :-(
104 my $t = !$_[0]->is_zero();
111 0+ numify), # Order of arguments unsignificant
114 ##############################################################################
115 # global constants, flags and accessory
117 use constant MB_NEVER_ROUND => 0x0001;
119 my $NaNOK=1; # are NaNs ok?
120 my $nan = 'NaN'; # constants for easier life
122 my $CALC = 'Math::BigInt::Calc'; # module to do low level math
123 sub _core_lib () { return $CALC; } # for test suite
125 $round_mode = 'even'; # one of 'even', 'odd', '+inf', '-inf', 'zero' or 'trunc'
133 # make Class->round_mode() work
135 my $class = ref($self) || $self || __PACKAGE__;
139 die "Unknown round mode $m"
140 if $m !~ /^(even|odd|\+inf|\-inf|zero|trunc)$/;
141 ${"${class}::round_mode"} = $m; return $m;
143 return ${"${class}::round_mode"};
149 # make Class->round_mode() work
151 my $class = ref($self) || $self || __PACKAGE__;
154 die ('div_scale must be greater than zero') if $_[0] < 0;
155 ${"${class}::div_scale"} = shift;
157 return ${"${class}::div_scale"};
162 # $x->accuracy($a); ref($x) $a
163 # $x->accuracy(); ref($x)
164 # Class->accuracy(); class
165 # Class->accuracy($a); class $a
168 my $class = ref($x) || $x || __PACKAGE__;
171 # need to set new value?
175 die ('accuracy must not be zero') if defined $a && $a == 0;
178 # $object->accuracy() or fallback to global
179 $x->bround($a) if defined $a;
180 $x->{_a} = $a; # set/overwrite, even if not rounded
181 $x->{_p} = undef; # clear P
186 ${"${class}::accuracy"} = $a;
188 return $a; # shortcut
193 # $object->accuracy() or fallback to global
194 return $x->{_a} || ${"${class}::accuracy"};
196 return ${"${class}::accuracy"};
201 # $x->precision($p); ref($x) $p
202 # $x->precision(); ref($x)
203 # Class->precision(); class
204 # Class->precision($p); class $p
207 my $class = ref($x) || $x || __PACKAGE__;
210 # need to set new value?
216 # $object->precision() or fallback to global
217 $x->bfround($p) if defined $p;
218 $x->{_p} = $p; # set/overwrite, even if not rounded
219 $x->{_a} = undef; # clear P
224 ${"${class}::precision"} = $p;
226 return $p; # shortcut
231 # $object->precision() or fallback to global
232 return $x->{_p} || ${"${class}::precision"};
234 return ${"${class}::precision"};
239 # select accuracy parameter based on precedence,
240 # used by bround() and bfround(), may return undef for scale (means no op)
241 my ($x,$s,$m,$scale,$mode) = @_;
242 $scale = $x->{_a} if !defined $scale;
243 $scale = $s if (!defined $scale);
244 $mode = $m if !defined $mode;
245 return ($scale,$mode);
250 # select precision parameter based on precedence,
251 # used by bround() and bfround(), may return undef for scale (means no op)
252 my ($x,$s,$m,$scale,$mode) = @_;
253 $scale = $x->{_p} if !defined $scale;
254 $scale = $s if (!defined $scale);
255 $mode = $m if !defined $mode;
256 return ($scale,$mode);
259 ##############################################################################
267 # if two arguments, the first one is the class to "swallow" subclasses
275 return unless ref($x); # only for objects
277 my $self = {}; bless $self,$c;
278 foreach my $k (keys %$x)
282 $self->{$k} = $CALC->_copy($x->{$k});
284 elsif (ref($x->{$k}) eq 'SCALAR')
286 $self->{$k} = \${$x->{$k}};
288 elsif (ref($x->{$k}) eq 'ARRAY')
290 $self->{$k} = [ @{$x->{$k}} ];
292 elsif (ref($x->{$k}) eq 'HASH')
294 # only one level deep!
295 foreach my $h (keys %{$x->{$k}})
297 $self->{$k}->{$h} = $x->{$k}->{$h};
300 elsif (ref($x->{$k}))
302 my $c = ref($x->{$k});
303 $self->{$k} = $c->new($x->{$k}); # no copy() due to deep rec
307 $self->{$k} = $x->{$k};
315 # create a new BigInt object from a string or another BigInt object.
316 # see hash keys documented at top
318 # the argument could be an object, so avoid ||, && etc on it, this would
319 # cause costly overloaded code to be called. The only allowed ops are
324 my $wanted = shift; # avoid numify call by not using || here
325 return $class->bzero() if !defined $wanted; # default to 0
326 return $class->copy($wanted) if ref($wanted);
328 my $self = {}; bless $self, $class;
329 # handle '+inf', '-inf' first
330 if ($wanted =~ /^[+-]?inf$/)
332 $self->{value} = $CALC->_zero();
333 $self->{sign} = $wanted; $self->{sign} = '+inf' if $self->{sign} eq 'inf';
336 # split str in m mantissa, e exponent, i integer, f fraction, v value, s sign
337 my ($mis,$miv,$mfv,$es,$ev) = _split(\$wanted);
340 die "$wanted is not a number initialized to $class" if !$NaNOK;
342 $self->{value} = $CALC->_zero();
343 $self->{sign} = $nan;
348 # _from_hex or _from_bin
349 $self->{value} = $mis->{value};
350 $self->{sign} = $mis->{sign};
351 return $self; # throw away $mis
353 # make integer from mantissa by adjusting exp, then convert to bigint
354 $self->{sign} = $$mis; # store sign
355 $self->{value} = $CALC->_zero(); # for all the NaN cases
356 my $e = int("$$es$$ev"); # exponent (avoid recursion)
359 my $diff = $e - CORE::length($$mfv);
360 if ($diff < 0) # Not integer
363 $self->{sign} = $nan;
367 # adjust fraction and add it to value
368 # print "diff > 0 $$miv\n";
369 $$miv = $$miv . ($$mfv . '0' x $diff);
374 if ($$mfv ne '') # e <= 0
376 # fraction and negative/zero E => NOI
377 #print "NOI 2 \$\$mfv '$$mfv'\n";
378 $self->{sign} = $nan;
382 # xE-y, and empty mfv
385 if ($$miv !~ s/0{$e}$//) # can strip so many zero's?
388 $self->{sign} = $nan;
392 $self->{sign} = '+' if $$miv eq '0'; # normalize -0 => +0
393 $self->{value} = $CALC->_new($miv) if $self->{sign} =~ /^[+-]$/;
394 # if any of the globals is set, use them to round and store them inside $self
395 $self->round($accuracy,$precision,$round_mode)
396 if defined $accuracy || defined $precision;
402 # create a bigint 'NaN', if given a BigInt, set it to 'NaN'
404 $self = $class if !defined $self;
407 my $c = $self; $self = {}; bless $self, $c;
409 return if $self->modify('bnan');
410 $self->{value} = $CALC->_zero();
411 $self->{sign} = $nan;
417 # create a bigint '+-inf', if given a BigInt, set it to '+-inf'
418 # the sign is either '+', or if given, used from there
420 my $sign = shift; $sign = '+' if !defined $sign || $sign ne '-';
421 $self = $class if !defined $self;
424 my $c = $self; $self = {}; bless $self, $c;
426 return if $self->modify('binf');
427 $self->{value} = $CALC->_zero();
428 $self->{sign} = $sign.'inf';
434 # create a bigint '+0', if given a BigInt, set it to 0
436 $self = $class if !defined $self;
440 my $c = $self; $self = {}; bless $self, $c;
442 return if $self->modify('bzero');
443 $self->{value} = $CALC->_zero();
450 # create a bigint '+1' (or -1 if given sign '-'),
451 # if given a BigInt, set it to +1 or -1, respecively
453 my $sign = shift; $sign = '+' if !defined $sign || $sign ne '-';
454 $self = $class if !defined $self;
458 my $c = $self; $self = {}; bless $self, $c;
460 return if $self->modify('bone');
461 $self->{value} = $CALC->_one();
462 $self->{sign} = $sign;
466 ##############################################################################
467 # string conversation
471 # (ref to BFLOAT or num_str ) return num_str
472 # Convert number from internal format to scientific string format.
473 # internal format is always normalized (no leading zeros, "-0E0" => "+0E0")
474 my $x = shift; $class = ref($x) || $x; $x = $class->new(shift) if !ref($x);
475 # my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
477 if ($x->{sign} !~ /^[+-]$/)
479 return $x->{sign} unless $x->{sign} eq '+inf'; # -inf, NaN
482 my ($m,$e) = $x->parts();
483 # e can only be positive
485 # MBF: my $s = $e->{sign}; $s = '' if $s eq '-'; my $sep = 'e'.$s;
486 return $m->bstr().$sign.$e->bstr();
491 # make a string from bigint object
492 my $x = shift; $class = ref($x) || $x; $x = $class->new(shift) if !ref($x);
493 # my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
495 if ($x->{sign} !~ /^[+-]$/)
497 return $x->{sign} unless $x->{sign} eq '+inf'; # -inf, NaN
500 my $es = ''; $es = $x->{sign} if $x->{sign} eq '-';
501 return $es.${$CALC->_str($x->{value})};
506 # Make a number from a BigInt object
507 my $x = shift; $x = $class->new($x) unless ref $x;
508 return $x->{sign} if $x->{sign} !~ /^[+-]$/;
509 my $num = $CALC->_num($x->{value});
510 return -$num if $x->{sign} eq '-';
514 ##############################################################################
515 # public stuff (usually prefixed with "b")
519 # return the sign of the number: +/-/NaN
520 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
525 sub _find_round_parameters
527 # After any operation or when calling round(), the result is rounded by
528 # regarding the A & P from arguments, local parameters, or globals.
529 # The result's A or P are set by the rounding, but not inspected beforehand
530 # (aka only the arguments enter into it). This works because the given
531 # 'first' argument is both the result and true first argument with unchanged
533 # This does not yet handle $x with A, and $y with P (which should be an
536 my $a = shift; # accuracy, if given by caller
537 my $p = shift; # precision, if given by caller
538 my $r = shift; # round_mode, if given by caller
539 my @args = @_; # all 'other' arguments (0 for unary, 1 for binary ops)
541 $self = new($self) unless ref($self); # if not object, make one
542 my $c = ref($self); # find out class of argument(s)
543 unshift @args,$self; # add 'first' argument
545 # leave bigfloat parts alone
546 return ($self) if exists $self->{_f} && $self->{_f} & MB_NEVER_ROUND != 0;
550 # now pick $a or $p, but only if we have got "arguments"
551 if ((!defined $a) && (!defined $p) && (@args > 0))
555 # take the defined one, or if both defined, the one that is smaller
556 $a = $_->{_a} if (defined $_->{_a}) && (!defined $a || $_->{_a} < $a);
558 if (!defined $a) # if it still is not defined, take p
562 # take the defined one, or if both defined, the one that is bigger
564 $p = $_->{_p} if (defined $_->{_p}) && (!defined $p || $_->{_p} > $p);
566 # if none defined, use globals (#2)
569 my $z = "$c\::accuracy"; my $a = $$z;
572 $z = "$c\::precision"; $p = $$z;
576 } # endif !$a || !$P && args > 0
577 my @params = ($self);
578 if (defined $a || defined $p)
580 $r = $r || ${"$c\::round_mode"};
581 die "Unknown round mode '$r'"
582 if $r !~ /^(even|odd|\+inf|\-inf|zero|trunc)$/;
583 push @params, ($a,$p,$r);
590 # round $self according to given parameters, or given second argument's
591 # parameters or global defaults
594 my @params = $self->_find_round_parameters(@_);
595 return $self->bnorm() if @params == 1; # no-op
597 # now round, by calling fround or ffround:
598 if (defined $params[1])
600 $self->bround($params[1],$params[3]);
604 $self->bfround($params[2],$params[3]);
606 return $self->bnorm(); # after round, normalize
611 # (numstr or or BINT) return BINT
612 # Normalize number -- no-op here
613 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
619 # (BINT or num_str) return BINT
620 # make number absolute, or return absolute BINT from string
621 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
623 return $x if $x->modify('babs');
624 # post-normalized abs for internal use (does nothing for NaN)
625 $x->{sign} =~ s/^-/+/;
631 # (BINT or num_str) return BINT
632 # negate number or make a negated number from string
633 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
635 return $x if $x->modify('bneg');
636 # for +0 dont negate (to have always normalized)
637 return $x if $x->is_zero();
638 $x->{sign} =~ tr/+\-/-+/; # does nothing for NaN
644 # Compares 2 values. Returns one of undef, <0, =0, >0. (suitable for sort)
645 # (BINT or num_str, BINT or num_str) return cond_code
646 my ($self,$x,$y) = objectify(2,@_);
648 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
650 # handle +-inf and NaN
651 return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
652 return 0 if $x->{sign} eq $y->{sign} && $x->{sign} =~ /^[+-]inf$/;
653 return +1 if $x->{sign} eq '+inf';
654 return -1 if $x->{sign} eq '-inf';
655 return -1 if $y->{sign} eq '+inf';
656 return +1 if $y->{sign} eq '-inf';
658 # check sign for speed first
659 return 1 if $x->{sign} eq '+' && $y->{sign} eq '-'; # does also 0 <=> -y
660 return -1 if $x->{sign} eq '-' && $y->{sign} eq '+'; # does also -x <=> 0
663 my $xz = $x->is_zero();
664 my $yz = $y->is_zero();
665 return 0 if $xz && $yz; # 0 <=> 0
666 return -1 if $xz && $y->{sign} eq '+'; # 0 <=> +y
667 return 1 if $yz && $x->{sign} eq '+'; # +x <=> 0
669 # post-normalized compare for internal use (honors signs)
670 if ($x->{sign} eq '+')
672 return 1 if $y->{sign} eq '-'; # 0 check handled above
673 return $CALC->_acmp($x->{value},$y->{value});
677 return -1 if $y->{sign} eq '+';
678 return $CALC->_acmp($y->{value},$x->{value}); # swaped
680 # &cmp($x->{value},$y->{value},$x->{sign},$y->{sign}) <=> 0;
685 # Compares 2 values, ignoring their signs.
686 # Returns one of undef, <0, =0, >0. (suitable for sort)
687 # (BINT, BINT) return cond_code
688 my ($self,$x,$y) = objectify(2,@_);
690 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
692 # handle +-inf and NaN
693 return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
694 return 0 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} =~ /^[+-]inf$/;
695 return +1; # inf is always bigger
697 $CALC->_acmp($x->{value},$y->{value}) <=> 0;
702 # add second arg (BINT or string) to first (BINT) (modifies first)
703 # return result as BINT
704 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
706 return $x if $x->modify('badd');
708 # inf and NaN handling
709 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
712 return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
714 if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
716 # + and + => +, - and - => -, + and - => 0, - and + => 0
717 return $x->bzero() if $x->{sign} ne $y->{sign};
720 # +-inf + something => +inf
721 # something +-inf => +-inf
722 $x->{sign} = $y->{sign}, return $x if $y->{sign} =~ /^[+-]inf$/;
726 my @bn = ($a,$p,$r,$y); # make array for round calls
727 # speed: no add for 0+y or x+0
728 return $x->round(@bn) if $y->is_zero(); # x+0
729 if ($x->is_zero()) # 0+y
731 # make copy, clobbering up x
732 $x->{value} = $CALC->_copy($y->{value});
733 $x->{sign} = $y->{sign} || $nan;
734 return $x->round(@bn);
737 my ($sx, $sy) = ( $x->{sign}, $y->{sign} ); # get signs
741 $x->{value} = $CALC->_add($x->{value},$y->{value}); # same sign, abs add
746 my $a = $CALC->_acmp ($y->{value},$x->{value}); # absolute compare
749 #print "swapped sub (a=$a)\n";
750 $x->{value} = $CALC->_sub($y->{value},$x->{value},1); # abs sub w/ swap
755 # speedup, if equal, set result to 0
756 #print "equal sub, result = 0\n";
757 $x->{value} = $CALC->_zero();
762 #print "unswapped sub (a=$a)\n";
763 $x->{value} = $CALC->_sub($x->{value}, $y->{value}); # abs sub
767 return $x->round(@bn);
772 # (BINT or num_str, BINT or num_str) return num_str
773 # subtract second arg from first, modify first
774 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
776 return $x if $x->modify('bsub');
777 $x->badd($y->bneg()); # badd does not leave internal zeros
778 $y->bneg(); # refix y, assumes no one reads $y in between
779 return $x->round($a,$p,$r,$y);
784 # increment arg by one
785 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
786 return $x if $x->modify('binc');
787 $x->badd($self->__one())->round($a,$p,$r);
792 # decrement arg by one
793 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
794 return $x if $x->modify('bdec');
795 $x->badd($self->__one('-'))->round($a,$p,$r);
800 # (BINT or num_str, BINT or num_str) return BINT
801 # does not modify arguments, but returns new object
802 # Lowest Common Multiplicator
804 my $y = shift; my ($x);
811 $x = $class->new($y);
813 while (@_) { $x = __lcm($x,shift); }
819 # (BINT or num_str, BINT or num_str) return BINT
820 # does not modify arguments, but returns new object
821 # GCD -- Euclids algorithm, variant C (Knuth Vol 3, pg 341 ff)
824 $y = __PACKAGE__->new($y) if !ref($y);
826 my $x = $y->copy(); # keep arguments
827 if ($CALC->can('_gcd'))
831 $y = shift; $y = $self->new($y) if !ref($y);
832 next if $y->is_zero();
833 return $x->bnan() if $y->{sign} !~ /^[+-]$/; # y NaN?
834 $x->{value} = $CALC->_gcd($x->{value},$y->{value}); last if $x->is_one();
841 $y = shift; $y = $self->new($y) if !ref($y);
842 $x = __gcd($x,$y->copy()); last if $x->is_one(); # _gcd handles NaN
850 # (num_str or BINT) return BINT
851 # represent ~x as twos-complement number
852 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
853 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
855 return $x if $x->modify('bnot');
856 $x->bneg(); $x->bdec(); # was: bsub(-1,$x);, time it someday
857 return $x->round($a,$p,$r);
862 # return true if arg (BINT or num_str) is zero (array '+', '0')
863 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
864 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
866 return 0 if $x->{sign} !~ /^\+$/; # -, NaN & +-inf aren't
867 $CALC->_is_zero($x->{value});
872 # return true if arg (BINT or num_str) is NaN
873 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
875 return 1 if $x->{sign} eq $nan;
881 # return true if arg (BINT or num_str) is +-inf
882 my ($self,$x,$sign) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
884 $sign = '' if !defined $sign;
885 return 0 if $sign !~ /^([+-]|)$/;
889 return 1 if ($x->{sign} =~ /^[+-]inf$/);
892 $sign = quotemeta($sign.'inf');
893 return 1 if ($x->{sign} =~ /^$sign$/);
899 # return true if arg (BINT or num_str) is +1
900 # or -1 if sign is given
901 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
902 my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
904 $sign = '' if !defined $sign; $sign = '+' if $sign ne '-';
906 return 0 if $x->{sign} ne $sign; # -1 != +1, NaN, +-inf aren't either
907 return $CALC->_is_one($x->{value});
912 # return true when arg (BINT or num_str) is odd, false for even
913 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
914 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
916 return 0 if $x->{sign} !~ /^[+-]$/; # NaN & +-inf aren't
917 return $CALC->_is_odd($x->{value});
922 # return true when arg (BINT or num_str) is even, false for odd
923 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
924 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
926 return 0 if $x->{sign} !~ /^[+-]$/; # NaN & +-inf aren't
927 return $CALC->_is_even($x->{value});
932 # return true when arg (BINT or num_str) is positive (>= 0)
933 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
934 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
936 return 1 if $x->{sign} =~ /^\+/;
942 # return true when arg (BINT or num_str) is negative (< 0)
943 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
944 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
946 return 1 if ($x->{sign} =~ /^-/);
950 ###############################################################################
954 # multiply two numbers -- stolen from Knuth Vol 2 pg 233
955 # (BINT or num_str, BINT or num_str) return BINT
956 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
958 return $x if $x->modify('bmul');
959 return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
961 return $x if $x->is_zero();
962 return $x->bzero() if $y->is_zero();
964 if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
966 # result will always be +-inf:
967 # +inf * +/+inf => +inf, -inf * -/-inf => +inf
968 # +inf * -/-inf => -inf, -inf * +/+inf => -inf
969 return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/);
970 return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/);
971 return $x->binf('-');
974 $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
976 $x->{value} = $CALC->_mul($x->{value},$y->{value}); # do actual math
977 return $x->round($a,$p,$r,$y);
979 # from http://groups.google.com/groups?selm=3BBF69A6.72E1%40pointecom.net
981 # my $yc = $y->copy(); # make copy of second argument
982 # my $carry = $self->bzero();
987 # #print "$x\t$yc\t$carry\n";
988 # $carry += $x if $yc->is_odd();
993 # #print "result $x\n";
995 # return $x->round($a,$p,$r,$y);
1000 # helper function that handles +-inf cases for bdiv()/bmod() to reuse code
1001 my ($self,$x,$y) = @_;
1003 # NaN if x == NaN or y == NaN or x==y==0
1004 return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan()
1005 if (($x->is_nan() || $y->is_nan()) ||
1006 ($x->is_zero() && $y->is_zero()));
1008 # +inf / +inf == -inf / -inf == 1, remainder is 0 (A / A = 1, remainder 0)
1009 if (($x->{sign} eq $y->{sign}) &&
1010 ($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1012 return wantarray ? ($x->bone(),$self->bzero()) : $x->bone();
1014 # +inf / -inf == -inf / +inf == -1, remainder 0
1015 if (($x->{sign} ne $y->{sign}) &&
1016 ($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1018 return wantarray ? ($x->bone('-'),$self->bzero()) : $x->bone('-');
1020 # x / +-inf => 0, remainder x (works even if x == 0)
1021 if ($y->{sign} =~ /^[+-]inf$/)
1023 my $t = $x->copy(); # binf clobbers up $x
1024 return wantarray ? ($x->bzero(),$t) : $x->bzero()
1027 # 5 / 0 => +inf, -6 / 0 => -inf
1028 # +inf / 0 = inf, inf, and -inf / 0 => -inf, -inf
1029 # exception: -8 / 0 has remainder -8, not 8
1030 # exception: -inf / 0 has remainder -inf, not inf
1033 # +-inf / 0 => special case for -inf
1034 return wantarray ? ($x,$x->copy()) : $x if $x->is_inf();
1035 if (!$x->is_zero() && !$x->is_inf())
1037 my $t = $x->copy(); # binf clobbers up $x
1039 ($x->binf($x->{sign}),$t) : $x->binf($x->{sign})
1043 # last case: +-inf / ordinary number
1045 $sign = '-inf' if substr($x->{sign},0,1) ne $y->{sign};
1047 return wantarray ? ($x,$self->bzero()) : $x;
1052 # (dividend: BINT or num_str, divisor: BINT or num_str) return
1053 # (BINT,BINT) (quo,rem) or BINT (only rem)
1054 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1056 return $x if $x->modify('bdiv');
1058 return $self->_div_inf($x,$y)
1059 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero());
1062 return wantarray ? ($x,$self->bzero()) : $x if $x->is_zero();
1064 # Is $x in the interval [0, $y) ?
1065 my $cmp = $CALC->_acmp($x->{value},$y->{value});
1066 if (($cmp < 0) and ($x->{sign} eq $y->{sign}))
1068 return $x->bzero() unless wantarray;
1069 my $t = $x->copy(); # make copy first, because $x->bzero() clobbers $x
1070 return ($x->bzero(),$t);
1074 # shortcut, both are the same, so set to +/- 1
1075 $x->__one( ($x->{sign} ne $y->{sign} ? '-' : '+') );
1076 return $x unless wantarray;
1077 return ($x,$self->bzero());
1080 # calc new sign and in case $y == +/- 1, return $x
1081 my $xsign = $x->{sign}; # keep
1082 $x->{sign} = ($x->{sign} ne $y->{sign} ? '-' : '+');
1083 # check for / +-1 (cant use $y->is_one due to '-'
1084 if (($y == 1) || ($y == -1)) # slow!
1086 return wantarray ? ($x,$self->bzero()) : $x;
1090 my $rem = $self->bzero();
1091 ($x->{value},$rem->{value}) = $CALC->_div($x->{value},$y->{value});
1092 # do not leave result "-0";
1093 $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1094 $x->round($a,$p,$r,$y);
1096 # print "in div round ",$a||'a undef'," ",$p|| 'p undef'," $r\n";
1099 if (! $CALC->_is_zero($rem->{value}))
1101 $rem->{sign} = $y->{sign};
1102 $rem = $y-$rem if $xsign ne $y->{sign}; # one of them '-'
1106 $rem->{sign} = '+'; # dont leave -0
1108 $rem->round($a,$p,$r,$x,$y);
1116 # modulus (or remainder)
1117 # (BINT or num_str, BINT or num_str) return BINT
1118 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1120 return $x if $x->modify('bmod');
1121 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero())
1123 my ($d,$r) = $self->_div_inf($x,$y);
1127 if ($CALC->can('_mod'))
1129 # calc new sign and in case $y == +/- 1, return $x
1130 $x->{value} = $CALC->_mod($x->{value},$y->{value});
1131 my $xsign = $x->{sign};
1132 if (!$CALC->_is_zero($x->{value}))
1134 $x->{sign} = $y->{sign};
1135 $x = $y-$x if $xsign ne $y->{sign}; # one of them '-'
1139 $x->{sign} = '+'; # dont leave -0
1144 $x = (&bdiv($self,$x,$y))[1];
1146 $x->bround($a,$p,$r);
1151 # (BINT or num_str, BINT or num_str) return BINT
1152 # compute power of two numbers -- stolen from Knuth Vol 2 pg 233
1153 # modifies first argument
1154 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1156 return $x if $x->modify('bpow');
1158 return $x if $x->{sign} =~ /^[+-]inf$/; # -inf/+inf ** x
1159 return $x->bnan() if $x->{sign} eq $nan || $y->{sign} eq $nan;
1160 return $x->__one() if $y->is_zero();
1161 return $x if $x->is_one() || $y->is_one();
1162 #if ($x->{sign} eq '-' && @{$x->{value}} == 1 && $x->{value}->[0] == 1)
1163 if ($x->{sign} eq '-' && $CALC->_is_one($x->{value}))
1165 # if $x == -1 and odd/even y => +1/-1
1166 return $y->is_odd() ? $x : $x->babs();
1167 # my Casio FX-5500L has a bug here: -1 ** 2 is -1, but -1 * -1 is 1;
1169 # 1 ** -y => 1 / (1 ** |y|)
1170 # so do test for negative $y after above's clause
1171 return $x->bnan() if $y->{sign} eq '-';
1172 return $x if $x->is_zero(); # 0**y => 0 (if not y <= 0)
1174 if ($CALC->can('_pow'))
1176 $x->{value} = $CALC->_pow($x->{value},$y->{value});
1177 return $x->round($a,$p,$r);
1179 # based on the assumption that shifting in base 10 is fast, and that mul
1180 # works faster if numbers are small: we count trailing zeros (this step is
1181 # O(1)..O(N), but in case of O(N) we save much more time due to this),
1182 # stripping them out of the multiplication, and add $count * $y zeros
1183 # afterwards like this:
1184 # 300 ** 3 == 300*300*300 == 3*3*3 . '0' x 2 * 3 == 27 . '0' x 6
1185 # creates deep recursion?
1186 # my $zeros = $x->_trailing_zeros();
1189 # $x->brsft($zeros,10); # remove zeros
1190 # $x->bpow($y); # recursion (will not branch into here again)
1191 # $zeros = $y * $zeros; # real number of zeros to add
1192 # $x->blsft($zeros,10);
1193 # return $x->round($a,$p,$r);
1196 my $pow2 = $self->__one();
1197 my $y1 = $class->new($y);
1199 my $two = $self->new(2);
1200 while (!$y1->is_one())
1202 # thats a tad (between 8 and 17%) faster for small results
1203 # 7777 ** 7777 is not faster, but 2 ** 150, 3 ** 16, 3 ** 256 etc are
1204 $pow2->bmul($x) if $y1->is_odd();
1206 $x->bmul($x) unless $y1->is_zero();
1208 # ($y1,$res)=&bdiv($y1,2);
1209 # if (!$res->is_zero()) { &bmul($pow2,$x); }
1210 # if (!$y1->is_zero()) { &bmul($x,$x); }
1212 $x->bmul($pow2) unless $pow2->is_one();
1213 return $x->round($a,$p,$r);
1218 # (BINT or num_str, BINT or num_str) return BINT
1219 # compute x << y, base n, y >= 0
1220 my ($self,$x,$y,$n) = objectify(2,@_);
1222 return $x if $x->modify('blsft');
1223 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1225 $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1227 my $t = $CALC->_lsft($x->{value},$y->{value},$n) if $CALC->can('_lsft');
1230 $x->{value} = $t; return $x;
1233 return $x->bmul( $self->bpow($n, $y) );
1238 # (BINT or num_str, BINT or num_str) return BINT
1239 # compute x >> y, base n, y >= 0
1240 my ($self,$x,$y,$n) = objectify(2,@_);
1242 return $x if $x->modify('brsft');
1243 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1245 $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1247 my $t = $CALC->_rsft($x->{value},$y->{value},$n) if $CALC->can('_rsft');
1250 $x->{value} = $t; return $x;
1253 return scalar bdiv($x, $self->bpow($n, $y));
1258 #(BINT or num_str, BINT or num_str) return BINT
1260 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1262 return $x if $x->modify('band');
1264 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1265 return $x->bzero() if $y->is_zero();
1267 my $sign = 0; # sign of result
1268 $sign = 1 if ($x->{sign} eq '-') && ($y->{sign} eq '-');
1269 my $sx = 1; $sx = -1 if $x->{sign} eq '-';
1270 my $sy = 1; $sy = -1 if $y->{sign} eq '-';
1272 if ($CALC->can('_and') && $sx == 1 && $sy == 1)
1274 $x->{value} = $CALC->_and($x->{value},$y->{value});
1275 return $x->round($a,$p,$r);
1278 my $m = new Math::BigInt 1; my ($xr,$yr);
1279 my $x10000 = new Math::BigInt (0x1000);
1280 my $y1 = copy(ref($x),$y); # make copy
1281 $y1->babs(); # and positive
1282 my $x1 = $x->copy()->babs(); $x->bzero(); # modify x in place!
1283 use integer; # need this for negative bools
1284 while (!$x1->is_zero() && !$y1->is_zero())
1286 ($x1, $xr) = bdiv($x1, $x10000);
1287 ($y1, $yr) = bdiv($y1, $x10000);
1288 # make both op's numbers!
1289 $x->badd( bmul( $class->new(
1290 abs($sx*int($xr->numify()) & $sy*int($yr->numify()))),
1294 $x->bneg() if $sign;
1295 return $x->round($a,$p,$r);
1300 #(BINT or num_str, BINT or num_str) return BINT
1302 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1304 return $x if $x->modify('bior');
1306 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1307 return $x if $y->is_zero();
1309 my $sign = 0; # sign of result
1310 $sign = 1 if ($x->{sign} eq '-') || ($y->{sign} eq '-');
1311 my $sx = 1; $sx = -1 if $x->{sign} eq '-';
1312 my $sy = 1; $sy = -1 if $y->{sign} eq '-';
1314 # don't use lib for negative values
1315 if ($CALC->can('_or') && $sx == 1 && $sy == 1)
1317 $x->{value} = $CALC->_or($x->{value},$y->{value});
1318 return $x->round($a,$p,$r);
1321 my $m = new Math::BigInt 1; my ($xr,$yr);
1322 my $x10000 = new Math::BigInt (0x10000);
1323 my $y1 = copy(ref($x),$y); # make copy
1324 $y1->babs(); # and positive
1325 my $x1 = $x->copy()->babs(); $x->bzero(); # modify x in place!
1326 use integer; # need this for negative bools
1327 while (!$x1->is_zero() || !$y1->is_zero())
1329 ($x1, $xr) = bdiv($x1,$x10000);
1330 ($y1, $yr) = bdiv($y1,$x10000);
1331 # make both op's numbers!
1332 $x->badd( bmul( $class->new(
1333 abs($sx*int($xr->numify()) | $sy*int($yr->numify()))),
1337 $x->bneg() if $sign;
1338 return $x->round($a,$p,$r);
1343 #(BINT or num_str, BINT or num_str) return BINT
1345 my ($self,$x,$y,$a,$p,$r) = objectify(2,@_);
1347 return $x if $x->modify('bxor');
1349 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1350 return $x if $y->is_zero();
1351 return $x->bzero() if $x == $y; # shortcut
1353 my $sign = 0; # sign of result
1354 $sign = 1 if $x->{sign} ne $y->{sign};
1355 my $sx = 1; $sx = -1 if $x->{sign} eq '-';
1356 my $sy = 1; $sy = -1 if $y->{sign} eq '-';
1358 # don't use lib for negative values
1359 if ($CALC->can('_xor') && $sx == 1 && $sy == 1)
1361 $x->{value} = $CALC->_xor($x->{value},$y->{value});
1362 return $x->round($a,$p,$r);
1365 my $m = new Math::BigInt 1; my ($xr,$yr);
1366 my $x10000 = new Math::BigInt (0x10000);
1367 my $y1 = copy(ref($x),$y); # make copy
1368 $y1->babs(); # and positive
1369 my $x1 = $x->copy()->babs(); $x->bzero(); # modify x in place!
1370 use integer; # need this for negative bools
1371 while (!$x1->is_zero() || !$y1->is_zero())
1373 ($x1, $xr) = bdiv($x1, $x10000);
1374 ($y1, $yr) = bdiv($y1, $x10000);
1375 # make both op's numbers!
1376 $x->badd( bmul( $class->new(
1377 abs($sx*int($xr->numify()) ^ $sy*int($yr->numify()))),
1381 $x->bneg() if $sign;
1382 return $x->round($a,$p,$r);
1387 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
1389 my $e = $CALC->_len($x->{value});
1390 return wantarray ? ($e,0) : $e;
1395 # return the nth decimal digit, negative values count backward, 0 is right
1399 return $CALC->_digit($x->{value},$n);
1404 # return the amount of trailing zeros in $x
1406 $x = $class->new($x) unless ref $x;
1408 return 0 if $x->is_zero() || $x->is_odd() || $x->{sign} !~ /^[+-]$/;
1410 return $CALC->_zeros($x->{value}) if $CALC->can('_zeros');
1412 # if not: since we do not know underlying internal representation:
1413 my $es = "$x"; $es =~ /([0]*)$/;
1415 return 0 if !defined $1; # no zeros
1416 return CORE::length("$1"); # as string, not as +0!
1421 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
1423 return $x->bnan() if $x->{sign} =~ /\-|$nan/; # -x or NaN => NaN
1424 return $x->bzero() if $x->is_zero(); # 0 => 0
1425 return $x if $x == 1; # 1 => 1
1427 my $y = $x->copy(); # give us one more digit accur.
1428 my $l = int($x->length()/2);
1431 $x->binc(); # keep ref($x), but modify it
1434 # print "x: $y guess $x\n";
1436 my $last = $self->bzero();
1448 # return a copy of the exponent (here always 0, NaN or 1 for $m == 0)
1449 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
1451 if ($x->{sign} !~ /^[+-]$/)
1453 my $s = $x->{sign}; $s =~ s/^[+-]//;
1454 return $self->new($s); # -inf,+inf => inf
1456 my $e = $class->bzero();
1457 return $e->binc() if $x->is_zero();
1458 $e += $x->_trailing_zeros();
1464 # return the mantissa (compatible to Math::BigFloat, e.g. reduced)
1465 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
1467 if ($x->{sign} !~ /^[+-]$/)
1469 my $s = $x->{sign}; $s =~ s/^[+]//;
1470 return $self->new($s); # +inf => inf
1473 # that's inefficient
1474 my $zeros = $m->_trailing_zeros();
1475 $m /= 10 ** $zeros if $zeros != 0;
1481 # return a copy of both the exponent and the mantissa
1482 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
1484 return ($x->mantissa(),$x->exponent());
1487 ##############################################################################
1488 # rounding functions
1492 # precision: round to the $Nth digit left (+$n) or right (-$n) from the '.'
1493 # $n == 0 || $n == 1 => round to integer
1494 my $x = shift; $x = $class->new($x) unless ref $x;
1495 my ($scale,$mode) = $x->_scale_p($x->precision(),$x->round_mode(),@_);
1496 return $x if !defined $scale; # no-op
1498 # no-op for BigInts if $n <= 0
1501 $x->{_p} = $scale; return $x;
1504 $x->bround( $x->length()-$scale, $mode);
1505 $x->{_a} = undef; # bround sets {_a}
1506 $x->{_p} = $scale; # so correct it
1510 sub _scan_for_nonzero
1516 my $len = $x->length();
1517 return 0 if $len == 1; # '5' is trailed by invisible zeros
1518 my $follow = $pad - 1;
1519 return 0 if $follow > $len || $follow < 1;
1520 #print "checking $x $r\n";
1522 # since we do not know underlying represention of $x, use decimal string
1523 #my $r = substr ($$xs,-$follow);
1524 my $r = substr ("$x",-$follow);
1525 return 1 if $r =~ /[^0]/; return 0;
1530 # to make life easier for switch between MBF and MBI (autoload fxxx()
1531 # like MBF does for bxxx()?)
1533 return $x->bround(@_);
1538 # accuracy: +$n preserve $n digits from left,
1539 # -$n preserve $n digits from right (f.i. for 0.1234 style in MBF)
1541 # and overwrite the rest with 0's, return normalized number
1542 # do not return $x->bnorm(), but $x
1543 my $x = shift; $x = $class->new($x) unless ref $x;
1544 my ($scale,$mode) = $x->_scale_a($x->accuracy(),$x->round_mode(),@_);
1545 return $x if !defined $scale; # no-op
1547 # print "MBI round: $x to $scale $mode\n";
1548 return $x if $x->{sign} !~ /^[+-]$/ || $x->is_zero() || $scale == 0;
1550 # we have fewer digits than we want to scale to
1551 my $len = $x->length();
1552 # print "$scale $len\n";
1553 # scale < 0, but > -len (not >=!)
1554 if (($scale < 0 && $scale < -$len-1) || ($scale >= $len))
1556 $x->{_a} = $scale if !defined $x->{_a}; # if not yet defined overwrite
1560 # count of 0's to pad, from left (+) or right (-): 9 - +6 => 3, or |-6| => 6
1561 my ($pad,$digit_round,$digit_after);
1562 $pad = $len - $scale;
1563 $pad = abs($scale-1) if $scale < 0;
1565 # do not use digit(), it is costly for binary => decimal
1566 #$digit_round = '0'; $digit_round = $x->digit($pad) if $pad < $len;
1567 #$digit_after = '0'; $digit_after = $x->digit($pad-1) if $pad > 0;
1569 my $xs = $CALC->_str($x->{value});
1572 # print "pad $pad pl $pl scale $scale len $len\n";
1573 # pad: 123: 0 => -1, at 1 => -2, at 2 => -3, at 3 => -4
1574 # pad+1: 123: 0 => 0, at 1 => -1, at 2 => -2, at 3 => -3
1575 $digit_round = '0'; $digit_round = substr($$xs,$pl,1) if $pad <= $len;
1576 $pl++; $pl ++ if $pad >= $len;
1577 $digit_after = '0'; $digit_after = substr($$xs,$pl,1)
1580 # print "$pad $pl $$xs dr $digit_round da $digit_after\n";
1582 # in case of 01234 we round down, for 6789 up, and only in case 5 we look
1583 # closer at the remaining digits of the original $x, remember decision
1584 my $round_up = 1; # default round up
1586 ($mode eq 'trunc') || # trunc by round down
1587 ($digit_after =~ /[01234]/) || # round down anyway,
1589 ($digit_after eq '5') && # not 5000...0000
1590 ($x->_scan_for_nonzero($pad,$xs) == 0) &&
1592 ($mode eq 'even') && ($digit_round =~ /[24680]/) ||
1593 ($mode eq 'odd') && ($digit_round =~ /[13579]/) ||
1594 ($mode eq '+inf') && ($x->{sign} eq '-') ||
1595 ($mode eq '-inf') && ($x->{sign} eq '+') ||
1596 ($mode eq 'zero') # round down if zero, sign adjusted below
1598 # allow rounding one place left of mantissa
1599 #print "$pad $len $scale\n";
1600 # this is triggering warnings, and buggy for $scale < 0
1601 #if (-$scale != $len)
1603 # old code, depend on internal representation
1604 # split mantissa at $pad and then pad with zeros
1605 #my $s5 = int($pad / 5);
1609 # $x->{value}->[$i++] = 0; # replace with 5 x 0
1611 #$x->{value}->[$s5] = '00000'.$x->{value}->[$s5]; # pad with 0
1612 #my $rem = $pad % 5; # so much left over
1615 # #print "remainder $rem\n";
1616 ## #print "elem $x->{value}->[$s5]\n";
1617 # substr($x->{value}->[$s5],-$rem,$rem) = '0' x $rem; # stamp w/ '0'
1619 #$x->{value}->[$s5] = int ($x->{value}->[$s5]); # str '05' => int '5'
1620 #print ${$CALC->_str($pad->{value})}," $len\n";
1621 if (($pad > 0) && ($pad <= $len))
1623 substr($$xs,-$pad,$pad) = '0' x $pad;
1624 $x->{value} = $CALC->_new($xs); # put back in
1628 $x->bzero(); # round to '0'
1630 # print "res $pad $len $x $$xs\n";
1632 # move this later on after the inc of the string
1633 #$x->{value} = $CALC->_new($xs); # put back in
1634 if ($round_up) # what gave test above?
1637 $pad = $len if $scale < 0; # tlr: whack 0.51=>1.0
1638 # modify $x in place, undef, undef to avoid rounding
1639 # str creation much faster than 10 ** something
1640 #print " $pad, $x => ";
1641 $x->badd( Math::BigInt->new($x->{sign}.'1'.'0'x$pad) );
1643 # increment string in place, to avoid dec=>hex for the '1000...000'
1647 #$x->{value} = $CALC->_new($xs); # put back in
1649 $x->{_a} = $scale if $scale >= 0;
1652 $x->{_a} = $len+$scale;
1653 $x->{_a} = 0 if $scale < -$len;
1660 # return integer less or equal then number, since it is already integer,
1661 # always returns $self
1662 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1664 # not needed: return $x if $x->modify('bfloor');
1665 return $x->round($a,$p,$r);
1670 # return integer greater or equal then number, since it is already integer,
1671 # always returns $self
1672 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1674 # not needed: return $x if $x->modify('bceil');
1675 return $x->round($a,$p,$r);
1678 ##############################################################################
1679 # private stuff (internal use only)
1683 # internal speedup, set argument to 1, or create a +/- 1
1685 my $x = $self->bone(); # $x->{value} = $CALC->_one();
1686 $x->{sign} = shift || '+';
1692 # Overload will swap params if first one is no object ref so that the first
1693 # one is always an object ref. In this case, third param is true.
1694 # This routine is to overcome the effect of scalar,$object creating an object
1695 # of the class of this package, instead of the second param $object. This
1696 # happens inside overload, when the overload section of this package is
1697 # inherited by sub classes.
1698 # For overload cases (and this is used only there), we need to preserve the
1699 # args, hence the copy().
1700 # You can override this method in a subclass, the overload section will call
1701 # $object->_swap() to make sure it arrives at the proper subclass, with some
1702 # exceptions like '+' and '-'.
1704 # object, (object|scalar) => preserve first and make copy
1705 # scalar, object => swapped, re-swap and create new from first
1706 # (using class of second object, not $class!!)
1707 my $self = shift; # for override in subclass
1708 #print "swap $self 0:$_[0] 1:$_[1] 2:$_[2]\n";
1711 my $c = ref ($_[0]) || $class; # fallback $class should not happen
1712 return ( $c->new($_[1]), $_[0] );
1714 return ( $_[0]->copy(), $_[1] );
1719 # check for strings, if yes, return objects instead
1721 # the first argument is number of args objectify() should look at it will
1722 # return $count+1 elements, the first will be a classname. This is because
1723 # overloaded '""' calls bstr($object,undef,undef) and this would result in
1724 # useless objects beeing created and thrown away. So we cannot simple loop
1725 # over @_. If the given count is 0, all arguments will be used.
1727 # If the second arg is a ref, use it as class.
1728 # If not, try to use it as classname, unless undef, then use $class
1729 # (aka Math::BigInt). The latter shouldn't happen,though.
1732 # $x->badd(1); => ref x, scalar y
1733 # Class->badd(1,2); => classname x (scalar), scalar x, scalar y
1734 # Class->badd( Class->(1),2); => classname x (scalar), ref x, scalar y
1735 # Math::BigInt::badd(1,2); => scalar x, scalar y
1736 # In the last case we check number of arguments to turn it silently into
1737 # $class,1,2. (We can not take '1' as class ;o)
1738 # badd($class,1) is not supported (it should, eventually, try to add undef)
1739 # currently it tries 'Math::BigInt' + 1, which will not work.
1741 # some shortcut for the common cases
1744 return (ref($_[1]),$_[1]) if (@_ == 2) && ($_[0]||0 == 1) && ref($_[1]);
1745 # $x->binary_op($y);
1746 #return (ref($_[1]),$_[1],$_[2]) if (@_ == 3) && ($_[0]||0 == 2)
1747 # && ref($_[1]) && ref($_[2]);
1749 # print "obj '",join ("' '", @_),"'\n";
1751 my $count = abs(shift || 0);
1753 # print "MBI ",caller(),"\n";
1755 my @a; # resulting array
1758 # okay, got object as first
1763 # nope, got 1,2 (Class->xxx(1) => Class,1 and not supported)
1765 #print "@_\n"; sleep(1);
1766 $a[0] = shift if $_[0] =~ /^[A-Z].*::/; # classname as first?
1768 #print caller(),"\n";
1769 # print "Now in objectify, my class is today $a[0]\n";
1778 $k = $a[0]->new($k);
1780 elsif (ref($k) ne $a[0])
1782 # foreign object, try to convert to integer
1783 $k->can('as_number') ? $k = $k->as_number() : $k = $a[0]->new($k);
1795 # print "$k (",ref($k),") => \n";
1798 $k = $a[0]->new($k);
1800 elsif (ref($k) ne $a[0])
1802 # foreign object, try to convert to integer
1803 $k->can('as_number') ? $k = $k->as_number() : $k = $a[0]->new($k);
1805 # print "$k (",ref($k),")\n";
1808 push @a,@_; # return other params, too
1813 # print "o $i $a[0]\n" if $i == 0;
1814 # print "o $i ",ref($_),"\n" if $i != 0; $i++;
1816 #print "objectify done: would return ",scalar @a," values\n";
1817 #print caller(1),"\n" unless wantarray;
1818 die "$class objectify needs list context" unless wantarray;
1825 #print "import $self @_\n";
1826 my @a = @_; my $l = scalar @_; my $j = 0;
1827 for ( my $i = 0; $i < $l ; $i++,$j++ )
1829 if ($_[$i] eq ':constant')
1831 # this causes overlord er load to step in
1832 overload::constant integer => sub { $self->new(shift) };
1833 splice @a, $j, 1; $j --;
1835 elsif ($_[$i] =~ /^lib$/i)
1837 # this causes a different low lib to take care...
1838 $CALC = $_[$i+1] || $CALC;
1839 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
1840 splice @a, $j, $s; $j -= $s;
1843 # any non :constant stuff is handled by our parent, Exporter
1844 # even if @_ is empty, to give it a chance
1845 $self->SUPER::import(@a); # need it for subclasses
1846 $self->export_to_level(1,$self,@a); # need it for MBF
1848 # try to load core math lib
1849 my @c = split /\s*,\s*/,$CALC;
1850 push @c,'Calc'; # if all fail, try this
1851 foreach my $lib (@c)
1853 $lib = 'Math::BigInt::'.$lib if $lib !~ /^Math::BigInt/i;
1857 # Perl < 5.6.0 dies with "out of memory!" when eval() and ':constant' is
1858 # used in the same script, or eval inside import().
1859 (my $mod = $lib . '.pm') =~ s!::!/!g;
1860 # require does not automatically :: => /, so portability problems arise
1861 eval { require $mod; $lib->import( @c ); }
1865 eval "use $lib @c;";
1867 $CALC = $lib, last if $@ eq ''; # no error in loading lib?
1873 # convert a (ref to) big hex string to BigInt, return undef for error
1876 my $x = Math::BigInt->bzero();
1877 return $x->bnan() if $$hs !~ /^[\-\+]?0x[0-9A-Fa-f]+$/;
1879 my $sign = '+'; $sign = '-' if ($$hs =~ /^-/);
1881 $$hs =~ s/^[+-]//; # strip sign
1882 if ($CALC->can('_from_hex'))
1884 $x->{value} = $CALC->_from_hex($hs);
1888 # fallback to pure perl
1889 my $mul = Math::BigInt->bzero(); $mul++;
1890 my $x65536 = Math::BigInt->new(65536);
1891 my $len = CORE::length($$hs)-2;
1892 $len = int($len/4); # 4-digit parts, w/o '0x'
1893 my $val; my $i = -4;
1896 $val = substr($$hs,$i,4);
1897 $val =~ s/^[+-]?0x// if $len == 0; # for last part only because
1898 $val = hex($val); # hex does not like wrong chars
1899 # print "$val ",substr($$hs,$i,4),"\n";
1901 $x += $mul * $val if $val != 0;
1902 $mul *= $x65536 if $len >= 0; # skip last mul
1905 $x->{sign} = $sign if !$x->is_zero(); # no '-0'
1911 # convert a (ref to) big binary string to BigInt, return undef for error
1914 my $x = Math::BigInt->bzero();
1915 return $x->bnan() if $$bs !~ /^[+-]?0b[01]+$/;
1917 my $mul = Math::BigInt->bzero(); $mul++;
1918 my $x256 = Math::BigInt->new(256);
1920 my $sign = '+'; $sign = '-' if ($$bs =~ /^\-/);
1921 $$bs =~ s/^[+-]//; # strip sign
1922 if ($CALC->can('_from_bin'))
1924 $x->{value} = $CALC->_from_bin($bs);
1928 my $len = CORE::length($$bs)-2;
1929 $len = int($len/8); # 8-digit parts, w/o '0b'
1930 my $val; my $i = -8;
1933 $val = substr($$bs,$i,8);
1934 $val =~ s/^[+-]?0b// if $len == 0; # for last part only
1935 #$val = oct('0b'.$val); # does not work on Perl prior to 5.6.0
1936 $val = ('0' x (8-CORE::length($val))).$val if CORE::length($val) < 8;
1937 $val = ord(pack('B8',$val));
1938 # print "$val ",substr($$bs,$i,16),"\n";
1940 $x += $mul * $val if $val != 0;
1941 $mul *= $x256 if $len >= 0; # skip last mul
1944 $x->{sign} = $sign if !$x->is_zero();
1950 # (ref to num_str) return num_str
1951 # internal, take apart a string and return the pieces
1952 # strip leading/trailing whitespace, leading zeros, underscore and reject
1956 # strip white space at front, also extranous leading zeros
1957 $$x =~ s/^\s*([-]?)0*([0-9])/$1$2/g; # will not strip ' .2'
1958 $$x =~ s/^\s+//; # but this will
1959 $$x =~ s/\s+$//g; # strip white space at end
1961 # shortcut, if nothing to split, return early
1962 if ($$x =~ /^[+-]?\d+$/)
1964 $$x =~ s/^([+-])0*([0-9])/$2/; my $sign = $1 || '+';
1965 return (\$sign, $x, \'', \'', \0);
1968 # invalid starting char?
1969 return if $$x !~ /^[+-]?(\.?[0-9]|0b[0-1]|0x[0-9a-fA-F])/;
1971 $$x =~ s/(\d)_(\d)/$1$2/g; # strip underscores between digits
1972 $$x =~ s/(\d)_(\d)/$1$2/g; # do twice for 1_2_3
1974 return __from_hex($x) if $$x =~ /^[\-\+]?0x/; # hex string
1975 return __from_bin($x) if $$x =~ /^[\-\+]?0b/; # binary string
1977 # some possible inputs:
1978 # 2.1234 # 0.12 # 1 # 1E1 # 2.134E1 # 434E-10 # 1.02009E-2
1979 # .2 # 1_2_3.4_5_6 # 1.4E1_2_3 # 1e3 # +.2
1981 #print "input: '$$x' ";
1982 my ($m,$e) = split /[Ee]/,$$x;
1983 $e = '0' if !defined $e || $e eq "";
1984 # print "m '$m' e '$e'\n";
1985 # sign,value for exponent,mantint,mantfrac
1986 my ($es,$ev,$mis,$miv,$mfv);
1988 if ($e =~ /^([+-]?)0*(\d+)$/) # strip leading zeros
1991 #print "'$m' '$e' e: $es $ev ";
1993 return if $m eq '.' || $m eq '';
1994 my ($mi,$mf) = split /\./,$m;
1995 $mi = '0' if !defined $mi;
1996 $mi .= '0' if $mi =~ /^[\-\+]?$/;
1997 $mf = '0' if !defined $mf || $mf eq '';
1998 if ($mi =~ /^([+-]?)0*(\d+)$/) # strip leading zeros
2000 $mis = $1||'+'; $miv = $2;
2001 # print "$mis $miv";
2002 # valid, existing fraction part of mantissa?
2003 return unless ($mf =~ /^(\d*?)0*$/); # strip trailing zeros
2005 #print " split: $mis $miv . $mfv E $es $ev\n";
2006 return (\$mis,\$miv,\$mfv,\$es,\$ev);
2009 return; # NaN, not a number
2014 # an object might be asked to return itself as bigint on certain overloaded
2015 # operations, this does exactly this, so that sub classes can simple inherit
2016 # it or override with their own integer conversion routine
2024 # return as hex string, with prefixed 0x
2025 my $x = shift; $x = $class->new($x) if !ref($x);
2027 return $x->bstr() if $x->{sign} !~ /^[+-]$/; # inf, nan etc
2028 return '0x0' if $x->is_zero();
2030 my $es = ''; my $s = '';
2031 $s = $x->{sign} if $x->{sign} eq '-';
2032 if ($CALC->can('_as_hex'))
2034 $es = ${$CALC->_as_hex($x->{value})};
2038 my $x1 = $x->copy()->babs(); my $xr;
2039 my $x100 = Math::BigInt->new (0x100);
2040 while (!$x1->is_zero())
2042 ($x1, $xr) = bdiv($x1,$x100);
2043 $es .= unpack('h2',pack('C',$xr->numify()));
2046 $es =~ s/^[0]+//; # strip leading zeros
2054 # return as binary string, with prefixed 0b
2055 my $x = shift; $x = $class->new($x) if !ref($x);
2057 return $x->bstr() if $x->{sign} !~ /^[+-]$/; # inf, nan etc
2058 return '0b0' if $x->is_zero();
2060 my $es = ''; my $s = '';
2061 $s = $x->{sign} if $x->{sign} eq '-';
2062 if ($CALC->can('_as_bin'))
2064 $es = ${$CALC->_as_bin($x->{value})};
2068 my $x1 = $x->copy()->babs(); my $xr;
2069 my $x100 = Math::BigInt->new (0x100);
2070 while (!$x1->is_zero())
2072 ($x1, $xr) = bdiv($x1,$x100);
2073 $es .= unpack('b8',pack('C',$xr->numify()));
2076 $es =~ s/^[0]+//; # strip leading zeros
2082 ##############################################################################
2083 # internal calculation routines (others are in Math::BigInt::Calc etc)
2087 # (BINT or num_str, BINT or num_str) return BINT
2088 # does modify first argument
2091 my $x = shift; my $ty = shift;
2092 return $x->bnan() if ($x->{sign} eq $nan) || ($ty->{sign} eq $nan);
2093 return $x * $ty / bgcd($x,$ty);
2098 # (BINT or num_str, BINT or num_str) return BINT
2099 # does modify both arguments
2100 # GCD -- Euclids algorithm E, Knuth Vol 2 pg 296
2103 return $x->bnan() if $x->{sign} !~ /^[+-]$/ || $ty->{sign} !~ /^[+-]$/;
2105 while (!$ty->is_zero())
2107 ($x, $ty) = ($ty,bmod($x,$ty));
2112 ###############################################################################
2113 # this method return 0 if the object can be modified, or 1 for not
2114 # We use a fast use constant statement here, to avoid costly calls. Subclasses
2115 # may override it with special code (f.i. Math::BigInt::Constant does so)
2117 sub modify () { 0; }
2124 Math::BigInt - Arbitrary size integer math package
2131 $x = Math::BigInt->new($str); # defaults to 0
2132 $nan = Math::BigInt->bnan(); # create a NotANumber
2133 $zero = Math::BigInt->bzero(); # create a +0
2134 $inf = Math::BigInt->binf(); # create a +inf
2135 $inf = Math::BigInt->binf('-'); # create a -inf
2136 $one = Math::BigInt->bone(); # create a +1
2137 $one = Math::BigInt->bone('-'); # create a -1
2140 $x->is_zero(); # true if arg is +0
2141 $x->is_nan(); # true if arg is NaN
2142 $x->is_one(); # true if arg is +1
2143 $x->is_one('-'); # true if arg is -1
2144 $x->is_odd(); # true if odd, false for even
2145 $x->is_even(); # true if even, false for odd
2146 $x->is_positive(); # true if >= 0
2147 $x->is_negative(); # true if < 0
2148 $x->is_inf(sign); # true if +inf, or -inf (sign is default '+')
2150 $x->bcmp($y); # compare numbers (undef,<0,=0,>0)
2151 $x->bacmp($y); # compare absolutely (undef,<0,=0,>0)
2152 $x->sign(); # return the sign, either +,- or NaN
2153 $x->digit($n); # return the nth digit, counting from right
2154 $x->digit(-$n); # return the nth digit, counting from left
2156 # The following all modify their first argument:
2159 $x->bzero(); # set $x to 0
2160 $x->bnan(); # set $x to NaN
2161 $x->bone(); # set $x to +1
2162 $x->bone('-'); # set $x to -1
2164 $x->bneg(); # negation
2165 $x->babs(); # absolute value
2166 $x->bnorm(); # normalize (no-op)
2167 $x->bnot(); # two's complement (bit wise not)
2168 $x->binc(); # increment x by 1
2169 $x->bdec(); # decrement x by 1
2171 $x->badd($y); # addition (add $y to $x)
2172 $x->bsub($y); # subtraction (subtract $y from $x)
2173 $x->bmul($y); # multiplication (multiply $x by $y)
2174 $x->bdiv($y); # divide, set $x to quotient
2175 # return (quo,rem) or quo if scalar
2177 $x->bmod($y); # modulus (x % y)
2178 $x->bpow($y); # power of arguments (x ** y)
2179 $x->blsft($y); # left shift
2180 $x->brsft($y); # right shift
2181 $x->blsft($y,$n); # left shift, by base $n (like 10)
2182 $x->brsft($y,$n); # right shift, by base $n (like 10)
2184 $x->band($y); # bitwise and
2185 $x->bior($y); # bitwise inclusive or
2186 $x->bxor($y); # bitwise exclusive or
2187 $x->bnot(); # bitwise not (two's complement)
2189 $x->bsqrt(); # calculate square-root
2191 $x->round($A,$P,$round_mode); # round to accuracy or precision using mode $r
2192 $x->bround($N); # accuracy: preserve $N digits
2193 $x->bfround($N); # round to $Nth digit, no-op for BigInts
2195 # The following do not modify their arguments in BigInt, but do in BigFloat:
2196 $x->bfloor(); # return integer less or equal than $x
2197 $x->bceil(); # return integer greater or equal than $x
2199 # The following do not modify their arguments:
2201 bgcd(@values); # greatest common divisor (no OO style)
2202 blcm(@values); # lowest common multiplicator (no OO style)
2204 $x->length(); # return number of digits in number
2205 ($x,$f) = $x->length(); # length of number and length of fraction part,
2206 # latter is always 0 digits long for BigInt's
2208 $x->exponent(); # return exponent as BigInt
2209 $x->mantissa(); # return (signed) mantissa as BigInt
2210 $x->parts(); # return (mantissa,exponent) as BigInt
2211 $x->copy(); # make a true copy of $x (unlike $y = $x;)
2212 $x->as_number(); # return as BigInt (in BigInt: same as copy())
2214 # conversation to string
2215 $x->bstr(); # normalized string
2216 $x->bsstr(); # normalized string in scientific notation
2217 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
2218 $x->as_bin(); # as signed binary string with prefixed 0b
2222 All operators (inlcuding basic math operations) are overloaded if you
2223 declare your big integers as
2225 $i = new Math::BigInt '123_456_789_123_456_789';
2227 Operations with overloaded operators preserve the arguments which is
2228 exactly what you expect.
2232 =item Canonical notation
2234 Big integer values are strings of the form C</^[+-]\d+$/> with leading
2237 '-0' canonical value '-0', normalized '0'
2238 ' -123_123_123' canonical value '-123123123'
2239 '1_23_456_7890' canonical value '1234567890'
2243 Input values to these routines may be either Math::BigInt objects or
2244 strings of the form C</^\s*[+-]?[\d]+\.?[\d]*E?[+-]?[\d]*$/>.
2246 You can include one underscore between any two digits.
2248 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
2249 Non integer values result in NaN.
2251 Math::BigInt::new() defaults to 0, while Math::BigInt::new('') results
2254 bnorm() on a BigInt object is now effectively a no-op, since the numbers
2255 are always stored in normalized form. On a string, it creates a BigInt
2260 Output values are BigInt objects (normalized), except for bstr(), which
2261 returns a string in normalized form.
2262 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
2263 C<is_nan()>) return true or false, while others (C<bcmp()>, C<bacmp()>)
2264 return either undef, <0, 0 or >0 and are suited for sort.
2268 =head1 ACCURACY and PRECISION
2270 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
2271 accuracy and precision based rounding, both automatically after every
2272 operation as well as manually.
2274 This section describes the accuracy/precision handling in Math::Big* as it
2275 used to be and as it is now, complete with an explanation of all terms and
2278 Not yet implemented things (but with correct description) are marked with '!',
2279 things that need to be answered are marked with '?'.
2281 In the next paragraph follows a short description of terms used here (because
2282 these may differ from terms used by others people or documentation).
2284 During the rest of this document, the shortcuts A (for accuracy), P (for
2285 precision), F (fallback) and R (rounding mode) will be used.
2289 A fixed number of digits before (positive) or after (negative)
2290 the decimal point. For example, 123.45 has a precision of -2. 0 means an
2291 integer like 123 (or 120). A precision of 2 means two digits to the left
2292 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
2293 numbers with zeros before the decimal point may have different precisions,
2294 because 1200 can have p = 0, 1 or 2 (depending on what the inital value
2295 was). It could also have p < 0, when the digits after the decimal point
2298 The string output (of floating point numbers) will be padded with zeros:
2300 Initial value P A Result String
2301 ------------------------------------------------------------
2302 1234.01 -3 1000 1000
2305 1234.001 1 1234 1234.0
2307 1234.01 2 1234.01 1234.01
2308 1234.01 5 1234.01 1234.01000
2310 For BigInts, no padding occurs.
2314 Number of significant digits. Leading zeros are not counted. A
2315 number may have an accuracy greater than the non-zero digits
2316 when there are zeros in it or trailing zeros. For example, 123.456 has
2317 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
2319 The string output (of floating point numbers) will be padded with zeros:
2321 Initial value P A Result String
2322 ------------------------------------------------------------
2324 1234.01 6 1234.01 1234.01
2325 1234.1 8 1234.1 1234.1000
2327 For BigInts, no padding occurs.
2331 When both A and P are undefined, this is used as a fallback accuracy when
2334 =head2 Rounding mode R
2336 When rounding a number, different 'styles' or 'kinds'
2337 of rounding are possible. (Note that random rounding, as in
2338 Math::Round, is not implemented.)
2344 truncation invariably removes all digits following the
2345 rounding place, replacing them with zeros. Thus, 987.65 rounded
2346 to tens (P=1) becomes 980, and rounded to the fourth sigdig
2347 becomes 987.6 (A=4). 123.456 rounded to the second place after the
2348 decimal point (P=-2) becomes 123.46.
2350 All other implemented styles of rounding attempt to round to the
2351 "nearest digit." If the digit D immediately to the right of the
2352 rounding place (skipping the decimal point) is greater than 5, the
2353 number is incremented at the rounding place (possibly causing a
2354 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
2355 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
2356 truncated at the rounding place: e.g. when rounding to units, 0.4
2357 rounds to 0, and -19.4 rounds to -19.
2359 However the results of other styles of rounding differ if the
2360 digit immediately to the right of the rounding place (skipping the
2361 decimal point) is 5 and if there are no digits, or no digits other
2362 than 0, after that 5. In such cases:
2366 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
2367 if it is not already. E.g., when rounding to the first sigdig, 0.45
2368 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
2372 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
2373 it is not already. E.g., when rounding to the first sigdig, 0.45
2374 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
2378 round to plus infinity, i.e. always round up. E.g., when
2379 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
2380 and 0.4501 also becomes 0.5.
2384 round to minus infinity, i.e. always round down. E.g., when
2385 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
2386 but 0.4501 becomes 0.5.
2390 round to zero, i.e. positive numbers down, negative ones up.
2391 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
2392 becomes -0.5, but 0.4501 becomes 0.5.
2396 The handling of A & P in MBI/MBF (the old core code shipped with Perl
2397 versions <= 5.7.2) is like this:
2403 * ffround($p) is able to round to $p number of digits after the decimal
2405 * otherwise P is unused
2407 =item Accuracy (significant digits)
2409 * fround($a) rounds to $a significant digits
2410 * only fdiv() and fsqrt() take A as (optional) paramater
2411 + other operations simply create the same number (fneg etc), or more (fmul)
2413 + rounding/truncating is only done when explicitly calling one of fround
2414 or ffround, and never for BigInt (not implemented)
2415 * fsqrt() simply hands its accuracy argument over to fdiv.
2416 * the documentation and the comment in the code indicate two different ways
2417 on how fdiv() determines the maximum number of digits it should calculate,
2418 and the actual code does yet another thing
2420 max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
2422 result has at most max(scale, length(dividend), length(divisor)) digits
2424 scale = max(scale, length(dividend)-1,length(divisor)-1);
2425 scale += length(divisior) - length(dividend);
2426 So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
2427 Actually, the 'difference' added to the scale is calculated from the
2428 number of "significant digits" in dividend and divisor, which is derived
2429 by looking at the length of the mantissa. Which is wrong, since it includes
2430 the + sign (oups) and actually gets 2 for '+100' and 4 for '+101'. Oups
2431 again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
2432 assumption that 124 has 3 significant digits, while 120/7 will get you
2433 '17', not '17.1' since 120 is thought to have 2 significant digits.
2434 The rounding after the division then uses the remainder and $y to determine
2435 wether it must round up or down.
2436 ? I have no idea which is the right way. That's why I used a slightly more
2437 ? simple scheme and tweaked the few failing testcases to match it.
2441 This is how it works now:
2445 =item Setting/Accessing
2447 * You can set the A global via $Math::BigInt::accuracy or
2448 $Math::BigFloat::accuracy or whatever class you are using.
2449 * You can also set P globally by using $Math::SomeClass::precision likewise.
2450 * Globals are classwide, and not inherited by subclasses.
2451 * to undefine A, use $Math::SomeCLass::accuracy = undef
2452 * to undefine P, use $Math::SomeClass::precision = undef
2453 * To be valid, A must be > 0, P can have any value.
2454 * If P is negative, this means round to the P'th place to the right of the
2455 decimal point; positive values mean to the left of the decimal point.
2456 P of 0 means round to integer.
2457 * to find out the current global A, take $Math::SomeClass::accuracy
2458 * use $x->accuracy() for the local setting of $x.
2459 * to find out the current global P, take $Math::SomeClass::precision
2460 * use $x->precision() for the local setting
2462 =item Creating numbers
2464 !* When you create a number, there should be a way to define its A & P
2465 * When a number without specific A or P is created, but the globals are
2466 defined, these should be used to round the number immediately and also
2467 stored locally with the number. Thus changing the global defaults later on
2468 will not change the A or P of previously created numbers (i.e., A and P of
2469 $x will be what was in effect when $x was created)
2473 * If A or P are enabled/defined, they are used to round the result of each
2474 operation according to the rules below
2475 * Negative P is ignored in Math::BigInt, since BigInts never have digits
2476 after the decimal point
2477 * Math::BigFloat uses Math::BigInts internally, but setting A or P inside
2478 Math::BigInt as globals should not tamper with the parts of a BigFloat.
2479 Thus a flag is used to mark all Math::BigFloat numbers as 'never round'
2483 * It only makes sense that a number has only one of A or P at a time.
2484 Since you can set/get both A and P, there is a rule that will practically
2485 enforce only A or P to be in effect at a time, even if both are set.
2486 This is called precedence.
2487 !* If two objects are involved in an operation, and one of them has A in
2488 ! effect, and the other P, this should result in a warning or an error,
2490 * A takes precendence over P (Hint: A comes before P). If A is defined, it
2491 is used, otherwise P is used. If neither of them is defined, nothing is
2492 used, i.e. the result will have as many digits as it can (with an
2493 exception for fdiv/fsqrt) and will not be rounded.
2494 * There is another setting for fdiv() (and thus for fsqrt()). If neither of
2495 A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
2496 If either the dividend's or the divisor's mantissa has more digits than
2497 the value of F, the higher value will be used instead of F.
2498 This is to limit the digits (A) of the result (just consider what would
2499 happen with unlimited A and P in the case of 1/3 :-)
2500 * fdiv will calculate 1 more digit than required (determined by
2501 A, P or F), and, if F is not used, round the result
2502 (this will still fail in the case of a result like 0.12345000000001 with A
2503 or P of 5, but this can not be helped - or can it?)
2504 * Thus you can have the math done by on Math::Big* class in three modes:
2505 + never round (this is the default):
2506 This is done by setting A and P to undef. No math operation
2507 will round the result, with fdiv() and fsqrt() as exceptions to guard
2508 against overflows. You must explicitely call bround(), bfround() or
2509 round() (the latter with parameters).
2510 Note: Once you have rounded a number, the settings will 'stick' on it
2511 and 'infect' all other numbers engaged in math operations with it, since
2512 local settings have the highest precedence. So, to get SaferRound[tm],
2513 use a copy() before rounding like this:
2515 $x = Math::BigFloat->new(12.34);
2516 $y = Math::BigFloat->new(98.76);
2517 $z = $x * $y; # 1218.6984
2518 print $x->copy()->fround(3); # 12.3 (but A is now 3!)
2519 $z = $x * $y; # still 1218.6984, without
2520 # copy would have been 1210!
2522 + round after each op:
2523 After each single operation (except for testing like is_zero()), the
2524 method round() is called and the result is rounded appropriately. By
2525 setting proper values for A and P, you can have all-the-same-A or
2526 all-the-same-P modes. For example, Math::Currency might set A to undef,
2527 and P to -2, globally.
2529 ?Maybe an extra option that forbids local A & P settings would be in order,
2530 ?so that intermediate rounding does not 'poison' further math?
2532 =item Overriding globals
2534 * you will be able to give A, P and R as an argument to all the calculation
2535 routines; the second parameter is A, the third one is P, and the fourth is
2536 R (shift place by one for binary operations like add). P is used only if
2537 the first parameter (A) is undefined. These three parameters override the
2538 globals in the order detailed as follows, i.e. the first defined value
2540 (local: per object, global: global default, parameter: argument to sub)
2543 + local A (if defined on both of the operands: smaller one is taken)
2544 + local P (if defined on both of the operands: smaller one is taken)
2548 * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
2549 arguments (A and P) instead of one
2551 =item Local settings
2553 * You can set A and P locally by using $x->accuracy() and $x->precision()
2554 and thus force different A and P for different objects/numbers.
2555 * Setting A or P this way immediately rounds $x to the new value.
2559 * the rounding routines will use the respective global or local settings.
2560 fround()/bround() is for accuracy rounding, while ffround()/bfround()
2562 * the two rounding functions take as the second parameter one of the
2563 following rounding modes (R):
2564 'even', 'odd', '+inf', '-inf', 'zero', 'trunc'
2565 * you can set and get the global R by using Math::SomeClass->round_mode()
2566 or by setting $Math::SomeClass::round_mode
2567 * after each operation, $result->round() is called, and the result may
2568 eventually be rounded (that is, if A or P were set either locally,
2569 globally or as parameter to the operation)
2570 * to manually round a number, call $x->round($A,$P,$round_mode);
2571 this will round the number by using the appropriate rounding function
2572 and then normalize it.
2573 * rounding modifies the local settings of the number:
2575 $x = Math::BigFloat->new(123.456);
2579 Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
2580 will be 4 from now on.
2582 =item Default values
2591 * The defaults are set up so that the new code gives the same results as
2592 the old code (except in a few cases on fdiv):
2593 + Both A and P are undefined and thus will not be used for rounding
2594 after each operation.
2595 + round() is thus a no-op, unless given extra parameters A and P
2601 The actual numbers are stored as unsigned big integers (with seperate sign).
2602 You should neither care about nor depend on the internal representation; it
2603 might change without notice. Use only method calls like C<< $x->sign(); >>
2604 instead relying on the internal hash keys like in C<< $x->{sign}; >>.
2608 Math with the numbers is done (by default) by a module called
2609 Math::BigInt::Calc. This is equivalent to saying:
2611 use Math::BigInt lib => 'Calc';
2613 You can change this by using:
2615 use Math::BigInt lib => 'BitVect';
2617 The following would first try to find Math::BigInt::Foo, then
2618 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
2620 use Math::BigInt lib => 'Foo,Math::BigInt::Bar';
2622 Calc.pm uses as internal format an array of elements of some decimal base
2623 (usually 1e5, but this might change to 1e7) with the least significant digit
2624 first, while BitVect.pm uses a bit vector of base 2, most significant bit
2625 first. Other modules might use even different means of representing the
2626 numbers. See the respective module documentation for further details.
2630 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
2632 A sign of 'NaN' is used to represent the result when input arguments are not
2633 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
2634 minus infinity. You will get '+inf' when dividing a positive number by 0, and
2635 '-inf' when dividing any negative number by 0.
2637 =head2 mantissa(), exponent() and parts()
2639 C<mantissa()> and C<exponent()> return the said parts of the BigInt such
2642 $m = $x->mantissa();
2643 $e = $x->exponent();
2644 $y = $m * ( 10 ** $e );
2645 print "ok\n" if $x == $y;
2647 C<< ($m,$e) = $x->parts() >> is just a shortcut that gives you both of them
2648 in one go. Both the returned mantissa and exponent have a sign.
2650 Currently, for BigInts C<$e> will be always 0, except for NaN, +inf and -inf,
2651 where it will be NaN; and for $x == 0, where it will be 1
2652 (to be compatible with Math::BigFloat's internal representation of a zero as
2655 C<$m> will always be a copy of the original number. The relation between $e
2656 and $m might change in the future, but will always be equivalent in a
2657 numerical sense, e.g. $m might get minimized.
2661 use Math::BigInt qw(bstr);
2663 sub bint { Math::BigInt->new(shift); }
2665 $x = bstr("1234") # string "1234"
2666 $x = "$x"; # same as bstr()
2667 $x = bneg("1234") # Bigint "-1234"
2668 $x = Math::BigInt->bneg("1234"); # Bigint "-1234"
2669 $x = Math::BigInt->babs("-12345"); # Bigint "12345"
2670 $x = Math::BigInt->bnorm("-0 00"); # BigInt "0"
2671 $x = bint(1) + bint(2); # BigInt "3"
2672 $x = bint(1) + "2"; # ditto (auto-BigIntify of "2")
2673 $x = bint(1); # BigInt "1"
2674 $x = $x + 5 / 2; # BigInt "3"
2675 $x = $x ** 3; # BigInt "27"
2676 $x *= 2; # BigInt "54"
2677 $x = new Math::BigInt; # BigInt "0"
2679 $x = Math::BigInt->badd(4,5) # BigInt "9"
2680 $x = Math::BigInt::badd(4,5) # BigInt "9"
2681 print $x->bsstr(); # 9e+0
2683 Examples for rounding:
2688 $x = Math::BigFloat->new(123.4567);
2689 $y = Math::BigFloat->new(123.456789);
2690 $Math::BigFloat::accuracy = 4; # no more A than 4
2692 ok ($x->copy()->fround(),123.4); # even rounding
2693 print $x->copy()->fround(),"\n"; # 123.4
2694 Math::BigFloat->round_mode('odd'); # round to odd
2695 print $x->copy()->fround(),"\n"; # 123.5
2696 $Math::BigFloat::accuracy = 5; # no more A than 5
2697 Math::BigFloat->round_mode('odd'); # round to odd
2698 print $x->copy()->fround(),"\n"; # 123.46
2699 $y = $x->copy()->fround(4),"\n"; # A = 4: 123.4
2700 print "$y, ",$y->accuracy(),"\n"; # 123.4, 4
2702 $Math::BigFloat::accuracy = undef; # A not important
2703 $Math::BigFloat::precision = 2; # P important
2704 print $x->copy()->bnorm(),"\n"; # 123.46
2705 print $x->copy()->fround(),"\n"; # 123.46
2707 Examples for converting:
2709 my $x = Math::BigInt->new('0b1'.'01' x 123);
2710 print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
2712 =head1 Autocreating constants
2714 After C<use Math::BigInt ':constant'> all the B<integer> decimal constants
2715 in the given scope are converted to C<Math::BigInt>. This conversion
2716 happens at compile time.
2720 perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'
2722 prints the integer value of C<2**100>. Note that without conversion of
2723 constants the expression 2**100 will be calculated as perl scalar.
2725 Please note that strings and floating point constants are not affected,
2728 use Math::BigInt qw/:constant/;
2730 $x = 1234567890123456789012345678901234567890
2731 + 123456789123456789;
2732 $y = '1234567890123456789012345678901234567890'
2733 + '123456789123456789';
2735 do not work. You need an explicit Math::BigInt->new() around one of the
2740 Using the form $x += $y; etc over $x = $x + $y is faster, since a copy of $x
2741 must be made in the second case. For long numbers, the copy can eat up to 20%
2742 of the work (in the case of addition/subtraction, less for
2743 multiplication/division). If $y is very small compared to $x, the form
2744 $x += $y is MUCH faster than $x = $x + $y since making the copy of $x takes
2745 more time then the actual addition.
2747 With a technique called copy-on-write, the cost of copying with overload could
2748 be minimized or even completely avoided. This is currently not implemented.
2750 The new version of this module is slower on new(), bstr() and numify(). Some
2751 operations may be slower for small numbers, but are significantly faster for
2752 big numbers. Other operations are now constant (O(1), like bneg(), babs()
2753 etc), instead of O(N) and thus nearly always take much less time.
2755 If you find the Calc module to slow, try to install any of the replacement
2756 modules and see if they help you.
2758 =head2 Alternative math libraries
2760 You can use an alternative library to drive Math::BigInt via:
2762 use Math::BigInt lib => 'Module';
2764 The default is called Math::BigInt::Calc and is a pure-perl implementation
2765 that consists mainly of the standard routine present in earlier versions of
2768 There are also Math::BigInt::Scalar (primarily for testing) and
2769 Math::BigInt::BitVect; as well as Math::BigInt::Pari and likely others.
2770 All these can be found via L<http://search.cpan.org/>:
2772 use Math::BigInt lib => 'BitVect';
2774 my $x = Math::BigInt->new(2);
2775 print $x ** (1024*1024);
2777 For more benchmark results see http://bloodgate.com/perl/benchmarks.html
2783 =item Out of Memory!
2785 Under Perl prior to 5.6.0 having an C<use Math::BigInt ':constant';> and
2786 C<eval()> in your code will crash with "Out of memory". This is probably an
2787 overload/exporter bug. You can workaround by not having C<eval()>
2788 and ':constant' at the same time or upgrade your Perl to a newer version.
2790 =item Fails to load Calc on Perl prior 5.6.0
2792 Since eval(' use ...') can not be used in conjunction with ':constant', BigInt
2793 will fall back to eval { require ... } when loading the math lib on Perls
2794 prior to 5.6.0. This simple replaces '::' with '/' and thus might fail on
2795 filesystems using a different seperator.
2801 Some things might not work as you expect them. Below is documented what is
2802 known to be troublesome:
2806 =item stringify, bstr(), bsstr() and 'cmp'
2808 Both stringify and bstr() now drop the leading '+'. The old code would return
2809 '+3', the new returns '3'. This is to be consistent with Perl and to make
2810 cmp (especially with overloading) to work as you expect. It also solves
2811 problems with Test.pm, it's ok() uses 'eq' internally.
2813 Mark said, when asked about to drop the '+' altogether, or make only cmp work:
2815 I agree (with the first alternative), don't add the '+' on positive
2816 numbers. It's not as important anymore with the new internal
2817 form for numbers. It made doing things like abs and neg easier,
2818 but those have to be done differently now anyway.
2820 So, the following examples will now work all as expected:
2823 BEGIN { plan tests => 1 }
2826 my $x = new Math::BigInt 3*3;
2827 my $y = new Math::BigInt 3*3;
2830 print "$x eq 9" if $x eq $y;
2831 print "$x eq 9" if $x eq '9';
2832 print "$x eq 9" if $x eq 3*3;
2834 Additionally, the following still works:
2836 print "$x == 9" if $x == $y;
2837 print "$x == 9" if $x == 9;
2838 print "$x == 9" if $x == 3*3;
2840 There is now a C<bsstr()> method to get the string in scientific notation aka
2841 C<1e+2> instead of C<100>. Be advised that overloaded 'eq' always uses bstr()
2842 for comparisation, but Perl will represent some numbers as 100 and others
2843 as 1e+308. If in doubt, convert both arguments to Math::BigInt before doing eq:
2846 BEGIN { plan tests => 3 }
2849 $x = Math::BigInt->new('1e56'); $y = 1e56;
2850 ok ($x,$y); # will fail
2851 ok ($x->bsstr(),$y); # okay
2852 $y = Math::BigInt->new($y);
2855 There is not yet a way to get a number automatically represented in exactly
2856 the way Perl represents it.
2860 C<int()> will return (at least for Perl v5.7.1 and up) another BigInt, not a
2863 $x = Math::BigInt->new(123);
2864 $y = int($x); # BigInt 123
2865 $x = Math::BigFloat->new(123.45);
2866 $y = int($x); # BigInt 123
2868 In all Perl versions you can use C<as_number()> for the same effect:
2870 $x = Math::BigFloat->new(123.45);
2871 $y = $x->as_number(); # BigInt 123
2873 This also works for other subclasses, like Math::String.
2875 It is yet unlcear whether overloaded int() should return a scalar or a BigInt.
2879 The following will probably not do what you expect:
2881 $c = Math::BigInt->new(123);
2882 print $c->length(),"\n"; # prints 30
2884 It prints both the number of digits in the number and in the fraction part
2885 since print calls C<length()> in list context. Use something like:
2887 print scalar $c->length(),"\n"; # prints 3
2891 The following will probably not do what you expect:
2893 print $c->bdiv(10000),"\n";
2895 It prints both quotient and remainder since print calls C<bdiv()> in list
2896 context. Also, C<bdiv()> will modify $c, so be carefull. You probably want
2899 print $c / 10000,"\n";
2900 print scalar $c->bdiv(10000),"\n"; # or if you want to modify $c
2904 The quotient is always the greatest integer less than or equal to the
2905 real-valued quotient of the two operands, and the remainder (when it is
2906 nonzero) always has the same sign as the second operand; so, for
2916 As a consequence, the behavior of the operator % agrees with the
2917 behavior of Perl's built-in % operator (as documented in the perlop
2918 manpage), and the equation
2920 $x == ($x / $y) * $y + ($x % $y)
2922 holds true for any $x and $y, which justifies calling the two return
2923 values of bdiv() the quotient and remainder. The only exception to this rule
2924 are when $y == 0 and $x is negative, then the remainder will also be
2925 negative. See below under "infinity handling" for the reasoning behing this.
2927 Perl's 'use integer;' changes the behaviour of % and / for scalars, but will
2928 not change BigInt's way to do things. This is because under 'use integer' Perl
2929 will do what the underlying C thinks is right and this is different for each
2930 system. If you need BigInt's behaving exactly like Perl's 'use integer', bug
2931 the author to implement it ;)
2933 =item infinity handling
2935 Here are some examples that explain the reasons why certain results occur while
2938 The following table shows the result of the division and the remainder, so that
2939 the equation above holds true. Some "ordinary" cases are strewn in to show more
2940 clearly the reasoning:
2942 A / B = C, R so that C * B + R = A
2943 =========================================================
2944 5 / 8 = 0, 5 0 * 8 + 5 = 5
2945 0 / 8 = 0, 0 0 * 8 + 0 = 0
2946 0 / inf = 0, 0 0 * inf + 0 = 0
2947 0 /-inf = 0, 0 0 * -inf + 0 = 0
2948 5 / inf = 0, 5 0 * inf + 5 = 5
2949 5 /-inf = 0, 5 0 * -inf + 5 = 5
2950 -5/ inf = 0, -5 0 * inf + -5 = -5
2951 -5/-inf = 0, -5 0 * -inf + -5 = -5
2952 inf/ 5 = inf, 0 inf * 5 + 0 = inf
2953 -inf/ 5 = -inf, 0 -inf * 5 + 0 = -inf
2954 inf/ -5 = -inf, 0 -inf * -5 + 0 = inf
2955 -inf/ -5 = inf, 0 inf * -5 + 0 = -inf
2956 5/ 5 = 1, 0 1 * 5 + 0 = 5
2957 -5/ -5 = 1, 0 1 * -5 + 0 = -5
2958 inf/ inf = 1, 0 1 * inf + 0 = inf
2959 -inf/-inf = 1, 0 1 * -inf + 0 = -inf
2960 inf/-inf = -1, 0 -1 * -inf + 0 = inf
2961 -inf/ inf = -1, 0 1 * -inf + 0 = -inf
2962 8/ 0 = inf, 8 inf * 0 + 8 = 8
2963 inf/ 0 = inf, inf inf * 0 + inf = inf
2966 These cases below violate the "remainder has the sign of the second of the two
2967 arguments", since they wouldn't match up otherwise.
2969 A / B = C, R so that C * B + R = A
2970 ========================================================
2971 -inf/ 0 = -inf, -inf -inf * 0 + inf = -inf
2972 -8/ 0 = -inf, -8 -inf * 0 + 8 = -8
2974 =item Modifying and =
2978 $x = Math::BigFloat->new(5);
2981 It will not do what you think, e.g. making a copy of $x. Instead it just makes
2982 a second reference to the B<same> object and stores it in $y. Thus anything
2983 that modifies $x (except overloaded operators) will modify $y, and vice versa.
2984 Or in other words, C<=> is only safe if you modify your BigInts only via
2985 overloaded math. As soon as you use a method call it breaks:
2988 print "$x, $y\n"; # prints '10, 10'
2990 If you want a true copy of $x, use:
2994 You can also chain the calls like this, this will make first a copy and then
2997 $y = $x->copy()->bmul(2);
2999 See also the documentation for overload.pm regarding C<=>.
3003 C<bpow()> (and the rounding functions) now modifies the first argument and
3004 returns it, unlike the old code which left it alone and only returned the
3005 result. This is to be consistent with C<badd()> etc. The first three will
3006 modify $x, the last one won't:
3008 print bpow($x,$i),"\n"; # modify $x
3009 print $x->bpow($i),"\n"; # ditto
3010 print $x **= $i,"\n"; # the same
3011 print $x ** $i,"\n"; # leave $x alone
3013 The form C<$x **= $y> is faster than C<$x = $x ** $y;>, though.
3015 =item Overloading -$x
3025 since overload calls C<sub($x,0,1);> instead of C<neg($x)>. The first variant
3026 needs to preserve $x since it does not know that it later will get overwritten.
3027 This makes a copy of $x and takes O(N), but $x->bneg() is O(1).
3029 With Copy-On-Write, this issue will be gone. Stay tuned...
3031 =item Mixing different object types
3033 In Perl you will get a floating point value if you do one of the following:
3039 With overloaded math, only the first two variants will result in a BigFloat:
3044 $mbf = Math::BigFloat->new(5);
3045 $mbi2 = Math::BigInteger->new(5);
3046 $mbi = Math::BigInteger->new(2);
3048 # what actually gets called:
3049 $float = $mbf + $mbi; # $mbf->badd()
3050 $float = $mbf / $mbi; # $mbf->bdiv()
3051 $integer = $mbi + $mbf; # $mbi->badd()
3052 $integer = $mbi2 / $mbi; # $mbi2->bdiv()
3053 $integer = $mbi2 / $mbf; # $mbi2->bdiv()
3055 This is because math with overloaded operators follows the first (dominating)
3056 operand, this one's operation is called and returns thus the result. So,
3057 Math::BigInt::bdiv() will always return a Math::BigInt, regardless whether
3058 the result should be a Math::BigFloat or the second operant is one.
3060 To get a Math::BigFloat you either need to call the operation manually,
3061 make sure the operands are already of the proper type or casted to that type
3062 via Math::BigFloat->new():
3064 $float = Math::BigFloat->new($mbi2) / $mbi; # = 2.5
3066 Beware of simple "casting" the entire expression, this would only convert
3067 the already computed result:
3069 $float = Math::BigFloat->new($mbi2 / $mbi); # = 2.0 thus wrong!
3071 Beware also of the order of more complicated expressions like:
3073 $integer = ($mbi2 + $mbi) / $mbf; # int / float => int
3074 $integer = $mbi2 / Math::BigFloat->new($mbi); # ditto
3076 If in doubt, break the expression into simpler terms, or cast all operands
3077 to the desired resulting type.
3079 Scalar values are a bit different, since:
3084 will both result in the proper type due to the way the overloaded math works.
3086 This section also applies to other overloaded math packages, like Math::String.
3090 C<bsqrt()> works only good if the result is an big integer, e.g. the square
3091 root of 144 is 12, but from 12 the square root is 3, regardless of rounding
3094 If you want a better approximation of the square root, then use:
3096 $x = Math::BigFloat->new(12);
3097 $Math::BigFloat::precision = 0;
3098 Math::BigFloat->round_mode('even');
3099 print $x->copy->bsqrt(),"\n"; # 4
3101 $Math::BigFloat::precision = 2;
3102 print $x->bsqrt(),"\n"; # 3.46
3103 print $x->bsqrt(3),"\n"; # 3.464
3109 This program is free software; you may redistribute it and/or modify it under
3110 the same terms as Perl itself.
3114 L<Math::BigFloat> and L<Math::Big>.
3116 L<Math::BigInt::BitVect> and L<Math::BigInt::Pari>.
3120 Original code by Mark Biggar, overloaded interface by Ilya Zakharevich.
3121 Completely rewritten by Tels http://bloodgate.com in late 2000, 2001.