Tags and Common Elements

Description

Contains types, constants and functions shared by both the encoding and decoding portions of MPack.

Data Structures
struct	mpack_timestamp_t
	A timestamp. More...

Macros
#define	MPACK_LIBRARY_STRING
	A string describing MPack, containing the library name, version and debug mode. More...
#define	MPACK_TIMESTAMP_NANOSECONDS_MAX   999999999
	The maximum value of nanoseconds for a timestamp. More...
#define	MPACK_VERSION
	A number containing the version number of MPack for comparison purposes. More...
#define	MPACK_VERSION_AT_LEAST(major, minor, patch)    (MPACK_VERSION >= (((major) * 10000) + ((minor) * 100) + (patch)))
	A macro to test for a minimum version of MPack. More...
#define	MPACK_VERSION_MAJOR   1
	The major version number of MPack. More...
#define	MPACK_VERSION_MINOR   1
	The minor version number of MPack. More...
#define	MPACK_VERSION_PATCH   1
	The patch version number of MPack. More...
#define	MPACK_VERSION_STRING
	A string containing the MPack version. More...

Typedefs
typedef struct mpack_tag_t	mpack_tag_t
	An MPack tag is a MessagePack object header. More...

Enumerations
enum	mpack_error_t {   mpack_ok = 0 , mpack_error_io = 2 , mpack_error_invalid , mpack_error_unsupported ,   mpack_error_type , mpack_error_too_big , mpack_error_memory , mpack_error_bug ,   mpack_error_data , mpack_error_eof }
	Error states for MPack objects. More...
enum	mpack_type_t {   mpack_type_missing = 0 , mpack_type_nil , mpack_type_bool , mpack_type_int ,   mpack_type_uint , mpack_type_float , mpack_type_double , mpack_type_str ,   mpack_type_bin , mpack_type_array , mpack_type_map , mpack_type_ext }
	Defines the type of a MessagePack tag. More...
enum	mpack_version_t { mpack_version_v4 = 4 , mpack_version_v5 = 5 , mpack_version_current = mpack_version_v5 }
	Versions of the MessagePack format. More...

Functions
const char *	mpack_error_to_string (mpack_error_t error)
	Converts an MPack error to a string. More...
const char *	mpack_type_to_string (mpack_type_t type)
	Converts an MPack type to a string. More...

Tag Generators
mpack_tag_t	mpack_tag_make_nil (void)
	Generates a nil tag. More...
mpack_tag_t	mpack_tag_make_bool (bool value)
	Generates a bool tag. More...
mpack_tag_t	mpack_tag_make_true (void)
	Generates a bool tag with value true. More...
mpack_tag_t	mpack_tag_make_false (void)
	Generates a bool tag with value false. More...
mpack_tag_t	mpack_tag_make_int (int64_t value)
	Generates a signed int tag. More...
mpack_tag_t	mpack_tag_make_uint (uint64_t value)
	Generates an unsigned int tag. More...
mpack_tag_t	mpack_tag_make_float (float value)
	Generates a float tag. More...
mpack_tag_t	mpack_tag_make_double (double value)
	Generates a double tag. More...
mpack_tag_t	mpack_tag_make_array (uint32_t count)
	Generates an array tag. More...
mpack_tag_t	mpack_tag_make_map (uint32_t count)
	Generates a map tag. More...
mpack_tag_t	mpack_tag_make_str (uint32_t length)
	Generates a str tag. More...
mpack_tag_t	mpack_tag_make_bin (uint32_t length)
	Generates a bin tag. More...
mpack_tag_t	mpack_tag_make_ext (int8_t exttype, uint32_t length)
	Generates an ext tag. More...
#define	MPACK_TAG_ZERO   {(mpack_type_t)0, 0, {0}}
	An mpack_tag_t initializer that zeroes the given tag. More...

Tag Querying Functions
mpack_type_t	mpack_tag_type (mpack_tag_t *tag)
	Gets the type of a tag. More...
bool	mpack_tag_bool_value (mpack_tag_t *tag)
	Gets the boolean value of a bool-type tag. More...
int64_t	mpack_tag_int_value (mpack_tag_t *tag)
	Gets the signed integer value of an int-type tag. More...
uint64_t	mpack_tag_uint_value (mpack_tag_t *tag)
	Gets the unsigned integer value of a uint-type tag. More...
float	mpack_tag_float_value (mpack_tag_t *tag)
	Gets the float value of a float-type tag. More...
double	mpack_tag_double_value (mpack_tag_t *tag)
	Gets the double value of a double-type tag. More...
uint32_t	mpack_tag_array_count (mpack_tag_t *tag)
	Gets the number of elements in an array tag. More...
