=head1 NAME
Data::IEEE754::Tools - Various tools for understanding and manipulating the underlying IEEE-754 representation of floating point values
=head1 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
=head1 DESCRIPTION
These tools give access to the underlying IEEE 754 floating-point 64bit representation
used by many instances of Perl (see L). 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 L or
"Unit in the Last Place").
=head2 Justification for the existence of B
L, or the equivalent L recipe L>, 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.
L has a similar suite of tools to B, but
uses numerical methods rather than accessing the underlying bits. It L that its interpretation function can take
an order of magnitude longer than a routine that manipulates the underlying bits
to gather the information.
This B 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.
=head2 Compatibility
B works with 64bit floating-point representations.
If you have a Perl setup which uses a larger representation (for example,
C