/ 
Data-Float-DoubleDouble-0.03
River stage zero No dependents
/ Data::Float::DoubleDouble

NAME

Data::Float::DoubleDouble - human-friendly representation of the "double-double" long double

AIM

Given a double-double value, we aim to be able to:
 1) Convert that double to its internal packed hex form;
 2) Convert the packed hex form of 1) back to the original value;
 3) Convert that double to a more readable 106-bit packed hex form,
    similar to what Data::Float's float_hex function achieves;
 4) Convert the packed hex form of 3) back to the original value;

 For 1) we use NV2H().
 For 2) we use H2NV().
 For 3) we use float_H().
 For 4) we use H_float().

 NOTE: If data is lost when float_H converts to the 106-bit form
       then H_float() cannot return the exact original value.
       (See example/caveats.p in the source.) 
       TODO: Alter float_H() so that it does not lose data. This
       would mean that it presents up to 2047-bit values (as
       needed - depending upon what the actual given value is).
       Such a change would then mean that H_float() can return
       the original value for all NV's. It would also mean that
       the string returned by float_H() is not necessarily so
       "human-friendly" after all, as it could consist of up to
       519 characters.

FUNCTIONS

#############################################
$hex = NV2H($nv);

 Returns a representation of the NV as a string of 32 hex characters.
 The first 16 characters relate to the value of the most significant
 double:
  Characters 1 to 3 (incl) embody the sign of the mantissa, the value 
  of the exponent, and the value (0 or 1) of the implied leading bit.
  Characters 4 to 16 (incl) embody the value of the 52-bit mantissa.

 The second 16 characters (17 to 32) relate to the value of the least
 siginificant double:
  Characters 17 to 19 (incl) embody the sign of the mantissa, the 
  value of the exponent, and the value (0 or 1) of the implied
  leading bit.
  Characters 20 to 32 (incl) embody the value of the 52-bit mantissa.

 For a more human-readable hex representation, use float_H().
#############################################   

#############################################
$nv = H2NV($hex);

 For $hex written in the format returned by NV2H, H2NV($hex)
 returns the NV.
#############################################

#############################################
$hex = D2H($nv);

 Treats the NV as a double and returns a string of 16 hex characters.
 Characters 1 to 3 (incl) embody the sign of the mantissa and the 
 value of the exponent.
 Characters 4 to 16 (incl) embody the value of the 52-bit mantissa
 of the first double.
#############################################
 
#############################################
$nv = H2D($hex);

 For $hex written in the format returned by D2H, H2D($hex) returns
 the NV.
#############################################    

#############################################
$readable_hex = float_H($nv);
($readable_hex, $mant_bin, $sign, $exp_bin) = float_H($nv);

 In scalar context returns a 106-bit hex representation of the NV
 (long double) $nv in the format
 s0xd.hhhhhhhhhhhhhhhhhhhhhhhhhhhpe where:
  s is the sign (either '-' or '+')
  0x is literally "0x"
  d is the leading (first) bit of the number (either '1' or '0')
  . is literally "." (the decimal point)
  hhhhhhhhhhhhhhhhhhhhhhhhhhh is a string of 27 hex digits
                              representing the remaining 105 bits
                              of the mantissa.
  p is a literal "p" that separates mantissa from exponent
  e is the (signed) exponent

 The keen mind will have realised that 27 hex digits encode 108
 (not 105) bits. However, the last 3 bits are to be ignored and
 will always be zero. Thus the 27th hex character will either be
 "8" (representing a "1") or "0" (representing a "0") for the
 106th bit.

 In list context, returns an additional 3 elements:
  1) the sign of the NV;
  2) a binary string representation of the NV with an *implicit*
     decimal point between the first and second (leftmost) digits;
  3) the exponent (as a base 10 count of the base 2 places).
#############################################    

#############################################
$nv = H_float($hex);

 For $hex written in the format returned by float_H(), returns
 the NV that corresponds to $hex.
#############################################    

#############################################
@signs = get_sign($nv);

 Returns the signs of the two doubles contained in $nv.
#############################################

#############################################
@exps = get_exp($nv);

 Returns the exponents of the two doubles contained in $nv.
#############################################

#############################################
@mantissas = get_mant_H(NV2H($nv));

 Returns an array of the two 52-bit mantissa components of the two
 doubles in their hex form. The value of the implied leading (most
 significant) bit is not provided. 
#############################################

#############################################
$intermediate_zeroes = inter_zero(get_exp($nv));

 Returns the number of zeroes that need to come between the
 mantissas of the 2 doubles when $nv is translated to the
 representation that float_H() returns.
#############################################

#############################################
$bool = are_inf(@nv);

 Returns true if and only if all of the (NV) arguments are
 infinities.
 Else returns false.
#############################################

#############################################
$bool = are_nan(@nv);

 Returns true if and only if all of the (NV) arguments are NaNs.
 Else returns false.
#############################################

TODO

Over time, introduce the features of (and functions provided by)
Data::Float

LICENSE

This program is free software; you may redistribute it and/or 
modify it under the same terms as Perl itself.
Copyright 2014 Sisyphus

AUTHOR

Sisyphus <sisyphus at(@) cpan dot (.) org>