% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(charsio): I/O on Lists of Character Codes}

\label{sec:charsio}

\begin{tags}
    \tag{Compatibility}
The naming of this library is not in line with the ISO standard.
We believe that the SWI-Prolog native predicates form a more elegant
alternative for this library.
\end{tags}

This module emulates the Quintus/SICStus library \file{charsio.pl} for reading
and writing from/to lists of character codes. Most of these predicates
are straight calls into similar SWI-Prolog primitives. Some can even be
replaced by ISO standard predicates.\vspace{0.7cm}

\begin{description}
    \predicate[det]{format_to_chars}{3}{+Format, +Args, -Codes}
Use \predref{format}{2} to write to a list of character codes.

    \predicate[det]{format_to_chars}{4}{+Format, +Args, -Codes, ?Tail}
Use \predref{format}{2} to write to a difference list of character codes.

    \predicate{write_to_chars}{2}{+Term, -Codes}
Write a term to a code list. True when \arg{Codes} is a list of
character codes written by \predref{write}{1} on \arg{Term}.

    \predicate{write_to_chars}{3}{+Term, -Codes, ?Tail}
Write a term to a code list. \arg{Codes}\Sneg{}\arg{Tail} is a difference list of
character codes produced by \predref{write}{1} on \arg{Term}.

    \predicate[det]{atom_to_chars}{2}{+Atom, -Codes}
Convert \arg{Atom} into a list of character codes.

\begin{tags}
    \tag{deprecated}
Use ISO \predref{atom_codes}{2}.
\end{tags}

    \predicate[det]{atom_to_chars}{3}{+Atom, -Codes, ?Tail}
Convert \arg{Atom} into a difference list of character codes.

    \predicate[det]{number_to_chars}{2}{+Number, -Codes}
Convert Atom into a list of character codes.

\begin{tags}
    \tag{deprecated}
Use ISO \predref{number_codes}{2}.
\end{tags}

    \predicate[det]{number_to_chars}{3}{+Number, -Codes, ?Tail}
Convert \arg{Number} into a difference list of character codes.

    \predicate[det]{read_from_chars}{2}{+Codes, -Term}
Read \arg{Codes} into \arg{Term}.

\begin{tags}
    \tag{Compatibility}
The SWI-Prolog version does not require \arg{Codes} to end
in a full-stop.
\end{tags}

    \predicate[det]{read_term_from_chars}{3}{+Codes, -Term, +Options}
Read \arg{Codes} into \arg{Term}. \arg{Options} are processed by \predref{read_term}{3}.

\begin{tags}
    \tag{Compatibility}
sicstus
\end{tags}

    \predicate[det]{open_chars_stream}{2}{+Codes, -Stream}
Open \arg{Codes} as an input stream.

\begin{tags}
    \tag{See also}
\predref{open_string}{2}.
\end{tags}

    \predicate[det]{with_output_to_chars}{2}{:Goal, -Codes}
Run \arg{Goal} as with \predref{once}{1}. Output written to \verb$current_output$
is collected in \arg{Codes}.

    \predicate[det]{with_output_to_chars}{3}{:Goal, -Codes, ?Tail}
Run \arg{Goal} as with \predref{once}{1}. Output written to \verb$current_output$
is collected in \arg{Codes}\Sneg{}\arg{Tail}.

    \predicate[det]{with_output_to_chars}{4}{:Goal, -Stream, -Codes, ?Tail}
Same as \predref{with_output_to_chars}{3} using an explicit stream. The
difference list \arg{Codes}\Sneg{}\arg{Tail} contains the character codes that
\arg{Goal} has written to \arg{Stream}.
\end{description}