Merge tag 'OTP-19.0' into sverker/19/binary_to_atom-utf8-crash/ERL-474/OTP-14590

1 files changed, 270 insertions, 156 deletions

diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml
index 3dac259477..931e50f6f2 100644
--- a/lib/stdlib/doc/src/io_lib.xml
+++ b/lib/stdlib/doc/src/io_lib.xml
@@ -1,23 +1,24 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2013</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-      The contents of this file are subject to the Erlang Public License,
-      Version 1.1, (the "License"); you may not use this file except in
-      compliance with the License. You should have received a copy of the
-      Erlang Public License along with this software. If not, it can be
-      retrieved online at http://www.erlang.org/.
-    
-      Software distributed under the License is distributed on an "AS IS"
-      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-      the License for the specific language governing rights and limitations
-      under the License.
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+ 
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
     
     </legalnotice>
 
@@ -28,14 +29,16 @@
     <rev></rev>
   </header>
   <module>io_lib</module>
-  <modulesummary>IO Library Functions</modulesummary>
+  <modulesummary>I/O library functions.</modulesummary>
   <description>
     <p>This module contains functions for converting to and from
       strings (lists of characters). They are used for implementing the
-      functions in the <c>io</c> module. There is no guarantee that the
+      functions in the <seealso marker="io"><c>io</c></seealso> module.
+      There is no guarantee that the
       character lists returned from some of the functions are flat,
-      they can be deep lists. <c>lists:flatten/1</c> can be used for
-      flattening deep lists.</p>
+      they can be deep lists. Function
+      <seealso marker="lists#flatten/1"><c>lists:flatten/1</c></seealso>
+      can be used for flattening deep lists.</p>
   </description>
 
   <datatypes>
@@ -44,7 +47,8 @@
     </datatype>
     <datatype>
       <name name="continuation"/>
-      <desc><p>A continuation as returned by <seealso marker="#fread/3"><c>fread/3</c></seealso>.</p>
+      <desc><p>A continuation as returned by
+        <seealso marker="#fread/3"><c>fread/3</c></seealso>.</p>
       </desc>
     </datatype>
     <datatype>
@@ -54,274 +58,384 @@
       <name name="fread_error"/>
     </datatype>
     <datatype>
+      <name name="fread_item"/>
+    </datatype>
+    <datatype>
       <name name="latin1_string"/>
     </datatype>
+    <datatype>
+      <name name="format_spec"/>
+      <desc><p>Where:</p>
+      <list type="bulleted">
+        <item><p><c>control_char</c> is the type of control
+          sequence: <c>$P</c>, <c>$w</c>, and so on.</p>
+        </item>
+        <item><p><c>args</c> is a list of the arguments used by the
+          control sequence, or an empty list if the control sequence
+          does not take any arguments.</p>
+        </item>
+        <item><p><c>width</c> is the field width.</p>
+        </item>
+        <item><p><c>adjust</c> is the adjustment.</p>
+        </item>
+        <item><p><c>precision</c> is the precision of the printed
+          argument.</p>
+        </item>
+        <item><p><c>pad_char</c> is the padding character.</p>
+        </item>
+        <item><p><c>encoding</c> is set to <c>true</c> if translation
+          modifier <c>t</c> is present.</p>
+        </item>
+        <item><p><c>strings</c> is set to <c>false</c> if modifier
+          <c>l</c> is present.</p>
+        </item>
+      </list>
+      </desc>
+    </datatype>
   </datatypes>
+
   <funcs>
     <func>
-      <name name="nl" arity="0"/>
-      <fsummary>Write a newline</fsummary>
+      <name name="build_text" arity="1"/>
+      <fsummary>Build the output text for a preparsed format list.</fsummary>
       <desc>
-        <p>Returns a character list which represents a new line
-          character.</p>
+        <p>For details, see
+          <seealso marker="#scan_format/2"><c>scan_format/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write" arity="1"/>
-      <name name="write" arity="2"/>
-      <fsummary>Write a term</fsummary>
+      <name name="char_list" arity="1"/>
+      <fsummary>Test for a list of characters.</fsummary>
       <desc>
