WPILibC++ 2024.3.2
Expect API

The MPack Expect API allows you to easily read MessagePack data when you expect it to follow a predefined schema. More...

Basic Number Functions

uint8_t mpack_expect_u8 (mpack_reader_t *reader)
 Reads an 8-bit unsigned integer. More...
 
uint16_t mpack_expect_u16 (mpack_reader_t *reader)
 Reads a 16-bit unsigned integer. More...
 
uint32_t mpack_expect_u32 (mpack_reader_t *reader)
 Reads a 32-bit unsigned integer. More...
 
uint64_t mpack_expect_u64 (mpack_reader_t *reader)
 Reads a 64-bit unsigned integer. More...
 
int8_t mpack_expect_i8 (mpack_reader_t *reader)
 Reads an 8-bit signed integer. More...
 
int16_t mpack_expect_i16 (mpack_reader_t *reader)
 Reads a 16-bit signed integer. More...
 
int32_t mpack_expect_i32 (mpack_reader_t *reader)
 Reads a 32-bit signed integer. More...
 
int64_t mpack_expect_i64 (mpack_reader_t *reader)
 Reads a 64-bit signed integer. More...
 
float mpack_expect_float (mpack_reader_t *reader)
 Reads a number, returning the value as a float. More...
 
double mpack_expect_double (mpack_reader_t *reader)
 Reads a number, returning the value as a double. More...
 
float mpack_expect_float_strict (mpack_reader_t *reader)
 Reads a float. More...
 
double mpack_expect_double_strict (mpack_reader_t *reader)
 Reads a double. More...
 
MPACK_INLINE unsigned int mpack_expect_uint (mpack_reader_t *reader)
 Reads an unsigned int. More...
 
MPACK_INLINE int mpack_expect_int (mpack_reader_t *reader)
 Reads a signed int. More...
 

Ranged Number Functions

uint8_t mpack_expect_u8_range (mpack_reader_t *reader, uint8_t min_value, uint8_t max_value)
 Reads an 8-bit unsigned integer, ensuring that it falls within the given range. More...
 
uint16_t mpack_expect_u16_range (mpack_reader_t *reader, uint16_t min_value, uint16_t max_value)
 Reads a 16-bit unsigned integer, ensuring that it falls within the given range. More...
 
uint32_t mpack_expect_u32_range (mpack_reader_t *reader, uint32_t min_value, uint32_t max_value)
 Reads a 32-bit unsigned integer, ensuring that it falls within the given range. More...
 
uint64_t mpack_expect_u64_range (mpack_reader_t *reader, uint64_t min_value, uint64_t max_value)
 Reads a 64-bit unsigned integer, ensuring that it falls within the given range. More...
 
MPACK_INLINE unsigned int mpack_expect_uint_range (mpack_reader_t *reader, unsigned int min_value, unsigned int max_value)
 Reads an unsigned integer, ensuring that it falls within the given range. More...
 
MPACK_INLINE uint8_t mpack_expect_u8_max (mpack_reader_t *reader, uint8_t max_value)
 Reads an 8-bit unsigned integer, ensuring that it is at most max_value. More...
 
MPACK_INLINE uint16_t mpack_expect_u16_max (mpack_reader_t *reader, uint16_t max_value)
 Reads a 16-bit unsigned integer, ensuring that it is at most max_value. More...
 
MPACK_INLINE uint32_t mpack_expect_u32_max (mpack_reader_t *reader, uint32_t max_value)
 Reads a 32-bit unsigned integer, ensuring that it is at most max_value. More...
 
MPACK_INLINE uint64_t mpack_expect_u64_max (mpack_reader_t *reader, uint64_t max_value)
 Reads a 64-bit unsigned integer, ensuring that it is at most max_value. More...
 
MPACK_INLINE unsigned int mpack_expect_uint_max (mpack_reader_t *reader, unsigned int max_value)
 Reads an unsigned integer, ensuring that it is at most max_value. More...
 
int8_t mpack_expect_i8_range (mpack_reader_t *reader, int8_t min_value, int8_t max_value)
 Reads an 8-bit signed integer, ensuring that it falls within the given range. More...
 
int16_t mpack_expect_i16_range (mpack_reader_t *reader, int16_t min_value, int16_t max_value)
 Reads a 16-bit signed integer, ensuring that it falls within the given range. More...
 
int32_t mpack_expect_i32_range (mpack_reader_t *reader, int32_t min_value, int32_t max_value)
 Reads a 32-bit signed integer, ensuring that it falls within the given range. More...
 
int64_t mpack_expect_i64_range (mpack_reader_t *reader, int64_t min_value, int64_t max_value)
 Reads a 64-bit signed integer, ensuring that it falls within the given range. More...
 
MPACK_INLINE int mpack_expect_int_range (mpack_reader_t *reader, int min_value, int max_value)
 Reads a signed integer, ensuring that it falls within the given range. More...
 
MPACK_INLINE int8_t mpack_expect_i8_max (mpack_reader_t *reader, int8_t max_value)
 Reads an 8-bit signed integer, ensuring that it is at least zero and at most max_value. More...
 
MPACK_INLINE int16_t mpack_expect_i16_max (mpack_reader_t *reader, int16_t max_value)
 Reads a 16-bit signed integer, ensuring that it is at least zero and at most max_value. More...
 
MPACK_INLINE int32_t mpack_expect_i32_max (mpack_reader_t *reader, int32_t max_value)
 Reads a 32-bit signed integer, ensuring that it is at least zero and at most max_value. More...
 
MPACK_INLINE int64_t mpack_expect_i64_max (mpack_reader_t *reader, int64_t max_value)
 Reads a 64-bit signed integer, ensuring that it is at least zero and at most max_value. More...
 
