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.

connection: an open connection or (for 'serialize') 'NULL' or (for
          'unserialize') a raw vector or a length-one character vector
          (see 'Details').

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

 refhook: a hook function for handling reference objects.

Details:

     The function 'serialize' writes '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 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.

     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.

Value:

     For 'serialize', 'NULL' unless 'connection = NULL', when the
     result is returned 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)

