readRDS
Serialization Interface for Single Objects
Functions to write a single R object to a file, and to restore it.
- Keywords
- file, connection
Usage
saveRDS(object, file = "", ascii = FALSE, version = NULL,
compress = TRUE, refhook = NULL)readRDS(file, refhook = NULL)
Arguments
- object
R object to serialize.
- file
a connection or the name of the file where the R object is saved to or read from.
- ascii
a logical. If
TRUEorNA, an ASCII representation is written; otherwise (default), a binary one is used. See the comments in the help forsave.- version
the workspace format version to use.
NULLspecifies the current default version (3). The only other supported value is 2, the default from R 1.4.0 to R 3.5.0.- compress
a logical specifying whether saving to a named file is to use
"gzip"compression, or one of"gzip","bzip2"or"xz"to indicate the type of compression to be used. Ignored iffileis a connection.- refhook
a hook function for handling reference objects.
Details
These functions provide the means to save a single R object to a
connection (typically a file) and to restore the object, quite
possibly under a different name. This differs from save
and load, which save and restore one or more named
objects into an environment. They are widely used by R itself, for
example to store metadata for a package and to store the
help.search databases: the ".rds" file extension
is most often used.
Functions serialize and unserialize
provide a slightly lower-level interface to serialization: objects
serialized to a connection by serialize can be read back by
readRDS and conversely.
All of these interfaces use the same serialization format, which has
been used since R 1.4.0 (but extended from time to time as new
object types have been added to R). However, save writes a
single line header (typically "RDXs\n") before the
serialization of a single object (a pairlist of all the objects to be
saved).
Compression is handled by the connection opened when file is a
file name, so is only possible when file is a connection if
handled by the connection. So e.g.url
connections will need to be wrapped in a call to gzcon.
If a connection is supplied it will be opened (in binary mode) for the
duration of the function if not already open: if it is already open it
must be in binary mode for saveRDS(ascii = FALSE) or to read
non-ASCII saves.
Value
For readRDS, an R object.
For saveRDS, NULL invisibly.
See Also
The ‘R Internals’ manual for details of the format used.
Examples
library(base)
# NOT RUN {
fil <- tempfile("women", fileext = ".rds")
## save a single object to file
saveRDS(women, fil)
## restore it under a different name
women2 <- readRDS(fil)
identical(women, women2)
## or examine the object via a connection, which will be opened as needed.
con <- gzfile(fil)
readRDS(con)
close(con)
## Less convenient ways to restore the object
## which demonstrate compatibility with unserialize()
con <- gzfile(fil, "rb")
identical(unserialize(con), women)
close(con)
con <- gzfile(fil, "rb")
wm <- readBin(con, "raw", n = 1e4) # size is a guess
close(con)
identical(unserialize(wm), women)
## Format compatibility with serialize():
fil2 <- tempfile("women")
con <- file(fil2, "w")
serialize(women, con) # ASCII, uncompressed
close(con)
identical(women, readRDS(fil2))
fil3 <- tempfile("women")
con <- bzfile(fil3, "w")
serialize(women, con) # binary, bzip2-compressed
close(con)
identical(women, readRDS(fil3))
unlink(c(fil, fil2, fil3))
# }