-        <p>Returns a character list which represents <c><anno>Term</anno></c>. The
-          <c><anno>Depth</anno></c> (-1) argument controls the depth of the
-          structures written. When the specified depth is reached,
-          everything below this level is replaced by "...". For
-          example:</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>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
+          characters in the Unicode range, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="print" arity="1"/>
-      <name name="print" arity="4"/>
-      <fsummary>Pretty print a term</fsummary>
+      <name name="deep_char_list" arity="1"/>
+      <fsummary>Test for a deep list of characters.</fsummary>
       <desc>
-        <p>Also returns a list of characters which represents
-          <c><anno>Term</anno></c>, but breaks representations which are longer than
-          one line into many lines and indents each line sensibly. It
-          also tries to detect and output lists of printable characters 
-          as strings. <c><anno>Column</anno></c> is the starting column (1),
-          <c><anno>LineLength</anno></c> the maximum line length (80), and
-          <c><anno>Depth</anno></c> (-1) the maximum print depth.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep,
+          list of characters in the Unicode range, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="fwrite" arity="2"/>
-      <name name="format" arity="2"/>
-      <fsummary>Write formatted output</fsummary>
+      <name name="deep_latin1_char_list" arity="1"/>
+      <fsummary>Test for a deep list of characters.</fsummary>
       <desc>
-        <p>Returns a character list which represents <c><anno>Data</anno></c>
-          formatted in accordance with <c><anno>Format</anno></c>. See
-          <seealso marker="io#fwrite/1">io:fwrite/1,2,3</seealso> for a detailed
-          description of the available formatting options. A fault is
-          generated if there is an error in the format string or
-          argument list.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep,
+          list of characters in the ISO Latin-1 range, otherwise
+          <c>false</c>.</p>
+      </desc>
+    </func>
 
-	  <p>If (and only if) the Unicode translation modifier is used
-	  in the format string (i.e. ~ts or ~tc), the resulting list
-	  may contain characters beyond the ISO-latin-1 character
-	  range (in other words, numbers larger than 255). If so, the
-	  result is not an ordinary Erlang string(), but can well be
-	  used in any context where Unicode data is allowed.</p>
-	  
+    <func>
+      <name name="format" arity="2"/>
+      <name name="fwrite" arity="2"/>
+      <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>.
+          For a detailed description of the available formatting options, see
+          <seealso marker="io#fwrite/1"><c>io:fwrite/1,2,3</c></seealso>.
+          If the format string or argument list contains an error, a fault is
+          generated.</p>
+        <p>If and only if the Unicode translation modifier is used in the
+          format string (that is, <c>~ts</c> or <c>~tc</c>), the resulting list
+          can contain characters beyond the ISO Latin-1 character range
+          (that is, numbers &gt; 255). If so, the
+          result is not an ordinary Erlang <c>string()</c>, but can well be
+          used in any context where Unicode data is allowed.</p>
       </desc>
     </func>
+
     <func>
       <name name="fread" arity="2"/>
-      <fsummary>Read formatted input</fsummary>
+      <fsummary>Read formatted input.</fsummary>
       <desc>
-        <p>Tries to read <c><anno>String</anno></c> in accordance with the control
-          sequences in <c><anno>Format</anno></c>. See
-          <seealso marker="io#fread/3">io:fread/3</seealso> for a detailed
-          description of the available formatting options. It is
-          assumed that <c><anno>String</anno></c> contains whole lines. It returns:</p>
+        <p>Tries to read <c><anno>String</anno></c> in accordance with the
+          control sequences in <c><anno>Format</anno></c>.
+          For a detailed description of the available formatting options, see
+          <seealso marker="io#fread/3"><c>io:fread/3</c></seealso>. It is
+          assumed that <c><anno>String</anno></c> contains whole lines.</p>
+        <p>The function returns:</p>
         <taglist>
-          <tag><c>{ok, <anno>InputList</anno>, <anno>LeftOverChars</anno>}</c></tag>
+          <tag><c>{ok, <anno>InputList</anno>,
+            <anno>LeftOverChars</anno>}</c></tag>
           <item>
