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
44              Where:
45
46                * control_char is the type of control sequence: $P, $w, and so
47                  on.
48
49                * args is a list of the arguments  used  by  the  control  se‐
50                  quence,  or  an  empty list if the control sequence does not
51                  take any arguments.
52
53                * width is the field width.
54
55                * adjust is the adjustment.
56
57                * precision is the precision of the printed argument.
58
59                * pad_char is the padding character.
60
61                * encoding is  set  to  true  if  translation  modifier  t  is
62                  present.
63
64                * strings is set to false if modifier l is present.
65

EXPORTS

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