writeMat: Writes a MAT file structure

Description

This function takes the given variables (...) and places them in a MAT file structure, which is then written to a binary connection.

Currently only the uncompressed MAT version 5 file format is supported, that is, compressed MAT files cannot be written (only read).

Usage

## S3 method for class 'default':
writeMat(con, ..., matVersion="5", onWrite=NULL, verbose=FALSE)

Arguments

con

Binary connection to which the MAT file structure should be written to. A string is interpreted as filename, which then will be opened (and closed afterwards).

...

Named variables to be written where the names must be unique.

matVersion

A character string specifying what MAT file format version to be written to the connection. If "5", a MAT v5 file structure is written. No other formats are currently supported.

onWrite

Function to be called just before starting to write to connection. Since the MAT file structure does not contain information about the total size of the structure this argument makes it possible to first write the structure size (in bytes) to

verbose

Either a logical, a numeric, or a Verbose object specifying how much verbose/debug inform

Value

Returns (invisibly) the number of bytes written. Any bytes written by any onWrite function are not included in this count.

Details on onWrite()

If specified, the onWrite() function is called before the data is written to the connection. This function must take a list argument as the first argument. This will hold the element con which is the opened connection to be written to. It will also hold the element length, which specified the number of bytes to be written. See example for an illustration.

Note, in order to provide the number of bytes before actually writing the data, a two-pass procedure has to be taken, where the first pass is immitating a complete writing without writing anything to the connection but only counting the total number of bytes. Then in the second pass, after calling onWrite(), the data is written.

Examples

Run this code

A <- matrix(1:27, ncol=3)
B <- as.matrix(1:10)
C <- array(1:18, dim=c(2,3,3))

filename <- paste(tempfile(), ".mat", sep="")

writeMat(filename, A=A, B=B, C=C)
data <- readMat(filename)
str(data)

X <- list(A=A, B=B, C=C)
stopifnot(all.equal(X, data[names(X)]))

unlink(filename)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# All objects written must be named uniquely
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
tryCatch({
  # Named
  writeMat(filename, A=A)
  # Not named
  writeMat(filename, A)
}, error = function(ex) {
  cat("ERROR:", ex$message, "")
})


tryCatch({
  # Uniquely named
  writeMat(filename, A=A, B=B, C=C)
  # Not uniquely named
  writeMat(filename, A=A, B=B, A=C)
}, error = function(ex) {
  cat("ERROR:", ex$message, "")
})


# When writing to a stream connection the receiver needs to know on
# beforehand how many bytes are available. This can be done by using
# the 'onWrite' argument.
onWrite <- function(x)
  writeBin(x$length, con=x$con, size=4, endian="little");
  writeMat(con, A=A, B=B, onWrite=onWrite)