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.

    These routines allow you to correctly handle significant figures. It can
    handle real number or exponentials correctly.

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

ROUTINES
    All routines return nothing if something other than a valid number is
    passed in for any argument.

    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.030   2
          1.2e2   2

        The number zero is not as well defined as other numbers. I have seen
        different answers for this. I have seen answers that say that '0'
        has 0, 1, or infinite significant figures and for '0.00', I have
        seen the number of significant figures given as 0, 1, 2, and 3.
        Everyone agrees on how to count signficant figures for non-zero
        numbers... but that agreement doesn't hold true for zero. At this
        time, this module will return:

          $N      $n
          -----   --
          0       1
          0.0     1
          0.00    2
          0.0e2   1

        I may try to improve the handling of zero at some point.

    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
          0.0300  2   0.030

          9.9     1   10
          9.9     2   9.9
          9.9     3   9.90

          0       2   0.00

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

        Working with zero is a special case. If 0 has 1 signficiant figure
        (i.e. '0') it is treated as exact. If it has more significant
        figures (i.e. 0.00), that number is used as appropriate.

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.

    The number zero is ambiguous
        There is not a universally accepted way to specify the number of
        significant figures that the number 0 has.

    perl cannot preserve significant figures in numbers
        If you run:

           CountSigFigs(20.00);
             => 1
           CountSigFigs("20.00");
             => 4

        This is simply due to the way that numbers are stored. When using
        this module, use numbers stored as strings in order to avoid
        unexpected results.

BUGS AND QUESTIONS
    If you find a bug in Math::SigFigs, please let me know. As CPAN has
    removed email support, the only supported way to submit a bug is via
    ticket:

    GitHub
        You can submit an issue or question on GitHub. This can be done at
        the following URL:

        <https://github.com/SBECK-github/Math-SigFigs>

        This is the preferred method. Please submit problems requests as
        GitHub issues if at all possible.

    Please do not use other means to report bugs (such as forums for a
    specific OS or Linux distribution) as it is impossible for me to keep up
    with all of them. These are the current methods that are guaranteed to
    notify me.

    When filing a bug report, please include the following information:

    Math::SigFigs version
        Please include the version of Math::SigFigs you are using. You can
        get this by using the script:

           use Math::SigFigs;
           print $Math::SigFigs::VERSION,"\n";

    If you find any problems with the documentation (errors, typos, or items
    that are not clear), please send them to me. I welcome any suggestions
    that will allow me to improve the documentation.

LICENSE
    This script is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR
    Sullivan Beck (https://github.com/SBECK-github/)