MPACK_INLINE int mpack_expect_int_max (mpack_reader_t *reader, int max_value)
 Reads an int, ensuring that it is at least zero and at most max_value. More...
 
float mpack_expect_float_range (mpack_reader_t *reader, float min_value, float max_value)
 Reads a number, ensuring that it falls within the given range and returning the value as a float. More...
 
double mpack_expect_double_range (mpack_reader_t *reader, double min_value, double max_value)
 Reads a number, ensuring that it falls within the given range and returning the value as a double. More...
 

Matching Number Functions

void mpack_expect_uint_match (mpack_reader_t *reader, uint64_t value)
 Reads an unsigned integer, ensuring that it exactly matches the given value. More...
 
void mpack_expect_int_match (mpack_reader_t *reader, int64_t value)
 Reads a signed integer, ensuring that it exactly matches the given value. More...
 

Other Basic Types

void mpack_expect_nil (mpack_reader_t *reader)
 Reads a nil, raising mpack_error_type if the value is not nil. More...
 
bool mpack_expect_bool (mpack_reader_t *reader)
 Reads a boolean. More...
 
void mpack_expect_true (mpack_reader_t *reader)
 Reads a boolean, raising mpack_error_type if its value is not true. More...
 
void mpack_expect_false (mpack_reader_t *reader)
 Reads a boolean, raising mpack_error_type if its value is not false. More...
 

Compound Types

uint32_t mpack_expect_map (mpack_reader_t *reader)
 Reads the start of a map, returning its element count. More...
 
uint32_t mpack_expect_map_range (mpack_reader_t *reader, uint32_t min_count, uint32_t max_count)
 Reads the start of a map with a number of elements in the given range, returning its element count. More...
 
MPACK_INLINE uint32_t mpack_expect_map_max (mpack_reader_t *reader, uint32_t max_count)
 Reads the start of a map with a number of elements at most max_count, returning its element count. More...
 
void mpack_expect_map_match (mpack_reader_t *reader, uint32_t count)
 Reads the start of a map of the exact size given. More...
 
bool mpack_expect_map_or_nil (mpack_reader_t *reader, uint32_t *count)
 Reads a nil node or the start of a map, returning whether a map was read and placing its number of key/value pairs in count. More...
 
bool mpack_expect_map_max_or_nil (mpack_reader_t *reader, uint32_t max_count, uint32_t *count)
 Reads a nil node or the start of a map with a number of elements at most max_count, returning whether a map was read and placing its number of key/value pairs in count. More...
 
uint32_t mpack_expect_array (mpack_reader_t *reader)
 Reads the start of an array, returning its element count. More...
 
uint32_t mpack_expect_array_range (mpack_reader_t *reader, uint32_t min_count, uint32_t max_count)
 Reads the start of an array with a number of elements in the given range, returning its element count. More...
 
MPACK_INLINE uint32_t mpack_expect_array_max (mpack_reader_t *reader, uint32_t max_count)
 Reads the start of an array with a number of elements at most max_count, returning its element count. More...
 
void mpack_expect_array_match (mpack_reader_t *reader, uint32_t count)
 Reads the start of an array of the exact size given. More...
 
bool mpack_expect_array_or_nil (mpack_reader_t *reader, uint32_t *count)
 Reads a nil node or the start of an array, returning whether an array was read and placing its number of elements in count. More...
 
bool mpack_expect_array_max_or_nil (mpack_reader_t *reader, uint32_t max_count, uint32_t *count)
 Reads a nil node or the start of an array with a number of elements at most max_count, returning whether an array was read and placing its number of key/value pairs in count. More...
 
#define mpack_expect_array_alloc(reader, Type, max_count, out_count)
 Reads the start of an array and allocates storage for it, placing its size in out_count. More...
 
#define mpack_expect_array_or_nil_alloc(reader, Type, max_count, out_count)
 Reads a nil node or the start of an array and allocates storage for it, placing its size in out_count. More...
 

String Functions

uint32_t mpack_expect_str (mpack_reader_t *reader)
 Reads the start of a string, returning its size in bytes. More...
 
size_t mpack_expect_str_buf (mpack_reader_t *reader, char *buf, size_t bufsize)
 Reads a string of at most the given size, writing it into the given buffer and returning its size in bytes. More...
 
size_t mpack_expect_utf8 (mpack_reader_t *reader, char *buf, size_t bufsize)
 Reads a string into the given buffer, ensuring it is a valid UTF-8 string and returning its size in bytes. More...
 
MPACK_INLINE uint32_t mpack_expect_str_max (mpack_reader_t *reader, uint32_t maxsize)
 Reads the start of a string, raising an error if its length is not at most the given number of bytes (not including any null-terminator.) More...
 
MPACK_INLINE void mpack_expect_str_length (mpack_reader_t *reader, uint32_t count)
 Reads the start of a string, raising an error if its length is not exactly the given number of bytes (not including any null-terminator.) More...
 
void mpack_expect_str_match (mpack_reader_t *reader, const char *str, size_t length)
 Reads a string, ensuring it exactly matches the given string. More...
 
void mpack_expect_cstr (mpack_reader_t *reader, char *buf, size_t size)
 Reads a string into the given buffer, ensures it has no null bytes, and adds a null-terminator at the end. More...
 
void mpack_expect_utf8_cstr (mpack_reader_t *reader, char *buf, size_t size)
 Reads a string into the given buffer, ensures it is a valid UTF-8 string without NUL characters, and adds a null-terminator at the end. More...
 