uint32_t	mpack_tag_map_count (mpack_tag_t *tag)
	Gets the number of key-value pairs in a map tag. More...
uint32_t	mpack_tag_str_length (mpack_tag_t *tag)
	Gets the length in bytes of a str-type tag. More...
uint32_t	mpack_tag_bin_length (mpack_tag_t *tag)
	Gets the length in bytes of a bin-type tag. More...
uint32_t	mpack_tag_ext_length (mpack_tag_t *tag)
	Gets the length in bytes of an ext-type tag. More...
int8_t	mpack_tag_ext_exttype (mpack_tag_t *tag)
	Gets the extension type (exttype) of an ext-type tag. More...
uint32_t	mpack_tag_bytes (mpack_tag_t *tag)
	Gets the length in bytes of a str-, bin- or ext-type tag. More...

Other tag functions
int	mpack_tag_cmp (mpack_tag_t left, mpack_tag_t right)
	Compares two tags with an arbitrary fixed ordering. More...
bool	mpack_tag_equal (mpack_tag_t left, mpack_tag_t right)
	Compares two tags for equality. More...
void	mpack_tag_debug_pseudo_json (mpack_tag_t tag, char *buffer, size_t buffer_size, const char *prefix, size_t prefix_size)
	Generates a json-like debug description of the given tag into the given buffer. More...
void	mpack_tag_debug_describe (mpack_tag_t tag, char *buffer, size_t buffer_size)
	Generates a debug string description of the given tag into the given buffer. More...
#define	MPACK_EXTTYPE_TIMESTAMP   ((int8_t)(-1))
	The extension type for a timestamp. More...

Deprecated Tag Generators
mpack_tag_t	mpack_tag_nil (void)
mpack_tag_t	mpack_tag_bool (bool value)
mpack_tag_t	mpack_tag_true (void)
mpack_tag_t	mpack_tag_false (void)
mpack_tag_t	mpack_tag_int (int64_t value)
mpack_tag_t	mpack_tag_uint (uint64_t value)
mpack_tag_t	mpack_tag_float (float value)
mpack_tag_t	mpack_tag_double (double value)
mpack_tag_t	mpack_tag_array (int32_t count)
mpack_tag_t	mpack_tag_map (int32_t count)
mpack_tag_t	mpack_tag_str (int32_t length)
mpack_tag_t	mpack_tag_bin (int32_t length)
mpack_tag_t	mpack_tag_ext (int8_t exttype, int32_t length)

---

Data Structure Documentation

mpack_timestamp_t

struct mpack_timestamp_t

A timestamp.

Note

This requires MPACK_EXTENSIONS.

Data Fields
uint32_t	nanoseconds
int64_t	seconds

Macro Definition Documentation

MPACK_EXTTYPE_TIMESTAMP

#define MPACK_EXTTYPE_TIMESTAMP   ((int8_t)(-1))

The extension type for a timestamp.

Note

This requires MPACK_EXTENSIONS.

MPACK_LIBRARY_STRING

#define MPACK_LIBRARY_STRING

A string describing MPack, containing the library name, version and debug mode.

MPACK_TAG_ZERO

#define MPACK_TAG_ZERO   {(mpack_type_t)0, 0, {0}}

An mpack_tag_t initializer that zeroes the given tag.

Warning

This does not make the tag nil! The tag's type is invalid when initialized this way. Use mpack_tag_make_nil() to generate a nil tag.

MPACK_TIMESTAMP_NANOSECONDS_MAX

#define MPACK_TIMESTAMP_NANOSECONDS_MAX   999999999

The maximum value of nanoseconds for a timestamp.

Note

This requires MPACK_EXTENSIONS.

MPACK_VERSION

#define MPACK_VERSION

Value:

        ((MPACK_VERSION_MAJOR * 10000) + \
        (MPACK_VERSION_MINOR * 100) + MPACK_VERSION_PATCH)

A number containing the version number of MPack for comparison purposes.

MPACK_VERSION_AT_LEAST

#define MPACK_VERSION_AT_LEAST	(		major,
			minor,
			patch
	)		(MPACK_VERSION >= (((major) * 10000) + ((minor) * 100) + (patch)))

A macro to test for a minimum version of MPack.

MPACK_VERSION_MAJOR

#define MPACK_VERSION_MAJOR   1

The major version number of MPack.

MPACK_VERSION_MINOR

#define MPACK_VERSION_MINOR   1

The minor version number of MPack.

MPACK_VERSION_PATCH

#define MPACK_VERSION_PATCH   1

The patch version number of MPack.

MPACK_VERSION_STRING

