From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/io_lib.xml | 400 +++++++++++++++++++++++------------------- 1 file changed, 221 insertions(+), 179 deletions(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index b22ec15a0c..931e50f6f2 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -29,14 +29,16 @@ io_lib - IO Library Functions + I/O library functions.

This module contains functions for converting to and from strings (lists of characters). They are used for implementing the - functions in the io module. There is no guarantee that the + functions in the io module. + There is no guarantee that the character lists returned from some of the functions are flat, - they can be deep lists. lists:flatten/1 can be used for - flattening deep lists.

+ they can be deep lists. Function + lists:flatten/1 + can be used for flattening deep lists.

 @@ -45,7 +47,8 @@ -

A continuation as returned by fread/3.

+

A continuation as returned by + fread/3.

 @@ -62,338 +65,377 @@ -

Description:

+

Where:

control_char is the type of control - sequence: $P, $w, and so on;

+ sequence: $P, $w, and so on.

args is a list of the arguments used by the control sequence, or an empty list if the control sequence - does not take any arguments;

+ does not take any arguments.

 -

width is the field width;

+

width is the field width.

 -

adjust is the adjustment;

+

adjust is the adjustment.

precision is the precision of the printed - argument;

+ argument.

 -

pad_char is the padding character;

+

pad_char is the padding character.

 -

encoding is set to true if the translation - modifier t is present;

+

encoding is set to true if translation + modifier t is present.

 -

strings is set to false if the modifier +

strings is set to false if modifier l is present.

 + - - Write a newline + + Build the output text for a preparsed format list. -

Returns a character list which represents a new line - character.

+

For details, see + scan_format/2.

 + - - - Write a term + + Test for a list of characters. -

Returns a character list which represents Term. The - Depth (-1) argument controls the depth of the - structures written. When the specified depth is reached, - everything below this level is replaced by "...". For - example:

- 
-1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
-"{1,[2],[3],[4,5],6,7,8,9}"
-2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
-"{1,[2],[3],[...],...}"
+

Returns true if Term is a flat list of + characters in the Unicode range, otherwise false.

 + - - - Pretty print a term + + Test for a deep list of characters. -

Also returns a list of characters which represents - Term, 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. Column is the starting column (1), - LineLength the maximum line length (80), and - Depth (-1) the maximum print depth.

+

Returns true if Term is a, possibly deep, + list of characters in the Unicode range, otherwise false.

 + - - - Write formatted output + + Test for a deep list of characters. -

Returns a character list which represents Data - formatted in accordance with Format. See - io:fwrite/1,2,3 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.

+

Returns true if Term is a, possibly deep, + list of characters in the ISO Latin-1 range, otherwise + false.

+ + -

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.

- + + + + Write formatted output. + +

Returns a character list that represents Data + formatted in accordance with Format. + For a detailed description of the available formatting options, see + io:fwrite/1,2,3. + If the format string or argument list contains an error, a fault is + generated.

+

If and only if the Unicode translation modifier is used in the + format string (that is, ~ts or ~tc), the resulting list + can contain characters beyond the ISO Latin-1 character range + (that is, numbers > 255). If so, the + result is not an ordinary Erlang string(), but can well be + used in any context where Unicode data is allowed.

 + - Read formatted input + Read formatted input. -

Tries to read String in accordance with the control - sequences in Format. See - io:fread/3 for a detailed - description of the available formatting options. It is - assumed that String contains whole lines. It returns:

+

Tries to read String in accordance with the + control sequences in Format. + For a detailed description of the available formatting options, see + io:fread/3. It is + assumed that String contains whole lines.

+

The function returns:

- {ok, InputList, LeftOverChars} + {ok, InputList, + LeftOverChars} -

The string was read. InputList is the list of - successfully matched and read items, and - LeftOverChars are the input characters not used.

+

The string was read. InputList is the list + of successfully matched and read items, and + LeftOverChars are the input characters not + used.

 - {more, RestFormat, Nchars, InputStack} + {more, RestFormat, Nchars, + InputStack} -

The string was read, but more input is needed in order - to complete the original format string. RestFormat - is the remaining format string, Nchars the number +

The string was read, but more input is needed to complete the + original format string. RestFormat is the + remaining format string, Nchars is the number of characters scanned, and InputStack is the reversed list of inputs matched up to that point.

 {error, What} -

The read operation failed and the parameter What +

The read operation failed and parameter What gives a hint about the error.

 -

Example:

+

Example:

 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
 {ok,[15.6,1.73e-5,24.5],[]}
 + Re-entrant formatted reader

This is the re-entrant formatted reader. The continuation of - the first call to the functions must be []. Refer to - Armstrong, Virding, Williams, 'Concurrent Programming in - Erlang', Chapter 13 for a complete description of how the - re-entrant input scheme works.

+ the first call to the functions must be []. For a complete + description of how the re-entrant input scheme works, see + Armstrong, Virding, Williams: 'Concurrent Programming in + Erlang', Chapter 13.

The function returns:

- {done, Result, LeftOverChars} + {done, Result, + LeftOverChars} -

The input is complete. The result is one of the - following:

+

The input is complete. The result is one of the following:

{ok, InputList} -

The string was read. InputList is the list of - successfully matched and read items, and - LeftOverChars are the remaining characters.

+

The string was read. InputList is the + list of successfully matched and read items, and + LeftOverChars are the remaining + characters.

 eof -

End of file has been encountered. +

End of file was encountered. LeftOverChars are the input characters not used.

 {error, What} -

An error occurred and the parameter What gives - a hint about the error.

+

An error occurred and parameter What + gives a hint about the error.

 {more, Continuation}

More data is required to build a term. - Continuation must be passed to fread/3, + Continuation must be passed to fread/3 when more data becomes available.

 + - - Write an atom + + Indentation after printing string. -

Returns the list of characters needed to print the atom - Atom.

+

Returns the indentation if String has been + printed, starting at StartIndent.

 + - - Write a string + + Test for a list of ISO Latin-1 characters. -

Returns the list of characters needed to print - String as a string.

+

Returns true if Term is a flat list of + characters in the ISO Latin-1 range, otherwise false.

 + - - Write a string + + Write a newline. -

Returns the list of characters needed to print - String as a string. Non-Latin-1 - characters are escaped.

+

Returns a character list that represents a new line character.

 + - - Write an ISO-latin-1 string + + + Pretty print a term. -

Returns the list of characters needed to print - Latin1String as a string.

+

Returns a list of characters that represents + Term, 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.

+ + Column is the starting column; defaults + to 1. + LineLength is the maximum line length; + defaults to 80. + Depth is the maximum print depth; + defaults to -1, which means no limitation. + + - - Write a character + + Test for a list of printable ISO Latin-1 characters. -

Returns the list of characters needed to print a character - constant in the Unicode character set.

+

Returns true if Term is a flat list of + printable ISO Latin-1 characters, otherwise false.

 + - - Write a character + + Test for a list of printable characters. -

Returns the list of characters needed to print a character - constant in the Unicode character set. Non-Latin-1 characters - are escaped.

+

Returns true if Term is a flat list of + printable characters, otherwise false.

+

What is a printable character in this case is determined by + startup flag +pc to the Erlang VM; see + + io:printable_range/0 and + erl(1).

 + - - Write an ISO-latin-1 character + + Test for a list of printable Unicode characters. -

Returns the list of characters needed to print a character - constant in the ISO-latin-1 character set.

+

Returns true if Term is a flat list of + printable Unicode characters, otherwise false.

 + - Parse all control sequences in the format string + Parse all control sequences in the format string. -

Returns a list corresponding to the given format string, +

Returns a list corresponding to the specified format string, where control sequences have been replaced with - corresponding tuples. This list can be passed to io_lib:build_text/1 to have - the same effect as io_lib:format(Format, Args), or to - io_lib:unscan_format/1 - in order to get the corresponding pair of Format and - Args (with every * and corresponding argument - expanded to numeric values).

+ corresponding tuples. This list can be passed to:

+ + +

build_text/1 + to have the same effect as format(Format, Args)

+ + +

+ unscan_format/1 to get the corresponding pair + of Format and Args (with every * and + corresponding argument expanded to numeric values)

+ +

A typical use of this function is to replace unbounded-size control sequences like ~w and ~p with the depth-limited variants ~W and ~P before - formatting to text, e.g. in a logger.

+ formatting to text in, for example, a logger.

 + - Revert a pre-parsed format list to a plain character list - and a list of arguments - -

See io_lib:scan_format/2 for - details.

- - - - - Build the output text for a pre-parsed format list + Revert a preparsed format list to a plain character list + and a list of arguments. -

See io_lib:scan_format/2 for - details.

+

For details, see + scan_format/2.

 + - - Indentation after printing string + + + Write a term. -

Returns the indentation if String has been printed, - starting at StartIndent.

+

Returns a character list that represents Term. + Argument Depth controls the depth of the + structures written. When the specified depth is reached, + everything below this level is replaced by "...". + Depth defaults to -1, which means + no limitation.

+

Example:

+ 
+1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
+"{1,[2],[3],[4,5],6,7,8,9}"
+2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
+"{1,[2],[3],[...],...}"
 + - - Test for a list of characters + + Write an atom. -

Returns true if Term is a flat list of - characters in the Unicode range, otherwise it returns false.

+

Returns the list of characters needed to print atom + Atom.

 + - - Test for a list of ISO-latin-1 characters + + Write a character. -

Returns true if Term is a flat list of - characters in the ISO-latin-1 range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the Unicode character set.

 + - - Test for a deep list of characters + + Write a character. -

Returns true if Term is a, possibly deep, list - of characters in the Unicode range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the Unicode character set. Non-Latin-1 characters + are escaped.

 + - - Test for a deep list of characters + + Write an ISO Latin-1 character. -

Returns true if Term is a, possibly deep, list - of characters in the ISO-latin-1 range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the ISO Latin-1 character set.

 + - - Test for a list of printable characters + + Write an ISO Latin-1 string. -

Returns true if Term is a flat list of - printable characters, otherwise it returns false.

-

What is a printable character in this case is determined by the - +pc start up flag to the Erlang VM. See - io:printable_range/0 - and erl(1).

+

Returns the list of characters needed to print + Latin1String as a string.

 + - - Test for a list of printable ISO-latin-1 characters + + Write a string. -

Returns true if Term is a flat list of - printable ISO-latin-1 characters, otherwise it returns false.

+

Returns the list of characters needed to print + String as a string.

 + - - Test for a list of printable Unicode characters + + Write a string. -

Returns true if Term is a flat list of - printable Unicode characters, otherwise it returns false.

+

Returns the list of characters needed to print + String as a string. Non-Latin-1 + characters are escaped.

 -- cgit v1.2.3