Skip to content

msgpack

primitive MessagePackDecoder

MessagePackDecoder¶

Implements low-level decoding from 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 incorrectly decoding documents. This is particularly true when using the array and map format family decoding methods, which only read headers — the caller must read each element individually afterward.

Two styles of decode methods are provided:

Compact methods (uint, int, str, byte_array, ext, array, map) peek at the format byte to determine the wire format and accept any format within the family.
Format-specific methods (u8, u16, str_8, str_16, bin_8, fixext_1, ext_8, etc.) validate a single expected format byte, then read the data directly. Use these when you know the exact wire format in advance.

This decoder assumes all data is available when decoding begins. If data may arrive incrementally, use MessagePackStreamingDecoder instead.

primitive val MessagePackDecoder

Constructors¶

create¶

new val create()
: MessagePackDecoder val^

Returns¶

MessagePackDecoder val^

Public Functions¶

uint¶

Decodes an unsigned integer from any uint or positive fixint format.

fun box uint(
  b: Reader ref)
: U64 val ?

Parameters¶

b: Reader ref

Returns¶

U64 val ?

int¶

Decodes a signed integer from any int, uint, or fixint format. Errors if a uint_64 value exceeds I64.max_value().

fun box int(
  b: Reader ref)
: I64 val ?

Parameters¶

b: Reader ref

Returns¶

I64 val ?

array¶

Reads an array header from any array format. Returns the element count. The caller must read that many elements afterward.

fun box array(
  b: Reader ref)
: U32 val ?

Parameters¶

b: Reader ref

Returns¶

U32 val ?

map¶

Reads a map header from any map format. Returns the pair count. The caller must read that many key-value pairs afterward.

fun box map(
  b: Reader ref)
: U32 val ?

Parameters¶

b: Reader ref

Returns¶

U32 val ?

nil¶

Returns nothing. Throws an error if the next byte isn't a MessagePack nil.

fun box nil(
  b: Reader ref)
: None val ?

Parameters¶

b: Reader ref

Returns¶

None val ?

bool¶

fun box bool(
  b: Reader ref)
: Bool val ?

Parameters¶

b: Reader ref

Returns¶

Bool val ?

positive_fixint¶

fun box positive_fixint(
  b: Reader ref)
: U8 val ?

Parameters¶

b: Reader ref

Returns¶

U8 val ?

negative_fixint¶

fun box negative_fixint(
  b: Reader ref)
: I8 val ?

Parameters¶

b: Reader ref

Returns¶

I8 val ?

u8¶

fun box u8(
  b: Reader ref)
: U8 val ?

Parameters¶

b: Reader ref

Returns¶

U8 val ?

u16¶

fun box u16(
  b: Reader ref)
: U16 val ?

Parameters¶

b: Reader ref

Returns¶

U16 val ?

u32¶

fun box u32(
  b: Reader ref)
: U32 val ?

Parameters¶

b: Reader ref

Returns¶

U32 val ?

u64¶

fun box u64(
  b: Reader ref)
: U64 val ?

Parameters¶

b: Reader ref

Returns¶

U64 val ?

i8¶

fun box i8(
  b: Reader ref)
: I8 val ?

Parameters¶

b: Reader ref

Returns¶

I8 val ?

i16¶

fun box i16(
  b: Reader ref)
: I16 val ?

Parameters¶

b: Reader ref

Returns¶

I16 val ?

i32¶

fun box i32(
  b: Reader ref)
: I32 val ?

Parameters¶

b: Reader ref

Returns¶

I32 val ?

i64¶

fun box i64(
  b: Reader ref)
: I64 val ?

Parameters¶

b: Reader ref

Returns¶

I64 val ?

f32¶

fun box f32(
  b: Reader ref)
: F32 val ?

Parameters¶

b: Reader ref

Returns¶

F32 val ?

f64¶

fun box f64(
  b: Reader ref)
: F64 val ?

Parameters¶

b: Reader ref

Returns¶

F64 val ?

fixstr¶

