v0.008 Thu Jul 07

- Convert from expand_ieee754 with fractions to to_hex/dec_floatingpoint() using BUK's simplified methodology (but 32bit compatible)
- Rename val_toggle_ulp() to toggle_ulp()
- Add nextup(), nextdown(), nextafter()

Signed-off-by: PeterCJ <pryrtcode@pryrt.com>

CHANGES

@@ -1,8 +1,27 @@
 Revision history for Perl module Data::IEEE754::Tools.
 
-v0.007
-    - Start additional features
-    - #199: working on debug
+TODO: v0.010 initial release?
+
+v0.008 Thu Jul 07
+    - Start simplification of expand_ieee754() to to_hex/dec_floatingpoint(),
+      using BrowserUK's suggestion that simpler is better.  They utilize the
+      more standard "-0x1.0123456789abcp+0000" notation
+    - remove expand_ieee754
+    - rename val_toggle_ulp to toggle_ulp
+    - update test suite / names
+    - add nextup(), nextdown(), nextafter(), and tests
+    - bug fix ulp/next*.t: include IND in the list of NAN|INF|IND
+      to ensure that on systems that distinguish -1.#IND from -1.#NAN,
+      it will still use the text-eq instead of numeric-==.
+    - bug fix nextafter.t: for nextafter(*NAN, +NAN), need to expect
+      the value (*NAN), not the direction (+NAN).
+    - bug fix to_xxx_floatingpoint(-1.#IND) and associated floatingpoint.t:
+      comparing against wrong $mant for -1.#IND, and wrongly expecting -1.#QNAN
+
+v0.007 Thu Jun 30
+    - Add ulp() and val_toggle_ulp() functions
+    - Experimented with value_plus/minus_ulp(), but deleted after major bug,
+      and discovered Data::Float, which has working versions of
 
 v0.006 Wed Jun 29
     - Full POD; good estimated test coverage

README

@@ -1,3 +1,36 @@
+NAME
+
+Data::IEEE754::Tools - Various tools for understanding and manipulating the underlying IEEE-754 representation of floating point values
+
+DESCRIPTION
+
+It appears that L<Data::Float> includes most of the functionality, but using IEEE 754
+standard function names... That may be a better choice, unless you've got a need
+for one of these specific implementations.
+
+The L<IEEE754|https://en.wikipedia.org/wiki/IEEE_floating_point> standard describes
+various floating-point encodings.  The double format (`binary64') is a 64-bit base-2
+encoding, and correpsonds to the usual Perl floating value (NV). The format  includes the
+sign (s), the power of 2 (q), and a coefficient (c): C<value = ((-1)**s) * (c) * (2**q)>.
+The C<(-1)**s> term evaluates to the SIGN of the number, where s=0 means the sign
+is +1 and s=1 means the sign is -1.
+The coefficient is internally encoded as an implied 1 plus an encoded FRACTION,
+which is itself encoded as a 52-bit integer divided by an implied 2**52.
+
+L<Data::IEEE754>, or the equivalent L<perlfunc/pack> recipe L<dE<gt>>, do a
+good job of converting a perl floating value (NV) into the big-endian bytes
+that encode that value, but they don't help you interpret the value.
+
+This B<Data::IEEE754::Tools> module takes it to the next step, and provideds
+the tools to expand the encoded floating point value into its component sign,
+fraction, and exponent, so you can see how it is encoded internally.
+
+There are also functions available to let you know what the
+L<ULP|https://en.wikipedia.org/wiki/Unit_in_the_last_place> ("Unit in the Last Place")
+is for a given value, and another that returns the original value, but modified
+by just one ULP (toggle the ULP bit).
+
+
 INSTALLATION
 
 To install this module type the following:
@@ -8,10 +41,12 @@ To install this module type the following:
    make install
 
 
-COPYRIGHT AND LICENCE
+COPYRIGHT
 
 Copyright (C) 2016 Peter C. Jones
 
+LICENCE
+
 This program is free software; you can redistribute it and/or modify it
 under the terms of either: the GNU General Public License as published
 by the Free Software Foundation; or the Artistic License.

t/01-convert.t → t/01-raw754.t

@@ -1,23 +1,24 @@
 ########################################################################
 # Verifies the following functions:
-#   hexstr754_from_double()
-#   binstr754_from_double()
-#   hexstr754_to_double()
-#   binstr754_to_double()
+#   :raw754
+#       hexstr754_from_double()
+#       binstr754_from_double()
+#       hexstr754_to_double()
+#       binstr754_to_double()
 ########################################################################
 # Subversion Info
 #   $Author: pryrtmx $
-#   $Date: 2016-06-28 12:59:14 -0700 (Tue, 28 Jun 2016) $
-#   $Revision: 196 $
-#   $URL: https://subversion.assembla.com/svn/pryrt/trunk/perl/Data-IEEE754-Tools/t/01-convert.t $
-#   $Header: https://subversion.assembla.com/svn/pryrt/trunk/perl/Data-IEEE754-Tools/t/01-convert.t 196 2016-06-28 19:59:14Z pryrtmx $
-#   $Id: 01-convert.t 196 2016-06-28 19:59:14Z pryrtmx $
+#   $Date: 2016-07-06 09:15:17 -0700 (Wed, 06 Jul 2016) $
+#   $Revision: 210 $
+#   $URL: https://subversion.assembla.com/svn/pryrt/trunk/perl/Data-IEEE754-Tools/t/01-raw754.t $
+#   $Header: https://subversion.assembla.com/svn/pryrt/trunk/perl/Data-IEEE754-Tools/t/01-raw754.t 210 2016-07-06 16:15:17Z pryrtmx $
+#   $Id: 01-raw754.t 210 2016-07-06 16:15:17Z pryrtmx $
 ########################################################################
 use 5.008005;
 use warnings;
 use strict;
 use Test::More tests => 4+22*2;
-use Data::IEEE754::Tools qw/%EXPAND_OPTS/;
+use Data::IEEE754::Tools qw/:raw754/;
 
 my ($src, $got, $expect_v, $expect_b, $expect_h);
 
@@ -26,19 +27,19 @@ $expect_h = 'BFC47AE147AE147B';
 $expect_v = -0.16;
 
 $src = $expect_v;
-$got = Data::IEEE754::Tools::hexstr754_from_double($src);
+$got = hexstr754_from_double($src);
 is( $got, $expect_h, "hexstr754_frpm_double($src)" );
 
 $src = $expect_h;
-$got = Data::IEEE754::Tools::hexstr754_to_double($src);
+$got = hexstr754_to_double($src);
 is( $got, $expect_v, "hexstr754_to_double($src)" );
 
 $src = $expect_v;
-$got = Data::IEEE754::Tools::binstr754_from_double($src);
+$got = binstr754_from_double($src);
 is( $got, $expect_b, "binstr754_from_double($src)" );
 
 $src = $expect_b;
-$got = Data::IEEE754::Tools::binstr754_to_double($src);
+$got = binstr754_to_double($src);
 is( $got, $expect_v, "binstr754_to_double($src)" );
 
 # http://perlmonks.org/?node_id=984255
@@ -99,12 +100,12 @@ foreach my $bits ( sort keys %cmpmap ) {
     $expect_v   = bitsToDouble( $bits );    # use BrowserUK's conversion to generated expected values
 
     $src        = $bits;
-    $got        = Data::IEEE754::Tools::binstr754_to_double($src);
+    $got        = binstr754_to_double($src);
     is( $got, $expect_v, "binstr754_to_double($bits)");
 
     $expect_b   = qr/$cmpmap{$bits}/;
     $src        = $expect_v;
-    $got        = Data::IEEE754::Tools::binstr754_from_double($src);
+    $got        = binstr754_from_double($src);
     like( $got, $expect_b, "binstr754_to_double($bits)");
 }