README
1NAME
2 Math::SigFigs - do math with correct handling of significant figures
3
4SYNOPSIS
5 If you only need to use CountSigFigs and FormatSigFigs, use the first
6 form. If you are going to be doing arithmetic, use the second line.
7
8 use Math::SigFigs;
9 use Math::SigFigs qw(:all);
10
11 The following routines do simple counting/formatting:
12
13 $n=CountSigFigs($num);
14 $num=FormatSigFigs($num,$n);
15
16 Use the following routines to do arithmetic operations.
17
18 $num=addSF($n1,$n2);
19 $num=subSF($n1,$n2);
20 $num=multSF($n1,$n2);
21 $num=divSF($n1,$n2);
22
23DESCRIPTION
24 In many scientific applications, it is useful (and in some cases
25 required) to be able to format numbers with a given number of
26 significant figures, or to do math in such a way as to maintain the
27 correct number of significant figures. The rules for significant figures
28 are too complicated to be handled solely using the sprintf function.
29
30 These routines allow you to correctly handle significant figures. It can
31 handle real number or exponentials correctly.
32
33 It can count the number of significant figures, format a number to a
34 given number of significant figures, and do basic arithmetic.
35
36ROUTINES
37 All routines return nothing if something other than a valid number is
38 passed in for any argument.
39
40 CountSigFigs
41 $n=CountSigFigs($N);
42
43 This returns the number of significant figures in a number. It
44 returns "()" if $N is not a number.
45
46 $N $n
47 ----- --
48 240 2
49 240. 3
50 241 3
51 0240 2
52 0.03 1
53 0.030 2
54 1.2e2 2
55
56 The number zero is not as well defined as other numbers. I have seen
57 different answers for this. I have seen answers that say that '0'
58 has 0, 1, or infinite significant figures and for '0.00', I have
59 seen the number of significant figures given as 0, 1, 2, and 3.
60 Everyone agrees on how to count signficant figures for non-zero
61 numbers... but that agreement doesn't hold true for zero. At this
62 time, this module will return:
63
64 $N $n
65 ----- --
66 0 1
67 0.0 1
68 0.00 2
69 0.0e2 1
70
71 I may try to improve the handling of zero at some point.
72
73 FormatSigFigs
74 $str=FormatSigFigs($N,$n)
75
76 This returns a string containing $N formatted to $n significant
77 figures. This will work for all cases except something like "2400"
78 formatted to 3 significant figures.
79
80 $N $n $str
81 ------ -- -------
82 2400 1 2000
83 2400 2 2400
84 2400 3 2400
85 2400 4 2400.
86 2400 5 2400.0
87
88 141 3 141
89 141 2 140
90
91 0.039 1 0.04
92 0.039 2 0.039
93 0.0300 2 0.030
94
95 9.9 1 10
96 9.9 2 9.9
97 9.9 3 9.90
98
99 0 2 0.00
100
101 addSF, subSF, multSF, divSF
102 These routines add/subtract/multiply/divide two numbers while
103 maintaining the proper number of significant figures.
104
105 Working with zero is a special case. If 0 has 1 signficiant figure
106 (i.e. '0') it is treated as exact. If it has more significant
107 figures (i.e. 0.00), that number is used as appropriate.
108
109KNOWN PROBLEMS
110 Without scientific notation, some numbers are ambiguous
111 These routines do not work with scientific notation (exponents). As
112 a result, it is impossible to unambiguously format some numbers. For
113 example,
114
115 $str = FormatSigFigs("2400",3);
116
117 will by necessity return the string "2400" which does NOT have 3
118 significant figures. This is not a bug. It is simply a fundamental
119 problem with working with significant figures when not using
120 scientific notation.
121
122 The number zero is ambiguous
123 There is not a universally accepted way to specify the number of
124 significant figures that the number 0 has.
125
126 perl cannot preserve significant figures in numbers
127 If you run:
128
129 CountSigFigs(20.00);
130 => 1
131 CountSigFigs("20.00");
132 => 4
133
134 This is simply due to the way that numbers are stored. When using
135 this module, use numbers stored as strings in order to avoid
136 unexpected results.
137
138LICENSE
139 This script is free software; you can redistribute it and/or modify it
140 under the same terms as Perl itself.
141
142AUTHOR
143 Sullivan Beck (sbeck@cpan.org)
144
145