| % File src/library/base/man/serialize.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{serialize} |
| \alias{serialize} |
| \alias{unserialize} |
| \title{Simple Serialization Interface} |
| \description{ |
| A simple low-level interface for serializing to connections. |
| } |
| \usage{ |
| serialize(object, connection, ascii, xdr = TRUE, |
| version = NULL, refhook = NULL) |
| |
| unserialize(connection, refhook = NULL) |
| } |
| \arguments{ |
| \item{object}{\R object to serialize.} |
| \item{connection}{an open \link{connection} or (for \code{serialize}) |
| \code{NULL} or (for \code{unserialize}) a raw vector |
| (see \sQuote{Details}).} |
| \item{ascii}{a logical. If \code{TRUE} or \code{NA}, an ASCII |
| representation is written; otherwise (default) a binary one. |
| See also the comments in the help for \code{\link{save}}.} |
| \item{xdr}{a logical: if a binary representation is used, should a |
| big-endian one (XDR) be used?} |
| \item{version}{the workspace format version to use. \code{NULL} |
| specifies the current default version (3). The only other supported |
| value is 2, the default from \R 1.4.0 to \R 3.5.0.} |
| \item{refhook}{a hook function for handling reference objects.} |
| } |
| \details{ |
| The function \code{serialize} serializes \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. |
| |
| 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 namespace and package |
| environments and \code{.GlobalEnv}). The hook function for |
| \code{serialize} should return a character vector for references it |
| wants to handle; otherwise it should return \code{NULL}. The hook for |
| \code{unserialize} will be called with character 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. |
| |
| The format consists of a single line followed by the data: the first |
| line contains a single character: \code{X} for binary serialization |
| and \code{A} for ASCII serialization, followed by a new line. (The |
| format used is identical to that used by \code{\link{readRDS}}.) |
| |
| As almost all systems in current use are little-endian, \code{xdr = |
| FALSE} can be used to avoid byte-shuffling at both ends when |
| transferring data from one little-endian machine to another (or |
| between processes on the same machine). Depending on the system, this |
| can speed up serialization and unserialization by a factor of up to |
| 3x. |
| } |
| \section{Warning}{ |
| These functions have provided a stable interface since \R 2.4.0 (when |
| the storage of serialized objects was changed from character to raw |
| vectors). However, the serialization format may change in future |
| versions of \R, so this interface should not be used for long-term |
| storage of \R objects. |
| |
| On 32-bit platforms 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. |
| } |
| \value{ |
| For \code{serialize}, \code{NULL} unless \code{connection = NULL}, when |
| the result is returned in a raw vector. |
| |
| For \code{unserialize} an \R object. |
| } |
| \seealso{ |
| \code{\link{saveRDS}} for a more convenient interface to serialize an |
| object to a file or connection. |
| |
| \code{\link{save}} and \code{\link{load}} to serialize and restore one |
| or more named objects. |
| |
| The \sQuote{R Internals} manual for details of the format used. |
| } |
| \examples{ |
| x <- serialize(list(1,2,3), NULL) |
| unserialize(x) |
| |
| ## see also the examples for saveRDS |
| } |
| \keyword{file} |
| \keyword{connection} |