This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clean up POD for Math::BigInt and Math::BigFloat
[perl5.git] / dist / Math-BigInt / lib / Math / BigFloat.pm
index 262e087..495bff1 100644 (file)
@@ -3808,6 +3808,7 @@ sub length
   }
 
 1;
+
 __END__
 
 =head1 NAME
@@ -3943,12 +3944,12 @@ declare your big floating point numbers as
 Operations with overloaded operators preserve the arguments, which is
 exactly what you expect.
 
-=head2 Canonical notation
+=head2 Input
 
 Input to these routines are either BigFloat objects, or strings of the
 following four forms:
 
-=over 2
+=over
 
 =item *
 
@@ -3996,16 +3997,16 @@ Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
 C<is_nan()>) return true or false, while others (C<bcmp()>, C<bacmp()>)
 return either undef, <0, 0 or >0 and are suited for sort.
 
-Actual math is done by using the class defined with C<< with => Class; >> (which
-defaults to BigInts) to represent the mantissa and exponent.
+Actual math is done by using the class defined with C<< with => Class; >>
+(which defaults to BigInts) to represent the mantissa and exponent.
 
 The sign C</^[+-]$/> is stored separately. The string 'NaN' is used to 
 represent the result when input arguments are not numbers, as well as 
 the result of dividing by zero.
 
-=head2 C<mantissa()>, C<exponent()> and C<parts()>
+=head2 mantissa(), exponent() and parts()
 
-C<mantissa()> and C<exponent()> return the said parts of the BigFloat 
+mantissa() and exponent() return the said parts of the BigFloat
 as BigInts such that:
 
        $m = $x->mantissa();
@@ -4080,7 +4081,7 @@ functions like so:
 
 =head2 Rounding
 
-=over 2
+=over
 
 =item ffround ( +$scale )
 
@@ -4136,14 +4137,16 @@ calculates non-integer results when possible. Please see L<Math::BigInt>
 for a full description of each method. Below are just the most important
 differences:
 
-=head2 accuracy
+=over
+
+=item 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()!
@@ -4161,25 +4164,25 @@ to the math operation as additional parameter:
         print scalar $x->copy()->bdiv($y, 2);           # print 4300
         print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300
 
-=head2 precision()
+=item 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
+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
 set the place where to round!
 
-=head2 bexp()
+=item bexp()
 
        $x->bexp($accuracy);            # calculate e ** X
 
@@ -4187,7 +4190,7 @@ Calculates the expression C<e ** $x> where C<e> is Euler's number.
 
 This method was added in v1.82 of Math::BigInt (April 2007).
 
-=head2 bnok()
+=item bnok()
 
        $x->bnok($y);   # x over y (binomial coefficient n over k)
 
@@ -4200,7 +4203,7 @@ function. The result is equivalent to:
 
 This method was added in v1.84 of Math::BigInt (April 2007).
 
-=head2 bpi()
+=item bpi()
 
        print Math::BigFloat->bpi(100), "\n";
 
@@ -4209,7 +4212,7 @@ rounded according to the current rounding mode, which defaults to "even".
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bcos()
+=item bcos()
 
        my $x = Math::BigFloat->new(1);
        print $x->bcos(100), "\n";
@@ -4218,7 +4221,7 @@ Calculate the cosinus of $x, modifying $x in place.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bsin()
+=item bsin()
 
        my $x = Math::BigFloat->new(1);
        print $x->bsin(100), "\n";
@@ -4227,7 +4230,7 @@ Calculate the sinus of $x, modifying $x in place.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan2()
+=item batan2()
 
        my $y = Math::BigFloat->new(2);
        my $x = Math::BigFloat->new(3);
@@ -4238,7 +4241,7 @@ See also L</batan()>.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan()
+=item batan()
 
        my $x = Math::BigFloat->new(1);
        print $x->batan(100), "\n";
@@ -4247,7 +4250,7 @@ Calculate the arcus tanges of $x, modifying $x in place. See also L</batan2()>.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bmuladd()
+=item bmuladd()
 
        $x->bmuladd($y,$z);
 
@@ -4255,6 +4258,8 @@ Multiply $x by $y, and then add $z to the result.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
+=back
+
 =head1 Autocreating constants
 
 After C<use Math::BigFloat ':constant'> all the floating point constants
