Common Elements

Description

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

Data Structures
struct	mpack_tag_t
	An MPack tag is a MessagePack object header. More...
union	mpack_tag_t.v
	The value for non-compound types. More...

Macros
#define	MPACK_LIBRARY_STRING
	A string describing MPack, containing the library name, version and debug mode. 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   0
	The major version number of MPack. More...
#define	MPACK_VERSION_MINOR   8
	The minor version number of MPack. More...
#define	MPACK_VERSION_PATCH   2
	The patch version number of MPack. More...
#define	MPACK_VERSION_STRING
	A string containing the MPack version. More...

Enumerations
enum	mpack_error_t {   mpack_ok = 0, mpack_error_io = 2, mpack_error_invalid, mpack_error_type,   mpack_error_too_big, mpack_error_memory, mpack_error_bug, mpack_error_data }
	Error states for MPack objects. More...
enum	mpack_type_t {   mpack_type_nil = 1, mpack_type_bool, mpack_type_float, mpack_type_double,   mpack_type_int, mpack_type_uint, mpack_type_str, mpack_type_bin,   mpack_type_ext, mpack_type_array, mpack_type_map }
	Defines the type of a MessagePack tag. More...

Functions
const char *	mpack_error_to_string (mpack_error_t error)
	Converts an MPack error to a string. More...
mpack_tag_t	mpack_tag_array (int32_t count)
	Generates an array tag. More...
mpack_tag_t	mpack_tag_bin (int32_t length)
	Generates a bin tag. More...
mpack_tag_t	mpack_tag_bool (bool value)
	Generates a bool tag. More...
int	mpack_tag_cmp (mpack_tag_t left, mpack_tag_t right)
	Compares two tags with an arbitrary fixed ordering. More...
mpack_tag_t	mpack_tag_double (double value)
	Generates a double tag. More...
bool	mpack_tag_equal (mpack_tag_t left, mpack_tag_t right)
	Compares two tags for equality. More...
mpack_tag_t	mpack_tag_ext (int8_t exttype, int32_t length)
	Generates an ext tag. More...
mpack_tag_t	mpack_tag_false (void)
	Generates a bool tag with value false. More...
mpack_tag_t	mpack_tag_float (float value)
	Generates a float tag. More...
mpack_tag_t	mpack_tag_int (int64_t value)
	Generates a signed int tag. More...
mpack_tag_t	mpack_tag_map (int32_t count)
	Generates a map tag. More...
mpack_tag_t	mpack_tag_nil (void)
	Generates a nil tag. More...
mpack_tag_t	mpack_tag_str (int32_t length)
	Generates a str tag. More...
mpack_tag_t	mpack_tag_true (void)
	Generates a bool tag with value true. More...
mpack_tag_t	mpack_tag_uint (uint64_t value)
	Generates an unsigned int tag. More...
const char *	mpack_type_to_string (mpack_type_t type)
	Converts an MPack type to a string. More...

---

Data Structure Documentation

struct mpack_tag_t

An MPack tag is a MessagePack object header.

It is a variant type representing any kind of object, and includes the value of that object when it is not a compound type (i.e. boolean, integer, float.)

If the type is compound (str, bin, ext, array or map), the embedded data is stored separately.

Data Fields
int8_t	exttype	The extension type if the type is mpack_type_ext.
mpack_type_t	type	The type of value.
union mpack_tag_t	v	The value for non-compound types.

union mpack_tag_t.v

The value for non-compound types.

Data Fields
bool	b	The value if the type is bool.
double	d	The value if the type is double.
float	f	The value if the type is float.
int64_t	i	The value if the type is signed int.
uint32_t	l	The number of bytes if the type is str, bin or ext.
uint32_t	n	The element count if the type is an array, or the number of key/value pairs if the type is map.
uint64_t	u	The value if the type is unsigned int.

Macro Definition Documentation

#define MPACK_LIBRARY_STRING

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

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

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

#define MPACK_VERSION_MAJOR   0

The major version number of MPack.

#define MPACK_VERSION_MINOR   8

The minor version number of MPack.

#define MPACK_VERSION_PATCH   2

The patch version number of MPack.

#define MPACK_VERSION_STRING

A string containing the MPack version.

Enumeration Type Documentation

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

enum mpack_type_t

Defines the type of a MessagePack tag.

Enumerator
mpack_type_nil	A null value.
mpack_type_bool	A boolean (true or false.)
mpack_type_float	A 32-bit IEEE 754 floating point number.
mpack_type_double	A 64-bit IEEE 754 floating point number.
mpack_type_int	A 64-bit signed integer.
mpack_type_uint	A 64-bit unsigned integer.
mpack_type_str	A string.
mpack_type_bin	A chunk of binary data.
mpack_type_ext	A typed MessagePack extension object containing 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.

Function Documentation

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_t mpack_tag_array

(

int32_t

count

)

Generates an array tag.

mpack_tag_t mpack_tag_bin

(

int32_t

length

)

Generates a bin tag.

mpack_tag_t mpack_tag_bool

(

bool

value

)

Generates a bool tag.

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_t mpack_tag_double

(

double

value

)

Generates a double tag.

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 much 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_t mpack_tag_ext	(	int8_t	exttype,
		int32_t	length
	)

Generates an ext tag.

mpack_tag_t mpack_tag_false

(

void

)

Generates a bool tag with value false.

mpack_tag_t mpack_tag_float

(

float

value

)

Generates a float tag.

mpack_tag_t mpack_tag_int

(

int64_t

value

)

Generates a signed int tag.

mpack_tag_t mpack_tag_map

(

int32_t

count

)

Generates a map tag.

mpack_tag_t mpack_tag_nil

(

void

)

Generates a nil tag.

mpack_tag_t mpack_tag_str

(

int32_t

length

)

Generates a str tag.

mpack_tag_t mpack_tag_true

(

void

)

Generates a bool tag with value true.

mpack_tag_t mpack_tag_uint

(

uint64_t

value

)

Generates an unsigned int tag.

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.