fun box fixstr(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str¶

fun box str(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_8¶

Decodes a MessagePack str 8 value. Validates that the format byte is str_8 (0xD9), then reads the 1-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any string wire format, use str() instead.

fun box str_8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_16¶

Decodes a MessagePack str 16 value. Validates that the format byte is str_16 (0xDA), then reads the 2-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any string wire format, use str() instead.

fun box str_16(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_32¶

Decodes a MessagePack str 32 value. Validates that the format byte is str_32 (0xDB), then reads the 4-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any string wire format, use str() instead.

fun box str_32(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_utf8¶

Decodes a MessagePack str value using the smallest matching format, then validates that the bytes are valid UTF-8.

Errors if the format byte is not a str type, if insufficient data is available, or if the decoded bytes are not valid UTF-8. On a UTF-8 validation error the bytes have already been consumed from the reader. For the non-validating variant, use str(). To retain access to the raw bytes on validation failure, use str() followed by MessagePackValidateUTF8.

fun box str_utf8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

fixstr_utf8¶

Decodes a MessagePack fixstr value, then validates that the bytes are valid UTF-8.

Errors if the format byte does not match, if insufficient data is available, or if the decoded bytes are not valid UTF-8. For the non-validating variant, use fixstr().

fun box fixstr_utf8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_8_utf8¶

Decodes a MessagePack str 8 value, then validates that the bytes are valid UTF-8.

Errors if the format byte does not match, if insufficient data is available, or if the decoded bytes are not valid UTF-8. For the non-validating variant, use str_8().

fun box str_8_utf8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_16_utf8¶

Decodes a MessagePack str 16 value, then validates that the bytes are valid UTF-8.

Errors if the format byte does not match, if insufficient data is available, or if the decoded bytes are not valid UTF-8. For the non-validating variant, use str_16().

fun box str_16_utf8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

str_32_utf8¶

Decodes a MessagePack str 32 value, then validates that the bytes are valid UTF-8.

Errors if the format byte does not match, if insufficient data is available, or if the decoded bytes are not valid UTF-8. For the non-validating variant, use str_32().

fun box str_32_utf8(
  b: Reader ref)
: String iso^ ?

Parameters¶

b: Reader ref

Returns¶

String iso^ ?

byte_array¶

fun box byte_array(
  b: Reader ref)
: Array[U8 val] iso^ ?

Parameters¶

b: Reader ref

Returns¶

Array[U8 val] iso^ ?

bin_8¶

Decodes a MessagePack bin 8 value. Validates that the format byte is bin_8 (0xC4), then reads the 1-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any bin wire format, use byte_array() instead.

fun box bin_8(
  b: Reader ref)
: Array[U8 val] iso^ ?

Parameters¶

b: Reader ref

Returns¶

Array[U8 val] iso^ ?

bin_16¶

Decodes a MessagePack bin 16 value. Validates that the format byte is bin_16 (0xC5), then reads the 2-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any bin wire format, use byte_array() instead.

fun box bin_16(
  b: Reader ref)
: Array[U8 val] iso^ ?

Parameters¶

b: Reader ref

Returns¶

Array[U8 val] iso^ ?

bin_32¶

Decodes a MessagePack bin 32 value. Validates that the format byte is bin_32 (0xC6), then reads the 4-byte length prefix and data.

Errors if the format byte does not match or if insufficient data is available. For a method that accepts any bin wire format, use byte_array() instead.

fun box bin_32(
  b: Reader ref)
: Array[U8 val] iso^ ?

Parameters¶

b: Reader ref

Returns¶

Array[U8 val] iso^ ?

fixarray¶

Reads a header for a MessgePack "fixarray". This only reads the header. The number of array items returned by this method needs to be read via other methods after this is called.

fun box fixarray(
  b: Reader ref)
: U8 val ?

Parameters¶

b: Reader ref

Returns¶

U8 val ?

array_16¶

Reads a header for a MessgePack "array_16". This only reads the header. The number of array items returned by this method needs to be read via other methods after this is called.

fun box array_16(
  b: Reader ref)
: U16 val ?

Parameters¶

b: Reader ref

Returns¶

U16 val ?

array_32¶

Reads a header for a MessgePack "array_32". This only reads the header. The number of array items returned by this method needs to be read via other methods after this is called.

fun box array_32(
  b: Reader ref)
: U32 val ?

Parameters¶

b: Reader ref

Returns¶

U32 val ?

fixmap¶

Reads a header for a MessgePack "fixmap". This only reads the header. The number of map items returned by this method needs to be read via other methods after this is called.

fun box fixmap(
  b: Reader ref)
: U8 val ?

Parameters¶

b: Reader ref

Returns¶

U8 val ?

map_16¶

Reads a header for a MessgePack "map_16". This only reads the header. The number of map items returned by this method needs to be read via other methods after this is called.

fun box map_16(
  b: Reader ref)
: U16 val ?

Parameters¶

b: Reader ref

Returns¶

U16 val ?

map_32¶

Reads a header for a MessgePack "map_32". This only reads the header. The number of map items returned by this method needs to be read via other methods after this is called.

fun box map_32(
  b: Reader ref)
: U32 val ?

Parameters¶

b: Reader ref

Returns¶

U32 val ?

ext¶

Allows for the reading of user supplied extensions to the MessagePack format.

fixext * types return a tuple representing:

(user supplied type indentifier, data byte array)

fun box ext(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

fixext_1¶

Decodes a MessagePack fixext 1 value. Validates that the format byte is fixext_1 (0xD4), then reads the ext type byte and 1 byte of data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box fixext_1(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

fixext_2¶

Decodes a MessagePack fixext 2 value. Validates that the format byte is fixext_2 (0xD5), then reads the ext type byte and 2 bytes of data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box fixext_2(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

fixext_4¶

Decodes a MessagePack fixext 4 value. Validates that the format byte is fixext_4 (0xD6), then reads the ext type byte and 4 bytes of data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box fixext_4(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

fixext_8¶

Decodes a MessagePack fixext 8 value. Validates that the format byte is fixext_8 (0xD7), then reads the ext type byte and 8 bytes of data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box fixext_8(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

fixext_16¶

Decodes a MessagePack fixext 16 value. Validates that the format byte is fixext_16 (0xD8), then reads the ext type byte and 16 bytes of data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box fixext_16(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

ext_8¶

Decodes a MessagePack ext 8 value. Validates that the format byte is ext_8 (0xC7), then reads the 1-byte length prefix, ext type byte, and data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box ext_8(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

ext_16¶

Decodes a MessagePack ext 16 value. Validates that the format byte is ext_16 (0xC8), then reads the 2-byte length prefix, ext type byte, and data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box ext_16(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

ext_32¶

Decodes a MessagePack ext 32 value. Validates that the format byte is ext_32 (0xC9), then reads the 4-byte length prefix, ext type byte, and data.

Returns (ext_type, data). Errors if the format byte does not match. For a method that accepts any ext wire format, use ext() instead.

fun box ext_32(
  b: Reader ref)
: (U8 val , Array[U8 val] val) ?

Parameters¶

b: Reader ref

Returns¶

(U8 val , Array[U8 val] val) ?

timestamp¶

fun box timestamp(
  b: Reader ref)
: (I64 val , U32 val) ?

Parameters¶

b: Reader ref

Returns¶

(I64 val , U32 val) ?

skip¶

Advances past one complete MessagePack value without decoding it. For containers (arrays and maps), skips all contained elements.

Errors if insufficient data is available or if the format byte is invalid (0xC1). On error, no bytes are consumed.

This method has no limit on the number of values traversed. For protection against container amplification attacks, use MessagePackStreamingDecoder.skip which enforces a configurable max_skip_values limit.

fun box skip(
  b: Reader ref)
: None val ?

Parameters¶

b: Reader ref

Returns¶

None val ?

eq¶

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

Parameters¶

that: MessagePackDecoder val

Returns¶

Bool val

ne¶

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

Parameters¶

that: MessagePackDecoder val

Returns¶

Bool val