File 0337-doc-refer-to-note-about-float-literals-to-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0337-doc-refer-to-note-about-float-literals-to-floats.patch of Package erlang

From 31425a5c83757ff3459b080bac3c6b061b3ff839 Mon Sep 17 00:00:00 2001
From: Kjell Winblad <kjellwinblad@gmail.com>
Date: Wed, 30 Sep 2020 11:47:22 +0200
Subject: [PATCH 37/39] doc: refer to note about float literals to floats

* Add note about that float literals may not be represented precisely
  as float values

* Refer to the above mentioned note from the documentation of
  erlang:trunc/1, erlang:round/1 and erlang:float_to_list/2
---
 erts/doc/src/erlang.xml                    | 22 ++++++++++++++++++++--
 system/doc/reference_manual/data_types.xml | 19 +++++++++++++++++++
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 349701ef72..bef39344c2 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1995,7 +1995,13 @@ true</pre>
 > <input>float_to_list(7.12, [{decimals, 4}, compact]).</input>
 "7.12"
 > <input>float_to_list(7.12, [{scientific, 3}]).</input>
-"7.120e+00"</pre>
+"7.120e+00"
+> <input>float_to_list(0.1+0.2)</input></pre>
+<p>In the last example, <c>float_to_list(0.1+0.2)</c> evaluates to
+<c>"3.00000000000000044409e-01"</c>. The reason for this is that
+<seeguide marker="system/reference_manual:data_types#float_represenation_problem"><c>0.1</c> and
+<c>0.2</c> cannot be represented exactly as float
+values</seeguide>.</p>
       </desc>
     </func>
 
@@ -6347,6 +6353,14 @@ true</pre>
         <pre>
 <input>round(-5.5).</input>
 -6</pre>
+        <pre>
+<input>round(36028797018963969.0).</input>
+36028797018963968</pre>
+      <p>In the last example, <c>round(36028797018963969.0)</c>
+      evaluates to <c>36028797018963968</c>. The reason for this is
+      that <seeguide
+      marker="system/reference_manual:data_types#float_represenation_problem"><c>36028797018963969.0</c>
+      cannot be represented exactly as a float value</seeguide>.</p>
         <p>Allowed in guard tests.</p>
       </desc>
     </func>
@@ -12109,8 +12123,12 @@ improper_end</pre>
 > <input>trunc(5).</input>
 5</pre>
         <pre>
-> <input>trunc(36028797018963970.0).</input>
+> <input>trunc(36028797018963969.0).</input>
 36028797018963968</pre>
+<p>In the last example, <c>trunc(36028797018963969.0)</c> evaluates to
+<c>36028797018963968</c>. The reason for this is that <seeguide
+marker="system/reference_manual:data_types#float_represenation_problem"><c>36028797018963969.0</c>
+cannot be represented exactly as a float value</seeguide>.</p>
         <p>Allowed in guard tests.</p>
       </desc>
     </func>
diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml
index 35e2ce1c7a..b3f1162209 100644
--- a/system/doc/reference_manual/data_types.xml
+++ b/system/doc/reference_manual/data_types.xml
@@ -79,6 +79,25 @@
 11> <input>1_234.333_333</input>
 1234.333333
 </pre>
+<marker id="float_represenation_problem" /><note>
+  <p>Float literals cannot always be
+  represented exactly as floats. This is due to the fact that floats
+  are represented by a fixed number of bits in a base-2 system while
+  float literals are represented with a base-10 system. Here are
+  examples of this phenomenon:</p>
+  <pre>
+    > <input>0.1+0.2.</input>
+    0.30000000000000004
+    > <input>36028797018963969.0.</input>
+    36028797018963970.0
+  </pre>
+  <p>See external resources for a detailed description of why this is
+  the case (for example <url
+  href="https://floating-point-gui.de/">https://floating-point-gui.de/</url>
+  and <url
+  href="https://0.30000000000000004.com/">https://0.30000000000000004.com/</url>)</p>
+</note>
+
   </section>
 
   <section>
-- 
2.26.2

Places

File 0337-doc-refer-to-note-about-float-literals-to-floats.patch of Package erlang

Places