From ab27e8699ef2a2bafe574158200993f184de3dc2 Mon Sep 17 00:00:00 2001
From: Serge Aleynikov <saleyn@gmail.com>
Date: Mon, 21 Jan 2013 15:36:43 +0100
Subject: Text representation of a float formatted using given options.

This BIF solves a problem of float_to_list/1 that doesn't allow
specifying the number of digits after the decimal point when
formatting floats.

    float_to_list(Float, Options) -> string()

    Float = float()
    Options = [Option]
    Option = {decimals, Decimals::0..249} |
             {scientific, Decimals::0..249} |
             compact

Returns a string which corresponds to the text representation of
a `Float` formatted using given options.

When decimals option is specified the returned value will contain
at most `Decimals` number of digits past the decimal point.
When `compact` option is provided the trailing zeros at the end
of the list are truncated (this option is only meaningful together
with the `decimals` option). When `scientific` option is provided,
the float will be formatted using scientific notation with
`Decimals` digits of precision. If `Options` is `[]` the function
behaves like `float_to_list/1`. When using `decimals` option and
the number doesn't fit in the static internal buffer of 256 bytes
the function throws `badarg`.
---
 erts/doc/src/erlang.xml | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'erts/doc/src/erlang.xml')

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 1d67be2e52..95862216b8 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -967,6 +967,37 @@ true
 "7.00000000000000000000e+00"</pre>
       </desc>
     </func>
+    <func>
+      <name>float_to_list(Float, Options) -> string()</name>
+      <fsummary>Text representation of a float formatted using given options</fsummary>
+      <type>
+        <v>Float = float()</v>
+        <v>Options = [Option]</v>
+        <v>Option = {decimals, Decimals::0..249} |
+                    {scientific, Decimals::0..249} |
+                    compact</v>
+      </type>
+      <desc>
+        <p>Returns a string which corresponds to the text
+          representation of <c>Float</c> using fixed decimal point formatting.
+          When <c>decimals</c> option is specified
+          the returned value will contain at most <c>Decimals</c> number of
+          digits past the decimal point.  If the number doesn't fit in the
+          internal static buffer of 256 bytes, the function throws <c>badarg</c>.
+          When <c>compact</c> option is provided
+          the trailing zeros at the end of the list are truncated (this option is
+          only meaningful together with the <c>decimals</c> option). When
+          <c>scientific</c> option is provided, the float will be formatted using
+          scientific notation with <c>Decimals</c> digits of precision. If
+          <c>Options</c> is <c>[]</c> the function behaves like <c>float_to_list/1</c>.
+          </p>
+        <pre>
+> <input>float_to_list(7.12, [{decimals, 4}]).</input>
+"7.1200"
+> <input>float_to_list(7.12, [{decimals, 4}, compact]).</input>
+"7.12"</pre>
+      </desc>
+    </func>
     <func>
       <name name="fun_info" arity="1"/>
       <fsummary>Information about a fun</fsummary>
-- 
cgit v1.2.3