#define MPACK_VERSION_STRING

A string containing the MPack version.

Typedef Documentation

mpack_tag_t

typedef struct mpack_tag_t mpack_tag_t

An MPack tag is a MessagePack object header.

It is a variant type representing any kind of object, and includes the length of compound types (e.g. map, array, string) or the value of non-compound types (e.g. boolean, integer, float.)

If the type is compound (str, bin, ext, array or map), the contained elements or bytes are stored separately.

This structure is opaque; its fields should not be accessed outside of MPack.

Enumeration Type Documentation

mpack_error_t

enum mpack_error_t

Error states for MPack objects.

When a reader, writer, or tree is in an error state, all subsequent calls are ignored and their return values are nil/zero. You should check whether the source is in an error state before using such values.

Enumerator
mpack_ok	No error.
mpack_error_io	The reader or writer failed to fill or flush, or some other file or socket error occurred.
mpack_error_invalid	The data read is not valid MessagePack.
mpack_error_unsupported	The data read is not supported by this configuration of MPack. (See MPACK_EXTENSIONS.)
mpack_error_type	The type or value range did not match what was expected by the caller.
mpack_error_too_big	A read or write was bigger than the maximum size allowed for that operation.
mpack_error_memory	An allocation failure occurred.
mpack_error_bug	The MPack API was used incorrectly. (This will always assert in debug mode.)
mpack_error_data	The contained data is not valid.
mpack_error_eof	The reader failed to read because of file or socket EOF.

mpack_type_t

enum mpack_type_t

Defines the type of a MessagePack tag.

Note that extension types, both user defined and built-in, are represented in tags as mpack_type_ext. The value for an extension type is stored separately.

Enumerator
mpack_type_missing	Special type indicating a missing optional value.
mpack_type_nil	A null value.
mpack_type_bool	A boolean (true or false.)
mpack_type_int	A 64-bit signed integer.
mpack_type_uint	A 64-bit unsigned integer.
mpack_type_float	A 32-bit IEEE 754 floating point number.
mpack_type_double	A 64-bit IEEE 754 floating point number.
mpack_type_str	A string.
mpack_type_bin	A chunk of binary data.
mpack_type_array	An array of MessagePack objects.
mpack_type_map	An ordered map of key/value pairs of MessagePack objects.
mpack_type_ext	A typed MessagePack extension object containing a chunk of binary data. Note This requires MPACK_EXTENSIONS.

mpack_version_t

enum mpack_version_t

Versions of the MessagePack format.

A reader, writer, or tree can be configured to serialize in an older version of the MessagePack spec. This is necessary to interface with older MessagePack libraries that do not support new MessagePack features.

Note

This requires MPACK_COMPATIBILITY.

Enumerator
mpack_version_v4	Version 1.0/v4, supporting only the raw type without str8.
mpack_version_v5	Version 2.0/v5, supporting the str8, bin and ext types.
mpack_version_current	The most recent supported version of MessagePack. This is the default.

Function Documentation

mpack_error_to_string()

const char * mpack_error_to_string

(

mpack_error_t

error

)

Converts an MPack error to a string.

This function returns an empty string when MPACK_DEBUG is not set.

mpack_tag_array()

mpack_tag_t mpack_tag_array

(

int32_t

count

)

Deprecated:

Renamed to mpack_tag_make_array().

mpack_tag_array_count()

uint32_t mpack_tag_array_count

(

mpack_tag_t *

tag

)

Gets the number of elements in an array tag.

This asserts that the type in the tag is mpack_type_array. (No check is performed if MPACK_DEBUG is not set.)

See also

mpack_type_array

mpack_tag_bin()

mpack_tag_t mpack_tag_bin

(

int32_t

length

)

Deprecated:

Renamed to mpack_tag_make_bin().

mpack_tag_bin_length()

uint32_t mpack_tag_bin_length

(

mpack_tag_t *

tag

)

Gets the length in bytes of a bin-type tag.

This asserts that the type in the tag is mpack_type_bin. (No check is performed if MPACK_DEBUG is not set.)

See also

mpack_type_bin

mpack_tag_bool()

mpack_tag_t mpack_tag_bool

(

bool

value

)

Deprecated:

Renamed to mpack_tag_make_bool().

mpack_tag_bool_value()

bool mpack_tag_bool_value

(

mpack_tag_t *

tag

)

Gets the boolean value of a bool-type tag.

The tag must be of type mpack_type_bool.

This asserts that the type in the tag is mpack_type_bool. (No check is performed if MPACK_DEBUG is not set.)

mpack_tag_bytes()

uint32_t mpack_tag_bytes

(

mpack_tag_t *

tag

)

