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.

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.

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...

unsigned int	mpack_expect_uint (mpack_reader_t *reader)
	Reads an unsigned int. More...

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...

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...

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...

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...

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...

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...

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...

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...

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...

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...

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...

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...

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...

Extension Functions
mpack_timestamp_t	mpack_expect_timestamp (mpack_reader_t *reader)
	Reads a timestamp. More...

int64_t	mpack_expect_timestamp_truncate (mpack_reader_t *reader)
	Reads a timestamp in seconds, truncating the nanoseconds (if any). More...

uint32_t	mpack_expect_ext (mpack_reader_t reader, int8_t type)
	Reads the start of an extension blob, returning its size in bytes and placing the type into `type`. More...

uint32_t	mpack_expect_ext_max (mpack_reader_t reader, int8_t type, uint32_t maxsize)
	Reads the start of an extension blob, raising an error if its length is not at most the given number of bytes and placing the type into `type`. More...

void	mpack_expect_ext_size (mpack_reader_t reader, int8_t type, uint32_t count)
	Reads the start of an extension blob, raising an error if its length is not exactly the given number of bytes and placing the type into `type`. More...

size_t	mpack_expect_ext_buf (mpack_reader_t reader, int8_t type, char *buf, size_t size)
	Reads an extension blob into the given buffer, returning its size in bytes and placing the type into `type`. More...

char *	mpack_expect_ext_alloc (mpack_reader_t reader, int8_t type, size_t maxsize, size_t *size)
	Reads an extension blob with the given total maximum size, allocating storage for it, and placing the type into `type`. 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...

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...

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...

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...

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...

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...

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...

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...

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_type if 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_type if 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_type if the value is not an array or if its size does not match the given count.

◆ mpack_expect_array_max()

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_type if 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_type if 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_type if 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_type if 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()

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()

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_type if 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_type if 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_big	If the string plus null-terminator is larger than the given maxsize.
mpack_error_type	If the value is not a string or contains a null byte.

◆ mpack_expect_cstr_match()

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_type if 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_type if 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_type if 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);

See Using the Expect API for more examples.

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

Parameters

reader	The reader
strings	An array of expected strings of length count
count	The 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);

See Using the Expect API for more examples.

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

Parameters

reader	The reader
strings	An array of expected strings of length count
count	The number of strings

Returns: The index of the matched string, or count if it does not match or an error occurs

◆ mpack_expect_ext()

uint32_t mpack_expect_ext	(	mpack_reader_t *	reader,
		int8_t *	type
	)

Reads the start of an extension blob, returning its size in bytes and placing the type into type.

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

type will be a user-defined type in the range [0,127] or a reserved type in the range [-128,-2].

mpack_error_type is raised if the value is not an extension blob. The type value is zero if an error occurs.

Note: This cannot be used to match a timestamp. mpack_error_type will be flagged if the value is a timestamp. Use mpack_expect_timestamp() or mpack_expect_timestamp_truncate() instead.; This requires MPACK_EXTENSIONS.

Warning: Be careful when using reserved types. They may no longer be ext types in the future, and previously valid data containing reserved types may become invalid in the future.

◆ mpack_expect_ext_alloc()

char * mpack_expect_ext_alloc	(	mpack_reader_t *	reader,
		int8_t *	type,
		size_t	maxsize,
		size_t *	size
	)

Reads an extension blob with the given total maximum size, allocating storage for it, and placing the type into type.

mpack_error_type is raised if the value is not an extension blob or if its length does not match. The type value is zero if an error is raised.

type will be a user-defined type in the range [0,127] or a reserved type in the range [-128,-2].

Note: This cannot be used to match a timestamp. mpack_error_type will be flagged if the value is a timestamp. Use mpack_expect_timestamp() or mpack_expect_timestamp_truncate() instead.

Warning: Be careful when using reserved types. They may no longer be ext types in the future, and previously valid data containing reserved types may become invalid in the future.

Note: This requires MPACK_EXTENSIONS and MPACK_MALLOC.

See also: mpack_expect_ext()

◆ mpack_expect_ext_buf()

size_t mpack_expect_ext_buf	(	mpack_reader_t *	reader,
		int8_t *	type,
		char *	buf,
		size_t	size
	)

Reads an extension blob into the given buffer, returning its size in bytes and placing the type into type.

mpack_error_type is raised if the value is not an extension blob or if its length does not match. The type value is zero if an error is raised.

type will be a user-defined type in the range [0,127] or a reserved type in the range [-128,-2].

Note: This cannot be used to match a timestamp. mpack_error_type will be flagged if the value is a timestamp. Use mpack_expect_timestamp() or mpack_expect_timestamp_truncate() instead.

Warning: Be careful when using reserved types. They may no longer be ext types in the future, and previously valid data containing reserved types may become invalid in the future.

Note: This requires MPACK_EXTENSIONS.

See also: mpack_expect_ext()

◆ mpack_expect_ext_max()

uint32_t mpack_expect_ext_max	(	mpack_reader_t *	reader,
		int8_t *	type,
		uint32_t	maxsize
	)

Reads the start of an extension blob, raising an error if its length is not at most the given number of bytes and placing the type into type.

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

mpack_error_type is raised if the value is not an extension blob or if its length does not match. The type value is zero if an error is raised.

type will be a user-defined type in the range [0,127] or a reserved type in the range [-128,-2].

Note: This cannot be used to match a timestamp. mpack_error_type will be flagged if the value is a timestamp. Use mpack_expect_timestamp() or mpack_expect_timestamp_truncate() instead.; This requires MPACK_EXTENSIONS.