-            <p>The string was read. <c><anno>InputList</anno></c> is the list of
-              successfully matched and read items, and
-              <c><anno>LeftOverChars</anno></c> are the input characters not used.</p>
+            <p>The string was read. <c><anno>InputList</anno></c> is the list
+              of successfully matched and read items, and
+              <c><anno>LeftOverChars</anno></c> are the input characters not
+              used.</p>
           </item>
-          <tag><c>{more, <anno>RestFormat</anno>, <anno>Nchars</anno>, <anno>InputStack</anno>}</c></tag>
+          <tag><c>{more, <anno>RestFormat</anno>, <anno>Nchars</anno>,
+            <anno>InputStack</anno>}</c></tag>
           <item>
-            <p>The string was read, but more input is needed in order
-              to complete the original format string. <c><anno>RestFormat</anno></c>
-              is the remaining format string, <c><anno>Nchars</anno></c> the number
+            <p>The string was read, but more input is needed to complete the
+              original format string. <c><anno>RestFormat</anno></c> is the
+              remaining format string, <c><anno>Nchars</anno></c> is the number
               of characters scanned, and <c><anno>InputStack</anno></c> is the
               reversed list of inputs matched up to that point.</p>
           </item>
           <tag><c>{error, <anno>What</anno>}</c></tag>
           <item>
-            <p>The read operation failed and the parameter <c><anno>What</anno></c>
+            <p>The read operation failed and parameter <c><anno>What</anno></c>
               gives a hint about the error.</p>
           </item>
         </taglist>
-        <p>Example:</p>
+        <p><em>Example:</em></p>
         <pre>
 3> <input>io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").</input>
 {ok,[15.6,1.73e-5,24.5],[]}</pre>
       </desc>
     </func>
+
     <func>
       <name name="fread" arity="3"/>
       <fsummary>Re-entrant formatted reader</fsummary>
       <desc>
         <p>This is the re-entrant formatted reader. The continuation of
-          the first call to the functions must be <c>[]</c>. Refer to
-          Armstrong, Virding, Williams, 'Concurrent Programming in
-          Erlang', Chapter 13 for a complete description of how the
-          re-entrant input scheme works.</p>
+          the first call to the functions must be <c>[]</c>. For a complete
+          description of how the re-entrant input scheme works, see
+          Armstrong, Virding, Williams: 'Concurrent Programming in
+          Erlang', Chapter 13.</p>
         <p>The function returns:</p>
         <taglist>
-          <tag><c>{done, <anno>Result</anno>, <anno>LeftOverChars</anno>}</c></tag>
+          <tag><c>{done, <anno>Result</anno>,
+            <anno>LeftOverChars</anno>}</c></tag>
           <item>
-            <p>The input is complete. The result is one of the
-              following:</p>
+            <p>The input is complete. The result is one of the following:</p>
             <taglist>
               <tag><c>{ok, <anno>InputList</anno>}</c></tag>
               <item>
-                <p>The string was read. <c><anno>InputList</anno></c> is the list of
-                  successfully matched and read items, and
-                  <c><anno>LeftOverChars</anno></c> are the remaining characters.</p>
+                <p>The string was read. <c><anno>InputList</anno></c> is the
+                  list of successfully matched and read items, and
+                  <c><anno>LeftOverChars</anno></c> are the remaining
+                  characters.</p>
               </item>
               <tag><c>eof</c></tag>
               <item>
-                <p>End of file has been encountered.
+                <p>End of file was encountered.
                   <c><anno>LeftOverChars</anno></c> are the input characters not
                   used.</p>
               </item>
               <tag><c>{error, <anno>What</anno>}</c></tag>
               <item>
-                <p>An error occurred and the parameter <c><anno>What</anno></c> gives
-                  a hint about the error.</p>
+                <p>An error occurred and parameter <c><anno>What</anno></c>
+                  gives a hint about the error.</p>
               </item>
             </taglist>
           </item>
           <tag><c>{more, <anno>Continuation</anno>}</c></tag>
           <item>
             <p>More data is required to build a term.
-              <c><anno>Continuation</anno></c> must be passed to <c>fread/3</c>,
+              <c><anno>Continuation</anno></c> must be passed to <c>fread/3</c>
               when more data becomes available.</p>
           </item>
         </taglist>
       </desc>
     </func>
+
     <func>
