serialize                package: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.

Examples:

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

