# `io_lib` [🔗](https://github.com/kikofernandez/otp/blob/kiko/otp/release-gh-action-backup-continuation/OTP-20040/lib/stdlib/src/io_lib.erl#L63) 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 `m:io` module. There is no guarantee that the character lists returned from some of the functions are flat, they can be deep lists. Function `lists:flatten/1` can be used for flattening deep lists. # `chars` ```elixir -type chars() :: [char() | chars()]. ``` An possibly deep list containing only `t:char/0`s. # `chars_limit` ```elixir -type chars_limit() :: integer(). ``` A soft limit on the number of characters returned. When the number of characters is reached, remaining structures are replaced by "`...`". `CharsLimit` defaults to -1, which means no limit on the number of characters returned. # `continuation` ```elixir -opaque continuation() :: {Format :: string(), Stack :: chars(), Nchars :: non_neg_integer(), Results :: [term()]}. ``` A continuation as returned by `fread/3`. # `depth` *not exported* ```elixir -type depth() :: -1 | non_neg_integer(). ``` # `format_options` ```elixir -type format_options() :: [{chars_limit, chars_limit()}]. ``` Options that can be passed to `format/3` and `fwrite/3`. # `format_spec` ```elixir -type format_spec() :: #{control_char := char(), args := [any()], width := none | integer(), adjust := left | right, precision := none | integer(), pad_char := char(), encoding := unicode | latin1, strings := boolean(), maps_order => maps:iterator_order()}. ``` A map describing the contents of a format string. - `control_char` is the type of control 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. - `width` is the field width. - `adjust` is the adjustment. - `precision` is the precision of the printed argument. - `pad_char` is the padding character. - `encoding` is set to `true` if translation modifier `t` is present. - `strings` is set to `false` if modifier `l` is present. - `maps_order` is set to `undefined` by default, `ordered` if modifier `k` is present, or `reversed` or `CmpFun` if modifier `K` is present. # `fread_error` ```elixir -type fread_error() :: atom | based | character | float | format | input | integer | string | unsigned. ``` # `fread_item` ```elixir -type fread_item() :: string() | atom() | integer() | float(). ``` # `latin1_string` ```elixir -type latin1_string() :: [unicode:latin1_char()]. ``` # `bformat` *since OTP 28.0* ```elixir -spec bformat(Format, Data) -> unicode:unicode_binary() when Format :: io:format(), Data :: [term()]. ``` # `bformat` *since OTP 28.0* ```elixir -spec bformat(Format, Data, Options) -> unicode:unicode_binary() when Format :: io:format(), Data :: [term()], Options :: format_options(). ``` # `bfwrite` *since OTP 28.0* ```elixir -spec bfwrite(Format, Data) -> unicode:unicode_binary() when Format :: io:format(), Data :: [term()]. ``` # `bfwrite` *since OTP 28.0* ```elixir -spec bfwrite(Format, Data, Options) -> unicode:unicode_binary() when Format :: io:format(), Data :: [term()], Options :: format_options(). ``` Binary variant of `fwrite/3` Returns a UTF-8 encoded binary string. # `build_text` *since OTP 18.0* ```elixir -spec build_text(FormatList) -> chars() when FormatList :: [char() | format_spec()]. ``` For details, see `scan_format/2`. # `bwrite` *since OTP 28.0* ```elixir -spec bwrite(Term, Options) -> unicode:unicode_binary() when Term :: term(), Options :: [Option], Option :: {chars_limit, CharsLimit} | {depth, Depth} | {encoding, latin1 | utf8 | unicode} | {maps_order, maps:iterator_order()}, CharsLimit :: chars_limit(), Depth :: depth(). ``` Behaves as `write/2` but returns a UTF-8 encoded binary string. # `bwrite_string` *since OTP 28.0* ```elixir -spec bwrite_string(String, Qoute, InEnc) -> unicode:unicode_binary() when String :: string() | binary(), Qoute :: integer() | [], InEnc :: unicode | latin1. ``` Returns the UTF-8 encoded binary `String` surrounded by `Qoute`. # `char_list` ```elixir -spec char_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a flat list of characters in the Unicode range, otherwise `false`. # `deep_char_list` ```elixir -spec deep_char_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a, possibly deep, list of characters in the Unicode range, otherwise `false`. # `deep_latin1_char_list` *since OTP R16B* ```elixir -spec deep_latin1_char_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a, possibly deep, list of characters in the ISO Latin-1 range, otherwise `false`. # `format` ```elixir -spec format(Format, Data) -> chars() when Format :: io:format(), Data :: [term()]. ``` # `format` *since OTP 21.0* ```elixir -spec format(Format, Data, Options) -> chars() when Format :: io:format(), Data :: [term()], Options :: format_options(). ``` # `fread` ```elixir -spec fread(Format, String) -> Result when Format :: string(), String :: string(), Result :: {ok, InputList :: [fread_item()], LeftOverChars :: string()} | {more, RestFormat :: string(), Nchars :: non_neg_integer(), InputStack :: chars()} | {error, {fread, What :: fread_error()}}. ``` 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}`** - 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 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 parameter `What` gives a hint about the error. _Example:_ ```erlang 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5"). {ok,[15.6,1.73e-5,24.5],[]} ``` # `fread` ```elixir -spec fread(Continuation, CharSpec, Format) -> Return when Continuation :: continuation() | [], CharSpec :: string() | eof, Format :: string(), Return :: {more, Continuation1 :: continuation()} | {done, Result, LeftOverChars :: string()}, Result :: {ok, InputList :: [fread_item()]} | eof | {error, {fread, What :: fread_error()}}. ``` This is the re-entrant formatted reader. The continuation of 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}`** - 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 was encountered. `LeftOverChars` are the input characters not used. - **`{error, What}`** - 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`](`fread/3`) when more data becomes available. # `fwrite` ```elixir -spec fwrite(Format, Data) -> chars() when Format :: io:format(), Data :: [term()]. ``` 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`](`io:fwrite/1`). 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 still an ordinary Erlang `t:string/0`, and can well be used in any context where Unicode data is allowed. # `fwrite` *since OTP 21.0* ```elixir -spec fwrite(Format, Data, Options) -> chars() when Format :: io:format(), Data :: [term()], Options :: format_options(). ``` Returns a character list that represents `Data` formatted in accordance with `Format` in the same way as `fwrite/2` and `format/2`, but takes an extra argument, a list of options. Valid option: - **`{chars_limit, CharsLimit}`** - A soft limit on the number of characters returned. When the number of characters is reached, remaining structures are replaced by "`...`". `CharsLimit` defaults to -1, which means no limit on the number of characters returned. # `indentation` ```elixir -spec indentation(String, StartIndent) -> integer() when String :: string(), StartIndent :: integer(). ``` Returns the indentation if `String` has been printed, starting at `StartIndent`. # `latin1_char_list` *since OTP R16B* ```elixir -spec latin1_char_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a flat list of characters in the ISO Latin-1 range, otherwise `false`. # `nl` ```elixir -spec nl() -> string(). ``` Returns a character list that represents a new line character. # `print` ```elixir -spec print(Term) -> chars() when Term :: term(). ``` # `print` ```elixir -spec print(Term, Column, LineLength, Depth) -> chars() when Term :: term(), Column :: non_neg_integer(), LineLength :: non_neg_integer(), Depth :: depth(). ``` 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. The value 0 can be used to specify infinite length, meaning that no line breaks are inserted. - `Depth` is the maximum print depth; defaults to -1, which means no limitation. # `printable_latin1_list` *since OTP R16B* ```elixir -spec printable_latin1_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a flat list of printable ISO Latin-1 characters, otherwise `false`. # `printable_list` ```elixir -spec printable_list(Term) -> boolean() when Term :: term(). ``` 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)`](`e:erts:erl_cmd.md`). # `printable_unicode_list` *since OTP R16B* ```elixir -spec printable_unicode_list(Term) -> boolean() when Term :: term(). ``` Returns `true` if `Term` is a flat list of printable Unicode characters, otherwise `false`. # `scan_format` *since OTP 18.0* ```elixir -spec scan_format(Format, Data) -> FormatList when Format :: io:format(), Data :: [term()], FormatList :: [char() | format_spec()]. ``` Returns a list corresponding to the specified format string, where control sequences have been replaced with corresponding tuples. This list can be passed to: - `build_text/1` to have the same effect as [`format(Format, Args)`](`format/2`) - `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 in, for example, a logger. # `unscan_format` *since OTP 18.0* ```elixir -spec unscan_format(FormatList) -> {Format, Data} when FormatList :: [char() | format_spec()], Format :: io:format(), Data :: [term()]. ``` For details, see `scan_format/2`. # `write` ```elixir -spec write(Term) -> chars() when Term :: term(). ``` # `write` ```elixir -spec write(Term, Depth) -> chars() when Term :: term(), Depth :: depth(); (Term, Options) -> chars() when Term :: term(), Options :: [Option], Option :: {chars_limit, CharsLimit} | {depth, Depth} | {encoding, latin1 | utf8 | unicode} | {maps_order, maps:iterator_order()}, CharsLimit :: chars_limit(), Depth :: depth(). ``` Returns a character list that represents `Term`. Option `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. Option `CharsLimit` puts a soft limit on the number of characters returned. When the number of characters is reached, remaining structures are replaced by "`...`". `CharsLimit` defaults to -1, which means no limit on the number of characters returned. _Example:_ ```erlang 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],[...],...}" 3> lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])). "{[1,2|...],[4|...],...}" ``` # `write_atom` ```elixir -spec write_atom(Atom) -> chars() when Atom :: atom(). ``` Returns the list of characters needed to print atom `Atom`. # `write_atom_as_latin1` *since OTP 20.0* ```elixir -spec write_atom_as_latin1(Atom) -> latin1_string() when Atom :: atom(). ``` Returns the list of characters needed to print atom `Atom`. Non-Latin-1 characters are escaped. # `write_char` ```elixir -spec write_char(Char) -> chars() when Char :: char(). ``` Returns the list of characters needed to print a character constant in the Unicode character set. # `write_char_as_latin1` *since OTP R16B* ```elixir -spec write_char_as_latin1(Char) -> latin1_string() when Char :: char(). ``` Returns the list of characters needed to print a character constant in the Unicode character set. Non-Latin-1 characters are escaped. # `write_latin1_char` *since OTP R16B* ```elixir -spec write_latin1_char(Latin1Char) -> latin1_string() when Latin1Char :: unicode:latin1_char(). ``` Returns the list of characters needed to print a character constant in the ISO Latin-1 character set. # `write_latin1_string` *since OTP R16B* ```elixir -spec write_latin1_string(Latin1String) -> latin1_string() when Latin1String :: latin1_string(). ``` Returns the list of characters needed to print `Latin1String` as a string. # `write_string` ```elixir -spec write_string(String) -> chars() when String :: string(). ``` Returns the list of characters needed to print `String` as a string. # `write_string_as_latin1` *since OTP R16B* ```elixir -spec write_string_as_latin1(String) -> latin1_string() when String :: string(). ``` Returns the list of characters needed to print `String` as a string. Non-Latin-1 characters are escaped. --- *Consult [api-reference.md](api-reference.md) for complete listing*