1io_lib(3)                  Erlang Module Definition                  io_lib(3)
2
3
4

NAME

6       io_lib - I/O library functions.
7

DESCRIPTION

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

DATA TYPES

16       chars() = [char() | chars()]
17
18       continuation()
19
20              A continuation as returned by fread/3.
21
22       chars_limit() = integer()
23
24       depth() = -1 | integer() >= 0
25
26       fread_error() =
27           atom | based | character | float | format | input | integer |
28           string | unsigned
29
30       fread_item() = string() | atom() | integer() | float()
31
32       latin1_string() = [unicode:latin1_char()]
33
34       format_spec() =
35           #{control_char := char(),
36             args := [any()],
37             width := none | integer(),
38             adjust := left | right,
39             precision := none | integer(),
40             pad_char := char(),
41             encoding := unicode | latin1,
42             strings := boolean(),
43             maps_order => maps:iterator_order()}
44
45              Where:
46
47                * control_char is the type of control sequence: $P, $w, and so
48                  on.
49
50                * args is a list of the arguments  used  by  the  control  se‐
51                  quence,  or  an  empty list if the control sequence does not
52                  take any arguments.
53
54                * width is the field width.
55
56                * adjust is the adjustment.
57
58                * precision is the precision of the printed argument.
59
60                * pad_char is the padding character.
61
62                * encoding is  set  to  true  if  translation  modifier  t  is
63                  present.
64
65                * strings is set to false if modifier l is present.
66
67                * maps_order  is set to undefined by default, ordered if modi‐
68                  fier k is present, or reversed or CmpFun if  modifier  K  is
69                  present.
70

EXPORTS

