NAME

Math::Ryu - perl interface to Ryu (float-to-string conversion).

DEPENDENCIES

   This module uses the Ryu C implementation,  which is included with
   this module's source. It is therefore unnecessary to download that
   Ryu code - but, should you wish to grab it, it's available at:
   https://github.com/ulfjack/ryu/tree/master/ryu

DESCRIPTION

   Convert an NV to a decimal string, such that no information is
   lost, yet keeping the string as short as possible.

   NOTE:
   NVs whose size is greater than 8 bytes are not currently catered for.

SYNOPSIS

   use Math::Ryu qw(:all);

   my $str = d2s(0.1);
   print $str;           # 1E-1

   $str = d2s(1.4 / 10);
   print $str;           # 1.3999999999999999E-1
   print fmtpy($str);    # 0.13999999999999999

   $str = d2s(sqrt 2);
   print $str;           # 1.4142135623730951E0
   print fmtpy($str);    # 1.4142135623730951

   # Also do the reverse of s2d()
   my $d = s2d('1E-1');
   printf "%.17g\n", $d;   # 0.10000000000000001
   print  d2s($d);         # 1E-1
   print  fmtpy(d2s($d));  # 0.1

FUNCTIONS

   $nv = s2d($str);
    Converts the string ($str) to a floating point value ($nv)
    and return $nv.

   $str = d2s($nv);
    $nv holds a floating point numeric value (NV).
    $str is a string in floating point format, that accurately
    and succinctly represents the value held by $nv.
    $str, when correctly assigned back to a perl number, will
    always be equivalent to $nv.
    This in stark contrast to perl's interpolation which does not
    guarantee that the condition ("$nv" == $nv) is true, even for
    non-nan values of $nv. (Eg if $nv is sqrt 2.0 or 1.4/10 .)
    Also, $str will contain as few digits as possible, without
    compromising that accuracy.
    Arguments that are not an NV will silently be coerced to an
    NV, following the rules that perl uses for such a coercion.

   $str = n2s($sv);
    If the argument is a floating point numeric value, then this
    function returns the same as d2s().
    Otherwise, it stringifies the numeric value of the given
    argument, according to whether that numeric value is an
    integer value (that fits into an IV or UV) or a floating
    point value.
    Some examples, assuming IVSIZE is 8:
    d2s(~0) returns 1.8446744073709552E19
    n2s(~0) returns 18446744073709551615
    n2s("18446744073709551615") returns 18446744073709551615
    But:
    n2s("18446744073709551615.0") returns 1.8446744073709552E19,
    because the string argument "18446744073709551615.0" numifies
    to an NV - whereas "18446744073709551615" numifies to a UV.
    References, such as Math::BigInt objects will currently
    throw an error when passed to n2s() - though this could be
    changed in the future if there's an appetite for such.
    If you want to know what happens when the argument is neither
    a reference, nor an IV/UV, nor a string (PV) nor a floating
    point value (NV), then you'll have to test that yourself ;-)

   $str = d2fixed($nv, $digits);
    $str is a $digits-decimal fixed point representation of $nv.
    For example, d2sfixed(1 / 10000, 6) returns '0.000100'.

   $str = d2exp($nv, $digits);
    $str is a $digits-decimal floating point representation of $nv.
    For example, d2exp(1 / 10000, 6) returns '1.000000e-04'.

   $str = d2s_buffered($nv);                       # Not very useful
    Returns the same as d2s($nv).

   ($str, $len) = d2s_buffered_n($nv);             # Not very useful
    $str is the same as returned by d2s($nv).
    $len is length($str).

   $str = d2fixed_buffered($nv, $digits);           # Not very useful
    Returns the same as d2fixed($nv, $digits).

   ($str, $len) = d2fixed_buffered_n($nv, $digits); # Not very useful
    $str is the same as returned by d2fixed($nv, $digits).
    $len is length($str).

   $str = d2exp_buffered($nv, $digits);             # Not very useful
    Returns the same as d2exp($nv, $digits).

   ($str, $len) = d2exp_buffered_n($nv, $digits);   # Not very useful
    $str is the same as returned by d2exp($nv, $digits).
    $len is length($str).

  $str = fmtpy($s);
    The argument $s is a string as returned by d2(s) or n2s().
    We reformat this string to be the same as the string that
    python3 produces and return it as $str.

TODO

    Cover larger precision NV types (ie long double and __float128)

LICENSE

    This perl module is free software; you may redistribute it
    and/or modify it under the same terms as Perl itself.
    However, the ".c" and ".h" files that ship with this distro
    are Copyright 2018 Ulf Adams, and can only be used under the
    the terms of version 2.0 the Apache License, or of version 1.0
    of the Boost Software License.
    A copy of the Apache License (Apache_License.txt) is included
    with this distro.

    The Apache License can also be found at:
    http://www.apache.org/licenses/LICENSE-2.0

    The Boost Software License can be found at:
    https://www.boost.org/LICENSE_1_0.txt

    This perl module is Copyright 2021-24 Sisyphus

AUTHOR

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