-      <name name="write_atom" arity="1"/>
-      <fsummary>Write an atom</fsummary>
+      <name name="indentation" arity="2"/>
+      <fsummary>Indentation after printing string.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print the atom
-          <c><anno>Atom</anno></c>.</p>
+        <p>Returns the indentation if <c><anno>String</anno></c> has been
+          printed, starting at <c><anno>StartIndent</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write_string" arity="1"/>
-      <fsummary>Write a string</fsummary>
+      <name name="latin1_char_list" arity="1"/>
+      <fsummary>Test for a list of ISO Latin-1 characters.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print
-          <c><anno>String</anno></c> as a string.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
+          characters in the ISO Latin-1 range, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write_string_as_latin1" arity="1"/>
-      <fsummary>Write a string</fsummary>
+      <name name="nl" arity="0"/>
+      <fsummary>Write a newline.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print
-          <c><anno>String</anno></c> as a string. Non-Latin-1
-          characters are escaped.</p>
+        <p>Returns a character list that represents a new line character.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write_latin1_string" arity="1"/>
-      <fsummary>Write an ISO-latin-1 string</fsummary>
+      <name name="print" arity="1"/>
+      <name name="print" arity="4"/>
+      <fsummary>Pretty print a term.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print
-          <c><anno>Latin1String</anno></c> as a string.</p>
+        <p>Returns a list of characters that represents
+          <c><anno>Term</anno></c>, but breaks representations longer
+          than one line into many lines and indents each line sensibly.
+          Also tries to detect and output lists of printable characters
+          as strings.</p>
+        <list type="bulleted">
+          <item><c><anno>Column</anno></c> is the starting column; defaults
+            to 1.</item>
+          <item><c><anno>LineLength</anno></c> is the maximum line length;
+            defaults to 80.</item>
+          <item><c><anno>Depth</anno></c> is the maximum print depth;
+            defaults to -1, which means no limitation.</item>
+        </list>
       </desc>
     </func>
+
     <func>
-      <name name="write_char" arity="1"/>
-      <fsummary>Write a character</fsummary>
+      <name name="printable_latin1_list" arity="1"/>
+      <fsummary>Test for a list of printable ISO Latin-1 characters.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print a character
-          constant in the Unicode character set.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
+          printable ISO Latin-1 characters, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write_char_as_latin1" arity="1"/>
-      <fsummary>Write a character</fsummary>
+      <name name="printable_list" arity="1"/>
+      <fsummary>Test for a list of printable characters.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print a character
-          constant in the Unicode character set. Non-Latin-1 characters
-          are escaped.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
+          printable characters, otherwise <c>false</c>.</p>
+        <p>What is a printable character in this case is determined by
+          startup flag <c>+pc</c> to the Erlang VM; see
+          <seealso marker="io#printable_range/0">
+          <c>io:printable_range/0</c></seealso> and 
+          <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="write_latin1_char" arity="1"/>
-      <fsummary>Write an ISO-latin-1 character</fsummary>
+      <name name="printable_unicode_list" arity="1"/>
+      <fsummary>Test for a list of printable Unicode characters.</fsummary>
       <desc>
-        <p>Returns the list of characters needed to print a character
-          constant in the ISO-latin-1 character set.</p>
+        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
+          printable Unicode characters, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="indentation" arity="2"/>
-      <fsummary>Indentation after printing string</fsummary>
+      <name name="scan_format" arity="2"/>
+      <fsummary>Parse all control sequences in the format string.</fsummary>
       <desc>
-        <p>Returns the indentation if <c><anno>String</anno></c> has been printed,
-          starting at <c><anno>StartIndent</anno></c>.</p>
+        <p>Returns a list corresponding to the specified format string,
+          where control sequences have been replaced with
+          corresponding tuples. This list can be passed to:</p>
+        <list type="bulleted">
+          <item>
+            <p><seealso marker="#build_text/1"><c>build_text/1</c></seealso>
+              to have the same effect as <c>format(Format, Args)</c></p>
+          </item>
+          <item>
+            <p><seealso marker="#unscan_format/1">
+              <c>unscan_format/1</c></seealso> to get the corresponding pair
+              of <c>Format</c> and <c>Args</c> (with every <c>*</c> and
+              corresponding argument expanded to numeric values)</p>
+          </item>
+        </list>
+        <p>A typical use of this function is to replace unbounded-size
+          control sequences like <c>~w</c> and <c>~p</c> with the
+          depth-limited variants <c>~W</c> and <c>~P</c> before
+          formatting to text in, for example, a logger.</p>
       </desc>
     </func>
