=pod

=head1 NAME

Math::Ryu - perl interface to the ryu C library.

=head1 DEPENDENCIES

   This module includes the Ryu C library, which is available from github:
   $ git clone https://github.com/ulfjack/ryu.git /home/me/ryu_source

=head1 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.

=head1 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

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

=head1 FUNCTIONS

   $str = d2s($nv);
    $nv holds a floating point numeric value.
    $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.

   $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).

=head1 TODO

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

=head1 LICENSE

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

=head1 AUTHOR

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

=cut
