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)
R object to serialize.
a connection or the name of the file where the R object is saved to or read from.
a logical. If TRUE or NA, an ASCII
representation is written; otherwise (default), a binary one is used.
See the comments in the help for save.
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 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.
a hook function for handling reference objects.
For readRDS, an R object.
For saveRDS, NULL invisibly.
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.
The ‘R Internals’ manual for details of the format used.
# 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))
# }