NAME
    Math::SigFigs - do math with correct handling of significant figures

SYNOPSIS
    If you only need to use CountSigFigs and FormatSigFigs, use the first
    form. If you are going to be doing arithmetic, use the second line.

      use Math::SigFigs;
      use Math::SigFigs qw(:all);

    The following routines do simple counting/formatting:

      $n=CountSigFigs($num);
      $num=FormatSigFigs($num,$n);

    Use the following routines to do arithmetic operations.

      $num=addSF($n1,$n2);
      $num=subSF($n1,$n2);
      $num=multSF($n1,$n2);
      $num=divSF($n1,$n2);

DESCRIPTION
    In many scientific applications, it is useful (and in some cases
    required) to be able to format numbers with a given number of
    significant figures, or to do math in such a way as to maintain the
    correct number of significant figures. The rules for significant figures
    are too complicated to be handled solely using the sprintf function
    (unless you happen to be Randal Schwartz :-).

    These routines allow you to correctly handle significan figures.

    It can count the number of significan figures, format a number to a
    given number of significant figures, and do basic arithmetic.

ROUTINES
    CountSigFigs
          $n=CountSigFigs($N);

        This returns the number of significant figures in a number. It
        returns () if $N is not a number.

          $N      $n
          -----   --
          240     2
          240.    3
          241     3
          0240    2
          0.03    1
          0       0
          0.0     0

    FormatSigFigs
          $str=FormatSigFigs($N,$n)

        This returns a string containing $N formatted to $n significant
        figures. This will work for all cases except something like "2400"
        formatted to 3 significant figures.

          $N     $n   $str
          ------ --   -------
          2400    1   2000
          2400    2   2400
          2400    3   2400
          2400    4   2400.
          2400    5   2400.0

          141     3   141.
          141     2   140

          0.039   1   0.04
          0.039   2   0.039

          9.9     1   10
          9.9     2   9.9
          9.9     3   9.90

    addSF, subSF, multSF, divSF
        These routines add/subtract/multiply/divide two numbers while
        maintaining the proper number of significant figures.

KNOWN PROBLEMS
    Without scientific notation, some numbers are ambiguous
        These routines do not work with scientific notation (exponents). As
        a result, it is impossible to unambiguously format some numbers. For
        example,

          $str=FormatSigFigs("2400",3);

        will by necessity return the string "2400" which does NOT have 3
        significant figures. This is not a bug. It is simply a fundamental
        problem with working with significant figures when not using
        scientific notation.

AUTHOR
    Sullivan Beck (sbeck@cpan.org)