char * mpack_expect_cstr_alloc (mpack_reader_t *reader, size_t maxsize)
 Reads a string with the given total maximum size (including space for a null-terminator), allocates storage for it, ensures it has no null-bytes, and adds a null-terminator at the end. More...
 
char * mpack_expect_utf8_cstr_alloc (mpack_reader_t *reader, size_t maxsize)
 Reads a string with the given total maximum size (including space for a null-terminator), allocates storage for it, ensures it is valid UTF-8 with no null-bytes, and adds a null-terminator at the end. More...
 
MPACK_INLINE void mpack_expect_cstr_match (mpack_reader_t *reader, const char *cstr)
 Reads a string, ensuring it exactly matches the given null-terminated string. More...
 

Binary Data

uint32_t mpack_expect_bin (mpack_reader_t *reader)
 Reads the start of a binary blob, returning its size in bytes. More...
 
MPACK_INLINE uint32_t mpack_expect_bin_max (mpack_reader_t *reader, uint32_t maxsize)
 Reads the start of a binary blob, raising an error if its length is not at most the given number of bytes. More...
 
MPACK_INLINE void mpack_expect_bin_size (mpack_reader_t *reader, uint32_t count)
 Reads the start of a binary blob, raising an error if its length is not exactly the given number of bytes. More...
 
size_t mpack_expect_bin_buf (mpack_reader_t *reader, char *buf, size_t size)
 Reads a binary blob into the given buffer, returning its size in bytes. More...
 
void mpack_expect_bin_size_buf (mpack_reader_t *reader, char *buf, uint32_t size)
 Reads a binary blob with the exact given size into the given buffer. More...
 
char * mpack_expect_bin_alloc (mpack_reader_t *reader, size_t maxsize, size_t *size)
 Reads a binary blob with the given total maximum size, allocating storage for it. More...
 

Special Functions

void mpack_expect_tag (mpack_reader_t *reader, mpack_tag_t tag)
 Reads a MessagePack object header (an MPack tag), expecting it to exactly match the given tag. More...
 
size_t mpack_expect_enum (mpack_reader_t *reader, const char *strings[], size_t count)
 Expects a string matching one of the strings in the given array, returning its array index. More...
 
size_t mpack_expect_enum_optional (mpack_reader_t *reader, const char *strings[], size_t count)
 Expects a string matching one of the strings in the given array returning its array index, or count if no strings match. More...
 
size_t mpack_expect_key_uint (mpack_reader_t *reader, bool found[], size_t count)
 Expects an unsigned integer map key between 0 and count-1, marking it as found in the given bool array and returning it. More...
 
size_t mpack_expect_key_cstr (mpack_reader_t *reader, const char *keys[], bool found[], size_t count)
 Expects a string map key matching one of the strings in the given key list, marking it as found in the given bool array and returning its index. More...
 

Detailed Description

The MPack Expect API allows you to easily read MessagePack data when you expect it to follow a predefined schema.

Note
If you are not writing code for an embedded device (or otherwise do not need maximum performance with minimal memory usage), you should not use this. You probably want to use the Node API instead.

See docs/expect.md for examples.

The main purpose of the Expect API is convenience, so the API is lax. It automatically converts between similar types where there is no loss of precision.

When using any of the expect functions, if the type or value of what was read does not match what is expected, mpack_error_type is raised.

Macro Definition Documentation

◆ mpack_expect_array_alloc

#define mpack_expect_array_alloc (   reader,
  Type,
  max_count,
  out_count 
)

Reads the start of an array and allocates storage for it, placing its size in out_count.

A number of objects follow equal to the element count of the array. You must call mpack_done_array() when done (even if the element count is zero.)

If an error occurs, NULL is returned and the reader is placed in an error state.

If the count is zero, NULL is returned. This does not indicate error. You should not check the return value for NULL to check for errors; only check the reader's error state.

The allocated array must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Exceptions
mpack_error_typeif the value is not an array or if its size is greater than max_count.

◆ mpack_expect_array_or_nil_alloc

#define mpack_expect_array_or_nil_alloc (   reader,
  Type,
  max_count,
  out_count 
)

Reads a nil node or the start of an array and allocates storage for it, placing its size in out_count.

A number of objects follow equal to the element count of the array if a non-empty array was read.

If an error occurs, NULL is returned and the reader is placed in an error state.

If a nil node was read, NULL is returned. If an empty array was read, mpack_done_array() is called automatically and NULL is returned. These do not indicate error. You should not check the return value for NULL to check for errors; only check the reader's error state.

The allocated array must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Warning
You must call mpack_done_array() if and only if a non-zero element count is read. This function does not differentiate between nil and an empty array.
Exceptions
mpack_error_typeif the value is not an array or if its size is greater than max_count.

Function Documentation

◆ mpack_expect_array()

uint32_t mpack_expect_array ( mpack_reader_t reader)

Reads the start of an array, returning its element count.

A number of values follow equal to the element count of the array. mpack_done_array() must be called once all elements have been read.

Warning
This call is dangerous! It does not have a size limit, and it does not have any way of checking whether there is enough data in the message (since the data could be coming from a stream.) When looping through the array's contents, you must check for errors on each iteration of the loop. Otherwise an attacker could craft a message declaring an array of a billion elements which would throw your parsing code into an infinite loop! You should strongly consider using mpack_expect_array_max() with a safe maximum size instead.

◆ mpack_expect_array_match()

void mpack_expect_array_match ( mpack_reader_t reader,
uint32_t  count 
)

Reads the start of an array of the exact size given.

A number of values follow equal to the element count of the array. mpack_done_array() must be called once all elements have been read.

Exceptions
mpack_error_typeif the value is not an array or if its size does not match the given count.

◆ mpack_expect_array_max()

