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



\section{library(fastrw): Fast reading and writing of terms}

\label{sec:fastrw}

\begin{tags}
    \tag{Compatibility}
The format is not compatible to SICStus/Ciao (which are not
compatible either). Future versions of this library might
implement a different encoding.
    \tag{bug}
The current implementation of \predref{fast_read}{1} \textbf{is not safe}.
It is guaranteed to safely read terms written using
\predref{fast_write}{1}, but may crash on arbitrary input. The
implementation does perform some basic sanity checks,
including validation of the magic start byte.
    \tag{To be done}
Establish a portable binary format.
\end{tags}

This library provides the SICStus and Ciao \file{library(fastrw)} interface.
The idea behind this library is to design a fast serialization for
Prolog terms. Ideally, this should be portable between Prolog
implementation. Unfortunately there is no portably binary term format
defined.

The current implementation is based on PL_record_external(), which
provides a binary representation of terms that is processed efficiently
and can handle subterm sharing, cycles and attributed variables. In
other words, this library can handle any Prolog term except \textit{blobs} such
as stream handles, database references, etc. We try to keep the format
compatible between versions, but this is not guaranteed. Conversion is
always possible by reading a database using the old version, dump it
using \predref{write_canonical}{1} and read it into the new version.

This library is built upon the following built in predicates:

\begin{itemize}
    \item \predref{fast_term_serialized}{2} translates between a term and its
serialization as a byte string.
    \item \predref{fast_read}{2} and \predref{fast_write}{2} read/write binary serializations.
\end{itemize}

\vspace{0.7cm}

\begin{description}
    \predicate{fast_read}{1}{-Term}
The next term is read from current standard input and is unified
with \arg{Term}. The syntax of the term must agree with fast_read /
fast_write format. If the end of the input has been reached,
\arg{Term} is unified with the term \verb$end_of_file$.

    \predicate{fast_write}{1}{+Term}
Output \arg{Term} in a way that \predref{fast_read}{1} and \predref{fast_read}{2} will be
able to read it back.

    \predicate{fast_write_to_string}{3}{+Term, -String, ?Tail}
Perform a fast-write to the difference-slist \arg{String}\Sneg{}\arg{Tail}.
\end{description}