This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Rewrap some verbatim pod in Math::BigInt
authorFather Chrysostomos <sprout@cpan.org>
Wed, 10 Aug 2011 19:23:51 +0000 (12:23 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Wed, 10 Aug 2011 20:32:40 +0000 (13:32 -0700)
I started to make Math::BigInt’s pod fit within 79 columns, but
soon petered out.  At least this is better than nothing.

dist/Math-BigInt/lib/Math/BigInt.pm
t/porting/known_pod_issues.dat

index 36b1049..3da16de 100644 (file)
@@ -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()
 
index 1f60461..b6f55d3 100644 (file)
@@ -148,7 +148,7 @@ dist/math-bigint/lib/math/bigfloat.pm       Apparent broken link    7
 dist/math-bigint/lib/math/bigfloat.pm  Apparent internal link is missing its forward slash     6
 dist/math-bigint/lib/math/bigint.pm    Apparent broken link    5
 dist/math-bigint/lib/math/bigint.pm    Apparent internal link is missing its forward slash     7
-dist/math-bigint/lib/math/bigint.pm    Verbatim line length including indents exceeds 79 by    122
+dist/math-bigint/lib/math/bigint.pm    Verbatim line length including indents exceeds 79 by    86
 dist/math-bigint/lib/math/bigint.pm    empty section in previous paragraph     1
 dist/math-bigint/lib/math/bigint/calcemu.pm    Apparent broken link    1
 dist/math-bigint/lib/math/bigint/calcemu.pm    empty section in previous paragraph     3