MPACK_INLINE uint32_t mpack_expect_array_max ( mpack_reader_t reader,
uint32_t  max_count 
)

Reads the start of an array with a number of elements at most max_count, returning its element count.

A number of values follow equal to the element count of the array. mpack_done_array() must be called once all elements have been read.

Zero is returned if an error occurs.

Exceptions
mpack_error_typeif the value is not an array or if its size is greater than max_count.

◆ mpack_expect_array_max_or_nil()

bool mpack_expect_array_max_or_nil ( mpack_reader_t reader,
uint32_t  max_count,
uint32_t *  count 
)

Reads a nil node or the start of an array with a number of elements at most max_count, returning whether an array was read and placing its number of key/value pairs in count.

If an array was read, a number of values follow equal to the element count of the array. mpack_done_array() should also be called once all elements have been read (only if an array was read.)

Returns
true if an array was read successfully; false if nil was read or an error occurred.
Exceptions
mpack_error_typeif the value is not a nil or array.

◆ mpack_expect_array_or_nil()

bool mpack_expect_array_or_nil ( mpack_reader_t reader,
uint32_t *  count 
)

Reads a nil node or the start of an array, returning whether an array was read and placing its number of elements in count.

If an array was read, a number of values follow equal to the element count of the array. mpack_done_array() should also be called once all elements have been read (only if an array was read.)

Warning
This call is dangerous! It does not have a size limit, and it does not have any way of checking whether there is enough data in the message (since the data could be coming from a stream.) When looping through the array's contents, you must check for errors on each iteration of the loop. Otherwise an attacker could craft a message declaring an array of a billion elements which would throw your parsing code into an infinite loop! You should strongly consider using mpack_expect_array_max_or_nil() with a safe maximum size instead.
Returns
true if an array was read successfully; false if nil was read or an error occurred.
Exceptions
mpack_error_typeif the value is not a nil or array.

◆ mpack_expect_array_range()

uint32_t mpack_expect_array_range ( mpack_reader_t reader,
uint32_t  min_count,
uint32_t  max_count 
)

Reads the start of an array with a number of elements in the given range, returning its element count.

A number of values follow equal to the element count of the array. mpack_done_array() must be called once all elements have been read.

min_count is returned if an error occurs.

Exceptions
mpack_error_typeif the value is not an array or if its size does not fall within the given range.

◆ mpack_expect_bin()

uint32_t mpack_expect_bin ( mpack_reader_t reader)

Reads the start of a binary blob, returning its size in bytes.

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_bin() must be called once all bytes have been read.

mpack_error_type is raised if the value is not a binary blob.

◆ mpack_expect_bin_alloc()

char * mpack_expect_bin_alloc ( mpack_reader_t reader,
size_t  maxsize,
size_t *  size 
)

Reads a binary blob with the given total maximum size, allocating storage for it.

◆ mpack_expect_bin_buf()

size_t mpack_expect_bin_buf ( mpack_reader_t reader,
char *  buf,
size_t  size 
)

Reads a binary blob into the given buffer, returning its size in bytes.

For compatibility, this will accept if the underlying type is string or binary (since in MessagePack 1.0, strings and binary data were combined under the "raw" type which became string in 1.1.)

◆ mpack_expect_bin_max()

MPACK_INLINE uint32_t mpack_expect_bin_max ( mpack_reader_t reader,
uint32_t  maxsize 
)

Reads the start of a binary blob, raising an error if its length is not at most the given number of bytes.

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_bin() must be called once all bytes have been read.

mpack_error_type is raised if the value is not a binary blob or if its length does not match.

◆ mpack_expect_bin_size()

MPACK_INLINE void mpack_expect_bin_size ( mpack_reader_t reader,
uint32_t  count 
)

Reads the start of a binary blob, raising an error if its length is not exactly the given number of bytes.

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_bin() must be called once all bytes have been read.

Exceptions
mpack_error_typeif the value is not a binary blob or if its size does not match.

◆ mpack_expect_bin_size_buf()

void mpack_expect_bin_size_buf ( mpack_reader_t reader,
char *  buf,
uint32_t  size 
)

Reads a binary blob with the exact given size into the given buffer.

For compatibility, this will accept if the underlying type is string or binary (since in MessagePack 1.0, strings and binary data were combined under the "raw" type which became string in 1.1.)

Exceptions
mpack_error_typeif the value is not a binary blob or if its size does not match.

◆ mpack_expect_bool()

bool mpack_expect_bool ( mpack_reader_t reader)

Reads a boolean.

Note
Integers will raise mpack_error_type; the value must be strictly a boolean.

◆ mpack_expect_cstr()

void mpack_expect_cstr ( mpack_reader_t reader,
char *  buf,
size_t  size 
)

Reads a string into the given buffer, ensures it has no null bytes, and adds a null-terminator at the end.

Raises mpack_error_too_big if there is not enough room for the string and null-terminator. Raises mpack_error_type if the value is not a string or contains a null byte.

◆ mpack_expect_cstr_alloc()

char * mpack_expect_cstr_alloc ( mpack_reader_t reader,
size_t  maxsize 
)

Reads a string with the given total maximum size (including space for a null-terminator), allocates storage for it, ensures it has no null-bytes, and adds a null-terminator at the end.

You assume ownership of the returned pointer if reading succeeds.

The allocated string must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.)

Exceptions
mpack_error_too_bigIf the string plus null-terminator is larger than the given maxsize.
mpack_error_typeIf the value is not a string or contains a null byte.

◆ mpack_expect_cstr_match()

MPACK_INLINE void mpack_expect_cstr_match ( mpack_reader_t reader,
const char *  cstr 
)

Reads a string, ensuring it exactly matches the given null-terminated string.

