R: Serialization Interface for Single Objects

readRDS {base} | R Documentation

## Serialization Interface for Single Objects

### Description

Functions to write a single R object to a file, and to restore it.

### Usage

    saveRDS(object, file = "", ascii = FALSE, version = NULL,
            compress = TRUE, refhook = NULL)

    readRDS(file, refhook = NULL)
    infoRDS(file)

### 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 `TRUE` or `NA`, an ASCII representation is written; otherwise (default), 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 (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 if `file` is a connection.
`refhook` | a hook function for handling reference objects.

### Details

`saveRDS` and `readRDS` 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.

Function `infoRDS` retrieves meta-data about serialization produced by `saveRDS` or `serialize`. `infoRDS` cannot be used to detect whether a file is a serialization nor whether it is valid.

All of these interfaces use the same serialization format, but `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).

If `file` is a file name, it is opened by `gzfile` except for `save(compress = FALSE)` which uses `file`. Only for the exception are marked encodings of `file` which cannot be translated to the native encoding handled on Windows.

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.

For `infoRDS`, an R list with elements `version` (version number, currently 2 or 3), `writer_version` (version of R that produced the serialization), `min_reader_version` (minimum version of R that can read the serialization), `format` (data representation) and `native_encoding` (native encoding of the session that produced the serialization, available since version 3). The data representation is given as `"xdr"` for big-endian binary representation, `"ascii"` for ASCII representation (produced via `ascii = TRUE` or `ascii = NA`) or `"binary"` (binary representation with native ‘endianness’ which can be produced by `serialize`).

### See Also

`serialize`, `save` and `load`.

The ‘R Internals’ manual for details of the format used.

### Examples

    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))

[Package base version 4.0.5 Index]