From bb5ef9963467421857c2ac8eec720cea6a98abe7 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pj@pehjota.net>
Date: Wed, 04 Jan 2017 23:58:22 -0500
Subject: lib/Math/Decimal/FastPP.pm: Add POD sections PHILOSOPHY and THEORY

---
(limited to 'lib')

diff --git a/lib/Math/Decimal/FastPP.pm b/lib/Math/Decimal/FastPP.pm
index ad1e7f8..030b4e5 100644
--- a/lib/Math/Decimal/FastPP.pm
+++ b/lib/Math/Decimal/FastPP.pm
@@ -8,7 +8,7 @@ Math::Decimal::FastPP - Fast pure-Perl decimal arithmetic
 
 	$a = dadd($a, "1.23");  # $a += 1.23
 	$c = dmul($a, $b);      # $c = $a * $b
-	$a = drhtz($a);         # Round half towards zero
+	$a = drhtz($a);         # Round half toward zero
 
 =head1 DESCRIPTION
 
@@ -21,6 +21,51 @@ This module is currently less complete than Perl's built-in arithmetic and other
 decimal arithmetic modules.  So far it only includes addition, multiplication,
 and rounding functions.
 
+Despite the similar name and purpose, this module is not compatible with
+L<Math::Decimal>.
+
+=head1 PHILOSOPHY
+
+This module is designed both to run fast and to be used fast.  The functions are
+written to be as short and fast as possible, at a small cost in readability.
+For help reading the bodies of these functions, see L<THEORY> below.
+
+The names and parameters of this module's functions are kept minimal to allow
+them to be typed quickly and to take little space in calling code.  After all, a
+function to add two numbers shouldn't take much more typing than C<+>.  The
+names of the rounding functions may look strange, but they are simply
+initialisms (or acronyms, if you're creative enough) of "decimal round toward
+zero" and "decimal round (away) from zero".
+
+=head1 THEORY
+
+The binary operation functions (C<dadd()> and C<dmul()>) operate on two numbers,
+C<a> and C<b>.  And obviously the unary operation functions (C<drhtz()> and
+C<drhfz()>) operate on one number, C<a>.  The binary operation functions produce
+a resulting number, C<c>.
+
+The input numbers C<a> and C<b> are broken into their integer (C<i>) and
+fractional (C<f>) parts, for example C<$ai> and C<$af>.  All three numbers C<a>,
+C<b>, and C<c> are comprised of a significand C<s> and (negated) exponent C<e>
+and can be expressed as C<s * 10**(-1*e)>.
+
+The significand is all of the significant digits (although the digits are
+preserved exactly as given, so leading zeroes are considered "significant") in
+the form of an integer, with no radix point.  It is formed simply by
+concatenating the integer and fractional parts, e.g. C<$as = $ai . $af>.  The
+exponent is simply the number of digits in the fractional part, e.g.
+C<$ae = length($af)>.
+
+Multiplication is done simply be multiplying the integer significands and adding
+the exponents.  The resulting significand and exponent is converted back into a
+string with integer and fractional parts.
+
+Addition is a little more complicated.  The exponents of the two input numbers
+must match; if they don't, zeroes are appended to the significand of the number
+with the smaller exponent to make the exponents match.  The significands are
+then added.  The output number is converted from the resulting significand and
+the common exponent of the input numbers.
+
 =head1 FUNCTIONS
 
 =over 4
@@ -106,7 +151,7 @@ sub dmul
 
 	$a = drhtz($a, $p);
 
-Rounds C<$a> with precision C<$p>.  Halves are rounded towards zero.  For
+Rounds C<$a> with precision C<$p>.  Halves are rounded toward zero.  For
 example:
 
 	drhtz("23.5", 0);   # Returns "23."
--
cgit v0.9.1