A simple low-level interface for serializing to connections.
serialize(object, connection, ascii, xdr = TRUE,
version = NULL, refhook = NULL)unserialize(connection, refhook = NULL)
R object to serialize.
an open connection or (for serialize
)
NULL
or (for unserialize
) a raw vector
(see ‘Details’).
a logical. If TRUE
or NA
, an ASCII
representation is written; otherwise (default) a binary one.
See also the comments in the help for save
.
a logical: if a binary representation is used, should a big-endian one (XDR) be used?
the workspace format version to use. 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.
a hook function for handling reference objects.
For serialize
, NULL
unless connection = NULL
, when
the result is returned in a raw vector.
For unserialize
an R object.
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 \(2^{31} - 1\) bytes, but R objects can exceed this and their serializations will normally be larger than the objects.
The function serialize
serializes object
to the specified
connection. If connection
is NULL
then object
is
serialized to a raw vector, which is returned as the result of
serialize
.
Sharing of reference objects is preserved within the object but not
across separate calls to serialize
.
unserialize
reads an object (as written by serialize
)
from connection
or a raw vector.
The 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 .GlobalEnv
). The hook function for
serialize
should return a character vector for references it
wants to handle; otherwise it should return NULL
. The hook for
unserialize
will be called with character vectors supplied to
serialize
and should return an appropriate object.
For a text-mode connection, the default value of ascii
is set
to TRUE
: only ASCII representations can be written to text-mode
connections and attempting to use ascii = FALSE
will throw an
error.
The format consists of a single line followed by the data: the first
line contains a single character: X
for binary serialization
and A
for ASCII serialization, followed by a new line. (The
format used is identical to that used by readRDS
.)
As almost all systems in current use are little-endian, 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.
saveRDS
for a more convenient interface to serialize an
object to a file or connection.
save
and load
to serialize and restore one
or more named objects.
The ‘R Internals’ manual for details of the format used.
# NOT RUN {
x <- serialize(list(1,2,3), NULL)
unserialize(x)
## see also the examples for saveRDS
# }
Run the code above in your browser using DataLab