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, xdr = TRUE,
              version = NULL, refhook = NULL)

    unserialize(connection, refhook = NULL)

### Arguments

`object` | R object to serialize.
`connection` | an open connection or (for `serialize`) `NULL` or (for `unserialize`) a raw vector (see ‘Details’).
`ascii` | a logical. If `TRUE`, an ASCII representation is written; otherwise binary one. The default is `TRUE` for a text-mode connection and `FALSE` otherwise. See also the comments in the help for `save`.
`xdr` | a logical: if a binary representation is used, should a big-endian one (XDR) be used?
`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.
`refhook` | a hook function for handling reference objects.

### Details

The function `serialize` serializes `object` to the specified connection. If `connection` is `NULL` then `object` is serialized to a raw vector, which is returned as the result of `serialize`.

Sharing of reference objects is preserved within the object but not across separate calls to `serialize`.

`unserialize` reads an object (as written by `serialize`) from `connection` or a raw 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 namespace and package environments and `.GlobalEnv`). The hook function for `serialize` should return a character vector for references it wants to handle; otherwise it should return `NULL`. The hook for `unserialize` will be called with character vectors supplied to `serialize` and should return an appropriate object.

For a text-mode connection, the default value of `ascii` is set to `TRUE`: only ASCII representations can be written to text-mode connections and attempting to use `ascii = FALSE` will throw an error.

The format consists of a single line followed by the data: the first line contains a single character: `X` for binary serialization and `A` for ASCII serialization, followed by a new line. (The format used is identical to that used by `readRDS`.)

The option of `xdr = FALSE` was introduced in R 2.15.0. As almost all systems in current use are little-endian, this can be used to avoid byte-shuffling at both ends when transferring data from one little-endian machine to another. Depending on the system, this can speed up serialization and unserialization by a factor of up to 3x.

### Value

For `serialize`, `NULL` unless `connection = NULL`, when the result is returned in a raw vector.

For `unserialize` an R object.

### Warning

These functions have provided a stable interface since R 2.4.0 (when the storage of serialized objects was changed from character to raw vectors). However, the serialization format may change in future versions of R, so this interface should not be used for long-term storage of R objects.

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.

### See Also

`saveRDS` for a more convenient interface to serialize an object to a file or connection.

`save` and `load` to serialize and restore one or more named objects.

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

### Examples

    x <- serialize(list(1,2,3), NULL)
    unserialize(x)

    ## see also the examples for saveRDS

[Package base version 2.15.1 Index]