\HeaderA{serialize}{Simple Serialization Interface}{serialize}
\aliasA{.readRDS}{serialize}{.readRDS}
\aliasA{.saveRDS}{serialize}{.saveRDS}
\aliasA{unserialize}{serialize}{unserialize}
\keyword{internal}{serialize}
\keyword{file}{serialize}
\begin{Description}\relax
A simple low-level interface for serializing to connections.
\end{Description}
\begin{Usage}
\begin{verbatim}
serialize(object, connection, ascii = FALSE, refhook = NULL)

unserialize(connection, refhook = NULL)

.saveRDS(object, file = "", ascii = FALSE, version = NULL,
         compress = TRUE, refhook = NULL)

.readRDS(file, refhook = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] \R{} object to serialize.
\item[\code{connection}] an open connection or (for \code{serialize})
\code{NULL} or (for \code{unserialize}) a raw vector or a length-one
character vector (see \sQuote{Details}).
\item[\code{file}] a connection or the name of the file where the R object
is saved to or read from.
\item[\code{ascii}] a logical.  If \code{TRUE}, an ASCII representation is
written; otherwise (default except for text-mode connections), a
more compact binary one is used.
\item[\code{version}] the workspace format version to use.  \code{NULL}
specifies the current default format.  The version used from \R{}
0.99.0 to \R{} 1.3.1 was version 1.  The default format as from \R{}
1.4.0 is version 2.
\item[\code{compress}] a logical specifying whether saving to a named file is
to use compression.  Ignored when \code{file} is a connection and for
workspace format version 1.
\item[\code{refhook}] a hook function for handling reference objects.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function \code{serialize} writes \code{object} to the specified
connection.  If \code{connection} is \code{NULL} then \code{object} is
serialized to a raw vector, which is returned as the result of
\code{serialize}.

Sharing of reference objects is preserved within the object but not
across separate calls to \code{serialize}.

\code{unserialize} reads an object (as written by \code{serialize})
from \code{connection} or a raw vector or (for compatibility with
earlier versions of \code{serialize}) a length-one character vector.

The \code{refhook} functions can be used to customize handling of
non-system reference objects (all external pointers and weak
references, and all environments other than name space and package
environments and \code{.GlobalEnv}).  The hook function for
\code{serialize} should return a raw vector for references it
wants to handle; otherwise it should return \code{NULL}.  The hook for
\code{unserialize} will be called with raw vectors supplied to
\code{serialize} and should return an appropriate object.

For a text-mode connection, the default value of \code{ascii} is set
to \code{TRUE}: only ASCII representations can be written to text-mode
connections and attempting to use \code{ascii = FALSE} will throw an
error.
\end{Details}
\begin{Value}
For \code{serialize}, \code{NULL} unless \code{connection = NULL}, when
the result is returned in a raw vector.

For \code{unserialize} and \code{.readRDS}, an \R{} object.

For \code{.saveRDS}, \code{NULL} invisibly.
\end{Value}
\begin{Section}{Warning}
These functions are still experimental.  Names, interfaces and
values might change in future versions (and the value of
\code{serialize} was changed for \R{} 2.4.0).  \code{.saveRDS} and
\code{.readRDS} are intended for internal use.

A raw vector is limited to \eqn{2^{31} - 1}{2^31 - 1} bytes, but \R{}
objects can exceed this and their serializations will normally be
larger than the objects.
\end{Section}
\begin{Examples}
\begin{ExampleCode}
x <- serialize(list(1,2,3), NULL)
unserialize(x)
## test earlier interface as a length-one character vector
y <- rawToChar(x)
unserialize(y)
\end{ExampleCode}
\end{Examples}