Remember that maps are unordered in JSON. Don't use this for map keys unless the map has only a single key!

◆ mpack_expect_double()

double mpack_expect_double ( mpack_reader_t reader)

Reads a number, returning the value as a double.

The underlying value can be an integer, float or double; the value is converted to a double.

Note
Reading a very large integer with this function can incur a loss of precision.
Exceptions
mpack_error_typeif the underlying value is not a float, double or integer.

◆ mpack_expect_double_range()

double mpack_expect_double_range ( mpack_reader_t reader,
double  min_value,
double  max_value 
)

Reads a number, ensuring that it falls within the given range and returning the value as a double.

The underlying value can be an integer, float or double; the value is converted to a double.

Note
Reading a very large integer with this function can incur a loss of precision.
Exceptions
mpack_error_typeif the underlying value is not a float, double or integer.

◆ mpack_expect_double_strict()

double mpack_expect_double_strict ( mpack_reader_t reader)

Reads a double.

The underlying value must be a float or double, not an integer. This ensures no loss of precision can occur.

Exceptions
mpack_error_typeif the underlying value is not a float or double.

◆ mpack_expect_enum()

size_t mpack_expect_enum ( mpack_reader_t reader,
const char *  strings[],
size_t  count 
)

Expects a string matching one of the strings in the given array, returning its array index.

If the value does not match any of the given strings, mpack_error_type is flagged. Use mpack_expect_enum_optional() if you want to allow other values than the given strings.

If any error occurs or the reader is in an error state, count is returned.

This can be used to quickly parse a string into an enum when the enum values range from 0 to count-1. If the last value in the enum is a special "count" value, it can be passed as the count, and the return value can be cast directly to the enum type.

typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
const char* fruits[] = {"apple", "banana", "orange"};
fruit_t fruit = (fruit_t)mpack_expect_enum(reader, fruits, COUNT);
size_t mpack_expect_enum(mpack_reader_t *reader, const char *strings[], size_t count)
Expects a string matching one of the strings in the given array, returning its array index.

See docs/expect.md for more examples.

The maximum string length is the size of the buffer (strings are read in-place.)

Parameters
readerThe reader
stringsAn array of expected strings of length count
countThe number of strings
Returns
The index of the matched string, or count in case of error

◆ mpack_expect_enum_optional()

size_t mpack_expect_enum_optional ( mpack_reader_t reader,
const char *  strings[],
size_t  count 
)

Expects a string matching one of the strings in the given array returning its array index, or count if no strings match.

If the value is not a string, or it does not match any of the given strings, count is returned and no error is flagged.

If any error occurs or the reader is in an error state, count is returned.

This can be used to quickly parse a string into an enum when the enum values range from 0 to count-1. If the last value in the enum is a special "count" value, it can be passed as the count, and the return value can be cast directly to the enum type.

typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
const char* fruits[] = {"apple", "banana", "orange"};
fruit_t fruit = (fruit_t)mpack_expect_enum_optional(reader, fruits, COUNT);
size_t mpack_expect_enum_optional(mpack_reader_t *reader, const char *strings[], size_t count)
Expects a string matching one of the strings in the given array returning its array index,...

See docs/expect.md for more examples.

The maximum string length is the size of the buffer (strings are read in-place.)

Parameters
readerThe reader
stringsAn array of expected strings of length count
countThe number of strings
Returns
The index of the matched string, or count if it does not match or an error occurs

◆ mpack_expect_false()

void mpack_expect_false ( mpack_reader_t reader)

Reads a boolean, raising mpack_error_type if its value is not false.

◆ mpack_expect_float()

float mpack_expect_float ( mpack_reader_t reader)

Reads a number, returning the value as a float.

The underlying value can be an integer, float or double; the value is converted to a float.

Note
Reading a double or a large integer with this function can incur a loss of precision.
Exceptions
mpack_error_typeif the underlying value is not a float, double or integer.

◆ mpack_expect_float_range()

float mpack_expect_float_range ( mpack_reader_t reader,
float  min_value,
float  max_value 
)

Reads a number, ensuring that it falls within the given range and returning the value as a float.

The underlying value can be an integer, float or double; the value is converted to a float.

Note
Reading a double or a large integer with this function can incur a loss of precision.
Exceptions
mpack_error_typeif the underlying value is not a float, double or integer.

◆ mpack_expect_float_strict()

float mpack_expect_float_strict ( mpack_reader_t reader)

Reads a float.

The underlying value must be a float, not a double or an integer. This ensures no loss of precision can occur.

Exceptions
mpack_error_typeif the underlying value is not a float.

◆ mpack_expect_i16()

int16_t mpack_expect_i16 ( mpack_reader_t reader)

Reads a 16-bit signed integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit signed int.

Returns zero if an error occurs.

◆ mpack_expect_i16_max()

MPACK_INLINE int16_t mpack_expect_i16_max ( mpack_reader_t reader,
int16_t  max_value 
)

Reads a 16-bit signed integer, ensuring that it is at least zero and at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit signed int.

Returns 0 if an error occurs.

◆ mpack_expect_i16_range()

int16_t mpack_expect_i16_range ( mpack_reader_t reader,
int16_t  min_value,
int16_t  max_value 
)

Reads a 16-bit signed integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit signed int.

Returns min_value if an error occurs.

◆ mpack_expect_i32()

int32_t mpack_expect_i32 ( mpack_reader_t reader)

Reads a 32-bit signed integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit signed int.

Returns zero if an error occurs.

◆ mpack_expect_i32_max()

MPACK_INLINE int32_t mpack_expect_i32_max ( mpack_reader_t reader,
int32_t  max_value 
)

