=pod

=head1 NAME

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

=head1 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);

=head1 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.

=head1 ROUTINES

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

=over 4

=item B<CountSigFigs>

  $n=CountSigFigs($N);

This returns the number of significant figures in a number.  It returns
C<()> if C<$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.

=item B<FormatSigFigs>

  $str=FormatSigFigs($N,$n)

This returns a string containing C<$N> formatted to C<$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

=item B<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.

=back

=head1 KNOWN PROBLEMS

=over 4

=item B<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.

=item B<The number zero is ambiguous>

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

=item B<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.

=back

=head1 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:

=over 4

=item GitHub

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

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

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

=back

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:

=over 4

=item B<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";

=back

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.

=head1 LICENSE

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

=head1 AUTHOR

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

=cut
