diff options
Diffstat (limited to 'dist/Math-BigInt/lib/Math/BigInt.pm')
| -rw-r--r-- | dist/Math-BigInt/lib/Math/BigInt.pm | 243 |
1 files changed, 127 insertions, 116 deletions
diff --git a/dist/Math-BigInt/lib/Math/BigInt.pm b/dist/Math-BigInt/lib/Math/BigInt.pm index 36b10490f4..3da16ded7e 100644 --- a/dist/Math-BigInt/lib/Math/BigInt.pm +++ b/dist/Math-BigInt/lib/Math/BigInt.pm @@ -18,7 +18,7 @@ package Math::BigInt; my $class = "Math::BigInt"; use 5.006002; -$VERSION = '1.995'; +$VERSION = '1.996'; @ISA = qw(Exporter); @EXPORT_OK = qw(objectify bgcd blcm); @@ -3344,9 +3344,10 @@ Math::BigInt - Arbitrary size integer/float math package $x->digit($n); # return the nth digit, counting from right $x->digit(-$n); # return the nth digit, counting from left - # The following all modify their first argument. If you want to preserve - # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is - # necessary when mixing $a = $b assignments with non-overloaded math. + # The following all modify their first argument. If you want to pre- + # serve $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for + # why this is necessary when mixing $a = $b assignments with non-over- + # loaded math. $x->bzero(); # set $x to 0 $x->bnan(); # set $x to NaN @@ -3377,10 +3378,12 @@ Math::BigInt - Arbitrary size integer/float math package $x->bpow($y); # power of arguments (x ** y) $x->blsft($y); # left shift in base 2 $x->brsft($y); # right shift in base 2 - # returns (quo,rem) or quo if in scalar context + # returns (quo,rem) or quo if in sca- + # lar context $x->blsft($y,$n); # left shift by $y places in base $n $x->brsft($y,$n); # right shift by $y places in base $n - # returns (quo,rem) or quo if in scalar context + # returns (quo,rem) or quo if in sca- + # lar context $x->band($y); # bitwise and $x->bior($y); # bitwise inclusive or @@ -3397,7 +3400,8 @@ Math::BigInt - Arbitrary size integer/float math package $x->blog($base); # logarithm of $x to base $base (f.i. 2) $x->bexp(); # calculate e ** $x where e is Euler's number - $x->round($A,$P,$mode); # round to accuracy or precision using mode $mode + $x->round($A,$P,$mode); # round to accuracy or precision using + # mode $mode $x->bround($n); # accuracy: preserve $n digits $x->bfround($n); # $n > 0: round $nth digits, # $n < 0: round to the $nth digit after the @@ -3417,36 +3421,38 @@ Math::BigInt - Arbitrary size integer/float math package my $lcm = Math::BigInt::blcm(@values); $x->length(); # return number of digits in number - ($xl,$f) = $x->length(); # length of number and length of fraction part, - # latter is always 0 digits long for BigInts + ($xl,$f) = $x->length(); # length of number and length of fraction + # part, latter is always 0 digits long + # for BigInts - $x->exponent(); # return exponent as BigInt - $x->mantissa(); # return (signed) mantissa as BigInt - $x->parts(); # return (mantissa,exponent) as BigInt - $x->copy(); # make a true copy of $x (unlike $y = $x;) - $x->as_int(); # return as BigInt (in BigInt: same as copy()) - $x->numify(); # return as scalar (might overflow!) + $x->exponent(); # return exponent as BigInt + $x->mantissa(); # return (signed) mantissa as BigInt + $x->parts(); # return (mantissa,exponent) as BigInt + $x->copy(); # make a true copy of $x (unlike $y = $x;) + $x->as_int(); # return as BigInt (in BigInt: same as copy()) + $x->numify(); # return as scalar (might overflow!) # conversion to string (do not modify their argument) - $x->bstr(); # normalized string (e.g. '3') - $x->bsstr(); # norm. string in scientific notation (e.g. '3E0') - $x->as_hex(); # as signed hexadecimal string with prefixed 0x - $x->as_bin(); # as signed binary string with prefixed 0b - $x->as_oct(); # as signed octal string with prefixed 0 + $x->bstr(); # normalized string (e.g. '3') + $x->bsstr(); # norm. string in scientific notation (e.g. '3E0') + $x->as_hex(); # as signed hexadecimal string with prefixed 0x + $x->as_bin(); # as signed binary string with prefixed 0b + $x->as_oct(); # as signed octal string with prefixed 0 # precision and accuracy (see section about rounding for more) - $x->precision(); # return P of $x (or global, if P of $x undef) - $x->precision($n); # set P of $x to $n - $x->accuracy(); # return A of $x (or global, if A of $x undef) - $x->accuracy($n); # set A $x to $n + $x->precision(); # return P of $x (or global, if P of $x undef) + $x->precision($n); # set P of $x to $n + $x->accuracy(); # return A of $x (or global, if A of $x undef) + $x->accuracy($n); # set A $x to $n # Global methods - Math::BigInt->precision(); # get/set global P for all BigInt objects - Math::BigInt->accuracy(); # get/set global A for all BigInt objects - Math::BigInt->round_mode(); # get/set global round mode, one of - # 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common' - Math::BigInt->config(); # return hash containing configuration + Math::BigInt->precision(); # get/set global P for all BigInt objects + Math::BigInt->accuracy(); # get/set global A for all BigInt objects + Math::BigInt->round_mode(); # get/set global round mode, one of + # 'even', 'odd', '+inf', '-inf', 'zero', + # 'trunc' or 'common' + Math::BigInt->config(); # return hash containing configuration =head1 DESCRIPTION @@ -3527,33 +3533,33 @@ Returns a hash containing the configuration, e.g. the version number, lib loaded etc. The following hash keys are currently filled in with the appropriate information. - key Description - Example + key Description + Example ============================================================ - lib Name of the low-level math library - Math::BigInt::Calc - lib_version Version of low-level math library (see 'lib') - 0.30 - class The class name of config() you just called - Math::BigInt - upgrade To which class math operations might be upgraded - Math::BigFloat - downgrade To which class math operations might be downgraded - undef - precision Global precision - undef - accuracy Global accuracy - undef - round_mode Global round mode - even - version version number of the class you used - 1.61 - div_scale Fallback accuracy for div - 40 - trap_nan If true, traps creation of NaN via croak() - 1 - trap_inf If true, traps creation of +inf/-inf via croak() - 1 + lib Name of the low-level math library + Math::BigInt::Calc + lib_version Version of low-level math library (see 'lib') + 0.30 + class The class name of config() you just called + Math::BigInt + upgrade To which class math operations might be upgraded + Math::BigFloat + downgrade To which class math operations might be downgraded + undef + precision Global precision + undef + accuracy Global accuracy + undef + round_mode Global round mode + even + version version number of the class you used + 1.61 + div_scale Fallback accuracy for div + 40 + trap_nan If true, traps creation of NaN via croak() + 1 + trap_inf If true, traps creation of +inf/-inf via croak() + 1 The following values can be set by passing C<config()> a reference to a hash: @@ -3562,16 +3568,18 @@ The following values can be set by passing C<config()> a reference to a hash: Example: - $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } ); + $new_cfg = Math::BigInt->config( + { trap_inf => 1, precision => 5 } + ); =head2 accuracy() - $x->accuracy(5); # local for $x - CLASS->accuracy(5); # global for all members of CLASS - # Note: This also applies to new()! + $x->accuracy(5); # local for $x + CLASS->accuracy(5); # global for all members of CLASS + # Note: This also applies to new()! - $A = $x->accuracy(); # read out accuracy that affects $x - $A = CLASS->accuracy(); # read out global accuracy + $A = $x->accuracy(); # read out accuracy that affects $x + $A = CLASS->accuracy(); # read out global accuracy Set or get the global or local accuracy, aka how many significant digits the results have. If you set a global accuracy, then this also applies to new()! @@ -3584,31 +3592,32 @@ In most cases, you should probably round the results explicitly using one of L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy to the math operation as additional parameter: - my $x = Math::BigInt->new(30000); - my $y = Math::BigInt->new(7); - print scalar $x->copy()->bdiv($y, 2); # print 4300 - print scalar $x->copy()->bdiv($y)->bround(2); # print 4300 + my $x = Math::BigInt->new(30000); + my $y = Math::BigInt->new(7); + print scalar $x->copy()->bdiv($y, 2); # print 4300 + print scalar $x->copy()->bdiv($y)->bround(2); # print 4300 Please see the section about L<ACCURACY and PRECISION> for further details. Value must be greater than zero. Pass an undef value to disable it: - $x->accuracy(undef); - Math::BigInt->accuracy(undef); + $x->accuracy(undef); + Math::BigInt->accuracy(undef); Returns the current accuracy. For C<< $x->accuracy() >> it will return either the local accuracy, or if not defined, the global. This means the return value represents the accuracy that will be in effect for $x: - $y = Math::BigInt->new(1234567); # unrounded - print Math::BigInt->accuracy(4),"\n"; # set 4, print 4 - $x = Math::BigInt->new(123456); # $x will be automatically rounded! - print "$x $y\n"; # '123500 1234567' - print $x->accuracy(),"\n"; # will be 4 - print $y->accuracy(),"\n"; # also 4, since global is 4 - print Math::BigInt->accuracy(5),"\n"; # set to 5, print 5 - print $x->accuracy(),"\n"; # still 4 - print $y->accuracy(),"\n"; # 5, since global is 5 + $y = Math::BigInt->new(1234567); # unrounded + print Math::BigInt->accuracy(4),"\n"; # set 4, print 4 + $x = Math::BigInt->new(123456); # $x will be automatic- + # ally rounded! + print "$x $y\n"; # '123500 1234567' + print $x->accuracy(),"\n"; # will be 4 + print $y->accuracy(),"\n"; # also 4, since global is 4 + print Math::BigInt->accuracy(5),"\n"; # set to 5, print 5 + print $x->accuracy(),"\n"; # still 4 + print $y->accuracy(),"\n"; # 5, since global is 5 Note: Works also for subclasses like Math::BigFloat. Each class has it's own globals separated from Math::BigInt, but it is possible to subclass @@ -3617,15 +3626,17 @@ Math::BigInt. =head2 precision() - $x->precision(-2); # local for $x, round at the second digit right of the dot - $x->precision(2); # ditto, round at the second digit left of the dot + $x->precision(-2); # local for $x, round at the second + # digit right of the dot + $x->precision(2); # ditto, round at the second digit left + # of the dot - CLASS->precision(5); # Global for all members of CLASS - # This also applies to new()! - CLASS->precision(-5); # ditto + CLASS->precision(5); # Global for all members of CLASS + # This also applies to new()! + CLASS->precision(-5); # ditto - $P = CLASS->precision(); # read out global precision - $P = $x->precision(); # read out precision that affects $x + $P = CLASS->precision(); # read out global precision + $P = $x->precision(); # read out precision that affects $x Note: You probably want to use L<accuracy()> instead. With L<accuracy> you set the number of digits each result should have, with L<precision> you @@ -3643,17 +3654,17 @@ Please see the section about L<ACCURACY and PRECISION> for further details. Pass an undef value to disable it: - $x->precision(undef); - Math::BigInt->precision(undef); + $x->precision(undef); + Math::BigInt->precision(undef); Returns the current precision. For C<< $x->precision() >> it will return either the local precision of $x, or if not defined, the global. This means the return value represents the prevision that will be in effect for $x: - $y = Math::BigInt->new(1234567); # unrounded - print Math::BigInt->precision(4),"\n"; # set 4, print 4 - $x = Math::BigInt->new(123456); # will be automatically rounded - print $x; # print "120000"! + $y = Math::BigInt->new(1234567); # unrounded + print Math::BigInt->precision(4),"\n"; # set 4, print 4 + $x = Math::BigInt->new(123456); # will be automatically rounded + print $x; # print "120000"! Note: Works also for subclasses like L<Math::BigFloat>. Each class has its own globals separated from Math::BigInt, but it is possible to subclass @@ -3762,12 +3773,12 @@ If used on an object, it will set it to one: =head2 is_one()/is_zero()/is_nan()/is_inf() - $x->is_zero(); # true if arg is +0 - $x->is_nan(); # true if arg is NaN - $x->is_one(); # true if arg is +1 - $x->is_one('-'); # true if arg is -1 - $x->is_inf(); # true if +inf - $x->is_inf('-'); # true if -inf (sign is default '+') + $x->is_zero(); # true if arg is +0 + $x->is_nan(); # true if arg is NaN + $x->is_one(); # true if arg is +1 + $x->is_one('-'); # true if arg is -1 + $x->is_inf(); # true if +inf + $x->is_inf('-'); # true if -inf (sign is default '+') These methods all test the BigInt for being one specific value and return true or false depending on the input. These are faster than doing something @@ -3831,7 +3842,7 @@ If you want $x to have a certain sign, use one of the following methods: =head2 digit() - $x->digit($n); # return the nth digit, counting from right + $x->digit($n); # return the nth digit, counting from right If C<$n> is negative, returns the digit counting from left. @@ -3866,23 +3877,23 @@ but faster. =head2 binc() - $x->binc(); # increment x by 1 + $x->binc(); # increment x by 1 =head2 bdec() - $x->bdec(); # decrement x by 1 + $x->bdec(); # decrement x by 1 =head2 badd() - $x->badd($y); # addition (add $y to $x) + $x->badd($y); # addition (add $y to $x) =head2 bsub() - $x->bsub($y); # subtraction (subtract $y from $x) + $x->bsub($y); # subtraction (subtract $y from $x) =head2 bmul() - $x->bmul($y); # multiplication (multiply $x by $y) + $x->bmul($y); # multiplication (multiply $x by $y) =head2 bmuladd() @@ -3894,16 +3905,16 @@ This method was added in v1.87 of Math::BigInt (June 2007). =head2 bdiv() - $x->bdiv($y); # divide, set $x to quotient - # return (quo,rem) or quo if scalar + $x->bdiv($y); # divide, set $x to quotient + # return (quo,rem) or quo if scalar =head2 bmod() - $x->bmod($y); # modulus (x % y) + $x->bmod($y); # modulus (x % y) =head2 bmodinv() - $x->bmodinv($mod); # modular multiplicative inverse + $x->bmodinv($mod); # modular multiplicative inverse Returns the multiplicative inverse of C<$x> modulo C<$mod>. If @@ -3942,19 +3953,19 @@ is exactly equivalent to =head2 bpow() - $x->bpow($y); # power of arguments (x ** y) + $x->bpow($y); # power of arguments (x ** y) =head2 blog() - $x->blog($base, $accuracy); # logarithm of x to the base $base + $x->blog($base, $accuracy); # logarithm of x to the base $base If C<$base> is not defined, Euler's number (e) is used: - print $x->blog(undef, 100); # log(x) to 100 digits + print $x->blog(undef, 100); # log(x) to 100 digits =head2 bexp() - $x->bexp($accuracy); # calculate e ** X + $x->bexp($accuracy); # calculate e ** X Calculates the expression C<e ** $x> where C<e> is Euler's number. @@ -3964,7 +3975,7 @@ See also L<blog()>. =head2 bnok() - $x->bnok($y); # x over y (binomial coefficient n over k) + $x->bnok($y); # x over y (binomial coefficient n over k) Calculates the binomial coefficient n over k, also called the "choose" function. The result is equivalent to: @@ -4154,11 +4165,11 @@ Return the signed mantissa of $x as BigInt. =head2 parts() - $x->parts(); # return (mantissa,exponent) as BigInt + $x->parts(); # return (mantissa,exponent) as BigInt =head2 copy() - $x->copy(); # make a true copy of $x (unlike $y = $x;) + $x->copy(); # make a true copy of $x (unlike $y = $x;) =head2 as_int()/as_number() @@ -4178,19 +4189,19 @@ Returns a normalized string representation of C<$x>. =head2 bsstr() - $x->bsstr(); # normalized string in scientific notation + $x->bsstr(); # normalized string in scientific notation =head2 as_hex() - $x->as_hex(); # as signed hexadecimal string with prefixed 0x + $x->as_hex(); # as signed hexadecimal string with prefixed 0x =head2 as_bin() - $x->as_bin(); # as signed binary string with prefixed 0b + $x->as_bin(); # as signed binary string with prefixed 0b =head2 as_oct() - $x->as_oct(); # as signed octal string with prefixed 0 + $x->as_oct(); # as signed octal string with prefixed 0 =head2 numify() |