NAME

Math SigDig - Perl extension for Math

SYNOPSIS

  #Example 1 (Using default of 3 significant digits):
 
  use Math::SigDig;
  print(sigdig(12.3456789));
  #prints "12.3"
 
  #Example 2 (Argument 2: Custom number of significant digits):
 
  use Math::SigDig;
  print(sigdig(12.3456789,4));
  #prints "12.35"

  #Example 3 (Signs & exponents are allowed):

  use Math::SigDig;
  print(sigdig("-12.345e-6789",2));
  #prints "-12e-6789"
 
  #Example 4 (No zero-padding by default):
 
  use Math::SigDig;
  print(sigdig(12.00456789,4));
  #prints "12"

  #Example 5 (Argument 3 [0 or non-zero]: Padding with zeros):

  use Math::SigDig;
  print(sigdig(12.00456789,4,1));
  #prints "12.00"

  #Example 6 (Fill/no-chop mode where arg2 = 0 & arg3 > 0):

  use Math::SigDig;
  print(sigdig(12.00456789,0,4),",",sigdig(12,0,4));
  #prints "12.00456789,12.00"

  #Example 7 (Getting number of significant digits):

  use Math::SigDig;
  $n = getsigdig(12.3456789);
  #$n = 9

  #Example 8 (Signs & exponents are allowed):

  use Math::SigDig;
  $n = getsigdig("+12.3456789e+123");
  #$n = 9

  #Example 9 (Assumed significance except leading whole-number zeros):

  use Math::SigDig;
  $n = getsigdig("0001000.000");
  #$n = 7

  #Example 10 (Using the significant digits argument (arg 2) [0 or non-zero]:
  #            No trailing zeros, unless decimal present):

  use Math::SigDig;
  $n = getsigdig(1000,1);
  #$n = 1
  $n = getsigdig("1000.000",1);
  #$n = 7

  #Example 11 (Using the pad argument (arg 3) [0 or non-zero]:
  #            No trailing zeros, inc. decimals):

  use Math::SigDig;
  $n = getsigdig("1000.000",0,1); #Arg 2 is ignored when arg3 is non-zero
  #$n = 1

  #Example 12 (Doing math):

  use Math::SigDig;
  $x = 12.3456789;
  $y = 12.34;
  $nx = getsigdig($x);
  $ny = getsigdig($y);
  $z = sigdig($x * $y,                #Multiplication
              ($nx<$ny ? $nx : $ny)); #The lesser number of significant digits
  #$z = 152.3

ABSTRACT

Math::SigDig allows you to edit numbers to a significant number of digits (whether they include a decimal point or not). In scientific endeavors, the number of digits that are "significant" in the result of a calculation using 2 numbers is frequently the number of significant digits in the number with the least number of significant digits (e.g. 2.0 * 232.12 = 464.24, where 464.24 is reduced to 2 significant digits: 460).

DESCRIPTION

Math::SigDig is a module that provides methods to round a number to a specified number of significant digits and count the number of significant digits.

It trims leading zeros. It counts, but trims trailing zeros after a decimal point, unless the pad argument (3) to sigdig is non-zero.

Math::SigDig differs from Math::SigFigs in a number of ways. In this module, a "whole-number" zero in a number without a decimal point does not convey significance, however zeros to the right of a decimal point will make them significant. Exponents are allowed ('e' or 'E'), but left untouched. Prepends a 1 to a number if the first character is 'e' or 'E', indicating an assumed '1'.

NOTES

No operator overloads are provided, thus you must enforce significant digits by making calls to getsigdig and sigdig with every math operation, as in example 12 above.

Math::SigDig is intended for use in printing and is not reliable in using its outputs in mathematical calculations. Returned values are strings, not floating point or integer values.

BUGS

No known bugs. Please report them to <robleach@buffalo.edu> if you find any.

SEE ALSO

Math

AUTHOR

Robert William Leach, <rleach@princeton.edu>

COPYRIGHT AND LICENSE

This software (Math::SigDig) and ancillary information (herein called "SOFTWARE") is free: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

If SOFTWARE is modified to produce derivative works, such modified SOFTWARE should be clearly marked, so as not to confuse it with this version.