| Title: | 'MsgPack' C++ Header Files and Interface Functions for R |
|---|---|
| Description: | 'MsgPack' header files are provided for use by R packages, along with the ability to access, create and alter 'MsgPack' objects directly from R. 'MsgPack' is an efficient binary serialization format. It lets you exchange data among multiple languages like 'JSON' but it is faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves. This package provides headers from the 'msgpack-c' implementation for C and C++(11) for use by R, particularly 'Rcpp'. The included 'msgpack-c' headers are licensed under the Boost Software License (Version 1.0); the code added by this package as well the R integration are licensed under the GPL (>= 2). See the files 'COPYRIGHTS' and 'AUTHORS' for a full list of copyright holders and contributors to 'msgpack-c'. |
| Authors: | Travers Ching and Dirk Eddelbuettel; the authors and contributors of MsgPack |
| Maintainer: | Dirk Eddelbuettel <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.2.3.2 |
| Built: | 2024-08-09 12:22:34 UTC |
| Source: | https://github.com/eddelbuettel/rcppmsgpack |
'MsgPack' header files are provided for use by R packages, along with the ability to access, create and alter 'MsgPack' objects directly from R. 'MsgPack' is an efficient binary serialization format. It lets you exchange data among multiple languages like 'JSON' but it is faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves. This package provides headers from the 'msgpack-c' implementation for C and C++(11) for use by R, particularly 'Rcpp'. The included 'msgpack-c' headers are licensed under the Boost Software License (Version 1.0); the code added by this package as well the R integration are licensed under the GPL (>= 2). See the files 'COPYRIGHTS' and 'AUTHORS' for a full list of copyright holders and contributors to 'msgpack-c'.
Index of help topics:
RcppMsgPack-package 'MsgPack' C++ Header Files and Interface
Functions for R
arrayEx Simple MsgPack Example
enumEx Second simple MsgPack Example
msgpack_format Format data for 'MsgPack'
msgpack_map 'MsgPack' Map
msgpack_pack 'MsgPack' Pack
msgpack_read 'MsgPack' read
msgpack_simplify Simplify 'MsgPack'
msgpack_timestamp_decode
'MsgPack' Timestamp
msgpack_timestamp_encode
'MsgPack' Timestamp
msgpack_unpack 'MsgPack' Unpack
msgpack_write 'MsgPack' write
Dirk Eddelbuettel <[email protected]>
Travers Ching and Dirk Eddelbuettel; the authors and contributors of MsgPack
Simple MsgPack Example
arrayEx()arrayEx()
The function provides a simple illustration of MessagePack.
A boolean value of TRUE is returned, but the function exists
for its side effect.
The MessagePack documentation, particularly the msgpack-c examples.
Second simple MsgPack Example
enumEx()enumEx()
The function provides a simple illustration of MessagePack.
A boolean value of TRUE is returned, but the function exists
for its side effect.
The MessagePack documentation, particularly the msgpack-c examples.
A helper function to format R data for input to 'MsgPack'.
msgpack_format(x) msgpackFormat(x)msgpack_format(x) msgpackFormat(x)
x |
An r object. |
A formatted R object to use as input to msgpack_pack. Vectors are converted into Lists.
x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)
A helper function to create a map object for input to 'MsgPack'.
msgpack_map(key, value) msgpackMap(key, value)msgpack_map(key, value) msgpackMap(key, value)
key |
A list or vector of keys (coerced to list). Duplicate keys are fine (connects to std::multimap in C++). |
value |
A list or vector of values (coerced to list). This should be the same length as key. |
An data.frame also of class "map" that can be used as input to msgpack_pack.
x <- msgpack_map(key=letters[1:10], value=1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed)x <- msgpack_map(key=letters[1:10], value=1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed)
Serialize any number of objects into a single message. Unnamed List is converted into Array, Map/Data.frame and Named Lists are converted into Maps. Integer, Double, Character, Raw vectors and NULL are converted into Int types (depending on size), Float types, String, Raw and Nil respectively. Raw vectors with EXT attribute are converted into Extension types. The EXT attribute should be an integer from 0 to 127.
msgpack_pack(...) msgpackPack(...)msgpack_pack(...) msgpackPack(...)
... |
Any R objects that have corresponding msgpack types. |
A raw vector containing the message.
See examples/tests.r for more examples.
x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)
A helper function to de-serialize an object read from a file or a connection.
msgpack_read(file, simplify = F, mode = "auto", nbytes = 16777216) msgpackRead(file, simplify = F, mode = "auto", nbytes = 16777216)msgpack_read(file, simplify = F, mode = "auto", nbytes = 16777216) msgpackRead(file, simplify = F, mode = "auto", nbytes = 16777216)
file |
A connection, or a string describing the file or pipe to write to, depending on the mode. |
simplify |
Passed to msgpack_unpack. Default: FALSE. |
mode |
One of "auto", "file", "gzip" or "pipe". If "auto", detects based on the file string (any space == pipe, ".gz" == gzip, file otherwise). Ignored if file is a connection. |
nbytes |
If reading from a pipe or gzip, how many bytes to read at a time. Default: 16777216 |
tmp <- tempfile(fileext=".gz") msgpack_write(1:10, file=tmp) x <- msgpack_read(tmp, simplify=TRUE)tmp <- tempfile(fileext=".gz") msgpack_write(1:10, file=tmp) x <- msgpack_read(tmp, simplify=TRUE)
A helper function for simplifying a 'MsgPack' return object.
msgpack_simplify(x) msgpackSimplify(x)msgpack_simplify(x) msgpackSimplify(x)
x |
Return object from msgpack_unpack. |
A simplified return object from msgpack_unpack. Lists of all the same type are concatenated into an atomic vector. Maps are simplified to named lists or named vectors as appropriate. NULLs are converted to NAs if simplified to vector.
x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)
Decodes a timestamp from the 'MsgPack' extension specifications.
msgpack_timestamp_decode(x, posix = T, tz = "UTC") msgpackTimestampDecode(x, posix = T, tz = "UTC")msgpack_timestamp_decode(x, posix = T, tz = "UTC") msgpackTimestampDecode(x, posix = T, tz = "UTC")
x |
A raw vector with attriubte EXT = -1, following the 'MsgPack' timestamp specifications. |
posix |
Return a POSIXct object. Otherwise, return a list with seconds and nanoseconds since 1970-01-01 00:00:00. |
tz |
If returning a POSIXct, set the timezone. Note that this doesn't change the underlying value. |
A POSIXct or list. mt <- Sys.time() attr(mt, "tzone") <- "UTC" mp <- msgpack_pack(msgpack_timestamp_encode(mt)) mtu <- msgpack_timestamp_decode(msgpack_unpack(mp)) identical(mt, mtu)
Encodes a timestamp to the 'MsgPack' specifications.
msgpack_timestamp_encode(posix = NULL, seconds = NULL, nanoseconds = NULL) msgpackTimestampEncode(posix = NULL, seconds = NULL, nanoseconds = NULL)msgpack_timestamp_encode(posix = NULL, seconds = NULL, nanoseconds = NULL) msgpackTimestampEncode(posix = NULL, seconds = NULL, nanoseconds = NULL)
posix |
A POSIXct or POSIXlt or anything that can be coerced to a numeric. |
seconds |
The number of seconds since 1970-01-01 00:00:00 UTC. Can be negative. Don't use seconds and nanoseconds if you use posix (and vice versa). |
nanoseconds |
The number of nanoseconds since 1970-01-01 00:00:00 UTC. Must be less than 1,000,000,000 and greater than 0. |
A serialized timestamp that can be used as input to msgpack_pack. Briefly, this is an extension type -1 that is variable length, depending on the desired range and precision.
mt <- Sys.time() attr(mt, "tzone") <- "UTC" mp <- msgpack_pack(msgpack_timestamp_encode(mt)) mtu <- msgpack_timestamp_decode(msgpack_unpack(mp)) identical(mt, mtu)mt <- Sys.time() attr(mt, "tzone") <- "UTC" mp <- msgpack_pack(msgpack_timestamp_encode(mt)) mtu <- msgpack_timestamp_decode(msgpack_unpack(mp)) identical(mt, mtu)
De-serialize a 'MsgPack' message. Array is converted into List. Map is converted into Map/Data.frame. Extension types are converted into raw vectors with EXT attribute. Integers, Floats, Strings, Raw and Nil are converted into Integer, Float, Character, Raw and NULL respectively.
msgpack_unpack(message, simplify = F) msgpackUnpack(message, simplify = F)msgpack_unpack(message, simplify = F) msgpackUnpack(message, simplify = F)
message |
A raw vector containing the message. |
simplify |
Default false. Should the return object be simplified? This is generally faster and more memory efficient. |
The message pack object(s) converted into R types. If more than one object exists in the message, a list of class "msgpack_set" containing the objects is returned.
See examples/tests.r for more examples.
x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)x <- msgpack_format(1:10) x_packed <- msgpack_pack(x) x_unpacked <- msgpack_unpack(x_packed) x_simplified <- msgpack_simplify(x_unpacked)
A helper function to serialize an object and write it to a file, or a connection.
msgpack_write(..., msg = NULL, file, mode = "auto") msgpackWrite(..., msg = NULL, file, mode = "auto")msgpack_write(..., msg = NULL, file, mode = "auto") msgpackWrite(..., msg = NULL, file, mode = "auto")
... |
Serializable R objects. |
msg |
Message to write to file. If not NULL and a raw vector, write it instead of the R objects. Default: NULL. |
file |
A connection, or a string describing the file or pipe to write to, depending on the mode. |
mode |
One of "auto", "file", "gzip" or "pipe". If "auto", detects based on the file string (any space == pipe, ".gz" == gzip, file otherwise). Ignored if file is a connection. |
tmp <- tempfile(fileext=".gz") msgpack_write(1:10, file=tmp) x <- msgpack_read(tmp, simplify=TRUE)tmp <- tempfile(fileext=".gz") msgpack_write(1:10, file=tmp) x <- msgpack_read(tmp, simplify=TRUE)