@@ -4363,7 +4368,7 @@ and B<VERY BAD THINGS> will happen when you use these together:
 
        my $flash_and_bang = $matter + $anti_matter;    # Don't do this!
 
-=over 1
+=over
 
 =item stringify, bstr()
 
@@ -4371,7 +4376,7 @@ Both stringify and bstr() now drop the leading '+'. The old code would return
 '+1.23', the new returns '1.23'. See the documentation in L<Math::BigInt> for
 reasoning and details.
 
-=item bdiv
+=item bdiv()
 
 The following will probably not print what you expect:
 
@@ -4385,7 +4390,7 @@ bdiv() will modify $c, so be careful. You probably want to use
 
 instead.
 
-=item brsft
+=item brsft()
 
 The following will probably not print what you expect:
 
@@ -4414,7 +4419,7 @@ a second reference to the B<same> object and stores it in $y. Thus anything
 that modifies $x will modify $y (except overloaded math operators), and vice
 versa. See L<Math::BigInt> for details and how to avoid that.
 
-=item bpow
+=item bpow()
 
 C<bpow()> now modifies the first argument, unlike the old code which left
 it alone and only returned the result. This is to be consistent with
@@ -4431,39 +4436,39 @@ a certain number of digits:
 
     use Math::BigFloat;
 
-    Math::BigFloat->precision(4);           # does not do what you
-                                            # think it does
-    my $x = Math::BigFloat->new(12345);             # rounds $x to "12000"!
-    print "$x\n";                           # print "12000"
-    my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
-    print "$y\n";                           # print "0"
-    $z = $x / $y;                           # 12000 / 0 => NaN!
+    Math::BigFloat->precision(4);          # does not do what you
+                                           # think it does
+    my $x = Math::BigFloat->new(12345);            # rounds $x to "12000"!
+    print "$x\n";                          # print "12000"
+    my $y = Math::BigFloat->new(3);        # rounds $y to "0"!
+    print "$y\n";                          # print "0"
+    $z = $x / $y;                          # 12000 / 0 => NaN!
     print "$z\n";
-    print $z->precision(),"\n";                     # 4
+    print $z->precision(),"\n";                    # 4
 
-Replacing L</precision()> with L</accuracy> is probably not what you want, either:
+Replacing L</precision()> with L</accuracy()> is probably not what you want, either:
 
     use Math::BigFloat;
 
-    Math::BigFloat->accuracy(4);            # enables global rounding:
-    my $x = Math::BigFloat->new(123456);     # rounded immediately
-                                             #   to "12350"
-    print "$x\n";                           # print "123500"
-    my $y = Math::BigFloat->new(3);         # rounded to "3
-    print "$y\n";                           # print "3"
-    print $z = $x->copy()->bdiv($y),"\n";    # 41170
-    print $z->accuracy(),"\n";              # 4
+    Math::BigFloat->accuracy(4);           # enables global rounding:
+    my $x = Math::BigFloat->new(123456);    # rounded immediately
+                                            #   to "12350"
+    print "$x\n";                          # print "123500"
+    my $y = Math::BigFloat->new(3);        # rounded to "3
+    print "$y\n";                          # print "3"
+    print $z = $x->copy()->bdiv($y),"\n";   # 41170
+    print $z->accuracy(),"\n";             # 4
 
 What you want to use instead is:
 
     use Math::BigFloat;
 
-    my $x = Math::BigFloat->new(123456);     # no rounding
-    print "$x\n";                           # print "123456"
-    my $y = Math::BigFloat->new(3);         # no rounding
-    print "$y\n";                           # print "3"
-    print $z = $x->copy()->bdiv($y,4),"\n";  # 41150
-    print $z->accuracy(),"\n";              # undef
+    my $x = Math::BigFloat->new(123456);    # no rounding
+    print "$x\n";                          # print "123456"
+    my $y = Math::BigFloat->new(3);        # no rounding
+    print "$y\n";                          # print "3"
+    print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
+    print $z->accuracy(),"\n";             # undef
 
 In addition to computing what you expected, the last example also does B<not>
 "taint" the result with an accuracy or precision setting, which would