Skip to content

msgpack

primitive MessagePackEncoder

MessagePackEncoder¶

Implements low-level encoding into the MessagePack serialization format.

You should be familiar with how MessagePack encodes messages if you use this API directly. There are very few guardrails preventing you from creating invalid documents. This is particularly true when using the array and map format family encoding methods, which only write headers — the caller must write each element individually afterward.

For decoding, see MessagePackDecoder (all-at-once) or MessagePackStreamingDecoder (incremental/streaming).

primitive val MessagePackEncoder

Constructors¶

create¶

new val create()
: MessagePackEncoder val^

Returns¶

MessagePackEncoder val^

Public Functions¶

uint¶

Encodes an unsigned integer using the smallest format that fits the value.

fun box uint(
  b: Writer ref,
  v: U64 val)
: None val

Parameters¶

b: Writer ref
v: U64 val

Returns¶

None val

int¶

Encodes a signed integer using the smallest format that fits the value. Positive values use unsigned formats when smaller, per the MessagePack spec (all int/uint formats are one family).

fun box int(
  b: Writer ref,
  v: I64 val)
: None val

Parameters¶

b: Writer ref
v: I64 val

Returns¶

None val

str¶

Encodes a string using the smallest format that fits the byte length.

fun box str(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

bin¶

Encodes a binary byte array using the smallest format that fits the byte length.

fun box bin(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

array¶

Creates an array header using the smallest format that fits the element count. The caller must write s elements after this call.

fun box array(
  b: Writer ref,
  s: U32 val)
: None val

Parameters¶

b: Writer ref
s: U32 val

Returns¶

None val

map¶

Creates a map header using the smallest format that fits the pair count. The caller must write s key-value pairs after this call.

fun box map(
  b: Writer ref,
  s: U32 val)
: None val

Parameters¶

b: Writer ref
s: U32 val

Returns¶

None val

ext¶

Encodes an extension value using the smallest format that fits the data length. Prefers fixext formats for sizes 1, 2, 4, 8, and 16.

fun box ext(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

timestamp¶

Encodes a timestamp using the smallest format that fits the value. Uses timestamp_32 when nanoseconds are zero and seconds fit in a U32, timestamp_64 when seconds fit in 34 bits, and timestamp_96 otherwise.

fun box timestamp(
  b: Writer ref,
  sec: I64 val,
  nsec: U32 val)
: None val ?

Parameters¶

b: Writer ref
sec: I64 val
nsec: U32 val

Returns¶

None val ?

nil¶

nil format stores nil in 1 byte.

fun box nil(
  b: Writer ref)
: None val

Parameters¶

b: Writer ref

Returns¶

None val

bool¶

bool format family stores false or true in 1 byte.

fun box bool(
  b: Writer ref,
  t_or_f: Bool val)
: None val

Parameters¶

b: Writer ref
t_or_f: Bool val

Returns¶

None val

positive_fixint¶

positive fixnum stores 7-bit positive integer.

Max value that can be encoded is 127.

Attemping to encode an out of range value will result in an error.

fun box positive_fixint(
  b: Writer ref,
  v: U8 val)
: None val ?

Parameters¶

b: Writer ref
v: U8 val

Returns¶

None val ?

negative_fixint¶

negative fixnum stores 5-bit negative integer.

Max value that can be encoded is -1.
Min value that can be encoded is -32.

Attemping to encode an out of range value will result in an error.

fun box negative_fixint(
  b: Writer ref,
  v: I8 val)
: None val ?

Parameters¶

b: Writer ref
v: I8 val

Returns¶

None val ?

uint_8¶

uint 8 stores a 8-bit unsigned integer.

fun box uint_8(
  b: Writer ref,
  v: U8 val)
: None val

Parameters¶

b: Writer ref
v: U8 val

Returns¶

None val

uint_16¶

uint 16 stores a 16-bit big-endian unsigned integer.

fun box uint_16(
  b: Writer ref,
  v: U16 val)
: None val

Parameters¶

b: Writer ref
v: U16 val

Returns¶

None val

uint_32¶

uint 32 stores a 32-bit big-endian unsigned integer.

fun box uint_32(
  b: Writer ref,
  v: U32 val)
: None val

Parameters¶

b: Writer ref
v: U32 val

Returns¶

None val

uint_64¶

uint 64 stores a 64-bit big-endian unsigned integer.

fun box uint_64(
  b: Writer ref,
  v: U64 val)
: None val

Parameters¶

b: Writer ref
v: U64 val

Returns¶

None val

int_8¶

int 8 stores a 8-bit signed integer.

fun box int_8(
  b: Writer ref,
  v: I8 val)
: None val

Parameters¶

b: Writer ref
v: I8 val

Returns¶

None val

int_16¶

int 16 stores a 16-bit big-endian signed integer.

fun box int_16(
  b: Writer ref,
  v: I16 val)
: None val

Parameters¶

b: Writer ref
v: I16 val

Returns¶

None val

int_32¶

int 32 stores a 32-bit big-endian signed integer.

fun box int_32(
  b: Writer ref,
  v: I32 val)
: None val

Parameters¶

b: Writer ref
v: I32 val

Returns¶

None val

int_64¶

int 64 stores a 64-bit big-endian signed integer.

fun box int_64(
  b: Writer ref,
  v: I64 val)
: None val

Parameters¶

b: Writer ref
v: I64 val

Returns¶

None val

float_32¶

float 32 stores a floating point number in IEEE 754 single precision floating point number format.

fun box float_32(
  b: Writer ref,
  v: F32 val)
: None val

Parameters¶

b: Writer ref
v: F32 val

Returns¶

None val

float_64¶

float 64 stores a floating point number in IEEE 754 double precision floating point number format.

fun box float_64(
  b: Writer ref,
  v: F64 val)
: None val

Parameters¶

b: Writer ref
v: F64 val

Returns¶

None val

fixstr¶

fixstr stores a byte array whose length is upto 31 bytes.

Attempting to encode a ByteSeq larger than 31 bytes will result in an error.

fun box fixstr(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_8¶

str 8 stores a byte array whose length is upto (2^8)-1 bytes.

Attempting to encode a ByteSeq larger than (2^8)-1 bytes will result in an error.

fun box str_8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_16¶

str 16 stores a byte array whose length is upto (2^16)-1 bytes.

Attempting to encode a ByteSeq larger than (2^16)-1 bytes will result in an error.

fun box str_16(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_32¶

str 32 stores a byte array whose length is upto (2^32)-1.

Attempting to encode a ByteSeq larger than (2^32)-1 bytes will result in an error.

fun box str_32(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_utf8¶

Encodes a string using the smallest format that fits the byte length, after validating that the bytes are valid UTF-8.

Errors if the bytes are not valid UTF-8 or if the value is too large to encode. For the non-validating variant, use str().

fun box str_utf8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixstr_utf8¶

Encodes a fixstr value after validating that the bytes are valid UTF-8.

Errors if the bytes are not valid UTF-8 or if the value exceeds 31 bytes. For the non-validating variant, use fixstr().

fun box fixstr_utf8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_8_utf8¶

Encodes a str 8 value after validating that the bytes are valid UTF-8.

Errors if the bytes are not valid UTF-8 or if the value exceeds (2^8)-1 bytes. For the non-validating variant, use str_8().

fun box str_8_utf8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_16_utf8¶

Encodes a str 16 value after validating that the bytes are valid UTF-8.

Errors if the bytes are not valid UTF-8 or if the value exceeds (2^16)-1 bytes. For the non-validating variant, use str_16().

fun box str_16_utf8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

str_32_utf8¶

Encodes a str 32 value after validating that the bytes are valid UTF-8.

Errors if the bytes are not valid UTF-8 or if the value exceeds (2^32)-1 bytes. For the non-validating variant, use str_32().

fun box str_32_utf8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

bin_8¶

bin 8 stores a byte array whose length is upto (2^8)-1 bytes.

Attempting to encode a ByteSeq larger than (2^8)-1 bytes will result in an error.

fun box bin_8(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

bin_16¶

bin 16 stores a byte array whose length is upto (2^16)-1 bytes.

Attempting to encode a ByteSeq larger than (2^16)-1 bytes will result in an error.

fun box bin_16(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

bin_32¶

bin 32 stores a byte array whose length is upto (2^32)-1 bytes.

Attempting to encode a ByteSeq larger than (2^32)-1 bytes will result in an error.

fun box bin_32(
  b: Writer ref,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixarray¶

Creates a header for a MessagePack "fixarray". This only creates the header. s number of array items should be written via other methods after this is called.

fixarray stores an array whose length is upto 15 elements.

Attempting to encode a value larger than 15 will result in an error.

fun box fixarray(
  b: Writer ref,
  s: U8 val)
: None val ?

Parameters¶

b: Writer ref
s: U8 val

Returns¶

None val ?

array_16¶

Creates a header for a MessagePack "array_16". This only creates the header. s number of array items should be written via other methods after this is called.

array 16 stores an array whose length is upto (2^16)-1 elements.

Attempting to encode a value larger than (2^16)-1 bytes will result in an error.

fun box array_16(
  b: Writer ref,
  s: U16 val)
: None val

Parameters¶

b: Writer ref
s: U16 val

Returns¶

None val

array_32¶

Creates a header for a MessagePack "array_32". This only creates the header. s number of array items should be written via other methods after this is called.

array 32 stores an array whose length is upto (2^32)-1 elements.

Attempting to encode a value larger than (2^32)-1 bytes will result in an error.

fun box array_32(
  b: Writer ref,
  s: U32 val)
: None val

Parameters¶

b: Writer ref
s: U32 val

Returns¶

None val

fixmap¶

Creates a header for a MessagePack "fixmap". This only creates the header. s number of map items should be written via other methods after this is called.

fixmap stores a map whose length is upto 15 elements.

Attempting to encode a value larger than 15 will result in an error.

fun box fixmap(
  b: Writer ref,
  s: U8 val)
: None val ?

Parameters¶

b: Writer ref
s: U8 val

Returns¶

None val ?

map_16¶

Creates a header for a MessagePack "map_16". This only creates the header. s number of map items should be written via other methods after this is called.

map 16 stores an array whose length is upto (2^16)-1 elements.

Attempting to encode a value larger than (2^16)-1 bytes will result in an error.

fun box map_16(
  b: Writer ref,
  s: U16 val)
: None val

Parameters¶

b: Writer ref
s: U16 val

Returns¶

None val

map_32¶

Creates a header for a MessagePack "map_32". This only creates the header. s number of map items should be written via other methods after this is called.

map 32 stores an array whose length is upto (2^32)-1 elements.

Attempting to encode a value larger than (2^32)-1 bytes will result in an error.

fun box map_32(
  b: Writer ref,
  s: U32 val)
: None val

Parameters¶

b: Writer ref
s: U32 val

Returns¶

None val

fixext_1¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

fixext 1 stores an integer and a byte array whose length is 1 byte.

Attempting to encode a ByteSeq that is not 1 element in size will result in an error.

fun box fixext_1(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixext_2¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

fixext 2 stores an integer and a byte array whose length is 2 byte.

Attempting to encode a ByteSeq that is not 2 element in size will result in an error.

fun box fixext_2(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixext_4¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

fixext 4 stores an integer and a byte array whose length is 4 byte.

Attempting to encode a ByteSeq that is not 4 element in size will result in an error.

fun box fixext_4(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixext_8¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

fixext 8 stores an integer and a byte array whose length is 8 byte.

Attempting to encode a ByteSeq that is not 8 element in size will result in an error.

fun box fixext_8(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

fixext_16¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

fixext 16 stores an integer and a byte array whose length is 16 byte.

Attempting to encode a ByteSeq that is not 16 element in size will result in an error.

fun box fixext_16(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

ext_8¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

ext 8 stores an integer and a byte array whose length is upto (2^8)-1 bytes.

Attempting to encode a ByteSeq that is larger than (2^8)-1 bytes in size will result in an error.

fun box ext_8(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

ext_16¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

ext 16 stores an integer and a byte array whose length is upto (2^16)-1 bytes.

Attempting to encode a ByteSeq that is larger than (2^16)-1 bytes in size will result in an error.

fun box ext_16(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

ext_32¶

Allows for the creation of user supplied extensions to the MessagePack format. User should provide not just the value v to be encoded, but a unique type identifier t as well.

Type identifiers 0 to 127 are valid for user supplied types. MessagePack reserves -1 to -128 for future extension to add predefined types.

ext 32 stores an integer and a byte array whose length is upto (2^32)-1 bytes.

Attempting to encode a ByteSeq that is larger than (2^32)-1 bytes in size will result in an error.

fun box ext_32(
  b: Writer ref,
  t: U8 val,
  v: (String val | Array[U8 val] val))
: None val ?

Parameters¶

b: Writer ref
t: U8 val
v: (String val | Array[U8 val] val)

Returns¶

None val ?

timestamp_32¶

timestamp 32 stores the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC in a 32-bit unsigned integer.

It can represent a timestamp in [1970-01-01 00:00:00 UTC, 2106-02-07 06:28:16 UTC).

Nanoseconds part is 0.

fun box timestamp_32(
  b: Writer ref,
  sec: U32 val)
: None val

Parameters¶

b: Writer ref
sec: U32 val

Returns¶

None val

timestamp_64¶

timestamp 64 stores the number of seconds and nanoseconds that have elapsed since 1970-01-01 00:00:00 UTC in 32-bit unsigned integers.

It can represent a timestamp in [1970-01-01 00:00:00.000000000 UTC, 2514-05-30 01:53:04.000000000 UTC).

nsec must not be larger than 999999999. sec must not be larger than (2^34 - 1).

fun box timestamp_64(
  b: Writer ref,
  sec: U64 val,
  nsec: U32 val)
: None val ?

Parameters¶

b: Writer ref
sec: U64 val
nsec: U32 val

Returns¶

None val ?

timestamp_96¶

timestamp 96 stores the number of seconds and nanoseconds that have elapsed since 1970-01-01 00:00:00 UTC in 64-bit signed integer and 32-bit unsigned integer.

It can represent a timestamp in [-584554047284-02-23 16:59:44 UTC, 584554051223-11-09 07:00:16.000000000 UTC).

nsec must not be larger than 999999999.

fun box timestamp_96(
  b: Writer ref,
  sec: I64 val,
  nsec: U32 val)
: None val ?

Parameters¶

b: Writer ref
sec: I64 val
nsec: U32 val

Returns¶

None val ?

eq¶

fun box eq(
  that: MessagePackEncoder val)
: Bool val

Parameters¶

that: MessagePackEncoder val

Returns¶

Bool val

ne¶

fun box ne(
  that: MessagePackEncoder val)
: Bool val

Parameters¶

that: MessagePackEncoder val

Returns¶

Bool val