aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/io_lib.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/stdlib/doc/src/io_lib.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/stdlib/doc/src/io_lib.xml')
-rw-r--r--lib/stdlib/doc/src/io_lib.xml300
1 files changed, 300 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml
new file mode 100644
index 0000000000..399f968c5f
--- /dev/null
+++ b/lib/stdlib/doc/src/io_lib.xml
@@ -0,0 +1,300 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</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.
+
+ </legalnotice>
+
+ <title>io_lib</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>io_lib</module>
+ <modulesummary>IO 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
+ 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>
+ </description>
+
+ <section>
+ <title>DATA TYPES</title>
+ <code type="none">
+chars() = [char() | chars()]</code>
+ </section>
+ <funcs>
+ <func>
+ <name>nl() -> chars()</name>
+ <fsummary>Write a newline</fsummary>
+ <desc>
+ <p>Returns a character list which represents a new line
+ character.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write(Term) -></name>
+ <name>write(Term, Depth) -> chars()</name>
+ <fsummary>Write a term</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Depth = int()</v>
+ </type>
+ <desc>
+ <p>Returns a character list which represents <c>Term</c>. The
+ <c>Depth</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>
+ </desc>
+ </func>
+ <func>
+ <name>print(Term) -></name>
+ <name>print(Term, Column, LineLength, Depth) -> chars()</name>
+ <fsummary>Pretty print a term</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Column = LineLenght = Depth = int()</v>
+ </type>
+ <desc>
+ <p>Also returns a list of characters which represents
+ <c>Term</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>Column</c> is the starting column (1),
+ <c>LineLength</c> the maximum line length (80), and
+ <c>Depth</c> (-1) the maximum print depth.</p>
+ </desc>
+ </func>
+ <func>
+ <name>fwrite(Format, Data) -></name>
+ <name>format(Format, Data) -> chars() | UnicodeList</name>
+ <fsummary>Write formatted output</fsummary>
+ <type>
+ <v>Format = atom() | string() | binary()</v>
+ <v>Data = [term()]</v>
+ <v>UnicodeList = [Unicode]</v>
+ <v>Unicode = int() representing valid unicode codepoint</v>
+ </type>
+ <desc>
+ <p>Returns a character list which represents <c>Data</c>
+ formatted in accordance with <c>Format</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>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>
+
+ </desc>
+ </func>
+ <func>
+ <name>fread(Format, String) -> Result</name>
+ <fsummary>Read formatted input</fsummary>
+ <type>
+ <v>Format = String = string()</v>
+ <v>Result = {ok, InputList, LeftOverChars} | {more, RestFormat, Nchars, InputStack} | {error, What}</v>
+ <v>&nbsp;InputList = chars()</v>
+ <v>&nbsp;LeftOverChars = string()</v>
+ <v>&nbsp;RestFormat = string()</v>
+ <v>&nbsp;Nchars = int()</v>
+ <v>&nbsp;InputStack = chars()</v>
+ <v>&nbsp;What = term()</v>
+ </type>
+ <desc>
+ <p>Tries to read <c>String</c> in accordance with the control
+ sequences in <c>Format</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>String</c> contains whole lines. It returns:</p>
+ <taglist>
+ <tag><c>{ok, InputList, LeftOverChars}</c></tag>
+ <item>
+ <p>The string was read. <c>InputList</c> is the list of
+ successfully matched and read items, and
+ <c>LeftOverChars</c> are the input characters not used.</p>
+ </item>
+ <tag><c>{more, RestFormat, Nchars, InputStack}</c></tag>
+ <item>
+ <p>The string was read, but more input is needed in order
+ to complete the original format string. <c>RestFormat</c>
+ is the remaining format string, <c>NChars</c> the number
+ of characters scanned, and <c>InputStack</c> is the
+ reversed list of inputs matched up to that point.</p>
+ </item>
+ <tag><c>{error, What}</c></tag>
+ <item>
+ <p>The read operation failed and the parameter <c>What</c>
+ gives a hint about the error.</p>
+ </item>
+ </taglist>
+ <p>Example:</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>fread(Continuation, String, Format) -> Return</name>
+ <fsummary>Re-entrant formatted reader</fsummary>
+ <type>
+ <v>Continuation = see below</v>
+ <v>String = Format = string()</v>
+ <v>Return = {done, Result, LeftOverChars} | {more, Continuation}</v>
+ <v>&nbsp;Result = {ok, InputList} | eof | {error, What}</v>
+ <v>&nbsp;&nbsp;InputList = chars()</v>
+ <v>&nbsp;&nbsp;What = term()()</v>
+ <v>&nbsp;LeftOverChars = string()</v>
+ </type>
+ <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>
+ <p>The function returns:</p>
+ <taglist>
+ <tag><c>{done, Result, LeftOverChars}</c></tag>
+ <item>
+ <p>The input is complete. The result is one of the
+ following:</p>
+ <taglist>
+ <tag><c>{ok, InputList}</c></tag>
+ <item>
+ <p>The string was read. <c>InputList</c> is the list of
+ successfully matched and read items, and
+ <c>LeftOverChars</c> are the remaining characters.</p>
+ </item>
+ <tag><c>eof</c></tag>
+ <item>
+ <p>End of file has been encountered.
+ <c>LeftOverChars</c> are the input characters not
+ used.</p>
+ </item>
+ <tag><c>{error, What}</c></tag>
+ <item>
+ <p>An error occurred and the parameter <c>What</c> gives
+ a hint about the error.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c>{more, Continuation}</c></tag>
+ <item>
+ <p>More data is required to build a term.
+ <c>Continuation</c> must be passed to <c>fread/3</c>,
+ when more data becomes available.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>write_atom(Atom) -> chars()</name>
+ <fsummary>Write an atom</fsummary>
+ <type>
+ <v>Atom = atom()</v>
+ </type>
+ <desc>
+ <p>Returns the list of characters needed to print the atom
+ <c>Atom</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_string(String) -> chars()</name>
+ <fsummary>Write a string</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns the list of characters needed to print <c>String</c>
+ as a string.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_char(Integer) -> chars()</name>
+ <fsummary>Write a character</fsummary>
+ <type>
+ <v>Integer = int()</v>
+ </type>
+ <desc>
+ <p>Returns the list of characters needed to print a character
+ constant in the ISO-latin-1 character set.</p>
+ </desc>
+ </func>
+ <func>
+ <name>indentation(String, StartIndent) -> int()</name>
+ <fsummary>Indentation after printing string</fsummary>
+ <type>
+ <v>String = string()</v>
+ <v>StartIndent = int()</v>
+ </type>
+ <desc>
+ <p>Returns the indentation if <c>String</c> has been printed,
+ starting at <c>StartIndent</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>char_list(Term) -> bool()</name>
+ <fsummary>Test for a list of characters</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a flat list of
+ characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>deep_char_list(Term) -> bool()</name>
+ <fsummary>Test for a deep list of characters</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a, possibly deep, list
+ of characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>printable_list(Term) -> bool()</name>
+ <fsummary>Test for a list of printable ISO-latin-1 characters</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a flat list of
+ printable ISO-latin-1 characters, otherwise it returns <c>false</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+