io:format and output

Format strings

io:format reads a format string and a list of terms. A tilde starts a control sequence: ~p prints any term readably, ~s prints a string without its quotes, ~w prints a term on one line, ~b prints an integer in decimal, ~B takes a base after the dot and prints the integer in that base, and ~f prints a float. ~n is the newline.

erl

1> io:format("Hello ~p!~n", ["world"]).
Hello "world"!
ok
2> io:format("Hello ~s!~n", ["world"]).
Hello world!
ok
3> io:format("~.2f~n", [3.14159]).
3.14
ok
4> io:format("~c ~b ~.16B~n", [$A, 255, 255]).
A 255 FF
ok

The answer ok after every call is the return value of io:format itself, not part of the text. ~p keeps the quotes around a string, which is why it is the debugging choice; ~s drops them and prints the text. The dot before a number is the precision, so ~.2f rounds to two decimals.

A table with widths

A number in the control sequence sets the field width, and a minus sign aligns the value to the left. That is all a plain text table needs. Save this module as report.erl.

-module(report). -export([print/1]). print(Rows) -> io:format("~-3s ~-10s ~s~n", ["#", "task", "done"]), lists:foreach(fun row/1, Rows). row({N, Task, Done}) -> io:format("~-3b ~-10s ~s~n", [N, Task, marker(Done)]). marker(true) -> "yes"; marker(false) -> "no".

erlc report.erl
erl

1> report:print([{1, "buy milk", false}, {2, "call Ada", true}]).
# task done
1 buy milk no
2 call Ada yes
ok

The width counts characters rather than bytes when the value is Unicode text, so a column of Russian text stays aligned as long as ~ts carries the binary and the device is in unicode mode.

io_lib

io_lib:format builds the same text without printing it. The answer is a deep list, which is exactly what file:write_file and gen_tcp:send want, and lists:flatten turns it into a plain string when you need one.

erl

1> lists:flatten(io_lib:format("~p", [{ok, 1}])).
"{ok,1}"

That pair is the way to build a log line, a JSON fragment or an HTTP header: format into a list, then hand the list to the writer. Nothing touches the console, so the code is easy to test.

Raw text

io:put_chars writes its argument as it is, with no format string and no tilde codes, and io:write prints one term in the canonical form. Both answer ok. The difference shows up at once: a ~n inside put_chars stays two characters.

erl

1> io:put_chars("raw text~n").
raw text~nok

Every printing function takes an optional first argument, the device: io:format(standard_error, "~p~n", [Term]) writes to standard error, and io:format(File, "~p~n", [Term]) writes to an open file. The default is standard_io, which is the terminal or the process that started the node.

Next: Let it crash: error handling

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does the ~p control sequence print?

    Answer

    A term readably, with quotes around strings

    ~p is the readable form of any term, so strings keep their quotes.

  2. How do ~p and ~s differ for a string?

    Answer

    ~p keeps the quotes, ~s drops them

    ~p shows the value as Erlang source, ~s prints the characters themselves.

  3. What does ~n print?

    Answer

    A newline

    ~n is the newline control; there is no escape sequence in the format string.

  4. What does ~.2f do to a float?

    Answer

    Rounds it to two decimals

    The dot introduces the precision, so 3.14159 prints as 3.14.

  5. What does ~-10s do?

    Answer

    Left aligns in ten characters

    The number is the field width and the minus sign moves the value to the left.

  6. What does io:format/2 return?

    Answer

    ok

    The return value is ok; the text goes to the device, not to the caller.

  7. What does io_lib:format/2 return?

    Answer

    A deep list of the formatted text

    It builds the text and hands it back as a deep list, ready for a writer.

  8. Why does io:put_chars("raw text~n") print raw text~n?

    Answer

    put_chars takes no format string

    put_chars writes the argument verbatim; only the format functions interpret tilde codes.

  9. How do you write to standard error?

    Answer

    io:format(standard_error, ...)

    The device is the optional first argument, and standard_error is one of the devices.

  10. Which sequence prints an integer in base 16?

    Answer

    ~.16B

    B takes a base after the dot, so ~.16B prints 255 as FF.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev