serialize {base} | R Documentation |
A simple low-level interface for serializing to connections.
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)
object |
R object to serialize. |
connection |
an open connection or (for serialize )
NULL or (for unserialize ) a raw vector or a length-one
character vector (see ‘Details’). |
file |
a connection or the name of the file where the R object is saved to or read from. |
ascii |
a logical. If TRUE , an ASCII representation is
written; otherwise (default except for text-mode connections), a
more compact binary one is used. |
version |
the workspace format version to use. 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. |
compress |
a logical specifying whether saving to a named file is
to use compression. Ignored when file is a connection and for
workspace format version 1. |
refhook |
a hook function for handling reference objects. |
The function serialize
writes 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 or (for compatibility with
earlier versions of serialize
) a length-one character 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 name space and package
environments and .GlobalEnv
). The hook function for
serialize
should return a raw vector for references it
wants to handle; otherwise it should return NULL
. The hook for
unserialize
will be called with raw 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.
For serialize
, NULL
unless connection = NULL
, when
the result is returned in a raw vector.
For unserialize
and .readRDS
, an R object.
For .saveRDS
, NULL
invisibly.
These functions are still experimental. Names, interfaces and
values might change in future versions (and the value of
serialize
was changed for R 2.4.0). .saveRDS
and
.readRDS
are intended for internal use.
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.
x <- serialize(list(1,2,3), NULL) unserialize(x) ## test earlier interface as a length-one character vector y <- rawToChar(x) unserialize(y)