msgpack (version 1.0)

unpackMsg: Decode msgpack messages.

Description

unpackMsg converts a raw array containing one message in msgpack format into the corresponding R data structure.

unpackMsgs extracts a number of msgpack messages from a raw object.

unpackOpts() interprets is passed to ... in unpackMsgs(), unpackMsg(), and msgConnection(). It is not exported.

Usage

unpackMsg(x, ...)
unpackMsgs(x, n = NA, reader = NULL, ...)
unpackOpts(parent = NULL, df = TRUE, simplify = TRUE, max_size = NA,
  max_depth = NA, underflow_handler = NULL)

Arguments

x

A raw() object, perhaps read from a file or socket.

...

Options passed to unpackOpts.

n

How many messages to read. An "NA" here means to read as much as possible.

reader

For implementing connections; a function that takes no arguments and returns a raw containing more data.

parent

When an environment is given, (such as emptyenv()), unpack msgpack dicts into environment objects, with the given value as parent. This option overrides use_df=TRUE. Otherwise, unpack dicts into named vectors / lists.

df

When TRUE, convert msgpack dicts, whose elements are all arrays having the same length, into data.frame()s.

simplify

If TRUE, simplify msgpack lists into primitive vectors.

max_size

The maximum length of message to decode.

max_depth

The maximum degree of nesting to support.

underflow_handler

Used internally.

Value

unpackMsg(x) returns one decoded message (which might be shorter than the input raw), or throws an error.

unpackMsgs(r, n) returns a list X with four elements:

• X$msgs is a list of the messages unpacked.

• X$remaining is data remaining to be parsed.

• X$status is a status message, typically "ok", "end of input", or "buffer underflow".

• x$bytes_read the number of bytes consumed.

Details

The msgpack format does not have typed arrays, so all msgpack arrays are effectively lists from the R perspective. However, if an array containing compatibly typed elements is read, unpack will return a logical, integer, real or string vector as appropriate. This behavior is disabled with simplify=FALSE. The coercion used is more conservative than R's coercion: Integer values may be converted to real, but boolean values will not be cast to numeric, nor any types to string. If conversion from a large integer to real loses precision, a warning is printed.

Msgpack also does not distinguish between NA and NULL. All nils will be decoded as NA.

Strings are assumed to be UTF-8 encoded. If a msgpack string does not appear to be valid UTF-8, a warning is printed and a raw object is produced instead.

Msgpack allows any type to be the key of a dict, but R only supports strings. If a non-string appears as key in a msgpack dict, it will be converted to string with deparse().

Extension types will be decoded as raw objects with a class like "ext120" and a warning.

Examples

# NOT RUN {
msg <- as.raw(c(0x82, 0xa7, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63, 0x74, 0xc3,
                0xa6, 0x73, 0x63, 0x68, 0x65, 0x6d, 0x61, 0x00))
unpackMsg(msg)
x <- packMsgs(list("one", "two", "three"))
unpackMsgs(x, 2)
# }