| readRDS {base} | R Documentation |
Functions to write a single R object to a file, and to restore it.
saveRDS(object, file = "", ascii = FALSE, version = NULL,
compress = TRUE, refhook = NULL)
readRDS(file, refhook = NULL)
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 TRUE, an ASCII representation is
written; otherwise (default except for text-mode connections), a
binary one is used. See the comments in the help for save. |
version |
the workspace format version to use. NULL
specifies the current default version (2). Versions prior to 2 are not
supported, so this will only be relevant when there are later versions. |
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 if file is a connection. |
refhook |
a hook function for handling reference objects. |
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
needed 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) (the
default).
For readRDS, an R object.
For saveRDS, NULL invisibly.
Prior to R 2.13.0 these functions were known as .readRDS() and
.saveRDS() and marked as ‘internal’. Otherwise their
interface has been stable since R 1.7.0, except that support for
support for types of compression was added in R 2.10.0 (previously
only "gzip" was available), and readRDS called
gzcon internally prior to R 2.13.0.
The internal-only .readRDS if given an un-opened connection
would wrap it in gzcon and close it after
use: this was undocumented.
The ‘R Internals’ manual for details of the format used.
## save a single object to file
saveRDS(women, "women.rds")
## restore it under a different name
women2 <- readRDS("women.rds")
identical(women, women2)
## or examine the object via a connection, which will be opened as needed.
con <- gzfile("women.rds")
str(readRDS(con))
close(con)
## Less convenient ways to restore the object
## which demonstrate compatibility with unserialize()
con <- gzfile("women.rds", "rb")
identical(unserialize(con), women)
close(con)
con <- gzfile("women.rds", "rb")
wm <- readBin(con, "raw", n = 1e4) # size is a guess
close(con)
identical(unserialize(wm), women)
## Format compatibility with serialize():
con <- file("women2", "w")
serialize(women, con) # ASCII, uncompressed
close(con)
identical(women, readRDS("women2"))
con <- bzfile("women3", "w")
serialize(women, con) # binary, bzip2-compressed
close(con)
identical(women, readRDS("women2"))