Gets the length in bytes of a str-, bin- or ext-type tag.

This asserts that the type in the tag is mpack_type_str, mpack_type_bin or mpack_type_ext. (No check is performed if MPACK_DEBUG is not set.)

See also

mpack_type_str

mpack_type_bin

mpack_type_ext

mpack_tag_cmp()

int mpack_tag_cmp	(	mpack_tag_t	left,
		mpack_tag_t	right
	)

Compares two tags with an arbitrary fixed ordering.

Returns 0 if the tags are equal, a negative integer if left comes before right, or a positive integer otherwise.

Warning

The ordering is not guaranteed to be preserved across MPack versions; do not rely on it in persistent data.

Floating point numbers are compared bit-for-bit, not using the language's operator==. This means that NaNs with matching representation will compare equal. This behaviour is up for debate; see comments in the definition of mpack_tag_cmp().

See mpack_tag_equal() for more information on when tags are considered equal.

mpack_tag_debug_describe()

void mpack_tag_debug_describe	(	mpack_tag_t	tag,
		char *	buffer,
		size_t	buffer_size
	)

Generates a debug string description of the given tag into the given buffer.

This is only available in debug mode, and only if stdio is available (since it uses snprintf().) It's strictly for debugging purposes.

mpack_tag_debug_pseudo_json()

void mpack_tag_debug_pseudo_json	(	mpack_tag_t	tag,
		char *	buffer,
		size_t	buffer_size,
		const char *	prefix,
		size_t	prefix_size
	)

Generates a json-like debug description of the given tag into the given buffer.

This is only available in debug mode, and only if stdio is available (since it uses snprintf().) It's strictly for debugging purposes.

The prefix is used to print the first few hexadecimal bytes of a bin or ext type. Pass NULL if not a bin or ext.

mpack_tag_double()

mpack_tag_t mpack_tag_double

(

double

value

)

Deprecated:

Renamed to mpack_tag_make_double().

mpack_tag_double_value()

double mpack_tag_double_value

(

mpack_tag_t *

tag

)

Gets the double value of a double-type tag.

This asserts that the type in the tag is mpack_type_double. (No check is performed if MPACK_DEBUG is not set.)

Warning

This does not convert between float and double tags! This can only be used if the type is mpack_type_double.

See also

mpack_type_double

mpack_tag_equal()

bool mpack_tag_equal	(	mpack_tag_t	left,
		mpack_tag_t	right
	)

Compares two tags for equality.

Tags are considered equal if the types are compatible and the values (for non-compound types) are equal.

The field width of variable-width fields is ignored (and in fact is not stored in a tag), and positive numbers in signed integers are considered equal to their unsigned counterparts. So for example the value 1 stored as a positive fixint is equal to the value 1 stored in a 64-bit unsigned integer field.

The "extension type" of an extension object is considered part of the value and must match exactly.

Warning

Floating point numbers are compared bit-for-bit, not using the language's operator==. This means that NaNs with matching representation will compare equal. This behaviour is up for debate; see comments in the definition of mpack_tag_cmp().

mpack_tag_ext()

mpack_tag_t mpack_tag_ext	(	int8_t	exttype,
		int32_t	length
	)

Deprecated:

Renamed to mpack_tag_make_ext().

mpack_tag_ext_exttype()

int8_t mpack_tag_ext_exttype

(

mpack_tag_t *

tag

)

Gets the extension type (exttype) of an ext-type tag.

This asserts that the type in the tag is mpack_type_ext. (No check is performed if MPACK_DEBUG is not set.)

Note

This requires MPACK_EXTENSIONS.

See also

mpack_type_ext

mpack_tag_ext_length()

uint32_t mpack_tag_ext_length

(

mpack_tag_t *

tag

)

Gets the length in bytes of an ext-type tag.

This asserts that the type in the tag is mpack_type_ext. (No check is performed if MPACK_DEBUG is not set.)

Note

This requires MPACK_EXTENSIONS.

See also

mpack_type_ext

mpack_tag_false()

mpack_tag_t mpack_tag_false

(

void

)

Deprecated:

Renamed to mpack_tag_make_false().

mpack_tag_float()

mpack_tag_t mpack_tag_float

(

float

value

)

Deprecated:

Renamed to mpack_tag_make_float().

mpack_tag_float_value()

float mpack_tag_float_value

(

mpack_tag_t *

tag

)

Gets the float value of a float-type tag.

This asserts that the type in the tag is mpack_type_float. (No check is performed if MPACK_DEBUG is not set.)

Warning

This does not convert between float and double tags! This can only be used if the type is mpack_type_float.

See also