72       build_text(FormatList) -> chars()
73
74              Types:
75
76                 FormatList = [char() | format_spec()]
77
78              For details, see scan_format/2.
79
80       char_list(Term) -> boolean()
81
82              Types:
83
84                 Term = term()
85
86              Returns true if Term is a flat list of characters in the Unicode
87              range, otherwise false.
88
89       deep_char_list(Term) -> boolean()
90
91              Types:
92
93                 Term = term()
94
95              Returns true if Term is a, possibly deep, list of characters  in
96              the Unicode range, otherwise false.
97
98       deep_latin1_char_list(Term) -> boolean()
99
100              Types:
101
102                 Term = term()
103
104              Returns  true if Term is a, possibly deep, list of characters in
105              the ISO Latin-1 range, otherwise false.
106
107       format(Format, Data) -> chars()
108
109       fwrite(Format, Data) -> chars()
110
111              Types:
112
113                 Format = io:format()
114                 Data = [term()]
115
116              Returns a character list that represents Data formatted  in  ac‐
117              cordance  with  Format. For a detailed description of the avail‐
118              able formatting options,  see  io:fwrite/1,2,3.  If  the  format
119              string or argument list contains an error, a fault is generated.
120
121              If  and  only if the Unicode translation modifier is used in the
122              format string (that is, ~ts or ~tc), the resulting list can con‐
123              tain characters beyond the ISO Latin-1 character range (that is,
124              numbers > 255). If so, the result is still  an  ordinary  Erlang
125              string(), and can well be used in any context where Unicode data
126              is allowed.
127
128       format(Format, Data, Options) -> chars()
129
130       fwrite(Format, Data, Options) -> chars()
131
132              Types:
133
134                 Format = io:format()
135                 Data = [term()]
136                 Options = [Option]
137                 Option = {chars_limit, CharsLimit}
138                 CharsLimit = chars_limit()
139
140              Returns a character list that represents Data formatted  in  ac‐
141              cordance  with  Format in the same way as fwrite/2 and format/2,
142              but takes an extra argument, a list of options.
143
144              Valid option:
145
146                {chars_limit, CharsLimit}:
147                  A soft limit on the number of characters returned. When  the
148                  number  of  characters  is reached, remaining structures are
149                  replaced by "...". CharsLimit defaults to -1, which means no
150                  limit on the number of characters returned.
151
152       fread(Format, String) -> Result
153
154              Types:
155
156                 Format = String = string()
157                 Result =
158                     {ok,   InputList   ::  [fread_item()],  LeftOverChars  ::
159                 string()} |
160                     {more,
161                      RestFormat :: string(),
162                      Nchars :: integer() >= 0,
163                      InputStack :: chars()} |
164                     {error, {fread, What :: fread_error()}}
165
166              Tries to read String in accordance with the control sequences in
167              Format.  For  a detailed description of the available formatting
168              options, see io:fread/3. It  is  assumed  that  String  contains
169              whole lines.
170
171              The function returns:
172
173                {ok, InputList, LeftOverChars}:
174                  The  string  was read. InputList is the list of successfully
175                  matched and read items,  and  LeftOverChars  are  the  input
176                  characters not used.
177
178                {more, RestFormat, Nchars, InputStack}:
179                  The  string  was  read, but more input is needed to complete
180                  the original format string. RestFormat is the remaining for‐
181                  mat  string, Nchars is the number of characters scanned, and
182                  InputStack is the reversed list of inputs matched up to that
183                  point.
184
185                {error, What}:
186                  The  read  operation  failed and parameter What gives a hint
187                  about the error.
188
189              Example:
190
191              3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
192              {ok,[15.6,1.73e-5,24.5],[]}
193
194       fread(Continuation, CharSpec, Format) -> Return
195
196              Types:
197
198                 Continuation = continuation() | []
199                 CharSpec = string() | eof
200                 Format = string()
201                 Return =
202                     {more, Continuation1 :: continuation()} |
203                     {done, Result, LeftOverChars :: string()}
204                 Result =
205                     {ok, InputList :: [fread_item()]} |
206                     eof |
207                     {error, {fread, What :: fread_error()}}
208
209              This is the re-entrant formatted reader. The continuation of the
210              first  call to the functions must be []. For a complete descrip‐
211              tion of how the re-entrant input scheme  works,  see  Armstrong,
212              Virding,  Williams:  'Concurrent Programming in Erlang', Chapter
213              13.
214
215              The function returns:
216
217                {done, Result, LeftOverChars}:
218                  The input is complete. The result is one of the following:
219
220                  {ok, InputList}:
221                    The string was read. InputList is the list of successfully
222                    matched  and read items, and LeftOverChars are the remain‐
223                    ing characters.
224
225                  eof:
226                    End of file was encountered. LeftOverChars are  the  input
227                    characters not used.
228
229                  {error, What}:
230                    An  error  occurred  and parameter What gives a hint about
231                    the error.
232
233                {more, Continuation}:
234                  More data is required to build a term. Continuation must  be
235                  passed to fread/3 when more data becomes available.
236
237       indentation(String, StartIndent) -> integer()
238
239              Types:
240
241                 String = string()
242                 StartIndent = integer()
243
244              Returns  the indentation if String has been printed, starting at
245              StartIndent.
246
247       latin1_char_list(Term) -> boolean()
248
249              Types:
250
251                 Term = term()
252
253              Returns true if Term is a flat list of  characters  in  the  ISO
254              Latin-1 range, otherwise false.
255
256       nl() -> string()
257
258              Returns a character list that represents a new line character.
259
260       print(Term) -> chars()
261
262       print(Term, Column, LineLength, Depth) -> chars()
263
264              Types:
265
266                 Term = term()
267                 Column = LineLength = integer() >= 0
268                 Depth = depth()
269
270              Returns  a  list  of characters that represents Term, but breaks
271              representations longer than one line into many lines and indents
272              each  line  sensibly.  Also  tries to detect and output lists of
273              printable characters as strings.
274
275                * Column is the starting column; defaults to 1.
276
277                * LineLength is the maximum line length; defaults to 80.
278
279                * Depth is the maximum print  depth;  defaults  to  -1,  which
280                  means no limitation.
281
282       printable_latin1_list(Term) -> boolean()
283
284              Types:
285
286                 Term = term()
287
288              Returns  true  if  Term  is a flat list of printable ISO Latin-1
289              characters, otherwise false.
290
291       printable_list(Term) -> boolean()
292
293              Types:
294
295                 Term = term()
296
297              Returns true if Term is a flat  list  of  printable  characters,
298              otherwise false.
299
300              What  is  a  printable  character  in this case is determined by
301              startup flag +pc to the Erlang VM; see io:printable_range/0  and
302              erl(1).
303
304       printable_unicode_list(Term) -> boolean()
305
306              Types:
307
308                 Term = term()
309
310              Returns true if Term is a flat list of printable Unicode charac‐
311              ters, otherwise false.
312
313       scan_format(Format, Data) -> FormatList
314
315              Types:
316
317                 Format = io:format()
318                 Data = [term()]
319                 FormatList = [char() | format_spec()]
320
321              Returns a list corresponding to  the  specified  format  string,
322              where  control  sequences  have been replaced with corresponding
323              tuples. This list can be passed to:
324
325                * build_text/1 to have the same effect as format(Format, Args)
326
327                * unscan_format/1 to get the corresponding pair of Format  and
328                  Args  (with  every  * and corresponding argument expanded to
329                  numeric values)
330
331              A typical use of this function is to replace unbounded-size con‐
332              trol sequences like ~w and ~p with the depth-limited variants ~W
333              and ~P before formatting to text in, for example, a logger.
334
335       unscan_format(FormatList) -> {Format, Data}
336
337              Types:
338
339                 FormatList = [char() | format_spec()]
340                 Format = io:format()
341                 Data = [term()]
342
343              For details, see scan_format/2.
344
345       write(Term) -> chars()
346
347       write(Term, Depth) -> chars()
348
349       write(Term, Options) -> chars()
350
351              Types:
352
353                 Term = term()
354                 Options = [Option]
355                 Option =
356                     {chars_limit, CharsLimit} |
357                     {depth, Depth} |
358                     {encoding, latin1 | utf8 | unicode}
359                 CharsLimit = chars_limit()
360                 Depth = depth()
361
362              Returns a character list that represents Term. Option Depth con‐
363              trols  the  depth  of the structures written. When the specified
364              depth is reached, everything below this  level  is  replaced  by
365              "...".  Depth  defaults to -1, which means no limitation. Option
366              CharsLimit puts a soft limit on the  number  of  characters  re‐
367              turned.  When  the  number  of  characters is reached, remaining
368              structures are replaced by "...".  CharsLimit  defaults  to  -1,
369              which means no limit on the number of characters returned.
370
371              Example:
372
373              1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
374              "{1,[2],[3],[4,5],6,7,8,9}"
375              2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
376              "{1,[2],[3],[...],...}"
377              3> lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])).
378              "{[1,2|...],[4|...],...}"
379
380       write_atom(Atom) -> chars()
381
382              Types:
383
384                 Atom = atom()
385
386              Returns the list of characters needed to print atom Atom.
387
388       write_atom_as_latin1(Atom) -> latin1_string()
389
390              Types:
391
392                 Atom = atom()
393
394              Returns  the  list of characters needed to print atom Atom. Non-
395              Latin-1 characters are escaped.
396
397       write_char(Char) -> chars()
398
399              Types:
400
401                 Char = char()
402
403              Returns the list of characters needed to print a character  con‐
404              stant in the Unicode character set.
405
406       write_char_as_latin1(Char) -> latin1_string()
407
408              Types:
409
410                 Char = char()
411
412              Returns  the list of characters needed to print a character con‐
413              stant in the Unicode character set. Non-Latin-1  characters  are
414              escaped.
415
416       write_latin1_char(Latin1Char) -> latin1_string()
417
418              Types:
419
420                 Latin1Char = unicode:latin1_char()
421
422              Returns  the list of characters needed to print a character con‐
423              stant in the ISO Latin-1 character set.
424
425       write_latin1_string(Latin1String) -> latin1_string()
426
427              Types:
428
429                 Latin1String = latin1_string()
430
431              Returns the list of characters needed to print Latin1String as a
432              string.
433
434       write_string(String) -> chars()
435
436              Types:
437
438                 String = string()
439
440              Returns  the  list  of  characters  needed  to print String as a
441              string.
442
443       write_string_as_latin1(String) -> latin1_string()
444
445              Types:
446
447                 String = string()
448
449              Returns the list of characters  needed  to  print  String  as  a
450              string. Non-Latin-1 characters are escaped.
451
452
453
454Ericsson AB                      stdlib 5.1.1                        io_lib(3)
Impressum