4 # "Mike had an infinite amount to do and a negative amount of time in which
5 # to do it." - Before and After
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
13 # _f : flags, used by MBF to flag parts of a float as untouchable
15 # Remember not to take shortcuts ala $xs = $x->{value}; $CALC->foo($xs); since
16 # underlying lib might change the reference!
18 my $class = "Math::BigInt";
24 @EXPORT_OK = qw(objectify bgcd blcm);
26 # _trap_inf and _trap_nan are internal and should never be accessed from the
28 use vars qw/$round_mode $accuracy $precision $div_scale $rnd_mode
29 $upgrade $downgrade $_trap_nan $_trap_inf/;
32 # Inside overload, the first arg is always an object. If the original code had
33 # it reversed (like $x = 2 * $y), then the third paramater is true.
34 # In some cases (like add, $x = $x + 2 is the same as $x = 2 + $x) this makes
35 # no difference, but in some cases it does.
37 # For overloaded ops with only one argument we simple use $_[0]->copy() to
38 # preserve the argument.
40 # Thus inheritance of overload operators becomes possible and transparent for
41 # our subclasses without the need to repeat the entire overload section there.
44 '=' => sub { $_[0]->copy(); },
46 # some shortcuts for speed (assumes that reversed order of arguments is routed
47 # to normal '+' and we thus can always modify first arg. If this is changed,
48 # this breaks and must be adjusted.)
49 '+=' => sub { $_[0]->badd($_[1]); },
50 '-=' => sub { $_[0]->bsub($_[1]); },
51 '*=' => sub { $_[0]->bmul($_[1]); },
52 '/=' => sub { scalar $_[0]->bdiv($_[1]); },
53 '%=' => sub { $_[0]->bmod($_[1]); },
54 '^=' => sub { $_[0]->bxor($_[1]); },
55 '&=' => sub { $_[0]->band($_[1]); },
56 '|=' => sub { $_[0]->bior($_[1]); },
58 '**=' => sub { $_[0]->bpow($_[1]); },
59 '<<=' => sub { $_[0]->blsft($_[1]); },
60 '>>=' => sub { $_[0]->brsft($_[1]); },
62 # not supported by Perl yet
63 '..' => \&_pointpoint,
65 '<=>' => sub { my $rc = $_[2] ?
66 ref($_[0])->bcmp($_[1],$_[0]) :
68 $rc = 1 unless defined $rc;
71 # we need '>=' to get things like "1 >= NaN" right:
72 '>=' => sub { my $rc = $_[2] ?
73 ref($_[0])->bcmp($_[1],$_[0]) :
75 # if there was a NaN involved, return false
76 return '' unless defined $rc;
81 "$_[1]" cmp $_[0]->bstr() :
82 $_[0]->bstr() cmp "$_[1]" },
84 'cos' => sub { $_[0]->copy->bcos(); },
85 'sin' => sub { $_[0]->copy->bsin(); },
86 'atan2' => sub { $_[2] ?
87 ref($_[0])->new($_[1])->batan2($_[0]) :
88 $_[0]->copy()->batan2($_[1]) },
90 # are not yet overloadable
91 #'hex' => sub { print "hex"; $_[0]; },
92 #'oct' => sub { print "oct"; $_[0]; },
94 # log(N) is log(N, e), where e is Euler's number
95 'log' => sub { $_[0]->copy()->blog($_[1], undef); },
96 'exp' => sub { $_[0]->copy()->bexp($_[1]); },
97 'int' => sub { $_[0]->copy(); },
98 'neg' => sub { $_[0]->copy()->bneg(); },
99 'abs' => sub { $_[0]->copy()->babs(); },
100 'sqrt' => sub { $_[0]->copy()->bsqrt(); },
101 '~' => sub { $_[0]->copy()->bnot(); },
103 # for subtract it's a bit tricky to not modify b: b-a => -a+b
104 '-' => sub { my $c = $_[0]->copy; $_[2] ?
105 $c->bneg()->badd( $_[1]) :
107 '+' => sub { $_[0]->copy()->badd($_[1]); },
108 '*' => sub { $_[0]->copy()->bmul($_[1]); },
111 $_[2] ? ref($_[0])->new($_[1])->bdiv($_[0]) : $_[0]->copy->bdiv($_[1]);
114 $_[2] ? ref($_[0])->new($_[1])->bmod($_[0]) : $_[0]->copy->bmod($_[1]);
117 $_[2] ? ref($_[0])->new($_[1])->bpow($_[0]) : $_[0]->copy->bpow($_[1]);
120 $_[2] ? ref($_[0])->new($_[1])->blsft($_[0]) : $_[0]->copy->blsft($_[1]);
123 $_[2] ? ref($_[0])->new($_[1])->brsft($_[0]) : $_[0]->copy->brsft($_[1]);
126 $_[2] ? ref($_[0])->new($_[1])->band($_[0]) : $_[0]->copy->band($_[1]);
129 $_[2] ? ref($_[0])->new($_[1])->bior($_[0]) : $_[0]->copy->bior($_[1]);
132 $_[2] ? ref($_[0])->new($_[1])->bxor($_[0]) : $_[0]->copy->bxor($_[1]);
135 # can modify arg of ++ and --, so avoid a copy() for speed, but don't
136 # use $_[0]->bone(), it would modify $_[0] to be 1!
137 '++' => sub { $_[0]->binc() },
138 '--' => sub { $_[0]->bdec() },
140 # if overloaded, O(1) instead of O(N) and twice as fast for small numbers
142 # this kludge is needed for perl prior 5.6.0 since returning 0 here fails :-/
143 # v5.6.1 dumps on this: return !$_[0]->is_zero() || undef; :-(
145 $t = 1 if !$_[0]->is_zero();
149 # the original qw() does not work with the TIESCALAR below, why?
150 # Order of arguments unsignificant
151 '""' => sub { $_[0]->bstr(); },
152 '0+' => sub { $_[0]->numify(); }
155 ##############################################################################
156 # global constants, flags and accessory
158 # These vars are public, but their direct usage is not recommended, use the
159 # accessor methods instead
161 $round_mode = 'even'; # one of 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
166 $upgrade = undef; # default is no upgrade
167 $downgrade = undef; # default is no downgrade
169 # These are internally, and not to be used from the outside at all
171 $_trap_nan = 0; # are NaNs ok? set w/ config()
172 $_trap_inf = 0; # are infs ok? set w/ config()
173 my $nan = 'NaN'; # constants for easier life
175 my $CALC = 'Math::BigInt::FastCalc'; # module to do the low level math
176 # default is FastCalc.pm
177 my $IMPORT = 0; # was import() called yet?
178 # used to make require work
179 my %WARN; # warn only once for low-level libs
180 my %CAN; # cache for $CALC->can(...)
181 my %CALLBACKS; # callbacks to notify on lib loads
182 my $EMU_LIB = 'Math/BigInt/CalcEmu.pm'; # emulate low-level math
184 ##############################################################################
185 # the old code had $rnd_mode, so we need to support it, too
188 sub TIESCALAR { my ($class) = @_; bless \$round_mode, $class; }
189 sub FETCH { return $round_mode; }
190 sub STORE { $rnd_mode = $_[0]->round_mode($_[1]); }
194 # tie to enable $rnd_mode to work transparently
195 tie $rnd_mode, 'Math::BigInt';
197 # set up some handy alias names
198 *as_int = \&as_number;
199 *is_pos = \&is_positive;
200 *is_neg = \&is_negative;
203 ##############################################################################
208 # make Class->round_mode() work
210 my $class = ref($self) || $self || __PACKAGE__;
214 if ($m !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
216 require Carp; Carp::croak ("Unknown round mode '$m'");
218 return ${"${class}::round_mode"} = $m;
220 ${"${class}::round_mode"};
226 # make Class->upgrade() work
228 my $class = ref($self) || $self || __PACKAGE__;
229 # need to set new value?
232 return ${"${class}::upgrade"} = $_[0];
234 ${"${class}::upgrade"};
240 # make Class->downgrade() work
242 my $class = ref($self) || $self || __PACKAGE__;
243 # need to set new value?
246 return ${"${class}::downgrade"} = $_[0];
248 ${"${class}::downgrade"};
254 # make Class->div_scale() work
256 my $class = ref($self) || $self || __PACKAGE__;
261 require Carp; Carp::croak ('div_scale must be greater than zero');
263 ${"${class}::div_scale"} = $_[0];
265 ${"${class}::div_scale"};
270 # $x->accuracy($a); ref($x) $a
271 # $x->accuracy(); ref($x)
272 # Class->accuracy(); class
273 # Class->accuracy($a); class $a
276 my $class = ref($x) || $x || __PACKAGE__;
279 # need to set new value?
283 # convert objects to scalars to avoid deep recursion. If object doesn't
284 # have numify(), then hopefully it will have overloading for int() and
285 # boolean test without wandering into a deep recursion path...
286 $a = $a->numify() if ref($a) && $a->can('numify');
290 # also croak on non-numerical
294 Carp::croak ('Argument to accuracy must be greater than zero');
299 Carp::croak ('Argument to accuracy must be an integer');
304 # $object->accuracy() or fallback to global
305 $x->bround($a) if $a; # not for undef, 0
306 $x->{_a} = $a; # set/overwrite, even if not rounded
307 delete $x->{_p}; # clear P
308 $a = ${"${class}::accuracy"} unless defined $a; # proper return value
312 ${"${class}::accuracy"} = $a; # set global A
313 ${"${class}::precision"} = undef; # clear global P
315 return $a; # shortcut
319 # $object->accuracy() or fallback to global
320 $a = $x->{_a} if ref($x);
321 # but don't return global undef, when $x's accuracy is 0!
322 $a = ${"${class}::accuracy"} if !defined $a;
328 # $x->precision($p); ref($x) $p
329 # $x->precision(); ref($x)
330 # Class->precision(); class
331 # Class->precision($p); class $p
334 my $class = ref($x) || $x || __PACKAGE__;
340 # convert objects to scalars to avoid deep recursion. If object doesn't
341 # have numify(), then hopefully it will have overloading for int() and
342 # boolean test without wandering into a deep recursion path...
343 $p = $p->numify() if ref($p) && $p->can('numify');
344 if ((defined $p) && (int($p) != $p))
346 require Carp; Carp::croak ('Argument to precision must be an integer');
350 # $object->precision() or fallback to global
351 $x->bfround($p) if $p; # not for undef, 0
352 $x->{_p} = $p; # set/overwrite, even if not rounded
353 delete $x->{_a}; # clear A
354 $p = ${"${class}::precision"} unless defined $p; # proper return value
358 ${"${class}::precision"} = $p; # set global P
359 ${"${class}::accuracy"} = undef; # clear global A
361 return $p; # shortcut
365 # $object->precision() or fallback to global
366 $p = $x->{_p} if ref($x);
367 # but don't return global undef, when $x's precision is 0!
368 $p = ${"${class}::precision"} if !defined $p;
374 # return (or set) configuration data as hash ref
375 my $class = shift || 'Math::BigInt';
378 if (@_ > 1 || (@_ == 1 && (ref($_[0]) eq 'HASH')))
380 # try to set given options as arguments from hash
383 if (ref($args) ne 'HASH')
387 # these values can be "set"
391 upgrade downgrade precision accuracy round_mode div_scale/
394 $set_args->{$key} = $args->{$key} if exists $args->{$key};
395 delete $args->{$key};
400 Carp::croak ("Illegal key(s) '",
401 join("','",keys %$args),"' passed to $class\->config()");
403 foreach my $key (keys %$set_args)
405 if ($key =~ /^trap_(inf|nan)\z/)
407 ${"${class}::_trap_$1"} = ($set_args->{"trap_$1"} ? 1 : 0);
410 # use a call instead of just setting the $variable to check argument
411 $class->$key($set_args->{$key});
415 # now return actual configuration
419 lib_version => ${"${CALC}::VERSION"},
421 trap_nan => ${"${class}::_trap_nan"},
422 trap_inf => ${"${class}::_trap_inf"},
423 version => ${"${class}::VERSION"},
426 upgrade downgrade precision accuracy round_mode div_scale
429 $cfg->{$key} = ${"${class}::$key"};
431 if (@_ == 1 && (ref($_[0]) ne 'HASH'))
433 # calls of the style config('lib') return just this value
434 return $cfg->{$_[0]};
441 # select accuracy parameter based on precedence,
442 # used by bround() and bfround(), may return undef for scale (means no op)
443 my ($x,$scale,$mode) = @_;
445 $scale = $x->{_a} unless defined $scale;
450 $scale = ${ $class . '::accuracy' } unless defined $scale;
451 $mode = ${ $class . '::round_mode' } unless defined $mode;
455 $scale = $scale->can('numify') ? $scale->numify() : "$scale" if ref($scale);
456 $scale = int($scale);
464 # select precision parameter based on precedence,
465 # used by bround() and bfround(), may return undef for scale (means no op)
466 my ($x,$scale,$mode) = @_;
468 $scale = $x->{_p} unless defined $scale;
473 $scale = ${ $class . '::precision' } unless defined $scale;
474 $mode = ${ $class . '::round_mode' } unless defined $mode;
478 $scale = $scale->can('numify') ? $scale->numify() : "$scale" if ref($scale);
479 $scale = int($scale);
485 ##############################################################################
490 # if two arguments, the first one is the class to "swallow" subclasses
494 sign => $_[1]->{sign},
495 value => $CALC->_copy($_[1]->{value}),
498 $self->{_a} = $_[1]->{_a} if defined $_[1]->{_a};
499 $self->{_p} = $_[1]->{_p} if defined $_[1]->{_p};
504 sign => $_[0]->{sign},
505 value => $CALC->_copy($_[0]->{value}),
508 $self->{_a} = $_[0]->{_a} if defined $_[0]->{_a};
509 $self->{_p} = $_[0]->{_p} if defined $_[0]->{_p};
515 # create a new BigInt object from a string or another BigInt object.
516 # see hash keys documented at top
518 # the argument could be an object, so avoid ||, && etc on it, this would
519 # cause costly overloaded code to be called. The only allowed ops are
522 my ($class,$wanted,$a,$p,$r) = @_;
524 # avoid numify-calls by not using || on $wanted!
525 return $class->bzero($a,$p) if !defined $wanted; # default to 0
526 return $class->copy($wanted,$a,$p,$r)
527 if ref($wanted) && $wanted->isa($class); # MBI or subclass
529 $class->import() if $IMPORT == 0; # make require work
531 my $self = bless {}, $class;
533 # shortcut for "normal" numbers
534 if ((!ref $wanted) && ($wanted =~ /^([+-]?)[1-9][0-9]*\z/))
536 $self->{sign} = $1 || '+';
538 if ($wanted =~ /^[+-]/)
540 # remove sign without touching wanted to make it work with constants
541 my $t = $wanted; $t =~ s/^[+-]//;
542 $self->{value} = $CALC->_new($t);
546 $self->{value} = $CALC->_new($wanted);
549 if ( (defined $a) || (defined $p)
550 || (defined ${"${class}::precision"})
551 || (defined ${"${class}::accuracy"})
554 $self->round($a,$p,$r) unless (@_ == 4 && !defined $a && !defined $p);
559 # handle '+inf', '-inf' first
560 if ($wanted =~ /^[+-]?inf\z/)
562 $self->{sign} = $wanted; # set a default sign for bstr()
563 return $self->binf($wanted);
565 # split str in m mantissa, e exponent, i integer, f fraction, v value, s sign
566 my ($mis,$miv,$mfv,$es,$ev) = _split($wanted);
571 require Carp; Carp::croak("$wanted is not a number in $class");
573 $self->{value} = $CALC->_zero();
574 $self->{sign} = $nan;
579 # _from_hex or _from_bin
580 $self->{value} = $mis->{value};
581 $self->{sign} = $mis->{sign};
582 return $self; # throw away $mis
584 # make integer from mantissa by adjusting exp, then convert to bigint
585 $self->{sign} = $$mis; # store sign
586 $self->{value} = $CALC->_zero(); # for all the NaN cases
587 my $e = int("$$es$$ev"); # exponent (avoid recursion)
590 my $diff = $e - CORE::length($$mfv);
591 if ($diff < 0) # Not integer
595 require Carp; Carp::croak("$wanted not an integer in $class");
598 return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
599 $self->{sign} = $nan;
603 # adjust fraction and add it to value
604 #print "diff > 0 $$miv\n";
605 $$miv = $$miv . ($$mfv . '0' x $diff);
610 if ($$mfv ne '') # e <= 0
612 # fraction and negative/zero E => NOI
615 require Carp; Carp::croak("$wanted not an integer in $class");
617 #print "NOI 2 \$\$mfv '$$mfv'\n";
618 return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
619 $self->{sign} = $nan;
623 # xE-y, and empty mfv
626 if ($$miv !~ s/0{$e}$//) # can strip so many zero's?
630 require Carp; Carp::croak("$wanted not an integer in $class");
633 return $upgrade->new($wanted,$a,$p,$r) if defined $upgrade;
634 $self->{sign} = $nan;
638 $self->{sign} = '+' if $$miv eq '0'; # normalize -0 => +0
639 $self->{value} = $CALC->_new($$miv) if $self->{sign} =~ /^[+-]$/;
640 # if any of the globals is set, use them to round and store them inside $self
641 # do not round for new($x,undef,undef) since that is used by MBF to signal
643 $self->round($a,$p,$r) unless @_ == 4 && !defined $a && !defined $p;
649 # create a bigint 'NaN', if given a BigInt, set it to 'NaN'
651 $self = $class if !defined $self;
654 my $c = $self; $self = {}; bless $self, $c;
657 if (${"${class}::_trap_nan"})
660 Carp::croak ("Tried to set $self to NaN in $class\::bnan()");
662 $self->import() if $IMPORT == 0; # make require work
663 return if $self->modify('bnan');
664 if ($self->can('_bnan'))
666 # use subclass to initialize
671 # otherwise do our own thing
672 $self->{value} = $CALC->_zero();
674 $self->{sign} = $nan;
675 delete $self->{_a}; delete $self->{_p}; # rounding NaN is silly
681 # create a bigint '+-inf', if given a BigInt, set it to '+-inf'
682 # the sign is either '+', or if given, used from there
684 my $sign = shift; $sign = '+' if !defined $sign || $sign !~ /^-(inf)?$/;
685 $self = $class if !defined $self;
688 my $c = $self; $self = {}; bless $self, $c;
691 if (${"${class}::_trap_inf"})
694 Carp::croak ("Tried to set $self to +-inf in $class\::binf()");
696 $self->import() if $IMPORT == 0; # make require work
697 return if $self->modify('binf');
698 if ($self->can('_binf'))
700 # use subclass to initialize
705 # otherwise do our own thing
706 $self->{value} = $CALC->_zero();
708 $sign = $sign . 'inf' if $sign !~ /inf$/; # - => -inf
709 $self->{sign} = $sign;
710 ($self->{_a},$self->{_p}) = @_; # take over requested rounding
716 # create a bigint '+0', if given a BigInt, set it to 0
718 $self = __PACKAGE__ if !defined $self;
722 my $c = $self; $self = {}; bless $self, $c;
724 $self->import() if $IMPORT == 0; # make require work
725 return if $self->modify('bzero');
727 if ($self->can('_bzero'))
729 # use subclass to initialize
734 # otherwise do our own thing
735 $self->{value} = $CALC->_zero();
742 # call like: $x->bzero($a,$p,$r,$y);
743 ($self,$self->{_a},$self->{_p}) = $self->_find_round_parameters(@_);
748 if ( (!defined $self->{_a}) || (defined $_[0] && $_[0] > $self->{_a}));
750 if ( (!defined $self->{_p}) || (defined $_[1] && $_[1] > $self->{_p}));
758 # create a bigint '+1' (or -1 if given sign '-'),
759 # if given a BigInt, set it to +1 or -1, respectively
761 my $sign = shift; $sign = '+' if !defined $sign || $sign ne '-';
762 $self = $class if !defined $self;
766 my $c = $self; $self = {}; bless $self, $c;
768 $self->import() if $IMPORT == 0; # make require work
769 return if $self->modify('bone');
771 if ($self->can('_bone'))
773 # use subclass to initialize
778 # otherwise do our own thing
779 $self->{value} = $CALC->_one();
781 $self->{sign} = $sign;
786 # call like: $x->bone($sign,$a,$p,$r,$y);
787 ($self,$self->{_a},$self->{_p}) = $self->_find_round_parameters(@_);
791 # call like: $x->bone($sign,$a,$p,$r);
793 if ( (!defined $self->{_a}) || (defined $_[0] && $_[0] > $self->{_a}));
795 if ( (!defined $self->{_p}) || (defined $_[1] && $_[1] > $self->{_p}));
801 ##############################################################################
802 # string conversation
806 # (ref to BFLOAT or num_str ) return num_str
807 # Convert number from internal format to scientific string format.
808 # internal format is always normalized (no leading zeros, "-0E0" => "+0E0")
809 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
811 if ($x->{sign} !~ /^[+-]$/)
813 return $x->{sign} unless $x->{sign} eq '+inf'; # -inf, NaN
816 my ($m,$e) = $x->parts();
817 #$m->bstr() . 'e+' . $e->bstr(); # e can only be positive in BigInt
818 # 'e+' because E can only be positive in BigInt
819 $m->bstr() . 'e+' . $CALC->_str($e->{value});
824 # make a string from bigint object
825 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
827 if ($x->{sign} !~ /^[+-]$/)
829 return $x->{sign} unless $x->{sign} eq '+inf'; # -inf, NaN
832 my $es = ''; $es = $x->{sign} if $x->{sign} eq '-';
833 $es.$CALC->_str($x->{value});
838 # Make a "normal" scalar from a BigInt object
839 my $x = shift; $x = $class->new($x) unless ref $x;
841 return $x->bstr() if $x->{sign} !~ /^[+-]$/;
842 my $num = $CALC->_num($x->{value});
843 return -$num if $x->{sign} eq '-';
847 ##############################################################################
848 # public stuff (usually prefixed with "b")
852 # return the sign of the number: +/-/-inf/+inf/NaN
853 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
858 sub _find_round_parameters
860 # After any operation or when calling round(), the result is rounded by
861 # regarding the A & P from arguments, local parameters, or globals.
863 # !!!!!!! If you change this, remember to change round(), too! !!!!!!!!!!
865 # This procedure finds the round parameters, but it is for speed reasons
866 # duplicated in round. Otherwise, it is tested by the testsuite and used
869 # returns ($self) or ($self,$a,$p,$r) - sets $self to NaN of both A and P
870 # were requested/defined (locally or globally or both)
872 my ($self,$a,$p,$r,@args) = @_;
873 # $a accuracy, if given by caller
874 # $p precision, if given by caller
875 # $r round_mode, if given by caller
876 # @args all 'other' arguments (0 for unary, 1 for binary ops)
878 my $c = ref($self); # find out class of argument(s)
881 # convert to normal scalar for speed and correctness in inner parts
882 $a = $a->can('numify') ? $a->numify() : "$a" if defined $a && ref($a);
883 $p = $p->can('numify') ? $p->numify() : "$p" if defined $p && ref($p);
885 # now pick $a or $p, but only if we have got "arguments"
888 foreach ($self,@args)
890 # take the defined one, or if both defined, the one that is smaller
891 $a = $_->{_a} if (defined $_->{_a}) && (!defined $a || $_->{_a} < $a);
896 # even if $a is defined, take $p, to signal error for both defined
897 foreach ($self,@args)
899 # take the defined one, or if both defined, the one that is bigger
901 $p = $_->{_p} if (defined $_->{_p}) && (!defined $p || $_->{_p} > $p);
904 # if still none defined, use globals (#2)
905 $a = ${"$c\::accuracy"} unless defined $a;
906 $p = ${"$c\::precision"} unless defined $p;
908 # A == 0 is useless, so undef it to signal no rounding
909 $a = undef if defined $a && $a == 0;
912 return ($self) unless defined $a || defined $p; # early out
914 # set A and set P is an fatal error
915 return ($self->bnan()) if defined $a && defined $p; # error
917 $r = ${"$c\::round_mode"} unless defined $r;
918 if ($r !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
920 require Carp; Carp::croak ("Unknown round mode '$r'");
923 $a = int($a) if defined $a;
924 $p = int($p) if defined $p;
931 # Round $self according to given parameters, or given second argument's
932 # parameters or global defaults
934 # for speed reasons, _find_round_parameters is embeded here:
936 my ($self,$a,$p,$r,@args) = @_;
937 # $a accuracy, if given by caller
938 # $p precision, if given by caller
939 # $r round_mode, if given by caller
940 # @args all 'other' arguments (0 for unary, 1 for binary ops)
942 my $c = ref($self); # find out class of argument(s)
945 # now pick $a or $p, but only if we have got "arguments"
948 foreach ($self,@args)
950 # take the defined one, or if both defined, the one that is smaller
951 $a = $_->{_a} if (defined $_->{_a}) && (!defined $a || $_->{_a} < $a);
956 # even if $a is defined, take $p, to signal error for both defined
957 foreach ($self,@args)
959 # take the defined one, or if both defined, the one that is bigger
961 $p = $_->{_p} if (defined $_->{_p}) && (!defined $p || $_->{_p} > $p);
964 # if still none defined, use globals (#2)
965 $a = ${"$c\::accuracy"} unless defined $a;
966 $p = ${"$c\::precision"} unless defined $p;
968 # A == 0 is useless, so undef it to signal no rounding
969 $a = undef if defined $a && $a == 0;
972 return $self unless defined $a || defined $p; # early out
974 # set A and set P is an fatal error
975 return $self->bnan() if defined $a && defined $p;
977 $r = ${"$c\::round_mode"} unless defined $r;
978 if ($r !~ /^(even|odd|\+inf|\-inf|zero|trunc|common)$/)
980 require Carp; Carp::croak ("Unknown round mode '$r'");
983 # now round, by calling either fround or ffround:
986 $self->bround(int($a),$r) if !defined $self->{_a} || $self->{_a} >= $a;
988 else # both can't be undefined due to early out
990 $self->bfround(int($p),$r) if !defined $self->{_p} || $self->{_p} <= $p;
992 # bround() or bfround() already callled bnorm() if nec.
998 # (numstr or BINT) return BINT
999 # Normalize number -- no-op here
1000 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1006 # (BINT or num_str) return BINT
1007 # make number absolute, or return absolute BINT from string
1008 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1010 return $x if $x->modify('babs');
1011 # post-normalized abs for internal use (does nothing for NaN)
1012 $x->{sign} =~ s/^-/+/;
1018 # (BINT or num_str) return BINT
1019 # negate number or make a negated number from string
1020 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1022 return $x if $x->modify('bneg');
1024 # for +0 dont negate (to have always normalized +0). Does nothing for 'NaN'
1025 $x->{sign} =~ tr/+-/-+/ unless ($x->{sign} eq '+' && $CALC->_is_zero($x->{value}));
1031 # Compares 2 values. Returns one of undef, <0, =0, >0. (suitable for sort)
1032 # (BINT or num_str, BINT or num_str) return cond_code
1035 my ($self,$x,$y) = (ref($_[0]),@_);
1037 # objectify is costly, so avoid it
1038 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1040 ($self,$x,$y) = objectify(2,@_);
1043 return $upgrade->bcmp($x,$y) if defined $upgrade &&
1044 ((!$x->isa($self)) || (!$y->isa($self)));
1046 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1048 # handle +-inf and NaN
1049 return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1050 return 0 if $x->{sign} eq $y->{sign} && $x->{sign} =~ /^[+-]inf$/;
1051 return +1 if $x->{sign} eq '+inf';
1052 return -1 if $x->{sign} eq '-inf';
1053 return -1 if $y->{sign} eq '+inf';
1056 # check sign for speed first
1057 return 1 if $x->{sign} eq '+' && $y->{sign} eq '-'; # does also 0 <=> -y
1058 return -1 if $x->{sign} eq '-' && $y->{sign} eq '+'; # does also -x <=> 0
1060 # have same sign, so compare absolute values. Don't make tests for zero here
1061 # because it's actually slower than testin in Calc (especially w/ Pari et al)
1063 # post-normalized compare for internal use (honors signs)
1064 if ($x->{sign} eq '+')
1066 # $x and $y both > 0
1067 return $CALC->_acmp($x->{value},$y->{value});
1071 $CALC->_acmp($y->{value},$x->{value}); # swaped acmp (lib returns 0,1,-1)
1076 # Compares 2 values, ignoring their signs.
1077 # Returns one of undef, <0, =0, >0. (suitable for sort)
1078 # (BINT, BINT) return cond_code
1081 my ($self,$x,$y) = (ref($_[0]),@_);
1082 # objectify is costly, so avoid it
1083 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1085 ($self,$x,$y) = objectify(2,@_);
1088 return $upgrade->bacmp($x,$y) if defined $upgrade &&
1089 ((!$x->isa($self)) || (!$y->isa($self)));
1091 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1093 # handle +-inf and NaN
1094 return undef if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1095 return 0 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} =~ /^[+-]inf$/;
1096 return 1 if $x->{sign} =~ /^[+-]inf$/ && $y->{sign} !~ /^[+-]inf$/;
1099 $CALC->_acmp($x->{value},$y->{value}); # lib does only 0,1,-1
1104 # add second arg (BINT or string) to first (BINT) (modifies first)
1105 # return result as BINT
1108 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1109 # objectify is costly, so avoid it
1110 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1112 ($self,$x,$y,@r) = objectify(2,@_);
1115 return $x if $x->modify('badd');
1116 return $upgrade->badd($upgrade->new($x),$upgrade->new($y),@r) if defined $upgrade &&
1117 ((!$x->isa($self)) || (!$y->isa($self)));
1119 $r[3] = $y; # no push!
1120 # inf and NaN handling
1121 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/))
1124 return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1126 if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1128 # +inf++inf or -inf+-inf => same, rest is NaN
1129 return $x if $x->{sign} eq $y->{sign};
1132 # +-inf + something => +inf
1133 # something +-inf => +-inf
1134 $x->{sign} = $y->{sign}, return $x if $y->{sign} =~ /^[+-]inf$/;
1138 my ($sx, $sy) = ( $x->{sign}, $y->{sign} ); # get signs
1142 $x->{value} = $CALC->_add($x->{value},$y->{value}); # same sign, abs add
1146 my $a = $CALC->_acmp ($y->{value},$x->{value}); # absolute compare
1149 $x->{value} = $CALC->_sub($y->{value},$x->{value},1); # abs sub w/ swap
1154 # speedup, if equal, set result to 0
1155 $x->{value} = $CALC->_zero();
1160 $x->{value} = $CALC->_sub($x->{value}, $y->{value}); # abs sub
1168 # (BINT or num_str, BINT or num_str) return BINT
1169 # subtract second arg from first, modify first
1172 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1174 # objectify is costly, so avoid it
1175 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1177 ($self,$x,$y,@r) = objectify(2,@_);
1180 return $x if $x->modify('bsub');
1182 return $upgrade->new($x)->bsub($upgrade->new($y),@r) if defined $upgrade &&
1183 ((!$x->isa($self)) || (!$y->isa($self)));
1185 return $x->round(@r) if $y->is_zero();
1187 # To correctly handle the lone special case $x->bsub($x), we note the sign
1188 # of $x, then flip the sign from $y, and if the sign of $x did change, too,
1189 # then we caught the special case:
1190 my $xsign = $x->{sign};
1191 $y->{sign} =~ tr/+\-/-+/; # does nothing for NaN
1192 if ($xsign ne $x->{sign})
1194 # special case of $x->bsub($x) results in 0
1195 return $x->bzero(@r) if $xsign =~ /^[+-]$/;
1196 return $x->bnan(); # NaN, -inf, +inf
1198 $x->badd($y,@r); # badd does not leave internal zeros
1199 $y->{sign} =~ tr/+\-/-+/; # refix $y (does nothing for NaN)
1200 $x; # already rounded by badd() or no round nec.
1205 # increment arg by one
1206 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1207 return $x if $x->modify('binc');
1209 if ($x->{sign} eq '+')
1211 $x->{value} = $CALC->_inc($x->{value});
1212 return $x->round($a,$p,$r);
1214 elsif ($x->{sign} eq '-')
1216 $x->{value} = $CALC->_dec($x->{value});
1217 $x->{sign} = '+' if $CALC->_is_zero($x->{value}); # -1 +1 => -0 => +0
1218 return $x->round($a,$p,$r);
1220 # inf, nan handling etc
1221 $x->badd($self->bone(),$a,$p,$r); # badd does round
1226 # decrement arg by one
1227 my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1228 return $x if $x->modify('bdec');
1230 if ($x->{sign} eq '-')
1233 $x->{value} = $CALC->_inc($x->{value});
1237 return $x->badd($self->bone('-'),@r) unless $x->{sign} eq '+'; # inf or NaN
1239 if ($CALC->_is_zero($x->{value}))
1242 $x->{value} = $CALC->_one(); $x->{sign} = '-'; # 0 => -1
1247 $x->{value} = $CALC->_dec($x->{value});
1255 # calculate $x = $a ** $base + $b and return $a (e.g. the log() to base
1259 my ($self,$x,$base,@r) = (undef,@_);
1260 # objectify is costly, so avoid it
1261 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1263 ($self,$x,$base,@r) = objectify(1,ref($x),@_);
1266 return $x if $x->modify('blog');
1268 $base = $self->new($base) if defined $base && !ref $base;
1270 # inf, -inf, NaN, <0 => NaN
1272 if $x->{sign} ne '+' || (defined $base && $base->{sign} ne '+');
1274 return $upgrade->blog($upgrade->new($x),$base,@r) if
1277 # fix for bug #24969:
1278 # the default base is e (Euler's number) which is not an integer
1281 require Math::BigFloat;
1282 my $u = Math::BigFloat->blog(Math::BigFloat->new($x))->as_int();
1283 # modify $x in place
1284 $x->{value} = $u->{value};
1285 $x->{sign} = $u->{sign};
1289 my ($rc,$exact) = $CALC->_log_int($x->{value},$base->{value});
1290 return $x->bnan() unless defined $rc; # not possible to take log?
1297 # Calculate n over k (binomial coefficient or "choose" function) as integer.
1299 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1301 # objectify is costly, so avoid it
1302 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1304 ($self,$x,$y,@r) = objectify(2,@_);
1307 return $x if $x->modify('bnok');
1308 return $x->bnan() if $x->{sign} eq 'NaN' || $y->{sign} eq 'NaN';
1309 return $x->binf() if $x->{sign} eq '+inf';
1311 # k > n or k < 0 => 0
1312 my $cmp = $x->bacmp($y);
1313 return $x->bzero() if $cmp < 0 || $y->{sign} =~ /^-/;
1315 return $x->bone(@r) if $cmp == 0;
1317 if ($CALC->can('_nok'))
1319 $x->{value} = $CALC->_nok($x->{value},$y->{value});
1323 # ( 7 ) 7! 1*2*3*4 * 5*6*7 5 * 6 * 7 6 7
1324 # ( - ) = --------- = --------------- = --------- = 5 * - * -
1325 # ( 3 ) (7-3)! 3! 1*2*3*4 * 1*2*3 1 * 2 * 3 2 3
1331 my $r = $z->copy(); $z->binc();
1332 my $d = $self->new(2);
1333 while ($z->bacmp($x) <= 0) # f <= x ?
1335 $r->bmul($z); $r->bdiv($d);
1336 $z->binc(); $d->binc();
1338 $x->{value} = $r->{value}; $x->{sign} = '+';
1340 else { $x->bone(); }
1347 # Calculate e ** $x (Euler's number to the power of X), truncated to
1349 my ($self,$x,@r) = ref($_[0]) ? (ref($_[0]),@_) : objectify(1,@_);
1350 return $x if $x->modify('bexp');
1352 # inf, -inf, NaN, <0 => NaN
1353 return $x->bnan() if $x->{sign} eq 'NaN';
1354 return $x->bone() if $x->is_zero();
1355 return $x if $x->{sign} eq '+inf';
1356 return $x->bzero() if $x->{sign} eq '-inf';
1360 # run through Math::BigFloat unless told otherwise
1361 require Math::BigFloat unless defined $upgrade;
1362 local $upgrade = 'Math::BigFloat' unless defined $upgrade;
1363 # calculate result, truncate it to integer
1364 $u = $upgrade->bexp($upgrade->new($x),@r);
1367 if (!defined $upgrade)
1370 # modify $x in place
1371 $x->{value} = $u->{value};
1379 # (BINT or num_str, BINT or num_str) return BINT
1380 # does not modify arguments, but returns new object
1381 # Lowest Common Multiple
1383 my $y = shift; my ($x);
1390 $x = $class->new($y);
1395 my $y = shift; $y = $self->new($y) if !ref ($y);
1403 # (BINT or num_str, BINT or num_str) return BINT
1404 # does not modify arguments, but returns new object
1405 # GCD -- Euclids algorithm, variant C (Knuth Vol 3, pg 341 ff)
1408 $y = $class->new($y) if !ref($y);
1410 my $x = $y->copy()->babs(); # keep arguments
1411 return $x->bnan() if $x->{sign} !~ /^[+-]$/; # x NaN?
1415 $y = shift; $y = $self->new($y) if !ref($y);
1416 return $x->bnan() if $y->{sign} !~ /^[+-]$/; # y NaN?
1417 $x->{value} = $CALC->_gcd($x->{value},$y->{value});
1418 last if $CALC->_is_one($x->{value});
1425 # (num_str or BINT) return BINT
1426 # represent ~x as twos-complement number
1427 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1428 my ($self,$x,$a,$p,$r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1430 return $x if $x->modify('bnot');
1431 $x->binc()->bneg(); # binc already does round
1434 ##############################################################################
1435 # is_foo test routines
1436 # we don't need $self, so undef instead of ref($_[0]) make it slightly faster
1440 # return true if arg (BINT or num_str) is zero (array '+', '0')
1441 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1443 return 0 if $x->{sign} !~ /^\+$/; # -, NaN & +-inf aren't
1444 $CALC->_is_zero($x->{value});
1449 # return true if arg (BINT or num_str) is NaN
1450 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1452 $x->{sign} eq $nan ? 1 : 0;
1457 # return true if arg (BINT or num_str) is +-inf
1458 my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1462 $sign = '[+-]inf' if $sign eq ''; # +- doesn't matter, only that's inf
1463 $sign = "[$1]inf" if $sign =~ /^([+-])(inf)?$/; # extract '+' or '-'
1464 return $x->{sign} =~ /^$sign$/ ? 1 : 0;
1466 $x->{sign} =~ /^[+-]inf$/ ? 1 : 0; # only +-inf is infinity
1471 # return true if arg (BINT or num_str) is +1, or -1 if sign is given
1472 my ($self,$x,$sign) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1474 $sign = '+' if !defined $sign || $sign ne '-';
1476 return 0 if $x->{sign} ne $sign; # -1 != +1, NaN, +-inf aren't either
1477 $CALC->_is_one($x->{value});
1482 # return true when arg (BINT or num_str) is odd, false for even
1483 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1485 return 0 if $x->{sign} !~ /^[+-]$/; # NaN & +-inf aren't
1486 $CALC->_is_odd($x->{value});
1491 # return true when arg (BINT or num_str) is even, false for odd
1492 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1494 return 0 if $x->{sign} !~ /^[+-]$/; # NaN & +-inf aren't
1495 $CALC->_is_even($x->{value});
1500 # return true when arg (BINT or num_str) is positive (> 0)
1501 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1503 return 1 if $x->{sign} eq '+inf'; # +inf is positive
1505 # 0+ is neither positive nor negative
1506 ($x->{sign} eq '+' && !$x->is_zero()) ? 1 : 0;
1511 # return true when arg (BINT or num_str) is negative (< 0)
1512 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1514 $x->{sign} =~ /^-/ ? 1 : 0; # -inf is negative, but NaN is not
1519 # return true when arg (BINT or num_str) is an integer
1520 # always true for BigInt, but different for BigFloats
1521 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
1523 $x->{sign} =~ /^[+-]$/ ? 1 : 0; # inf/-inf/NaN aren't
1526 ###############################################################################
1530 # multiply the first number by the second number
1531 # (BINT or num_str, BINT or num_str) return BINT
1534 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1535 # objectify is costly, so avoid it
1536 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1538 ($self,$x,$y,@r) = objectify(2,@_);
1541 return $x if $x->modify('bmul');
1543 return $x->bnan() if (($x->{sign} eq $nan) || ($y->{sign} eq $nan));
1546 if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1548 return $x->bnan() if $x->is_zero() || $y->is_zero();
1549 # result will always be +-inf:
1550 # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1551 # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1552 return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/);
1553 return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/);
1554 return $x->binf('-');
1557 return $upgrade->bmul($x,$upgrade->new($y),@r)
1558 if defined $upgrade && !$y->isa($self);
1560 $r[3] = $y; # no push here
1562 $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1564 $x->{value} = $CALC->_mul($x->{value},$y->{value}); # do actual math
1565 $x->{sign} = '+' if $CALC->_is_zero($x->{value}); # no -0
1572 # multiply two numbers and then add the third to the result
1573 # (BINT or num_str, BINT or num_str, BINT or num_str) return BINT
1576 my ($self,$x,$y,$z,@r) = (ref($_[0]),@_);
1577 # objectify is costly, so avoid it
1578 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1580 ($self,$x,$y,$z,@r) = objectify(3,@_);
1583 return $x if $x->modify('bmuladd');
1585 return $x->bnan() if ($x->{sign} eq $nan) ||
1586 ($y->{sign} eq $nan) ||
1587 ($z->{sign} eq $nan);
1589 # inf handling of x and y
1590 if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1592 return $x->bnan() if $x->is_zero() || $y->is_zero();
1593 # result will always be +-inf:
1594 # +inf * +/+inf => +inf, -inf * -/-inf => +inf
1595 # +inf * -/-inf => -inf, -inf * +/+inf => -inf
1596 return $x->binf() if ($x->{sign} =~ /^\+/ && $y->{sign} =~ /^\+/);
1597 return $x->binf() if ($x->{sign} =~ /^-/ && $y->{sign} =~ /^-/);
1598 return $x->binf('-');
1600 # inf handling x*y and z
1601 if (($z->{sign} =~ /^[+-]inf$/))
1603 # something +-inf => +-inf
1604 $x->{sign} = $z->{sign}, return $x if $z->{sign} =~ /^[+-]inf$/;
1607 return $upgrade->bmuladd($x,$upgrade->new($y),$upgrade->new($z),@r)
1608 if defined $upgrade && (!$y->isa($self) || !$z->isa($self) || !$x->isa($self));
1610 # TODO: what if $y and $z have A or P set?
1611 $r[3] = $z; # no push here
1613 $x->{sign} = $x->{sign} eq $y->{sign} ? '+' : '-'; # +1 * +1 or -1 * -1 => +
1615 $x->{value} = $CALC->_mul($x->{value},$y->{value}); # do actual math
1616 $x->{sign} = '+' if $CALC->_is_zero($x->{value}); # no -0
1618 my ($sx, $sz) = ( $x->{sign}, $z->{sign} ); # get signs
1622 $x->{value} = $CALC->_add($x->{value},$z->{value}); # same sign, abs add
1626 my $a = $CALC->_acmp ($z->{value},$x->{value}); # absolute compare
1629 $x->{value} = $CALC->_sub($z->{value},$x->{value},1); # abs sub w/ swap
1634 # speedup, if equal, set result to 0
1635 $x->{value} = $CALC->_zero();
1640 $x->{value} = $CALC->_sub($x->{value}, $z->{value}); # abs sub
1648 # helper function that handles +-inf cases for bdiv()/bmod() to reuse code
1649 my ($self,$x,$y) = @_;
1651 # NaN if x == NaN or y == NaN or x==y==0
1652 return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan()
1653 if (($x->is_nan() || $y->is_nan()) ||
1654 ($x->is_zero() && $y->is_zero()));
1656 # +-inf / +-inf == NaN, reminder also NaN
1657 if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1659 return wantarray ? ($x->bnan(),$self->bnan()) : $x->bnan();
1661 # x / +-inf => 0, remainder x (works even if x == 0)
1662 if ($y->{sign} =~ /^[+-]inf$/)
1664 my $t = $x->copy(); # bzero clobbers up $x
1665 return wantarray ? ($x->bzero(),$t) : $x->bzero()
1668 # 5 / 0 => +inf, -6 / 0 => -inf
1669 # +inf / 0 = inf, inf, and -inf / 0 => -inf, -inf
1670 # exception: -8 / 0 has remainder -8, not 8
1671 # exception: -inf / 0 has remainder -inf, not inf
1674 # +-inf / 0 => special case for -inf
1675 return wantarray ? ($x,$x->copy()) : $x if $x->is_inf();
1676 if (!$x->is_zero() && !$x->is_inf())
1678 my $t = $x->copy(); # binf clobbers up $x
1680 ($x->binf($x->{sign}),$t) : $x->binf($x->{sign})
1684 # last case: +-inf / ordinary number
1686 $sign = '-inf' if substr($x->{sign},0,1) ne $y->{sign};
1688 return wantarray ? ($x,$self->bzero()) : $x;
1693 # (dividend: BINT or num_str, divisor: BINT or num_str) return
1694 # (BINT,BINT) (quo,rem) or BINT (only rem)
1697 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1698 # objectify is costly, so avoid it
1699 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1701 ($self,$x,$y,@r) = objectify(2,@_);
1704 return $x if $x->modify('bdiv');
1706 return $self->_div_inf($x,$y)
1707 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero());
1709 return $upgrade->bdiv($upgrade->new($x),$upgrade->new($y),@r)
1710 if defined $upgrade;
1712 $r[3] = $y; # no push!
1714 # calc new sign and in case $y == +/- 1, return $x
1715 my $xsign = $x->{sign}; # keep
1716 $x->{sign} = ($x->{sign} ne $y->{sign} ? '-' : '+');
1720 my $rem = $self->bzero();
1721 ($x->{value},$rem->{value}) = $CALC->_div($x->{value},$y->{value});
1722 $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1723 $rem->{_a} = $x->{_a};
1724 $rem->{_p} = $x->{_p};
1726 if (! $CALC->_is_zero($rem->{value}))
1728 $rem->{sign} = $y->{sign};
1729 $rem = $y->copy()->bsub($rem) if $xsign ne $y->{sign}; # one of them '-'
1733 $rem->{sign} = '+'; # dont leave -0
1739 $x->{value} = $CALC->_div($x->{value},$y->{value});
1740 $x->{sign} = '+' if $CALC->_is_zero($x->{value});
1745 ###############################################################################
1750 # modulus (or remainder)
1751 # (BINT or num_str, BINT or num_str) return BINT
1754 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1755 # objectify is costly, so avoid it
1756 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1758 ($self,$x,$y,@r) = objectify(2,@_);
1761 return $x if $x->modify('bmod');
1762 $r[3] = $y; # no push!
1763 if (($x->{sign} !~ /^[+-]$/) || ($y->{sign} !~ /^[+-]$/) || $y->is_zero())
1765 my ($d,$r) = $self->_div_inf($x,$y);
1766 $x->{sign} = $r->{sign};
1767 $x->{value} = $r->{value};
1768 return $x->round(@r);
1771 # calc new sign and in case $y == +/- 1, return $x
1772 $x->{value} = $CALC->_mod($x->{value},$y->{value});
1773 if (!$CALC->_is_zero($x->{value}))
1775 $x->{value} = $CALC->_sub($y->{value},$x->{value},1) # $y-$x
1776 if ($x->{sign} ne $y->{sign});
1777 $x->{sign} = $y->{sign};
1781 $x->{sign} = '+'; # dont leave -0
1788 # Modular inverse. given a number which is (hopefully) relatively
1789 # prime to the modulus, calculate its inverse using Euclid's
1790 # alogrithm. If the number is not relatively prime to the modulus
1791 # (i.e. their gcd is not one) then NaN is returned.
1794 my ($self,$x,$y,@r) = (undef,@_);
1795 # objectify is costly, so avoid it
1796 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1798 ($self,$x,$y,@r) = objectify(2,@_);
1801 return $x if $x->modify('bmodinv');
1804 if ($y->{sign} ne '+' # -, NaN, +inf, -inf
1805 || $x->is_zero() # or num == 0
1806 || $x->{sign} !~ /^[+-]$/ # or num NaN, inf, -inf
1809 # put least residue into $x if $x was negative, and thus make it positive
1810 $x->bmod($y) if $x->{sign} eq '-';
1813 ($x->{value},$sign) = $CALC->_modinv($x->{value},$y->{value});
1814 return $x->bnan() if !defined $x->{value}; # in case no GCD found
1815 return $x if !defined $sign; # already real result
1816 $x->{sign} = $sign; # flip/flop see below
1817 $x->bmod($y); # calc real result
1823 # takes a very large number to a very large exponent in a given very
1824 # large modulus, quickly, thanks to binary exponentation. Supports
1825 # negative exponents.
1826 my ($self,$num,$exp,$mod,@r) = objectify(3,@_);
1828 return $num if $num->modify('bmodpow');
1830 # check modulus for valid values
1831 return $num->bnan() if ($mod->{sign} ne '+' # NaN, - , -inf, +inf
1832 || $mod->is_zero());
1834 # check exponent for valid values
1835 if ($exp->{sign} =~ /\w/)
1837 # i.e., if it's NaN, +inf, or -inf...
1838 return $num->bnan();
1841 $num->bmodinv ($mod) if ($exp->{sign} eq '-');
1843 # check num for valid values (also NaN if there was no inverse but $exp < 0)
1844 return $num->bnan() if $num->{sign} !~ /^[+-]$/;
1846 # $mod is positive, sign on $exp is ignored, result also positive
1847 $num->{value} = $CALC->_modpow($num->{value},$exp->{value},$mod->{value});
1851 ###############################################################################
1855 # (BINT or num_str, BINT or num_str) return BINT
1856 # compute factorial number from $x, modify $x in place
1857 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
1859 return $x if $x->modify('bfac') || $x->{sign} eq '+inf'; # inf => inf
1860 return $x->bnan() if $x->{sign} ne '+'; # NaN, <0 etc => NaN
1862 $x->{value} = $CALC->_fac($x->{value});
1868 # (BINT or num_str, BINT or num_str) return BINT
1869 # compute power of two numbers -- stolen from Knuth Vol 2 pg 233
1870 # modifies first argument
1873 my ($self,$x,$y,@r) = (ref($_[0]),@_);
1874 # objectify is costly, so avoid it
1875 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1877 ($self,$x,$y,@r) = objectify(2,@_);
1880 return $x if $x->modify('bpow');
1882 return $x->bnan() if $x->{sign} eq $nan || $y->{sign} eq $nan;
1885 if (($x->{sign} =~ /^[+-]inf$/) || ($y->{sign} =~ /^[+-]inf$/))
1887 if (($x->{sign} =~ /^[+-]inf$/) && ($y->{sign} =~ /^[+-]inf$/))
1893 if ($x->{sign} =~ /^[+-]inf/)
1896 return $x->bnan() if $y->is_zero();
1897 # -inf ** -1 => 1/inf => 0
1898 return $x->bzero() if $y->is_one('-') && $x->is_negative();
1901 return $x if $x->{sign} eq '+inf';
1903 # -inf ** Y => -inf if Y is odd
1904 return $x if $y->is_odd();
1910 return $x if $x->is_one();
1913 return $x if $x->is_zero() && $y->{sign} =~ /^[+]/;
1916 return $x->binf() if $x->is_zero();
1919 return $x->bnan() if $x->is_one('-') && $y->{sign} =~ /^[-]/;
1922 return $x->bzero() if $x->{sign} eq '-' && $y->{sign} =~ /^[-]/;
1925 return $x->bnan() if $x->{sign} eq '-';
1928 return $x->binf() if $y->{sign} =~ /^[+]/;
1933 return $upgrade->bpow($upgrade->new($x),$y,@r)
1934 if defined $upgrade && (!$y->isa($self) || $y->{sign} eq '-');
1936 $r[3] = $y; # no push!
1938 # cases 0 ** Y, X ** 0, X ** 1, 1 ** Y are handled by Calc or Emu
1941 $new_sign = $y->is_odd() ? '-' : '+' if ($x->{sign} ne '+');
1943 # 0 ** -7 => ( 1 / (0 ** 7)) => 1 / 0 => +inf
1945 if $y->{sign} eq '-' && $x->{sign} eq '+' && $CALC->_is_zero($x->{value});
1946 # 1 ** -y => 1 / (1 ** |y|)
1947 # so do test for negative $y after above's clause
1948 return $x->bnan() if $y->{sign} eq '-' && !$CALC->_is_one($x->{value});
1950 $x->{value} = $CALC->_pow($x->{value},$y->{value});
1951 $x->{sign} = $new_sign;
1952 $x->{sign} = '+' if $CALC->_is_zero($y->{value});
1958 # (BINT or num_str, BINT or num_str) return BINT
1959 # compute x << y, base n, y >= 0
1962 my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
1963 # objectify is costly, so avoid it
1964 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1966 ($self,$x,$y,$n,@r) = objectify(2,@_);
1969 return $x if $x->modify('blsft');
1970 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1971 return $x->round(@r) if $y->is_zero();
1973 $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1975 $x->{value} = $CALC->_lsft($x->{value},$y->{value},$n);
1981 # (BINT or num_str, BINT or num_str) return BINT
1982 # compute x >> y, base n, y >= 0
1985 my ($self,$x,$y,$n,@r) = (ref($_[0]),@_);
1986 # objectify is costly, so avoid it
1987 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
1989 ($self,$x,$y,$n,@r) = objectify(2,@_);
1992 return $x if $x->modify('brsft');
1993 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
1994 return $x->round(@r) if $y->is_zero();
1995 return $x->bzero(@r) if $x->is_zero(); # 0 => 0
1997 $n = 2 if !defined $n; return $x->bnan() if $n <= 0 || $y->{sign} eq '-';
1999 # this only works for negative numbers when shifting in base 2
2000 if (($x->{sign} eq '-') && ($n == 2))
2002 return $x->round(@r) if $x->is_one('-'); # -1 => -1
2005 # although this is O(N*N) in calc (as_bin!) it is O(N) in Pari et al
2006 # but perhaps there is a better emulation for two's complement shift...
2007 # if $y != 1, we must simulate it by doing:
2008 # convert to bin, flip all bits, shift, and be done
2009 $x->binc(); # -3 => -2
2010 my $bin = $x->as_bin();
2011 $bin =~ s/^-0b//; # strip '-0b' prefix
2012 $bin =~ tr/10/01/; # flip bits
2014 if ($y >= CORE::length($bin))
2016 $bin = '0'; # shifting to far right creates -1
2017 # 0, because later increment makes
2018 # that 1, attached '-' makes it '-1'
2019 # because -1 >> x == -1 !
2023 $bin =~ s/.{$y}$//; # cut off at the right side
2024 $bin = '1' . $bin; # extend left side by one dummy '1'
2025 $bin =~ tr/10/01/; # flip bits back
2027 my $res = $self->new('0b'.$bin); # add prefix and convert back
2028 $res->binc(); # remember to increment
2029 $x->{value} = $res->{value}; # take over value
2030 return $x->round(@r); # we are done now, magic, isn't?
2032 # x < 0, n == 2, y == 1
2033 $x->bdec(); # n == 2, but $y == 1: this fixes it
2036 $x->{value} = $CALC->_rsft($x->{value},$y->{value},$n);
2042 #(BINT or num_str, BINT or num_str) return BINT
2046 my ($self,$x,$y,@r) = (ref($_[0]),@_);
2047 # objectify is costly, so avoid it
2048 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2050 ($self,$x,$y,@r) = objectify(2,@_);
2053 return $x if $x->modify('band');
2055 $r[3] = $y; # no push!
2057 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2059 my $sx = $x->{sign} eq '+' ? 1 : -1;
2060 my $sy = $y->{sign} eq '+' ? 1 : -1;
2062 if ($sx == 1 && $sy == 1)
2064 $x->{value} = $CALC->_and($x->{value},$y->{value});
2065 return $x->round(@r);
2068 if ($CAN{signed_and})
2070 $x->{value} = $CALC->_signed_and($x->{value},$y->{value},$sx,$sy);
2071 return $x->round(@r);
2075 __emu_band($self,$x,$y,$sx,$sy,@r);
2080 #(BINT or num_str, BINT or num_str) return BINT
2084 my ($self,$x,$y,@r) = (ref($_[0]),@_);
2085 # objectify is costly, so avoid it
2086 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2088 ($self,$x,$y,@r) = objectify(2,@_);
2091 return $x if $x->modify('bior');
2092 $r[3] = $y; # no push!
2094 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2096 my $sx = $x->{sign} eq '+' ? 1 : -1;
2097 my $sy = $y->{sign} eq '+' ? 1 : -1;
2099 # the sign of X follows the sign of X, e.g. sign of Y irrelevant for bior()
2101 # don't use lib for negative values
2102 if ($sx == 1 && $sy == 1)
2104 $x->{value} = $CALC->_or($x->{value},$y->{value});
2105 return $x->round(@r);
2108 # if lib can do negative values, let it handle this
2109 if ($CAN{signed_or})
2111 $x->{value} = $CALC->_signed_or($x->{value},$y->{value},$sx,$sy);
2112 return $x->round(@r);
2116 __emu_bior($self,$x,$y,$sx,$sy,@r);
2121 #(BINT or num_str, BINT or num_str) return BINT
2125 my ($self,$x,$y,@r) = (ref($_[0]),@_);
2126 # objectify is costly, so avoid it
2127 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2129 ($self,$x,$y,@r) = objectify(2,@_);
2132 return $x if $x->modify('bxor');
2133 $r[3] = $y; # no push!
2135 return $x->bnan() if ($x->{sign} !~ /^[+-]$/ || $y->{sign} !~ /^[+-]$/);
2137 my $sx = $x->{sign} eq '+' ? 1 : -1;
2138 my $sy = $y->{sign} eq '+' ? 1 : -1;
2140 # don't use lib for negative values
2141 if ($sx == 1 && $sy == 1)
2143 $x->{value} = $CALC->_xor($x->{value},$y->{value});
2144 return $x->round(@r);
2147 # if lib can do negative values, let it handle this
2148 if ($CAN{signed_xor})
2150 $x->{value} = $CALC->_signed_xor($x->{value},$y->{value},$sx,$sy);
2151 return $x->round(@r);
2155 __emu_bxor($self,$x,$y,$sx,$sy,@r);
2160 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2162 my $e = $CALC->_len($x->{value});
2163 wantarray ? ($e,0) : $e;
2168 # return the nth decimal digit, negative values count backward, 0 is right
2169 my ($self,$x,$n) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2171 $n = $n->numify() if ref($n);
2172 $CALC->_digit($x->{value},$n||0);
2177 # return the amount of trailing zeros in $x (as scalar)
2179 $x = $class->new($x) unless ref $x;
2181 return 0 if $x->{sign} !~ /^[+-]$/; # NaN, inf, -inf etc
2183 $CALC->_zeros($x->{value}); # must handle odd values, 0 etc
2188 # calculate square root of $x
2189 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2191 return $x if $x->modify('bsqrt');
2193 return $x->bnan() if $x->{sign} !~ /^\+/; # -x or -inf or NaN => NaN
2194 return $x if $x->{sign} eq '+inf'; # sqrt(+inf) == inf
2196 return $upgrade->bsqrt($x,@r) if defined $upgrade;
2198 $x->{value} = $CALC->_sqrt($x->{value});
2204 # calculate $y'th root of $x
2207 my ($self,$x,$y,@r) = (ref($_[0]),@_);
2209 $y = $self->new(2) unless defined $y;
2211 # objectify is costly, so avoid it
2212 if ((!ref($x)) || (ref($x) ne ref($y)))
2214 ($self,$x,$y,@r) = objectify(2,$self || $class,@_);
2217 return $x if $x->modify('broot');
2219 # NaN handling: $x ** 1/0, x or y NaN, or y inf/-inf or y == 0
2220 return $x->bnan() if $x->{sign} !~ /^\+/ || $y->is_zero() ||
2221 $y->{sign} !~ /^\+$/;
2223 return $x->round(@r)
2224 if $x->is_zero() || $x->is_one() || $x->is_inf() || $y->is_one();
2226 return $upgrade->new($x)->broot($upgrade->new($y),@r) if defined $upgrade;
2228 $x->{value} = $CALC->_root($x->{value},$y->{value});
2234 # return a copy of the exponent (here always 0, NaN or 1 for $m == 0)
2235 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2237 if ($x->{sign} !~ /^[+-]$/)
2239 my $s = $x->{sign}; $s =~ s/^[+-]//; # NaN, -inf,+inf => NaN or inf
2240 return $self->new($s);
2242 return $self->bone() if $x->is_zero();
2244 # 12300 => 2 trailing zeros => exponent is 2
2245 $self->new( $CALC->_zeros($x->{value}) );
2250 # return the mantissa (compatible to Math::BigFloat, e.g. reduced)
2251 my ($self,$x) = ref($_[0]) ? (ref($_[0]),$_[0]) : objectify(1,@_);
2253 if ($x->{sign} !~ /^[+-]$/)
2255 # for NaN, +inf, -inf: keep the sign
2256 return $self->new($x->{sign});
2258 my $m = $x->copy(); delete $m->{_p}; delete $m->{_a};
2260 # that's a bit inefficient:
2261 my $zeros = $CALC->_zeros($m->{value});
2262 $m->brsft($zeros,10) if $zeros != 0;
2268 # return a copy of both the exponent and the mantissa
2269 my ($self,$x) = ref($_[0]) ? (undef,$_[0]) : objectify(1,@_);
2271 ($x->mantissa(),$x->exponent());
2274 ##############################################################################
2275 # rounding functions
2279 # precision: round to the $Nth digit left (+$n) or right (-$n) from the '.'
2280 # $n == 0 || $n == 1 => round to integer
2281 my $x = shift; my $self = ref($x) || $x; $x = $self->new($x) unless ref $x;
2283 my ($scale,$mode) = $x->_scale_p(@_);
2285 return $x if !defined $scale || $x->modify('bfround'); # no-op
2287 # no-op for BigInts if $n <= 0
2288 $x->bround( $x->length()-$scale, $mode) if $scale > 0;
2290 delete $x->{_a}; # delete to save memory
2291 $x->{_p} = $scale; # store new _p
2295 sub _scan_for_nonzero
2297 # internal, used by bround() to scan for non-zeros after a '5'
2298 my ($x,$pad,$xs,$len) = @_;
2300 return 0 if $len == 1; # "5" is trailed by invisible zeros
2301 my $follow = $pad - 1;
2302 return 0 if $follow > $len || $follow < 1;
2304 # use the string form to check whether only '0's follow or not
2305 substr ($xs,-$follow) =~ /[^0]/ ? 1 : 0;
2310 # Exists to make life easier for switch between MBF and MBI (should we
2311 # autoload fxxx() like MBF does for bxxx()?)
2312 my $x = shift; $x = $class->new($x) unless ref $x;
2318 # accuracy: +$n preserve $n digits from left,
2319 # -$n preserve $n digits from right (f.i. for 0.1234 style in MBF)
2321 # and overwrite the rest with 0's, return normalized number
2322 # do not return $x->bnorm(), but $x
2324 my $x = shift; $x = $class->new($x) unless ref $x;
2325 my ($scale,$mode) = $x->_scale_a(@_);
2326 return $x if !defined $scale || $x->modify('bround'); # no-op
2328 if ($x->is_zero() || $scale == 0)
2330 $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2333 return $x if $x->{sign} !~ /^[+-]$/; # inf, NaN
2335 # we have fewer digits than we want to scale to
2336 my $len = $x->length();
2337 # convert $scale to a scalar in case it is an object (put's a limit on the
2338 # number length, but this would already limited by memory constraints), makes
2340 $scale = $scale->numify() if ref ($scale);
2342 # scale < 0, but > -len (not >=!)
2343 if (($scale < 0 && $scale < -$len-1) || ($scale >= $len))
2345 $x->{_a} = $scale if !defined $x->{_a} || $x->{_a} > $scale; # 3 > 2
2349 # count of 0's to pad, from left (+) or right (-): 9 - +6 => 3, or |-6| => 6
2350 my ($pad,$digit_round,$digit_after);
2351 $pad = $len - $scale;
2352 $pad = abs($scale-1) if $scale < 0;
2354 # do not use digit(), it is very costly for binary => decimal
2355 # getting the entire string is also costly, but we need to do it only once
2356 my $xs = $CALC->_str($x->{value});
2359 # pad: 123: 0 => -1, at 1 => -2, at 2 => -3, at 3 => -4
2360 # pad+1: 123: 0 => 0, at 1 => -1, at 2 => -2, at 3 => -3
2361 $digit_round = '0'; $digit_round = substr($xs,$pl,1) if $pad <= $len;
2362 $pl++; $pl ++ if $pad >= $len;
2363 $digit_after = '0'; $digit_after = substr($xs,$pl,1) if $pad > 0;
2365 # in case of 01234 we round down, for 6789 up, and only in case 5 we look
2366 # closer at the remaining digits of the original $x, remember decision
2367 my $round_up = 1; # default round up
2369 ($mode eq 'trunc') || # trunc by round down
2370 ($digit_after =~ /[01234]/) || # round down anyway,
2372 ($digit_after eq '5') && # not 5000...0000
2373 ($x->_scan_for_nonzero($pad,$xs,$len) == 0) &&
2375 ($mode eq 'even') && ($digit_round =~ /[24680]/) ||
2376 ($mode eq 'odd') && ($digit_round =~ /[13579]/) ||
2377 ($mode eq '+inf') && ($x->{sign} eq '-') ||
2378 ($mode eq '-inf') && ($x->{sign} eq '+') ||
2379 ($mode eq 'zero') # round down if zero, sign adjusted below
2381 my $put_back = 0; # not yet modified
2383 if (($pad > 0) && ($pad <= $len))
2385 substr($xs,-$pad,$pad) = '0' x $pad; # replace with '00...'
2386 $put_back = 1; # need to put back
2390 $x->bzero(); # round to '0'
2393 if ($round_up) # what gave test above?
2395 $put_back = 1; # need to put back
2396 $pad = $len, $xs = '0' x $pad if $scale < 0; # tlr: whack 0.51=>1.0
2398 # we modify directly the string variant instead of creating a number and
2399 # adding it, since that is faster (we already have the string)
2400 my $c = 0; $pad ++; # for $pad == $len case
2401 while ($pad <= $len)
2403 $c = substr($xs,-$pad,1) + 1; $c = '0' if $c eq '10';
2404 substr($xs,-$pad,1) = $c; $pad++;
2405 last if $c != 0; # no overflow => early out
2407 $xs = '1'.$xs if $c == 0;
2410 $x->{value} = $CALC->_new($xs) if $put_back == 1; # put back, if needed
2412 $x->{_a} = $scale if $scale >= 0;
2415 $x->{_a} = $len+$scale;
2416 $x->{_a} = 0 if $scale < -$len;
2423 # return integer less or equal then number; no-op since it's already integer
2424 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2431 # return integer greater or equal then number; no-op since it's already int
2432 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2439 # An object might be asked to return itself as bigint on certain overloaded
2440 # operations. This does exactly this, so that sub classes can simple inherit
2441 # it or override with their own integer conversion routine.
2447 # return as hex string, with prefixed 0x
2448 my $x = shift; $x = $class->new($x) if !ref($x);
2450 return $x->bstr() if $x->{sign} !~ /^[+-]$/; # inf, nan etc
2453 $s = $x->{sign} if $x->{sign} eq '-';
2454 $s . $CALC->_as_hex($x->{value});
2459 # return as binary string, with prefixed 0b
2460 my $x = shift; $x = $class->new($x) if !ref($x);
2462 return $x->bstr() if $x->{sign} !~ /^[+-]$/; # inf, nan etc
2464 my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2465 return $s . $CALC->_as_bin($x->{value});
2470 # return as octal string, with prefixed 0
2471 my $x = shift; $x = $class->new($x) if !ref($x);
2473 return $x->bstr() if $x->{sign} !~ /^[+-]$/; # inf, nan etc
2475 my $s = ''; $s = $x->{sign} if $x->{sign} eq '-';
2476 return $s . $CALC->_as_oct($x->{value});
2479 ##############################################################################
2480 # private stuff (internal use only)
2484 # check for strings, if yes, return objects instead
2486 # the first argument is number of args objectify() should look at it will
2487 # return $count+1 elements, the first will be a classname. This is because
2488 # overloaded '""' calls bstr($object,undef,undef) and this would result in
2489 # useless objects being created and thrown away. So we cannot simple loop
2490 # over @_. If the given count is 0, all arguments will be used.
2492 # If the second arg is a ref, use it as class.
2493 # If not, try to use it as classname, unless undef, then use $class
2494 # (aka Math::BigInt). The latter shouldn't happen,though.
2497 # $x->badd(1); => ref x, scalar y
2498 # Class->badd(1,2); => classname x (scalar), scalar x, scalar y
2499 # Class->badd( Class->(1),2); => classname x (scalar), ref x, scalar y
2500 # Math::BigInt::badd(1,2); => scalar x, scalar y
2501 # In the last case we check number of arguments to turn it silently into
2502 # $class,1,2. (We can not take '1' as class ;o)
2503 # badd($class,1) is not supported (it should, eventually, try to add undef)
2504 # currently it tries 'Math::BigInt' + 1, which will not work.
2506 # some shortcut for the common cases
2508 return (ref($_[1]),$_[1]) if (@_ == 2) && ($_[0]||0 == 1) && ref($_[1]);
2510 my $count = abs(shift || 0);
2512 my (@a,$k,$d); # resulting array, temp, and downgrade
2515 # okay, got object as first
2520 # nope, got 1,2 (Class->xxx(1) => Class,1 and not supported)
2522 $a[0] = shift if $_[0] =~ /^[A-Z].*::/; # classname as first?
2526 # disable downgrading, because Math::BigFLoat->foo('1.0','2.0') needs floats
2527 if (defined ${"$a[0]::downgrade"})
2529 $d = ${"$a[0]::downgrade"};
2530 ${"$a[0]::downgrade"} = undef;
2533 my $up = ${"$a[0]::upgrade"};
2534 # print STDERR "# Now in objectify, my class is today $a[0], count = $count\n";
2542 $k = $a[0]->new($k);
2544 elsif (!defined $up && ref($k) ne $a[0])
2546 # foreign object, try to convert to integer
2547 $k->can('as_number') ? $k = $k->as_number() : $k = $a[0]->new($k);
2560 $k = $a[0]->new($k);
2562 elsif (!defined $up && ref($k) ne $a[0])
2564 # foreign object, try to convert to integer
2565 $k->can('as_number') ? $k = $k->as_number() : $k = $a[0]->new($k);
2569 push @a,@_; # return other params, too
2573 require Carp; Carp::croak ("$class objectify needs list context");
2575 ${"$a[0]::downgrade"} = $d;
2579 sub _register_callback
2581 my ($class,$callback) = @_;
2583 if (ref($callback) ne 'CODE')
2586 Carp::croak ("$callback is not a coderef");
2588 $CALLBACKS{$class} = $callback;
2595 $IMPORT++; # remember we did import()
2596 my @a; my $l = scalar @_;
2597 my $warn_or_die = 0; # 0 - no warn, 1 - warn, 2 - die
2598 for ( my $i = 0; $i < $l ; $i++ )
2600 if ($_[$i] eq ':constant')
2602 # this causes overlord er load to step in
2604 integer => sub { $self->new(shift) },
2605 binary => sub { $self->new(shift) };
2607 elsif ($_[$i] eq 'upgrade')
2609 # this causes upgrading
2610 $upgrade = $_[$i+1]; # or undef to disable
2613 elsif ($_[$i] =~ /^(lib|try|only)\z/)
2615 # this causes a different low lib to take care...
2616 $CALC = $_[$i+1] || '';
2617 # lib => 1 (warn on fallback), try => 0 (no warn), only => 2 (die on fallback)
2618 $warn_or_die = 1 if $_[$i] eq 'lib';
2619 $warn_or_die = 2 if $_[$i] eq 'only';
2627 # any non :constant stuff is handled by our parent, Exporter
2632 $self->SUPER::import(@a); # need it for subclasses
2633 $self->export_to_level(1,$self,@a); # need it for MBF
2636 # try to load core math lib
2637 my @c = split /\s*,\s*/,$CALC;
2640 $_ =~ tr/a-zA-Z0-9://cd; # limit to sane characters
2642 push @c, \'FastCalc', \'Calc' # if all fail, try these
2643 if $warn_or_die < 2; # but not for "only"
2644 $CALC = ''; # signal error
2647 # fallback libraries are "marked" as \'string', extract string if nec.
2648 my $lib = $l; $lib = $$l if ref($l);
2650 next if ($lib || '') eq '';
2651 $lib = 'Math::BigInt::'.$lib if $lib !~ /^Math::BigInt/i;
2655 # Perl < 5.6.0 dies with "out of memory!" when eval("") and ':constant' is
2656 # used in the same script, or eval("") inside import().
2657 my @parts = split /::/, $lib; # Math::BigInt => Math BigInt
2658 my $file = pop @parts; $file .= '.pm'; # BigInt => BigInt.pm
2660 $file = File::Spec->catfile (@parts, $file);
2661 eval { require "$file"; $lib->import( @c ); }
2665 eval "use $lib qw/@c/;";
2670 # loaded it ok, see if the api_version() is high enough
2671 if ($lib->can('api_version') && $lib->api_version() >= 1.0)
2674 # api_version matches, check if it really provides anything we need
2678 add mul div sub dec inc
2679 acmp len digit is_one is_zero is_even is_odd
2681 zeros new copy check
2682 from_hex from_oct from_bin as_hex as_bin as_oct
2683 rsft lsft xor and or
2684 mod sqrt root fac pow modinv modpow log_int gcd
2687 if (!$lib->can("_$method"))
2689 if (($WARN{$lib}||0) < 2)
2692 Carp::carp ("$lib is missing method '_$method'");
2693 $WARN{$lib} = 1; # still warn about the lib
2702 if ($warn_or_die > 0 && ref($l))
2705 my $msg = "Math::BigInt: couldn't load specified math lib(s), fallback to $lib";
2706 Carp::carp ($msg) if $warn_or_die == 1;
2707 Carp::croak ($msg) if $warn_or_die == 2;
2709 last; # found a usable one, break
2713 if (($WARN{$lib}||0) < 2)
2715 my $ver = eval "\$$lib\::VERSION" || 'unknown';
2717 Carp::carp ("Cannot load outdated $lib v$ver, please upgrade");
2718 $WARN{$lib} = 2; # never warn again
2726 if ($warn_or_die == 2)
2728 Carp::croak ("Couldn't load specified math lib(s) and fallback disallowed");
2732 Carp::croak ("Couldn't load any math lib(s), not even fallback to Calc.pm");
2737 foreach my $class (keys %CALLBACKS)
2739 &{$CALLBACKS{$class}}($CALC);
2742 # Fill $CAN with the results of $CALC->can(...) for emulating lower math lib
2746 for my $method (qw/ signed_and signed_or signed_xor /)
2748 $CAN{$method} = $CALC->can("_$method") ? 1 : 0;
2756 # create a bigint from a hexadecimal string
2757 my ($self, $hs) = @_;
2759 my $rc = __from_hex($hs);
2761 return $self->bnan() unless defined $rc;
2768 # create a bigint from a hexadecimal string
2769 my ($self, $bs) = @_;
2771 my $rc = __from_bin($bs);
2773 return $self->bnan() unless defined $rc;
2780 # create a bigint from a hexadecimal string
2781 my ($self, $os) = @_;
2783 my $x = $self->bzero();
2786 $os =~ s/([0-7])_([0-7])/$1$2/g;
2787 $os =~ s/([0-7])_([0-7])/$1$2/g;
2789 return $x->bnan() if $os !~ /^[\-\+]?0[0-7]+\z/;
2791 my $sign = '+'; $sign = '-' if $os =~ /^-/;
2793 $os =~ s/^[+-]//; # strip sign
2794 $x->{value} = $CALC->_from_oct($os);
2795 $x->{sign} = $sign unless $CALC->_is_zero($x->{value}); # no '-0'
2802 # convert a (ref to) big hex string to BigInt, return undef for error
2805 my $x = Math::BigInt->bzero();
2808 $hs =~ s/([0-9a-fA-F])_([0-9a-fA-F])/$1$2/g;
2809 $hs =~ s/([0-9a-fA-F])_([0-9a-fA-F])/$1$2/g;
2811 return $x->bnan() if $hs !~ /^[\-\+]?0x[0-9A-Fa-f]+$/;
2813 my $sign = '+'; $sign = '-' if $hs =~ /^-/;
2815 $hs =~ s/^[+-]//; # strip sign
2816 $x->{value} = $CALC->_from_hex($hs);
2817 $x->{sign} = $sign unless $CALC->_is_zero($x->{value}); # no '-0'
2824 # convert a (ref to) big binary string to BigInt, return undef for error
2827 my $x = Math::BigInt->bzero();
2830 $bs =~ s/([01])_([01])/$1$2/g;
2831 $bs =~ s/([01])_([01])/$1$2/g;
2832 return $x->bnan() if $bs !~ /^[+-]?0b[01]+$/;
2834 my $sign = '+'; $sign = '-' if $bs =~ /^\-/;
2835 $bs =~ s/^[+-]//; # strip sign
2837 $x->{value} = $CALC->_from_bin($bs);
2838 $x->{sign} = $sign unless $CALC->_is_zero($x->{value}); # no '-0'
2844 # input: num_str; output: undef for invalid or
2845 # (\$mantissa_sign,\$mantissa_value,\$mantissa_fraction,\$exp_sign,\$exp_value)
2846 # Internal, take apart a string and return the pieces.
2847 # Strip leading/trailing whitespace, leading zeros, underscore and reject
2851 # strip white space at front, also extranous leading zeros
2852 $x =~ s/^\s*([-]?)0*([0-9])/$1$2/g; # will not strip ' .2'
2853 $x =~ s/^\s+//; # but this will
2854 $x =~ s/\s+$//g; # strip white space at end
2856 # shortcut, if nothing to split, return early
2857 if ($x =~ /^[+-]?[0-9]+\z/)
2859 $x =~ s/^([+-])0*([0-9])/$2/; my $sign = $1 || '+';
2860 return (\$sign, \$x, \'', \'', \0);
2863 # invalid starting char?
2864 return if $x !~ /^[+-]?(\.?[0-9]|0b[0-1]|0x[0-9a-fA-F])/;
2866 return __from_hex($x) if $x =~ /^[\-\+]?0x/; # hex string
2867 return __from_bin($x) if $x =~ /^[\-\+]?0b/; # binary string
2869 # strip underscores between digits
2870 $x =~ s/([0-9])_([0-9])/$1$2/g;
2871 $x =~ s/([0-9])_([0-9])/$1$2/g; # do twice for 1_2_3
2873 # some possible inputs:
2874 # 2.1234 # 0.12 # 1 # 1E1 # 2.134E1 # 434E-10 # 1.02009E-2
2875 # .2 # 1_2_3.4_5_6 # 1.4E1_2_3 # 1e3 # +.2 # 0e999
2877 my ($m,$e,$last) = split /[Ee]/,$x;
2878 return if defined $last; # last defined => 1e2E3 or others
2879 $e = '0' if !defined $e || $e eq "";
2881 # sign,value for exponent,mantint,mantfrac
2882 my ($es,$ev,$mis,$miv,$mfv);
2884 if ($e =~ /^([+-]?)0*([0-9]+)$/) # strip leading zeros
2888 return if $m eq '.' || $m eq '';
2889 my ($mi,$mf,$lastf) = split /\./,$m;
2890 return if defined $lastf; # lastf defined => 1.2.3 or others
2891 $mi = '0' if !defined $mi;
2892 $mi .= '0' if $mi =~ /^[\-\+]?$/;
2893 $mf = '0' if !defined $mf || $mf eq '';
2894 if ($mi =~ /^([+-]?)0*([0-9]+)$/) # strip leading zeros
2896 $mis = $1||'+'; $miv = $2;
2897 return unless ($mf =~ /^([0-9]*?)0*$/); # strip trailing zeros
2899 # handle the 0e999 case here
2900 $ev = 0 if $miv eq '0' && $mfv eq '';
2901 return (\$mis,\$miv,\$mfv,\$es,\$ev);
2904 return; # NaN, not a number
2907 ##############################################################################
2908 # internal calculation routines (others are in Math::BigInt::Calc etc)
2912 # (BINT or num_str, BINT or num_str) return BINT
2913 # does modify first argument
2917 return $x->bnan() if ($x->{sign} eq $nan) || ($ty->{sign} eq $nan);
2918 my $method = ref($x) . '::bgcd';
2920 $x * $ty / &$method($x,$ty);
2923 ###############################################################################
2924 # trigonometric functions
2928 # Calculate PI to N digits. Unless upgrading is in effect, returns the
2929 # result truncated to an integer, that is, always returns '3'.
2933 # called like Math::BigInt::bpi(10);
2934 $n = $self; $self = $class;
2936 $self = ref($self) if ref($self);
2938 return $upgrade->new($n) if defined $upgrade;
2946 # Calculate cosinus(x) to N digits. Unless upgrading is in effect, returns the
2947 # result truncated to an integer.
2948 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2950 return $x if $x->modify('bcos');
2952 return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
2954 return $upgrade->new($x)->bcos(@r) if defined $upgrade;
2956 require Math::BigFloat;
2957 # calculate the result and truncate it to integer
2958 my $t = Math::BigFloat->new($x)->bcos(@r)->as_int();
2960 $x->bone() if $t->is_one();
2961 $x->bzero() if $t->is_zero();
2967 # Calculate sinus(x) to N digits. Unless upgrading is in effect, returns the
2968 # result truncated to an integer.
2969 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
2971 return $x if $x->modify('bsin');
2973 return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
2975 return $upgrade->new($x)->bsin(@r) if defined $upgrade;
2977 require Math::BigFloat;
2978 # calculate the result and truncate it to integer
2979 my $t = Math::BigFloat->new($x)->bsin(@r)->as_int();
2981 $x->bone() if $t->is_one();
2982 $x->bzero() if $t->is_zero();
2988 # calculate arcus tangens of ($y/$x)
2991 my ($self,$y,$x,@r) = (ref($_[0]),@_);
2992 # objectify is costly, so avoid it
2993 if ((!ref($_[0])) || (ref($_[0]) ne ref($_[1])))
2995 ($self,$y,$x,@r) = objectify(2,@_);
2998 return $y if $y->modify('batan2');
3000 return $y->bnan() if ($y->{sign} eq $nan) || ($x->{sign} eq $nan);
3003 # != 0 -inf result is +- pi
3004 if ($x->is_inf() || $y->is_inf())
3006 # upgrade to BigFloat etc.
3007 return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3010 if ($x->{sign} eq '-inf')
3012 # calculate 3 pi/4 => 2.3.. => 2
3013 $y->bone( substr($y->{sign},0,1) );
3014 $y->bmul($self->new(2));
3016 elsif ($x->{sign} eq '+inf')
3018 # calculate pi/4 => 0.7 => 0
3023 # calculate pi/2 => 1.5 => 1
3024 $y->bone( substr($y->{sign},0,1) );
3029 if ($x->{sign} eq '+inf')
3031 # calculate pi/4 => 0.7 => 0
3036 # PI => 3.1415.. => 3
3037 $y->bone( substr($y->{sign},0,1) );
3038 $y->bmul($self->new(3));
3044 return $upgrade->new($y)->batan2($upgrade->new($x),@r) if defined $upgrade;
3046 require Math::BigFloat;
3047 my $r = Math::BigFloat->new($y)->batan2(Math::BigFloat->new($x),@r)->as_int();
3049 $x->{value} = $r->{value};
3050 $x->{sign} = $r->{sign};
3057 # Calculate arcus tangens of x to N digits. Unless upgrading is in effect, returns the
3058 # result truncated to an integer.
3059 my ($self,$x,@r) = ref($_[0]) ? (undef,@_) : objectify(1,@_);
3061 return $x if $x->modify('batan');
3063 return $x->bnan() if $x->{sign} !~ /^[+-]\z/; # -inf +inf or NaN => NaN
3065 return $upgrade->new($x)->batan(@r) if defined $upgrade;
3067 # calculate the result and truncate it to integer
3068 my $t = Math::BigFloat->new($x)->batan(@r);
3070 $x->{value} = $CALC->_new( $x->as_int()->bstr() );
3074 ###############################################################################
3075 # this method returns 0 if the object can be modified, or 1 if not.
3076 # We use a fast constant sub() here, to avoid costly calls. Subclasses
3077 # may override it with special code (f.i. Math::BigInt::Constant does so)
3079 sub modify () { 0; }
3088 Math::BigInt - Arbitrary size integer/float math package
3094 # or make it faster with huge numbers: install (optional)
3095 # Math::BigInt::GMP and always use (it will fall back to
3096 # pure Perl if the GMP library is not installed):
3097 # (See also the L<MATH LIBRARY> section!)
3099 # will warn if Math::BigInt::GMP cannot be found
3100 use Math::BigInt lib => 'GMP';
3102 # to supress the warning use this:
3103 # use Math::BigInt try => 'GMP';
3105 # dies if GMP cannot be loaded:
3106 # use Math::BigInt only => 'GMP';
3108 my $str = '1234567890';
3109 my @values = (64,74,18);
3110 my $n = 1; my $sign = '-';
3113 my $x = Math::BigInt->new($str); # defaults to 0
3114 my $y = $x->copy(); # make a true copy
3115 my $nan = Math::BigInt->bnan(); # create a NotANumber
3116 my $zero = Math::BigInt->bzero(); # create a +0
3117 my $inf = Math::BigInt->binf(); # create a +inf
3118 my $inf = Math::BigInt->binf('-'); # create a -inf
3119 my $one = Math::BigInt->bone(); # create a +1
3120 my $mone = Math::BigInt->bone('-'); # create a -1
3122 my $pi = Math::BigInt->bpi(); # returns '3'
3123 # see Math::BigFloat::bpi()
3125 $h = Math::BigInt->new('0x123'); # from hexadecimal
3126 $b = Math::BigInt->new('0b101'); # from binary
3127 $o = Math::BigInt->from_oct('0101'); # from octal
3129 # Testing (don't modify their arguments)
3130 # (return true if the condition is met, otherwise false)
3132 $x->is_zero(); # if $x is +0
3133 $x->is_nan(); # if $x is NaN
3134 $x->is_one(); # if $x is +1
3135 $x->is_one('-'); # if $x is -1
3136 $x->is_odd(); # if $x is odd
3137 $x->is_even(); # if $x is even
3138 $x->is_pos(); # if $x > 0
3139 $x->is_neg(); # if $x < 0
3140 $x->is_inf($sign); # if $x is +inf, or -inf (sign is default '+')
3141 $x->is_int(); # if $x is an integer (not a float)
3143 # comparing and digit/sign extraction
3144 $x->bcmp($y); # compare numbers (undef,<0,=0,>0)
3145 $x->bacmp($y); # compare absolutely (undef,<0,=0,>0)
3146 $x->sign(); # return the sign, either +,- or NaN
3147 $x->digit($n); # return the nth digit, counting from right
3148 $x->digit(-$n); # return the nth digit, counting from left
3150 # The following all modify their first argument. If you want to preserve
3151 # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
3152 # necessary when mixing $a = $b assignments with non-overloaded math.
3154 $x->bzero(); # set $x to 0
3155 $x->bnan(); # set $x to NaN
3156 $x->bone(); # set $x to +1
3157 $x->bone('-'); # set $x to -1
3158 $x->binf(); # set $x to inf
3159 $x->binf('-'); # set $x to -inf
3161 $x->bneg(); # negation
3162 $x->babs(); # absolute value
3163 $x->bnorm(); # normalize (no-op in BigInt)
3164 $x->bnot(); # two's complement (bit wise not)
3165 $x->binc(); # increment $x by 1
3166 $x->bdec(); # decrement $x by 1
3168 $x->badd($y); # addition (add $y to $x)
3169 $x->bsub($y); # subtraction (subtract $y from $x)
3170 $x->bmul($y); # multiplication (multiply $x by $y)
3171 $x->bdiv($y); # divide, set $x to quotient
3172 # return (quo,rem) or quo if scalar
3174 $x->bmuladd($y,$z); # $x = $x * $y + $z
3176 $x->bmod($y); # modulus (x % y)
3177 $x->bmodpow($exp,$mod); # modular exponentation (($num**$exp) % $mod))
3178 $x->bmodinv($mod); # the inverse of $x in the given modulus $mod
3180 $x->bpow($y); # power of arguments (x ** y)
3181 $x->blsft($y); # left shift in base 2
3182 $x->brsft($y); # right shift in base 2
3183 # returns (quo,rem) or quo if in scalar context
3184 $x->blsft($y,$n); # left shift by $y places in base $n
3185 $x->brsft($y,$n); # right shift by $y places in base $n
3186 # returns (quo,rem) or quo if in scalar context
3188 $x->band($y); # bitwise and
3189 $x->bior($y); # bitwise inclusive or
3190 $x->bxor($y); # bitwise exclusive or
3191 $x->bnot(); # bitwise not (two's complement)
3193 $x->bsqrt(); # calculate square-root
3194 $x->broot($y); # $y'th root of $x (e.g. $y == 3 => cubic root)
3195 $x->bfac(); # factorial of $x (1*2*3*4*..$x)
3197 $x->bnok($y); # x over y (binomial coefficient n over k)
3199 $x->blog(); # logarithm of $x to base e (Euler's number)
3200 $x->blog($base); # logarithm of $x to base $base (f.i. 2)
3201 $x->bexp(); # calculate e ** $x where e is Euler's number
3203 $x->round($A,$P,$mode); # round to accuracy or precision using mode $mode
3204 $x->bround($n); # accuracy: preserve $n digits
3205 $x->bfround($n); # $n > 0: round $nth digits,
3206 # $n < 0: round to the $nth digit after the
3207 # dot, no-op for BigInts
3209 # The following do not modify their arguments in BigInt (are no-ops),
3210 # but do so in BigFloat:
3212 $x->bfloor(); # return integer less or equal than $x
3213 $x->bceil(); # return integer greater or equal than $x
3215 # The following do not modify their arguments:
3217 # greatest common divisor (no OO style)
3218 my $gcd = Math::BigInt::bgcd(@values);
3219 # lowest common multiple (no OO style)
3220 my $lcm = Math::BigInt::blcm(@values);
3222 $x->length(); # return number of digits in number
3223 ($xl,$f) = $x->length(); # length of number and length of fraction part,
3224 # latter is always 0 digits long for BigInts
3226 $x->exponent(); # return exponent as BigInt
3227 $x->mantissa(); # return (signed) mantissa as BigInt
3228 $x->parts(); # return (mantissa,exponent) as BigInt
3229 $x->copy(); # make a true copy of $x (unlike $y = $x;)
3230 $x->as_int(); # return as BigInt (in BigInt: same as copy())
3231 $x->numify(); # return as scalar (might overflow!)
3233 # conversation to string (do not modify their argument)
3234 $x->bstr(); # normalized string (e.g. '3')
3235 $x->bsstr(); # norm. string in scientific notation (e.g. '3E0')
3236 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
3237 $x->as_bin(); # as signed binary string with prefixed 0b
3238 $x->as_oct(); # as signed octal string with prefixed 0
3241 # precision and accuracy (see section about rounding for more)
3242 $x->precision(); # return P of $x (or global, if P of $x undef)
3243 $x->precision($n); # set P of $x to $n
3244 $x->accuracy(); # return A of $x (or global, if A of $x undef)
3245 $x->accuracy($n); # set A $x to $n
3248 Math::BigInt->precision(); # get/set global P for all BigInt objects
3249 Math::BigInt->accuracy(); # get/set global A for all BigInt objects
3250 Math::BigInt->round_mode(); # get/set global round mode, one of
3251 # 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
3252 Math::BigInt->config(); # return hash containing configuration
3256 All operators (including basic math operations) are overloaded if you
3257 declare your big integers as
3259 $i = new Math::BigInt '123_456_789_123_456_789';
3261 Operations with overloaded operators preserve the arguments which is
3262 exactly what you expect.
3268 Input values to these routines may be any string, that looks like a number
3269 and results in an integer, including hexadecimal and binary numbers.
3271 Scalars holding numbers may also be passed, but note that non-integer numbers
3272 may already have lost precision due to the conversation to float. Quote
3273 your input if you want BigInt to see all the digits:
3275 $x = Math::BigInt->new(12345678890123456789); # bad
3276 $x = Math::BigInt->new('12345678901234567890'); # good
3278 You can include one underscore between any two digits.
3280 This means integer values like 1.01E2 or even 1000E-2 are also accepted.
3281 Non-integer values result in NaN.
3283 Hexadecimal (prefixed with "0x") and binary numbers (prefixed with "0b")
3284 are accepted, too. Please note that octal numbers are not recognized
3285 by new(), so the following will print "123":
3287 perl -MMath::BigInt -le 'print Math::BigInt->new("0123")'
3289 To convert an octal number, use from_oct();
3291 perl -MMath::BigInt -le 'print Math::BigInt->from_oct("0123")'
3293 Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('')
3294 results in 'NaN'. This might change in the future, so use always the following
3295 explicit forms to get a zero or NaN:
3297 $zero = Math::BigInt->bzero();
3298 $nan = Math::BigInt->bnan();
3300 C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers
3301 are always stored in normalized form. If passed a string, creates a BigInt
3302 object from the input.
3306 Output values are BigInt objects (normalized), except for the methods which
3307 return a string (see L<SYNOPSIS>).
3309 Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
3310 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
3311 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
3317 Each of the methods below (except config(), accuracy() and precision())
3318 accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
3319 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
3320 L<ACCURACY and PRECISION> for more information.
3326 print Dumper ( Math::BigInt->config() );
3327 print Math::BigInt->config()->{lib},"\n";
3329 Returns a hash containing the configuration, e.g. the version number, lib
3330 loaded etc. The following hash keys are currently filled in with the
3331 appropriate information.
3335 ============================================================
3336 lib Name of the low-level math library
3338 lib_version Version of low-level math library (see 'lib')
3340 class The class name of config() you just called
3342 upgrade To which class math operations might be upgraded
3344 downgrade To which class math operations might be downgraded
3346 precision Global precision
3348 accuracy Global accuracy
3350 round_mode Global round mode
3352 version version number of the class you used
3354 div_scale Fallback accuracy for div
3356 trap_nan If true, traps creation of NaN via croak()
3358 trap_inf If true, traps creation of +inf/-inf via croak()
3361 The following values can be set by passing C<config()> a reference to a hash:
3364 upgrade downgrade precision accuracy round_mode div_scale
3368 $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );
3372 $x->accuracy(5); # local for $x
3373 CLASS->accuracy(5); # global for all members of CLASS
3374 # Note: This also applies to new()!
3376 $A = $x->accuracy(); # read out accuracy that affects $x
3377 $A = CLASS->accuracy(); # read out global accuracy
3379 Set or get the global or local accuracy, aka how many significant digits the
3380 results have. If you set a global accuracy, then this also applies to new()!
3382 Warning! The accuracy I<sticks>, e.g. once you created a number under the
3383 influence of C<< CLASS->accuracy($A) >>, all results from math operations with
3384 that number will also be rounded.
3386 In most cases, you should probably round the results explicitly using one of
3387 L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy
3388 to the math operation as additional parameter:
3390 my $x = Math::BigInt->new(30000);
3391 my $y = Math::BigInt->new(7);
3392 print scalar $x->copy()->bdiv($y, 2); # print 4300
3393 print scalar $x->copy()->bdiv($y)->bround(2); # print 4300
3395 Please see the section about L<ACCURACY and PRECISION> for further details.
3397 Value must be greater than zero. Pass an undef value to disable it:
3399 $x->accuracy(undef);
3400 Math::BigInt->accuracy(undef);
3402 Returns the current accuracy. For C<< $x->accuracy() >> it will return either
3403 the local accuracy, or if not defined, the global. This means the return value
3404 represents the accuracy that will be in effect for $x:
3406 $y = Math::BigInt->new(1234567); # unrounded
3407 print Math::BigInt->accuracy(4),"\n"; # set 4, print 4
3408 $x = Math::BigInt->new(123456); # $x will be automatically rounded!
3409 print "$x $y\n"; # '123500 1234567'
3410 print $x->accuracy(),"\n"; # will be 4
3411 print $y->accuracy(),"\n"; # also 4, since global is 4
3412 print Math::BigInt->accuracy(5),"\n"; # set to 5, print 5
3413 print $x->accuracy(),"\n"; # still 4
3414 print $y->accuracy(),"\n"; # 5, since global is 5
3416 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
3417 globals separated from Math::BigInt, but it is possible to subclass
3418 Math::BigInt and make the globals of the subclass aliases to the ones from
3423 $x->precision(-2); # local for $x, round at the second digit right of the dot
3424 $x->precision(2); # ditto, round at the second digit left of the dot
3426 CLASS->precision(5); # Global for all members of CLASS
3427 # This also applies to new()!
3428 CLASS->precision(-5); # ditto
3430 $P = CLASS->precision(); # read out global precision
3431 $P = $x->precision(); # read out precision that affects $x
3433 Note: You probably want to use L<accuracy()> instead. With L<accuracy> you
3434 set the number of digits each result should have, with L<precision> you
3435 set the place where to round!
3437 C<precision()> sets or gets the global or local precision, aka at which digit
3438 before or after the dot to round all results. A set global precision also
3439 applies to all newly created numbers!
3441 In Math::BigInt, passing a negative number precision has no effect since no
3442 numbers have digits after the dot. In L<Math::BigFloat>, it will round all
3443 results to P digits after the dot.
3445 Please see the section about L<ACCURACY and PRECISION> for further details.
3447 Pass an undef value to disable it:
3449 $x->precision(undef);
3450 Math::BigInt->precision(undef);
3452 Returns the current precision. For C<< $x->precision() >> it will return either
3453 the local precision of $x, or if not defined, the global. This means the return
3454 value represents the prevision that will be in effect for $x:
3456 $y = Math::BigInt->new(1234567); # unrounded
3457 print Math::BigInt->precision(4),"\n"; # set 4, print 4
3458 $x = Math::BigInt->new(123456); # will be automatically rounded
3459 print $x; # print "120000"!
3461 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
3462 own globals separated from Math::BigInt, but it is possible to subclass
3463 Math::BigInt and make the globals of the subclass aliases to the ones from
3470 Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and
3471 2, but others work, too.
3473 Right shifting usually amounts to dividing $x by $n ** $y and truncating the
3477 $x = Math::BigInt->new(10);
3478 $x->brsft(1); # same as $x >> 1: 5
3479 $x = Math::BigInt->new(1234);
3480 $x->brsft(2,10); # result 12
3482 There is one exception, and that is base 2 with negative $x:
3485 $x = Math::BigInt->new(-5);
3488 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
3493 $x = Math::BigInt->new($str,$A,$P,$R);
3495 Creates a new BigInt object from a scalar or another BigInt object. The
3496 input is accepted as decimal, hex (with leading '0x') or binary (with leading
3499 See L<Input> for more info on accepted input formats.
3503 $x = Math::BigInt->from_oct("0775"); # input is octal
3507 $x = Math::BigInt->from_hex("0xcafe"); # input is hexadecimal
3511 $x = Math::BigInt->from_bin("0x10011"); # input is binary
3515 $x = Math::BigInt->bnan();
3517 Creates a new BigInt object representing NaN (Not A Number).
3518 If used on an object, it will set it to NaN:
3524 $x = Math::BigInt->bzero();
3526 Creates a new BigInt object representing zero.
3527 If used on an object, it will set it to zero:
3533 $x = Math::BigInt->binf($sign);
3535 Creates a new BigInt object representing infinity. The optional argument is
3536 either '-' or '+', indicating whether you want infinity or minus infinity.
3537 If used on an object, it will set it to infinity:
3544 $x = Math::BigInt->binf($sign);
3546 Creates a new BigInt object representing one. The optional argument is
3547 either '-' or '+', indicating whether you want one or minus one.
3548 If used on an object, it will set it to one:
3553 =head2 is_one()/is_zero()/is_nan()/is_inf()
3556 $x->is_zero(); # true if arg is +0
3557 $x->is_nan(); # true if arg is NaN
3558 $x->is_one(); # true if arg is +1
3559 $x->is_one('-'); # true if arg is -1
3560 $x->is_inf(); # true if +inf
3561 $x->is_inf('-'); # true if -inf (sign is default '+')
3563 These methods all test the BigInt for being one specific value and return
3564 true or false depending on the input. These are faster than doing something
3569 =head2 is_pos()/is_neg()/is_positive()/is_negative()
3571 $x->is_pos(); # true if > 0
3572 $x->is_neg(); # true if < 0
3574 The methods return true if the argument is positive or negative, respectively.
3575 C<NaN> is neither positive nor negative, while C<+inf> counts as positive, and
3576 C<-inf> is negative. A C<zero> is neither positive nor negative.
3578 These methods are only testing the sign, and not the value.
3580 C<is_positive()> and C<is_negative()> are aliases to C<is_pos()> and
3581 C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
3582 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
3585 =head2 is_odd()/is_even()/is_int()
3587 $x->is_odd(); # true if odd, false for even
3588 $x->is_even(); # true if even, false for odd
3589 $x->is_int(); # true if $x is an integer
3591 The return true when the argument satisfies the condition. C<NaN>, C<+inf>,
3592 C<-inf> are not integers and are neither odd nor even.
3594 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
3600 Compares $x with $y and takes the sign into account.
3601 Returns -1, 0, 1 or undef.
3607 Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or undef.
3613 Return the sign, of $x, meaning either C<+>, C<->, C<-inf>, C<+inf> or NaN.
3615 If you want $x to have a certain sign, use one of the following methods:
3618 $x->babs()->bneg(); # '-'
3620 $x->binf(); # '+inf'
3621 $x->binf('-'); # '-inf'
3625 $x->digit($n); # return the nth digit, counting from right
3627 If C<$n> is negative, returns the digit counting from left.
3633 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
3634 and '-inf', respectively. Does nothing for NaN or zero.
3640 Set the number to its absolute value, e.g. change the sign from '-' to '+'
3641 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
3646 $x->bnorm(); # normalize (no-op)
3652 Two's complement (bitwise not). This is equivalent to
3660 $x->binc(); # increment x by 1
3664 $x->bdec(); # decrement x by 1
3668 $x->badd($y); # addition (add $y to $x)
3672 $x->bsub($y); # subtraction (subtract $y from $x)
3676 $x->bmul($y); # multiplication (multiply $x by $y)
3682 Multiply $x by $y, and then add $z to the result,
3684 This method was added in v1.87 of Math::BigInt (June 2007).
3688 $x->bdiv($y); # divide, set $x to quotient
3689 # return (quo,rem) or quo if scalar
3693 $x->bmod($y); # modulus (x % y)
3697 num->bmodinv($mod); # modular inverse
3699 Returns the inverse of C<$num> in the given modulus C<$mod>. 'C<NaN>' is
3700 returned unless C<$num> is relatively prime to C<$mod>, i.e. unless
3701 C<bgcd($num, $mod)==1>.
3705 $num->bmodpow($exp,$mod); # modular exponentation
3706 # ($num**$exp % $mod)
3708 Returns the value of C<$num> taken to the power C<$exp> in the modulus
3709 C<$mod> using binary exponentation. C<bmodpow> is far superior to
3714 because it is much faster - it reduces internal variables into
3715 the modulus whenever possible, so it operates on smaller numbers.
3717 C<bmodpow> also supports negative exponents.
3719 bmodpow($num, -1, $mod)
3721 is exactly equivalent to
3727 $x->bpow($y); # power of arguments (x ** y)
3731 $x->blog($base, $accuracy); # logarithm of x to the base $base
3733 If C<$base> is not defined, Euler's number (e) is used:
3735 print $x->blog(undef, 100); # log(x) to 100 digits
3739 $x->bexp($accuracy); # calculate e ** X
3741 Calculates the expression C<e ** $x> where C<e> is Euler's number.
3743 This method was added in v1.82 of Math::BigInt (April 2007).
3749 $x->bnok($y); # x over y (binomial coefficient n over k)
3751 Calculates the binomial coefficient n over k, also called the "choose"
3752 function. The result is equivalent to:
3758 This method was added in v1.84 of Math::BigInt (April 2007).
3762 print Math::BigInt->bpi(100), "\n"; # 3
3764 Returns PI truncated to an integer, with the argument being ignored. This means
3765 under BigInt this always returns C<3>.
3767 If upgrading is in effect, returns PI, rounded to N digits with the
3768 current rounding mode:
3771 use Math::BigInt upgrade => Math::BigFloat;
3772 print Math::BigInt->bpi(3), "\n"; # 3.14
3773 print Math::BigInt->bpi(100), "\n"; # 3.1415....
3775 This method was added in v1.87 of Math::BigInt (June 2007).
3779 my $x = Math::BigInt->new(1);
3780 print $x->bcos(100), "\n";
3782 Calculate the cosinus of $x, modifying $x in place.
3784 In BigInt, unless upgrading is in effect, the result is truncated to an
3787 This method was added in v1.87 of Math::BigInt (June 2007).
3791 my $x = Math::BigInt->new(1);
3792 print $x->bsin(100), "\n";
3794 Calculate the sinus of $x, modifying $x in place.
3796 In BigInt, unless upgrading is in effect, the result is truncated to an
3799 This method was added in v1.87 of Math::BigInt (June 2007).
3803 my $x = Math::BigInt->new(1);
3804 my $y = Math::BigInt->new(1);
3805 print $y->batan2($x), "\n";
3807 Calculate the arcus tangens of C<$y> divided by C<$x>, modifying $y in place.
3809 In BigInt, unless upgrading is in effect, the result is truncated to an
3812 This method was added in v1.87 of Math::BigInt (June 2007).
3816 my $x = Math::BigFloat->new(0.5);
3817 print $x->batan(100), "\n";
3819 Calculate the arcus tangens of $x, modifying $x in place.
3821 In BigInt, unless upgrading is in effect, the result is truncated to an
3824 This method was added in v1.87 of Math::BigInt (June 2007).
3828 $x->blsft($y); # left shift in base 2
3829 $x->blsft($y,$n); # left shift, in base $n (like 10)
3833 $x->brsft($y); # right shift in base 2
3834 $x->brsft($y,$n); # right shift, in base $n (like 10)
3838 $x->band($y); # bitwise and
3842 $x->bior($y); # bitwise inclusive or
3846 $x->bxor($y); # bitwise exclusive or
3850 $x->bnot(); # bitwise not (two's complement)
3854 $x->bsqrt(); # calculate square-root
3860 Calculates the N'th root of C<$x>.
3864 $x->bfac(); # factorial of $x (1*2*3*4*..$x)
3868 $x->round($A,$P,$round_mode);
3870 Round $x to accuracy C<$A> or precision C<$P> using the round mode
3875 $x->bround($N); # accuracy: preserve $N digits
3881 If N is > 0, rounds to the Nth digit from the left. If N < 0, rounds to
3882 the Nth digit after the dot. Since BigInts are integers, the case N < 0
3883 is a no-op for them.
3888 ===================================================
3889 123456.123456 3 123500
3890 123456.123456 2 123450
3891 123456.123456 -2 123456.12
3892 123456.123456 -3 123456.123
3898 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
3899 does change $x in BigFloat.
3905 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
3906 does change $x in BigFloat.
3910 bgcd(@values); # greatest common divisor (no OO style)
3914 blcm(@values); # lowest common multiple (no OO style)
3919 ($xl,$fl) = $x->length();
3921 Returns the number of digits in the decimal representation of the number.
3922 In list context, returns the length of the integer and fraction part. For
3923 BigInt's, the length of the fraction part will always be 0.
3929 Return the exponent of $x as BigInt.
3935 Return the signed mantissa of $x as BigInt.
3939 $x->parts(); # return (mantissa,exponent) as BigInt
3943 $x->copy(); # make a true copy of $x (unlike $y = $x;)
3945 =head2 as_int()/as_number()
3949 Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as
3952 C<as_number()> is an alias to this method. C<as_number> was introduced in
3953 v1.22, while C<as_int()> was only introduced in v1.68.
3959 Returns a normalized string representation of C<$x>.
3963 $x->bsstr(); # normalized string in scientific notation
3967 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
3971 $x->as_bin(); # as signed binary string with prefixed 0b
3975 $x->as_oct(); # as signed octal string with prefixed 0
3981 This returns a normal Perl scalar from $x. It is used automatically
3982 whenever a scalar is needed, for instance in array index operations.
3984 This loses precision, to avoid this use L<as_int()> instead.
3988 $x->modify('bpowd');
3990 This method returns 0 if the object can be modified with the given
3991 peration, or 1 if not.
3993 This is used for instance by L<Math::BigInt::Constant>.
3995 =head2 upgrade()/downgrade()
3997 Set/get the class for downgrade/upgrade operations. Thuis is used
3998 for instance by L<bignum>. The defaults are '', thus the following
3999 operation will create a BigInt, not a BigFloat:
4001 my $i = Math::BigInt->new(123);
4002 my $f = Math::BigFloat->new('123.1');
4004 print $i + $f,"\n"; # print 246
4008 Set/get the number of digits for the default precision in divide
4013 Set/get the current round mode.
4015 =head1 ACCURACY and PRECISION
4017 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
4018 accuracy and precision based rounding, both automatically after every
4019 operation, as well as manually.
4021 This section describes the accuracy/precision handling in Math::Big* as it
4022 used to be and as it is now, complete with an explanation of all terms and
4025 Not yet implemented things (but with correct description) are marked with '!',
4026 things that need to be answered are marked with '?'.
4028 In the next paragraph follows a short description of terms used here (because
4029 these may differ from terms used by others people or documentation).
4031 During the rest of this document, the shortcuts A (for accuracy), P (for
4032 precision), F (fallback) and R (rounding mode) will be used.
4036 A fixed number of digits before (positive) or after (negative)
4037 the decimal point. For example, 123.45 has a precision of -2. 0 means an
4038 integer like 123 (or 120). A precision of 2 means two digits to the left
4039 of the decimal point are zero, so 123 with P = 1 becomes 120. Note that
4040 numbers with zeros before the decimal point may have different precisions,
4041 because 1200 can have p = 0, 1 or 2 (depending on what the inital value
4042 was). It could also have p < 0, when the digits after the decimal point
4045 The string output (of floating point numbers) will be padded with zeros:
4047 Initial value P A Result String
4048 ------------------------------------------------------------
4049 1234.01 -3 1000 1000
4052 1234.001 1 1234 1234.0
4054 1234.01 2 1234.01 1234.01
4055 1234.01 5 1234.01 1234.01000
4057 For BigInts, no padding occurs.
4061 Number of significant digits. Leading zeros are not counted. A
4062 number may have an accuracy greater than the non-zero digits
4063 when there are zeros in it or trailing zeros. For example, 123.456 has
4064 A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.
4066 The string output (of floating point numbers) will be padded with zeros:
4068 Initial value P A Result String
4069 ------------------------------------------------------------
4071 1234.01 6 1234.01 1234.01
4072 1234.1 8 1234.1 1234.1000
4074 For BigInts, no padding occurs.
4078 When both A and P are undefined, this is used as a fallback accuracy when
4081 =head2 Rounding mode R
4083 When rounding a number, different 'styles' or 'kinds'
4084 of rounding are possible. (Note that random rounding, as in
4085 Math::Round, is not implemented.)
4091 truncation invariably removes all digits following the
4092 rounding place, replacing them with zeros. Thus, 987.65 rounded
4093 to tens (P=1) becomes 980, and rounded to the fourth sigdig
4094 becomes 987.6 (A=4). 123.456 rounded to the second place after the
4095 decimal point (P=-2) becomes 123.46.
4097 All other implemented styles of rounding attempt to round to the
4098 "nearest digit." If the digit D immediately to the right of the
4099 rounding place (skipping the decimal point) is greater than 5, the
4100 number is incremented at the rounding place (possibly causing a
4101 cascade of incrementation): e.g. when rounding to units, 0.9 rounds
4102 to 1, and -19.9 rounds to -20. If D < 5, the number is similarly
4103 truncated at the rounding place: e.g. when rounding to units, 0.4
4104 rounds to 0, and -19.4 rounds to -19.
4106 However the results of other styles of rounding differ if the
4107 digit immediately to the right of the rounding place (skipping the
4108 decimal point) is 5 and if there are no digits, or no digits other
4109 than 0, after that 5. In such cases:
4113 rounds the digit at the rounding place to 0, 2, 4, 6, or 8
4114 if it is not already. E.g., when rounding to the first sigdig, 0.45
4115 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.
4119 rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if
4120 it is not already. E.g., when rounding to the first sigdig, 0.45
4121 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.
4125 round to plus infinity, i.e. always round up. E.g., when
4126 rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5,
4127 and 0.4501 also becomes 0.5.
4131 round to minus infinity, i.e. always round down. E.g., when
4132 rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6,
4133 but 0.4501 becomes 0.5.
4137 round to zero, i.e. positive numbers down, negative ones up.
4138 E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55
4139 becomes -0.5, but 0.4501 becomes 0.5.
4143 round up if the digit immediately to the right of the rounding place
4144 is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
4149 The handling of A & P in MBI/MBF (the old core code shipped with Perl
4150 versions <= 5.7.2) is like this:
4156 * ffround($p) is able to round to $p number of digits after the decimal
4158 * otherwise P is unused
4160 =item Accuracy (significant digits)
4162 * fround($a) rounds to $a significant digits
4163 * only fdiv() and fsqrt() take A as (optional) paramater
4164 + other operations simply create the same number (fneg etc), or more (fmul)
4166 + rounding/truncating is only done when explicitly calling one of fround
4167 or ffround, and never for BigInt (not implemented)
4168 * fsqrt() simply hands its accuracy argument over to fdiv.
4169 * the documentation and the comment in the code indicate two different ways
4170 on how fdiv() determines the maximum number of digits it should calculate,
4171 and the actual code does yet another thing
4173 max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
4175 result has at most max(scale, length(dividend), length(divisor)) digits
4177 scale = max(scale, length(dividend)-1,length(divisor)-1);
4178 scale += length(divisor) - length(dividend);
4179 So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
4180 Actually, the 'difference' added to the scale is calculated from the
4181 number of "significant digits" in dividend and divisor, which is derived
4182 by looking at the length of the mantissa. Which is wrong, since it includes
4183 the + sign (oops) and actually gets 2 for '+100' and 4 for '+101'. Oops
4184 again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
4185 assumption that 124 has 3 significant digits, while 120/7 will get you
4186 '17', not '17.1' since 120 is thought to have 2 significant digits.
4187 The rounding after the division then uses the remainder and $y to determine
4188 wether it must round up or down.
4189 ? I have no idea which is the right way. That's why I used a slightly more
4190 ? simple scheme and tweaked the few failing testcases to match it.
4194 This is how it works now:
4198 =item Setting/Accessing
4200 * You can set the A global via C<< Math::BigInt->accuracy() >> or
4201 C<< Math::BigFloat->accuracy() >> or whatever class you are using.
4202 * You can also set P globally by using C<< Math::SomeClass->precision() >>
4204 * Globals are classwide, and not inherited by subclasses.
4205 * to undefine A, use C<< Math::SomeCLass->accuracy(undef); >>
4206 * to undefine P, use C<< Math::SomeClass->precision(undef); >>
4207 * Setting C<< Math::SomeClass->accuracy() >> clears automatically
4208 C<< Math::SomeClass->precision() >>, and vice versa.
4209 * To be valid, A must be > 0, P can have any value.
4210 * If P is negative, this means round to the P'th place to the right of the
4211 decimal point; positive values mean to the left of the decimal point.
4212 P of 0 means round to integer.
4213 * to find out the current global A, use C<< Math::SomeClass->accuracy() >>
4214 * to find out the current global P, use C<< Math::SomeClass->precision() >>
4215 * use C<< $x->accuracy() >> respective C<< $x->precision() >> for the local
4216 setting of C<< $x >>.
4217 * Please note that C<< $x->accuracy() >> respective C<< $x->precision() >>
4218 return eventually defined global A or P, when C<< $x >>'s A or P is not
4221 =item Creating numbers
4223 * When you create a number, you can give the desired A or P via:
4224 $x = Math::BigInt->new($number,$A,$P);
4225 * Only one of A or P can be defined, otherwise the result is NaN
4226 * If no A or P is give ($x = Math::BigInt->new($number) form), then the
4227 globals (if set) will be used. Thus changing the global defaults later on
4228 will not change the A or P of previously created numbers (i.e., A and P of
4229 $x will be what was in effect when $x was created)
4230 * If given undef for A and P, B<no> rounding will occur, and the globals will
4231 B<not> be used. This is used by subclasses to create numbers without
4232 suffering rounding in the parent. Thus a subclass is able to have its own
4233 globals enforced upon creation of a number by using
4234 C<< $x = Math::BigInt->new($number,undef,undef) >>:
4236 use Math::BigInt::SomeSubclass;
4239 Math::BigInt->accuracy(2);
4240 Math::BigInt::SomeSubClass->accuracy(3);
4241 $x = Math::BigInt::SomeSubClass->new(1234);
4243 $x is now 1230, and not 1200. A subclass might choose to implement
4244 this otherwise, e.g. falling back to the parent's A and P.
4248 * If A or P are enabled/defined, they are used to round the result of each
4249 operation according to the rules below
4250 * Negative P is ignored in Math::BigInt, since BigInts never have digits
4251 after the decimal point
4252 * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
4253 Math::BigInt as globals does not tamper with the parts of a BigFloat.
4254 A flag is used to mark all Math::BigFloat numbers as 'never round'.
4258 * It only makes sense that a number has only one of A or P at a time.
4259 If you set either A or P on one object, or globally, the other one will
4260 be automatically cleared.
4261 * If two objects are involved in an operation, and one of them has A in
4262 effect, and the other P, this results in an error (NaN).
4263 * A takes precedence over P (Hint: A comes before P).
4264 If neither of them is defined, nothing is used, i.e. the result will have
4265 as many digits as it can (with an exception for fdiv/fsqrt) and will not
4267 * There is another setting for fdiv() (and thus for fsqrt()). If neither of
4268 A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
4269 If either the dividend's or the divisor's mantissa has more digits than
4270 the value of F, the higher value will be used instead of F.
4271 This is to limit the digits (A) of the result (just consider what would
4272 happen with unlimited A and P in the case of 1/3 :-)
4273 * fdiv will calculate (at least) 4 more digits than required (determined by
4274 A, P or F), and, if F is not used, round the result
4275 (this will still fail in the case of a result like 0.12345000000001 with A
4276 or P of 5, but this can not be helped - or can it?)
4277 * Thus you can have the math done by on Math::Big* class in two modi:
4278 + never round (this is the default):
4279 This is done by setting A and P to undef. No math operation
4280 will round the result, with fdiv() and fsqrt() as exceptions to guard
4281 against overflows. You must explicitly call bround(), bfround() or
4282 round() (the latter with parameters).
4283 Note: Once you have rounded a number, the settings will 'stick' on it
4284 and 'infect' all other numbers engaged in math operations with it, since
4285 local settings have the highest precedence. So, to get SaferRound[tm],
4286 use a copy() before rounding like this:
4288 $x = Math::BigFloat->new(12.34);
4289 $y = Math::BigFloat->new(98.76);
4290 $z = $x * $y; # 1218.6984
4291 print $x->copy()->fround(3); # 12.3 (but A is now 3!)
4292 $z = $x * $y; # still 1218.6984, without
4293 # copy would have been 1210!
4295 + round after each op:
4296 After each single operation (except for testing like is_zero()), the
4297 method round() is called and the result is rounded appropriately. By
4298 setting proper values for A and P, you can have all-the-same-A or
4299 all-the-same-P modes. For example, Math::Currency might set A to undef,
4300 and P to -2, globally.
4302 ?Maybe an extra option that forbids local A & P settings would be in order,
4303 ?so that intermediate rounding does not 'poison' further math?
4305 =item Overriding globals
4307 * you will be able to give A, P and R as an argument to all the calculation
4308 routines; the second parameter is A, the third one is P, and the fourth is
4309 R (shift right by one for binary operations like badd). P is used only if
4310 the first parameter (A) is undefined. These three parameters override the
4311 globals in the order detailed as follows, i.e. the first defined value
4313 (local: per object, global: global default, parameter: argument to sub)
4316 + local A (if defined on both of the operands: smaller one is taken)
4317 + local P (if defined on both of the operands: bigger one is taken)
4321 * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
4322 arguments (A and P) instead of one
4324 =item Local settings
4326 * You can set A or P locally by using C<< $x->accuracy() >> or
4327 C<< $x->precision() >>
4328 and thus force different A and P for different objects/numbers.
4329 * Setting A or P this way immediately rounds $x to the new value.
4330 * C<< $x->accuracy() >> clears C<< $x->precision() >>, and vice versa.
4334 * the rounding routines will use the respective global or local settings.
4335 fround()/bround() is for accuracy rounding, while ffround()/bfround()
4337 * the two rounding functions take as the second parameter one of the
4338 following rounding modes (R):
4339 'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
4340 * you can set/get the global R by using C<< Math::SomeClass->round_mode() >>
4341 or by setting C<< $Math::SomeClass::round_mode >>
4342 * after each operation, C<< $result->round() >> is called, and the result may
4343 eventually be rounded (that is, if A or P were set either locally,
4344 globally or as parameter to the operation)
4345 * to manually round a number, call C<< $x->round($A,$P,$round_mode); >>
4346 this will round the number by using the appropriate rounding function
4347 and then normalize it.
4348 * rounding modifies the local settings of the number:
4350 $x = Math::BigFloat->new(123.456);
4354 Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
4355 will be 4 from now on.