Warning: Be careful when using reserved types. They may no longer be ext types in the future, and previously valid data containing reserved types may become invalid in the future.

See also: mpack_expect_ext()

◆ mpack_expect_ext_size()

void mpack_expect_ext_size	(	mpack_reader_t *	reader,
		int8_t *	type,
		uint32_t	count
	)

Reads the start of an extension blob, raising an error if its length is not exactly the given number of bytes and placing the type into type.

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

mpack_error_type is raised if the value is not an extension blob or if its length does not match. The type value is zero if an error is raised.

type will be a user-defined type in the range [0,127] or a reserved type in the range [-128,-2].

Note: This cannot be used to match a timestamp. mpack_error_type will be flagged if the value is a timestamp. Use mpack_expect_timestamp() or mpack_expect_timestamp_truncate() instead.; This requires MPACK_EXTENSIONS.

Warning: Be careful when using reserved types. They may no longer be ext types in the future, and previously valid data containing reserved types may become invalid in the future.

See also: mpack_expect_ext()

◆ 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_type if 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_type if 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_type if 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()

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()

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()

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()

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()

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()

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()

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 Using the Expect API 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

reader	The reader
keys	An array of expected string keys of length count
found	An array of bool flags of length count
count	The number of values in the keys and found arrays

See also: Using the Expect API

◆ 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 Using the Expect API 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

reader	The reader
found	An array of bool flags of length count
count	The number of values in the found array, and one more than the maximum allowed key

See also: Using the Expect API

◆ 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_type if 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_type if the value is not a map or if its size does not match the given count.

◆ mpack_expect_map_max()

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_type if 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 Using the Expect API for examples.

Returns: true if a map was read successfully; false if nil was read or an error occurred.

Exceptions

mpack_error_type if 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_type if 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_type if 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()

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()

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_type	If the value is not a string.
mpack_error_too_big	If 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_type if 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_timestamp()

mpack_timestamp_t mpack_expect_timestamp ( mpack_reader_t * reader )

Reads a timestamp.

Note: This requires MPACK_EXTENSIONS.

◆ mpack_expect_timestamp_truncate()

int64_t mpack_expect_timestamp_truncate ( mpack_reader_t * reader )

Reads a timestamp in seconds, truncating the nanoseconds (if any).

Note: This requires MPACK_EXTENSIONS.

◆ 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()

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()

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()

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()

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()

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()

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()

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_big	If the string plus null-terminator is larger than the given maxsize.
mpack_error_type	If the value is not a string or contains invalid UTF-8 or a null byte.

Description

Basic Number Functions

Ranged Number Functions

Matching Number Functions

Other Basic Types

Extension Functions

Compound Types

String Functions

Binary Data

Special Functions

Macro Definition Documentation

◆ mpack_expect_array_alloc

◆ mpack_expect_array_or_nil_alloc

Function Documentation

◆ mpack_expect_array()

◆ mpack_expect_array_match()

◆ mpack_expect_array_max()

◆ mpack_expect_array_max_or_nil()

◆ mpack_expect_array_or_nil()

◆ mpack_expect_array_range()

◆ mpack_expect_bin()

◆ mpack_expect_bin_alloc()

◆ mpack_expect_bin_buf()

◆ mpack_expect_bin_max()

◆ mpack_expect_bin_size()

◆ mpack_expect_bin_size_buf()

◆ mpack_expect_bool()

◆ mpack_expect_cstr()

◆ mpack_expect_cstr_alloc()

◆ mpack_expect_cstr_match()

◆ mpack_expect_double()

◆ mpack_expect_double_range()

◆ mpack_expect_double_strict()

◆ mpack_expect_enum()

◆ mpack_expect_enum_optional()

◆ mpack_expect_ext()

◆ mpack_expect_ext_alloc()

◆ mpack_expect_ext_buf()

◆ mpack_expect_ext_max()

◆ mpack_expect_ext_size()

◆ mpack_expect_false()

◆ mpack_expect_float()

◆ mpack_expect_float_range()

◆ mpack_expect_float_strict()

◆ mpack_expect_i16()

◆ mpack_expect_i16_max()

◆ mpack_expect_i16_range()

◆ mpack_expect_i32()

◆ mpack_expect_i32_max()

◆ mpack_expect_i32_range()

◆ mpack_expect_i64()

◆ mpack_expect_i64_max()

◆ mpack_expect_i64_range()

◆ mpack_expect_i8()

◆ mpack_expect_i8_max()

◆ mpack_expect_i8_range()

◆ mpack_expect_int()

◆ mpack_expect_int_match()

◆ mpack_expect_int_max()

◆ mpack_expect_int_range()

◆ mpack_expect_key_cstr()

◆ mpack_expect_key_uint()

◆ mpack_expect_map()

◆ mpack_expect_map_match()

◆ mpack_expect_map_max()

◆ mpack_expect_map_max_or_nil()

◆ mpack_expect_map_or_nil()

◆ mpack_expect_map_range()

◆ mpack_expect_nil()

◆ mpack_expect_str()

◆ mpack_expect_str_buf()

◆ mpack_expect_str_length()

◆ mpack_expect_str_match()

◆ mpack_expect_str_max()

◆ mpack_expect_tag()

◆ mpack_expect_timestamp()

◆ mpack_expect_timestamp_truncate()

◆ mpack_expect_true()

◆ mpack_expect_u16()

◆ mpack_expect_u16_max()