mpack_type_float

mpack_tag_int()

mpack_tag_t mpack_tag_int

(

int64_t

value

)

Deprecated:

Renamed to mpack_tag_make_int().

mpack_tag_int_value()

int64_t mpack_tag_int_value

(

mpack_tag_t *

tag

)

Gets the signed integer value of an int-type tag.

This asserts that the type in the tag is mpack_type_int. (No check is performed if MPACK_DEBUG is not set.)

Warning

This does not convert between signed and unsigned tags! A positive integer may be stored in a tag as either mpack_type_int or mpack_type_uint. You must check the type first; this can only be used if the type is mpack_type_int.

See also

mpack_type_int

mpack_tag_make_array()

mpack_tag_t mpack_tag_make_array

(

uint32_t

count

)

Generates an array tag.

mpack_tag_make_bin()

mpack_tag_t mpack_tag_make_bin

(

uint32_t

length

)

Generates a bin tag.

mpack_tag_make_bool()

mpack_tag_t mpack_tag_make_bool

(

bool

value

)

Generates a bool tag.

mpack_tag_make_double()

mpack_tag_t mpack_tag_make_double

(

double

value

)

Generates a double tag.

mpack_tag_make_ext()

mpack_tag_t mpack_tag_make_ext	(	int8_t	exttype,
		uint32_t	length
	)

Generates an ext tag.

Note

This requires MPACK_EXTENSIONS.

mpack_tag_make_false()

mpack_tag_t mpack_tag_make_false

(

void

)

Generates a bool tag with value false.

mpack_tag_make_float()

mpack_tag_t mpack_tag_make_float

(

float

value

)

Generates a float tag.

mpack_tag_make_int()

mpack_tag_t mpack_tag_make_int

(

int64_t

value

)

Generates a signed int tag.

mpack_tag_make_map()

mpack_tag_t mpack_tag_make_map

(

uint32_t

count

)

Generates a map tag.

mpack_tag_make_nil()

mpack_tag_t mpack_tag_make_nil

(

void

)

Generates a nil tag.

mpack_tag_make_str()

mpack_tag_t mpack_tag_make_str

(

uint32_t

length

)

Generates a str tag.

mpack_tag_make_true()

mpack_tag_t mpack_tag_make_true

(

void

)

Generates a bool tag with value true.

mpack_tag_make_uint()

mpack_tag_t mpack_tag_make_uint

(

uint64_t

value

)

Generates an unsigned int tag.

mpack_tag_map()

mpack_tag_t mpack_tag_map

(

int32_t

count

)

Deprecated:

Renamed to mpack_tag_make_map().

mpack_tag_map_count()

uint32_t mpack_tag_map_count

(

mpack_tag_t *

tag

)

Gets the number of key-value pairs in a map tag.

This asserts that the type in the tag is mpack_type_map. (No check is performed if MPACK_DEBUG is not set.)

See also

mpack_type_map

mpack_tag_nil()

mpack_tag_t mpack_tag_nil

(

void

)

Deprecated:

Renamed to mpack_tag_make_nil().

mpack_tag_str()

mpack_tag_t mpack_tag_str

(

int32_t

length

)

Deprecated:

Renamed to mpack_tag_make_str().

mpack_tag_str_length()

uint32_t mpack_tag_str_length

(

mpack_tag_t *

tag

)

Gets the length in bytes of a str-type tag.

This asserts that the type in the tag is mpack_type_str. (No check is performed if MPACK_DEBUG is not set.)

See also

mpack_type_str

mpack_tag_true()

mpack_tag_t mpack_tag_true

(

void

)

Deprecated:

Renamed to mpack_tag_make_true().

mpack_tag_type()

mpack_type_t mpack_tag_type

(

mpack_tag_t *

tag

)

Gets the type of a tag.

mpack_tag_uint()

mpack_tag_t mpack_tag_uint

(

uint64_t

value

)

Deprecated:

Renamed to mpack_tag_make_uint().

mpack_tag_uint_value()

uint64_t mpack_tag_uint_value

(

mpack_tag_t *

tag

)

Gets the unsigned integer value of a uint-type tag.

This asserts that the type in the tag is mpack_type_uint. (No check is performed if MPACK_DEBUG is not set.)

Warning

This does not convert between signed and unsigned tags! A positive integer may be stored in a tag as either mpack_type_int or mpack_type_uint. You must check the type first; this can only be used if the type is mpack_type_uint.

See also

mpack_type_uint

mpack_type_to_string()

const char * mpack_type_to_string

(

mpack_type_t

type

)

Converts an MPack type to a string.

This function returns an empty string when MPACK_DEBUG is not set.