SWI-Prolog -- Write onto atoms, code-lists, etc.

Run Goal as once/1, while characters written to the current output are sent to Output. The predicate is SWI-Prolog-specific, inspired by various posts to the mailinglist. It provides a flexible replacement for predicates such as sformat/3 , swritef/3, term_to_atom/2, atom_number/2 converting numbers to atoms, etc. The predicate format/3 accepts the same terms as output argument.

For capturing other streams, see with_output_to/3.

Applications should generally avoid creating atoms by breaking and concatenating other atoms, as the creation of large numbers of intermediate atoms generally leads to poor performance, even more so in multithreaded applications. This predicate supports creating difference lists from character data efficiently. The example below defines the DCG rule term//1 to insert a term in the output:

term(Term, In, Tail) :-
        with_output_to(codes(In, Tail), write(Term)).

?- phrase(term(hello), X).

X = [104, 101, 108, 108, 111]

Output takes one of the shapes below. Except for the first, the system creates a temporary stream using the wchar_t internal encoding that points at a memory buffer. The encoding cannot be changed and an attempt to call set_stream/2 using encoding(Encoding) results in a permission_error exception.

A Stream handle or alias: Temporarily switch current output to the given stream. Redirection using with_output_to/2 guarantees the original output is restored, also if Goal fails or raises an exception. See also call_cleanup/2.
atom(-Atom): Create an atom from the emitted characters. Please note the remark above.
string(-String): Create a string object as defined in section 5.2.
codes(-Codes): Create a list of character codes from the emitted characters, similar to atom_codes/2.
codes(-Codes, -Tail): Create a list of character codes as a difference list.
chars(-Chars): Create a list of one-character atoms from the emitted characters, similar to atom_chars/2.
chars(-Chars, -Tail): Create a list of one-character atoms as a difference list.

4.17.6 Write onto atoms, code-lists, etc.