Reads a 32-bit signed integer, ensuring that it is at least zero and at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit signed int.

Returns 0 if an error occurs.

◆ mpack_expect_i32_range()

int32_t mpack_expect_i32_range ( mpack_reader_t reader,
int32_t  min_value,
int32_t  max_value 
)

Reads a 32-bit signed integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit signed int.

Returns min_value if an error occurs.

◆ mpack_expect_i64()

int64_t mpack_expect_i64 ( mpack_reader_t reader)

Reads a 64-bit signed integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit signed int.

Returns zero if an error occurs.

◆ mpack_expect_i64_max()

MPACK_INLINE int64_t mpack_expect_i64_max ( mpack_reader_t reader,
int64_t  max_value 
)

Reads a 64-bit signed integer, ensuring that it is at least zero and at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit signed int.

Returns 0 if an error occurs.

◆ mpack_expect_i64_range()

int64_t mpack_expect_i64_range ( mpack_reader_t reader,
int64_t  min_value,
int64_t  max_value 
)

Reads a 64-bit signed integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit signed int.

Returns min_value if an error occurs.

◆ mpack_expect_i8()

int8_t mpack_expect_i8 ( mpack_reader_t reader)

Reads an 8-bit signed integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit signed int.

Returns zero if an error occurs.

◆ mpack_expect_i8_max()

MPACK_INLINE int8_t mpack_expect_i8_max ( mpack_reader_t reader,
int8_t  max_value 
)

Reads an 8-bit signed integer, ensuring that it is at least zero and at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit signed int.

Returns 0 if an error occurs.

◆ mpack_expect_i8_range()

int8_t mpack_expect_i8_range ( mpack_reader_t reader,
int8_t  min_value,
int8_t  max_value 
)

Reads an 8-bit signed integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit signed int.

Returns min_value if an error occurs.

◆ mpack_expect_int()

MPACK_INLINE int mpack_expect_int ( mpack_reader_t reader)

Reads a signed int.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a signed int.

Returns zero if an error occurs.

◆ mpack_expect_int_match()

void mpack_expect_int_match ( mpack_reader_t reader,
int64_t  value 
)

Reads a signed integer, ensuring that it exactly matches the given value.

mpack_error_type is raised if the value is not representable as a signed integer or if it does not exactly match the given value.

◆ mpack_expect_int_max()

MPACK_INLINE int mpack_expect_int_max ( mpack_reader_t reader,
int  max_value 
)

Reads an int, ensuring that it is at least zero and at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a signed int.

Returns 0 if an error occurs.

◆ mpack_expect_int_range()

MPACK_INLINE int mpack_expect_int_range ( mpack_reader_t reader,
int  min_value,
int  max_value 
)

Reads a signed integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a signed int.

Returns min_value if an error occurs.

◆ mpack_expect_key_cstr()

size_t mpack_expect_key_cstr ( mpack_reader_t reader,
const char *  keys[],
bool  found[],
size_t  count 
)

Expects a string map key matching one of the strings in the given key list, marking it as found in the given bool array and returning its index.

This is a helper for switching among string keys in a map. It is typically used with an enum with names matching the strings in the array to define the key indices. It should be called in the expression of a switch() statement. See docs/expect.md for an example.

The found array must be cleared before expecting the first key. If the flag for a given key is already set when found (i.e. the map contains a duplicate key), mpack_error_invalid is flagged.

If the key is unrecognized, count is returned and no error is flagged. If you want an error on unrecognized keys, flag an error in the default case in your switch; otherwise you must call mpack_discard() to discard its content.

The maximum key length is the size of the buffer (keys are read in-place.)

Parameters
readerThe reader
keysAn array of expected string keys of length count
foundAn array of bool flags of length count
countThe number of values in the keys and found arrays
See also
docs/expect.md

◆ mpack_expect_key_uint()

size_t mpack_expect_key_uint ( mpack_reader_t reader,
bool  found[],
size_t  count 
)

Expects an unsigned integer map key between 0 and count-1, marking it as found in the given bool array and returning it.

This is a helper for switching among int keys in a map. It is typically used with an enum to define the key values. It should be called in the expression of a switch() statement. See docs/expect.md for an example.

The found array must be cleared before expecting the first key. If the flag for a given key is already set when found (i.e. the map contains a duplicate key), mpack_error_invalid is flagged.

If the key is not a non-negative integer, or if the key is count or larger, count is returned and no error is flagged. If you want an error on unrecognized keys, flag an error in the default case in your switch; otherwise you must call mpack_discard() to discard its content.

Parameters
readerThe reader
foundAn array of bool flags of length count
countThe number of values in the found array, and one more than the maximum allowed key
See also
docs/expect.md

◆ mpack_expect_map()

uint32_t mpack_expect_map ( mpack_reader_t reader)

Reads the start of a map, returning its element count.

A number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() must be called once all elements have been read.

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.
Warning
This call is dangerous! It does not have a size limit, and it does not have any way of checking whether there is enough data in the message (since the data could be coming from a stream.) When looping through the map's contents, you must check for errors on each iteration of the loop. Otherwise an attacker could craft a message declaring a map of a billion elements which would throw your parsing code into an infinite loop! You should strongly consider using mpack_expect_map_max() with a safe maximum size instead.
Exceptions
mpack_error_typeif the value is not a map.

◆ mpack_expect_map_match()

void mpack_expect_map_match ( mpack_reader_t reader,
uint32_t  count 
)

Reads the start of a map of the exact size given.

A number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() must be called once all elements have been read.

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.
Exceptions
mpack_error_typeif the value is not a map or if its size does not match the given count.

◆ mpack_expect_map_max()

