stdlib: Introduce characters limit of formated strings

Inspiration from module lager_format.

Also some improvements of Unicode handling.

io_lib:format/3 and io_lib:fwrite/3 are new functions. The
representation of the options is a list, but we are considering using
a map instead. If we change, it will happen after Erlang/OTP 21.0-rc1
is released.

1 files changed, 35 insertions, 4 deletions

diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml
index bc1d77ac83..4a2b425e8e 100644
--- a/lib/stdlib/doc/src/io_lib.xml
+++ b/lib/stdlib/doc/src/io_lib.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2017</year>
+      <year>1996</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -52,6 +52,9 @@
       </desc>
     </datatype>
     <datatype>
+      <name name="chars_limit"/>
+    </datatype>
+    <datatype>
       <name name="depth"/>
     </datatype>
     <datatype>
@@ -153,6 +156,27 @@
     </func>
 
     <func>
+      <name name="format" arity="3"/>
+      <name name="fwrite" arity="3"/>
+      <fsummary>Write formatted output.</fsummary>
+      <desc>
+        <p>Returns a character list that represents <c><anno>Data</anno></c>
+          formatted in accordance with <c><anno>Format</anno></c> in
+          the same way as
+	  <seealso marker="#fwrite/2"><c>fwrite/2</c></seealso> and
+	  <seealso marker="#format/2"><c>format/2</c></seealso>,
+	  but takes an extra argument, a list of options.</p>
+	  <p>Available options:</p>
+	  <taglist>
+	    <tag><c><anno>CharsLimit</anno></c></tag>
+	    <item>
+	      <p>A soft limit on the number of characters returned.</p>
+	    </item>
+	  </taglist>
+      </desc>
+    </func>
+
+    <func>
       <name name="fread" arity="2"/>
       <fsummary>Read formatted input.</fsummary>
       <desc>
@@ -361,17 +385,24 @@
       <fsummary>Write a term.</fsummary>
       <desc>
         <p>Returns a character list that represents <c><anno>Term</anno></c>.
-          Argument <c><anno>Depth</anno></c> controls the depth of the
+          Option <c><anno>Depth</anno></c> controls the depth of the
           structures written. When the specified depth is reached,
           everything below this level is replaced by "<c>...</c>".
           <c><anno>Depth</anno></c> defaults to -1, which means
-          no limitation.</p>
+          no limitation. Option <c><anno>CharsLimit</anno></c> puts a
+	  soft limit on the number of characters returned. When the
+	  number of characters is reached, remaining structures are
+	  replaced by "<c>...</c>". <c><anno>CharsLimit</anno></c>
+	  defaults to -1, which means no limit on the number of
+	  characters returned.</p>
         <p><em>Example:</em></p>
         <pre>
 1> <input>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).</input>
 "{1,[2],[3],[4,5],6,7,8,9}"
 2> <input>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).</input>
-"{1,[2],[3],[...],...}"</pre>
+"{1,[2],[3],[...],...}"
+3> <input>lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])).</input>
+"{[1,2|...],[4|...],...}"</pre>
       </desc>
     </func>