+
     <func>
-      <name name="char_list" arity="1"/>
-      <fsummary>Test for a list of characters</fsummary>
+      <name name="unscan_format" arity="1"/>
+      <fsummary>Revert a preparsed format list to a plain character list
+        and a list of arguments.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
-          characters in the Unicode range, otherwise it returns <c>false</c>.</p>
+        <p>For details, see
+          <seealso marker="#scan_format/2"><c>scan_format/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="latin1_char_list" arity="1"/>
-      <fsummary>Test for a list of ISO-latin-1 characters</fsummary>
+      <name name="write" arity="1"/>
+      <name name="write" arity="2"/>
+      <fsummary>Write a term.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
-          characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p>
+        <p>Returns a character list that represents <c><anno>Term</anno></c>.
+          Argument <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>
+        <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>
       </desc>
     </func>
+
     <func>
-      <name name="deep_char_list" arity="1"/>
-      <fsummary>Test for a deep list of characters</fsummary>
+      <name name="write_atom" arity="1"/>
+      <fsummary>Write an atom.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, list
-          of characters in the Unicode range, otherwise it returns <c>false</c>.</p>
+        <p>Returns the list of characters needed to print atom
+          <c><anno>Atom</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="deep_latin1_char_list" arity="1"/>
-      <fsummary>Test for a deep list of characters</fsummary>
+      <name name="write_char" arity="1"/>
+      <fsummary>Write a character.</fsummary>
+      <desc>
+        <p>Returns the list of characters needed to print a character
+          constant in the Unicode character set.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="write_char_as_latin1" arity="1"/>
+      <fsummary>Write a character.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, list
-          of characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p>
+        <p>Returns the list of characters needed to print a character
+          constant in the Unicode character set. Non-Latin-1 characters
+          are escaped.</p>
       </desc>
     </func>
+
     <func>
-      <name name="printable_list" arity="1"/>
-      <fsummary>Test for a list of printable characters</fsummary>
+      <name name="write_latin1_char" arity="1"/>
+      <fsummary>Write an ISO Latin-1 character.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
-          printable characters, otherwise it returns <c>false</c>.</p>
-	  <p>What is a printable character in this case is determined by the
-	  <c>+pc</c> start up flag to the Erlang VM. See 
-	  <seealso marker="io#printable_range/0">io:printable_range/0</seealso> 
-	  and <seealso marker="erts:erl#erl">erl(1)</seealso>.</p>
+        <p>Returns the list of characters needed to print a character
+          constant in the ISO Latin-1 character set.</p>
       </desc>
     </func>
+
     <func>
-      <name name="printable_latin1_list" arity="1"/>
-      <fsummary>Test for a list of printable ISO-latin-1 characters</fsummary>
+      <name name="write_latin1_string" arity="1"/>
+      <fsummary>Write an ISO Latin-1 string.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
-          printable ISO-latin-1 characters, otherwise it returns <c>false</c>.</p>
+        <p>Returns the list of characters needed to print
+          <c><anno>Latin1String</anno></c> as a string.</p>
       </desc>
     </func>
+
     <func>
-      <name name="printable_unicode_list" arity="1"/>
-      <fsummary>Test for a list of printable Unicode characters</fsummary>
+      <name name="write_string" arity="1"/>
+      <fsummary>Write a string.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of
-          printable Unicode characters, otherwise it returns <c>false</c>.</p>
+        <p>Returns the list of characters needed to print
+          <c><anno>String</anno></c> as a string.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="write_string_as_latin1" arity="1"/>
+      <fsummary>Write a string.</fsummary>
+      <desc>
+        <p>Returns the list of characters needed to print
+          <c><anno>String</anno></c> as a string. Non-Latin-1
+          characters are escaped.</p>
       </desc>
     </func>
   </funcs>