# R: Simple Serialization Interface

serialize {base} | R Documentation

## Simple Serialization Interface

### Description

A simple low level interface for serializing to connections.

### Usage

    serialize(object, connection, ascii = FALSE, refhook = NULL)

    unserialize(connection, refhook = NULL)

    .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, or `NULL` for `serialize` or for `unserialize` an object returned by `serialize` (see Details).
`ascii` | a logical. If `TRUE`, an ASCII representation is written; otherwise (default), a more compact binary one is used.
`version` | the workspace format version to use. `NULL` specifies the current default format. The version used from R 0.99.0 to R 1.3.1 was version 1. The default format as from R 1.4.0 is version 2.
`compress` | a logical specifying whether saving to a named file is to use compression. Ignored when `file` is a connection and for workspace format version 1.
`connection` | an open connection, a raw vector or a length-one character vector.
`refhook` | a hook function for handling reference objects.

### Details

The function `serialize` writes `object` to the specified connection. Sharing of reference objects is preserved within the object but not across separate calls to serialize. If `connection` is `NULL` then `object` is serialized to a raw vector, which is returned as the result of `serialize`. For a text mode connection, the default value of `ascii` is set to `TRUE`.

`unserialize` reads an object (as written by `serialize`) from `connection` or a raw vector or (for compatibility with earlier versions of `serialize`) a length-one character vector.

The `refhook` functions can be used to customize handling of non-system reference objects (all external pointers and weak references, and all environments other than name space and package environments and `.GlobalEnv`). The hook function for `serialize` should return a raw vector for references it wants to handle; otherwise it should return `NULL`. The hook for `unserialize` will be called with raw vectors supplied to `serialize` and should return an appropriate object.

### Value

For `serialize`, `NULL` unless `connection = NULL`, when the result is stored in a raw vector.
For `unserialize` and `.readRDS`, an R object.
For `.saveRDS`, `NULL` invisibly.

### Warning

These functions are still experimental. Names, interfaces and values might change in future versions (and the value of `serialize` was changed for R 2.4.0). `.saveRDS` and `.readRDS` are intended for internal use.

A raw vector is limited to 2^31 - 1 bytes, but R objects can exceed this and their serializations will normally be larger than the objects.

### Examples

    x <- serialize(list(1,2,3), NULL)
    unserialize(x)
    ## test earlier interface as a length-one character vector
    y <- rawToChar(x)
    unserialize(y)

[Package base version 2.6.0 Index]