MPACK_INLINE uint32_t mpack_expect_map_max ( mpack_reader_t reader,
uint32_t  max_count 
)

Reads the start of a map with a number of elements at most max_count, returning its element count.

A number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() must be called once all elements have been read.

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.

Zero is returned if an error occurs.

Exceptions
mpack_error_typeif the value is not a map or if its size is greater than max_count.

◆ mpack_expect_map_max_or_nil()

bool mpack_expect_map_max_or_nil ( mpack_reader_t reader,
uint32_t  max_count,
uint32_t *  count 
)

Reads a nil node or the start of a map with a number of elements at most max_count, returning whether a map was read and placing its number of key/value pairs in count.

If a map was read, a number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() should anlso be called once all elements have been read (only if a map was read.)

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON. Consider using mpack_expect_key_cstr() or mpack_expect_key_uint() to switch on the key; see docs/expect.md for examples.
Returns
true if a map was read successfully; false if nil was read or an error occurred.
Exceptions
mpack_error_typeif the value is not a nil or map.

◆ mpack_expect_map_or_nil()

bool mpack_expect_map_or_nil ( mpack_reader_t reader,
uint32_t *  count 
)

Reads a nil node or the start of a map, returning whether a map was read and placing its number of key/value pairs in count.

If a map was read, a number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() should also be called once all elements have been read (only if a map was read.)

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.
Warning
This call is dangerous! It does not have a size limit, and it does not have any way of checking whether there is enough data in the message (since the data could be coming from a stream.) When looping through the map's contents, you must check for errors on each iteration of the loop. Otherwise an attacker could craft a message declaring a map of a billion elements which would throw your parsing code into an infinite loop! You should strongly consider using mpack_expect_map_max_or_nil() with a safe maximum size instead.
Returns
true if a map was read successfully; false if nil was read or an error occurred.
Exceptions
mpack_error_typeif the value is not a nil or map.

◆ mpack_expect_map_range()

uint32_t mpack_expect_map_range ( mpack_reader_t reader,
uint32_t  min_count,
uint32_t  max_count 
)

Reads the start of a map with a number of elements in the given range, returning its element count.

A number of values follow equal to twice the element count of the map, alternating between keys and values. mpack_done_map() must be called once all elements have been read.

Note
Maps in JSON are unordered, so it is recommended not to expect a specific ordering for your map values in case your data is converted to/from JSON.

min_count is returned if an error occurs.

Exceptions
mpack_error_typeif the value is not a map or if its size does not fall within the given range.

◆ mpack_expect_nil()

void mpack_expect_nil ( mpack_reader_t reader)

Reads a nil, raising mpack_error_type if the value is not nil.

◆ mpack_expect_str()

uint32_t mpack_expect_str ( mpack_reader_t reader)

Reads the start of a string, returning its size in bytes.

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_str() must be called once all bytes have been read.

NUL bytes are allowed in the string, and no encoding checks are done.

mpack_error_type is raised if the value is not a string.

◆ mpack_expect_str_buf()

size_t mpack_expect_str_buf ( mpack_reader_t reader,
char *  buf,
size_t  bufsize 
)

Reads a string of at most the given size, writing it into the given buffer and returning its size in bytes.

This does not add a null-terminator! Use mpack_expect_cstr() to add a null-terminator.

NUL bytes are allowed in the string, and no encoding checks are done.

◆ mpack_expect_str_length()

MPACK_INLINE void mpack_expect_str_length ( mpack_reader_t reader,
uint32_t  count 
)

Reads the start of a string, raising an error if its length is not exactly the given number of bytes (not including any null-terminator.)

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_str() must be called once all bytes have been read.

mpack_error_type is raised if the value is not a string or if its length does not match.

◆ mpack_expect_str_match()

void mpack_expect_str_match ( mpack_reader_t reader,
const char *  str,
size_t  length 
)

Reads a string, ensuring it exactly matches the given string.

Remember that maps are unordered in JSON. Don't use this for map keys unless the map has only a single key!

◆ mpack_expect_str_max()

MPACK_INLINE uint32_t mpack_expect_str_max ( mpack_reader_t reader,
uint32_t  maxsize 
)

Reads the start of a string, raising an error if its length is not at most the given number of bytes (not including any null-terminator.)

The bytes follow and must be read separately with mpack_read_bytes() or mpack_read_bytes_inplace(). mpack_done_str() must be called once all bytes have been read.

Exceptions
mpack_error_typeIf the value is not a string.
mpack_error_too_bigIf the string's length in bytes is larger than the given maximum size.

◆ mpack_expect_tag()

void mpack_expect_tag ( mpack_reader_t reader,
mpack_tag_t  tag 
)

Reads a MessagePack object header (an MPack tag), expecting it to exactly match the given tag.

If the type is compound (i.e. is a map, array, string, binary or extension type), additional reads are required to get the contained data, and the corresponding done function must be called when done.

Exceptions
mpack_error_typeif the tag does not match
See also
mpack_read_bytes()
mpack_done_array()
mpack_done_map()
mpack_done_str()
mpack_done_bin()
mpack_done_ext()

◆ mpack_expect_true()

void mpack_expect_true ( mpack_reader_t reader)

Reads a boolean, raising mpack_error_type if its value is not true.

◆ mpack_expect_u16()

uint16_t mpack_expect_u16 ( mpack_reader_t reader)

Reads a 16-bit unsigned integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit unsigned int.

Returns zero if an error occurs.

◆ mpack_expect_u16_max()

MPACK_INLINE uint16_t mpack_expect_u16_max ( mpack_reader_t reader,
uint16_t  max_value 
)

Reads a 16-bit unsigned integer, ensuring that it is at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit unsigned int.

Returns 0 if an error occurs.

