NAME
Data::IEEE754::Tools - Various tools for understanding and manipulating the underlying IEEE-754 representation of floating point values
SYNOPSIS
use Data::IEEE754::Tools qw/:convertToString :ulp/;
# return -12.875 as strings of decimal or hexadecimal floating point numbers ("convertTo*Character" in IEEE-754 parlance)
convertToDecimalString(-12.875); # -0d1.6093750000000000p+0003
convertToHexString(-12.875); # -0x1.9c00000000000p+0003
# shows the smallest value you can add or subtract to 16.16 (ulp = "Unit in the Last Place")
print ulp( 16.16 ); # 3.5527136788005e-015
# toggles the ulp: returns a float that has the ULP of 16.16 toggled
# (if it was a 1, it will be 0, and vice versa);
# running it twice should give the original value
print $t16 = toggle_ulp( 16.16 ); # 16.159999999999997
print $v16 = toggle_ulp( $t16 ); # 16.160000000000000
DESCRIPTION
These tools give access to the underlying IEEE 754 floating-point 64bit representation used by many instances of Perl (see perlguts). They include functions for converting from the 64bit internal representation to a string that shows those bits (either as hexadecimal or binary) and back, functions for converting that encoded value into a more human-readable format to give insight into the meaning of the encoded values, and functions to manipulate the smallest possible change for a given floating-point value (which is the ULP or "Unit in the Last Place").
Justification for the existence of Data::IEEE754::Tools
Data::IEEE754, or the equivalent "pack" in perlfunc recipe d>, 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.
Data::Float has a similar suite of tools to Data::IEEE754::Tools, but uses numerical methods rather than accessing the underlying bits. It has been shown that its interpretation function can take an order of magnitude longer than a routine that manipulates the underlying bits to gather the information.
This Data::IEEE754::Tools module combines the two sets of functions, giving access to the raw IEEE 754 encoding, or a stringification of the encoding which interprets the encoding as a sign and a coefficient and a power of 2, or access to the ULP and ULP-manipulating features, all using direct bit manipulation when appropriate.
Compatibility
Data::IEEE754::Tools works with 64bit floating-point representations.
If you have a Perl setup which uses a larger representation (for example,
use [Config](https://metacpan.org/pod/Config); print $Config{nvsize}; # 16 => 128bit), values reported by
this module will be reduced in precision to fit the 64bit representation.
If you have a Perl setup which uses a smaller representation (for example,
use [Config](https://metacpan.org/pod/Config); print $Config{nvsize}; # 4 => 32bit), the installation
will likely fail, because the unit tests were not set up for lower precision
inputs. However, forcing the installation might still allow coercion
from the smaller Perl NV into a true IEEE 754 double (64bit) floating-point,
but there is no guarantee it will work.
INSTALLATION
To install this module, use your favorite CPAN client.
For a manual install, type the following:
perl Makefile.PL
make
make test
make install
(On Windows machines, you may need to use "dmake" or "gmake" instead of "make", depending on your setup.)
AUTHOR
Peter C. Jones <petercj AT cpan DOT org>
Please report any bugs or feature requests emailing <bug-Data-IEEE754-Tools AT rt.cpan.org>
or thru the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-IEEE754-Tools,
or thru the repository's interface at https://github.com/pryrt/Data-IEEE754-Tools/issues.
COPYRIGHT
Copyright (C) 2016-2017 Peter C. Jones
LICENSE
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.
See http://dev.perl.org/licenses/ for more information.