# io_lib

### MODULE

io_lib

### MODULE SUMMARY

IO Library Functions

### DESCRIPTION

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 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.

### DATA TYPES

    chars() = [char() | chars()]

### EXPORTS

`nl() -> chars()`

Returns a character list which represents a new line character.

`write(Term) ->`
`write(Term, Depth) -> chars()`

Types:

`Term = term()`
`Depth = int()`

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],[...]|...}"

`print(Term) ->`
`print(Term, Column, LineLength, Depth) -> chars()`

Types:

`Term = term()`
`Column = LineLenght = Depth = int()`

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.

`fwrite(Format, Data) ->`
`format(Format, Data) -> chars()`

Types:

`Format = string()`
`Data = [term()]`

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.

`fread(Format, String) -> Result`

Types:

`Format = String = string()`
`Result = {ok, InputList, LeftOverChars} | {more, RestFormat, Nchars, InputStack} | {error, What}`
`InputList = chars()`
`LeftOverChars = string()`
`RestFormat = string()`
`Nchars = int()`
`InputStack = chars()`
`What = term()`

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:

`{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.
`{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 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` gives a hint about the error.

Example:

    3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
    {ok,[15.6000,1.73000e-5,24.5000],[]}

`fread(Continuation, String, Format) -> Return`

Types:

`Continuation = see below`
`String = Format = string()`
`Return = {done, Result, LeftOverChars} | {more, Continuation}`
`Result = {ok, InputList} | eof | {error, What}`
`InputList = chars()`
`What = term()()`
`LeftOverChars = string()`

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 function returns:

`{done, Result, LeftOverChars}`
  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.
  `eof`
    End of file has been encountered. `LeftOverChars` are the input characters not used.
  `{error, What}`
    An error occurred and the 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`, when more data becomes available.

`write_atom(Atom) -> chars()`

Types:

`Atom = atom()`

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

`write_string(String) -> chars()`

Types:

`String = string()`

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

`write_char(Integer) -> chars()`

Types:

`Integer = int()`

Returns the list of characters needed to print a character constant.

`indentation(String, StartIndent) -> int()`

Types:

`String = string()`
`StartIndent = int()`

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

`char_list(Term) -> bool()`

Types:

`Term = term()`

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

`deep_char_list(Term) -> bool()`

Types:

`Term = term()`

Returns `true` if `Term` is a, possibly deep, list of characters, otherwise it returns `false`.

`printable_list(Term) -> bool()`

Types:

`Term = term()`

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

### AUTHORS

Robert Virding - support@erlang.ericsson.se

stdlib 1.14
Copyright © 1991-2006 Ericsson AB