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)

### 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`, 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.

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

### Value

For `readRDS`, an R object.

For `saveRDS`, `NULL` invisibly.

### See Also

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

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

### Examples

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

[Package base version 2.15.1 Index]