◆ mpack_expect_u16_range()

uint16_t mpack_expect_u16_range ( mpack_reader_t reader,
uint16_t  min_value,
uint16_t  max_value 
)

Reads a 16-bit unsigned integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 16-bit unsigned int.

Returns min_value if an error occurs.

◆ mpack_expect_u32()

uint32_t mpack_expect_u32 ( mpack_reader_t reader)

Reads a 32-bit unsigned integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit unsigned int.

Returns zero if an error occurs.

◆ mpack_expect_u32_max()

MPACK_INLINE uint32_t mpack_expect_u32_max ( mpack_reader_t reader,
uint32_t  max_value 
)

Reads a 32-bit unsigned integer, ensuring that it is at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit unsigned int.

Returns 0 if an error occurs.

◆ mpack_expect_u32_range()

uint32_t mpack_expect_u32_range ( mpack_reader_t reader,
uint32_t  min_value,
uint32_t  max_value 
)

Reads a 32-bit unsigned integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 32-bit unsigned int.

Returns min_value if an error occurs.

◆ mpack_expect_u64()

uint64_t mpack_expect_u64 ( mpack_reader_t reader)

Reads a 64-bit unsigned integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit unsigned int.

Returns zero if an error occurs.

◆ mpack_expect_u64_max()

MPACK_INLINE uint64_t mpack_expect_u64_max ( mpack_reader_t reader,
uint64_t  max_value 
)

Reads a 64-bit unsigned integer, ensuring that it is at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit unsigned int.

Returns 0 if an error occurs.

◆ mpack_expect_u64_range()

uint64_t mpack_expect_u64_range ( mpack_reader_t reader,
uint64_t  min_value,
uint64_t  max_value 
)

Reads a 64-bit unsigned integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in a 64-bit unsigned int.

Returns min_value if an error occurs.

◆ mpack_expect_u8()

uint8_t mpack_expect_u8 ( mpack_reader_t reader)

Reads an 8-bit unsigned integer.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit unsigned int.

Returns zero if an error occurs.

◆ mpack_expect_u8_max()

MPACK_INLINE uint8_t mpack_expect_u8_max ( mpack_reader_t reader,
uint8_t  max_value 
)

Reads an 8-bit unsigned integer, ensuring that it is at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit unsigned int.

Returns 0 if an error occurs.

◆ mpack_expect_u8_range()

uint8_t mpack_expect_u8_range ( mpack_reader_t reader,
uint8_t  min_value,
uint8_t  max_value 
)

Reads an 8-bit unsigned integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an 8-bit unsigned int.

Returns min_value if an error occurs.

◆ mpack_expect_uint()

MPACK_INLINE unsigned int mpack_expect_uint ( mpack_reader_t reader)

Reads an unsigned int.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an unsigned int.

Returns zero if an error occurs.

◆ mpack_expect_uint_match()

void mpack_expect_uint_match ( mpack_reader_t reader,
uint64_t  value 
)

Reads an unsigned integer, ensuring that it exactly matches the given value.

mpack_error_type is raised if the value is not representable as an unsigned integer or if it does not exactly match the given value.

◆ mpack_expect_uint_max()

MPACK_INLINE unsigned int mpack_expect_uint_max ( mpack_reader_t reader,
unsigned int  max_value 
)

Reads an unsigned integer, ensuring that it is at most max_value.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an unsigned int.

Returns 0 if an error occurs.

◆ mpack_expect_uint_range()

MPACK_INLINE unsigned int mpack_expect_uint_range ( mpack_reader_t reader,
unsigned int  min_value,
unsigned int  max_value 
)

Reads an unsigned integer, ensuring that it falls within the given range.

The underlying type may be an integer type of any size and signedness, as long as the value can be represented in an unsigned int.

Returns min_value if an error occurs.

◆ mpack_expect_utf8()

size_t mpack_expect_utf8 ( mpack_reader_t reader,
char *  buf,
size_t  bufsize 
)

Reads a string into the given buffer, ensuring it is a valid UTF-8 string and returning its size in bytes.

This does not add a null-terminator! Use mpack_expect_utf8_cstr() to add a null-terminator.

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed.

NUL bytes are allowed in the string (as they are in UTF-8.)

Raises mpack_error_too_big if there is not enough room for the string. Raises mpack_error_type if the value is not a string or is not a valid UTF-8 string.

◆ mpack_expect_utf8_cstr()

void mpack_expect_utf8_cstr ( mpack_reader_t reader,
char *  buf,
size_t  size 
)

Reads a string into the given buffer, ensures it is a valid UTF-8 string without NUL characters, and adds a null-terminator at the end.

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since it cannot be represented in a null-terminated string.

Raises mpack_error_too_big if there is not enough room for the string and null-terminator. Raises mpack_error_type if the value is not a string or is not a valid UTF-8 string.

◆ mpack_expect_utf8_cstr_alloc()

char * mpack_expect_utf8_cstr_alloc ( mpack_reader_t reader,
size_t  maxsize 
)

Reads a string with the given total maximum size (including space for a null-terminator), allocates storage for it, ensures it is valid UTF-8 with no null-bytes, and adds a null-terminator at the end.

You assume ownership of the returned pointer if reading succeeds.

The length in bytes of the string, not including the null-terminator, will be written to size.

This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since it cannot be represented in a null-terminated string.

The allocated string must be freed with MPACK_FREE() (or simply free() if MPack's allocator hasn't been customized.) if you want a null-terminator.

Exceptions
mpack_error_too_bigIf the string plus null-terminator is larger than the given maxsize.
mpack_error_typeIf the value is not a string or contains invalid UTF-8 or a null byte.