Tags and Common Elements

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

Macros
#define	MPACK_VERSION_MAJOR   1
	The major version number of MPack.
#define	MPACK_VERSION_MINOR   1
	The minor version number of MPack.
#define	MPACK_VERSION_PATCH   1
	The patch version number of MPack.
#define	MPACK_VERSION
	A number containing the version number of MPack for comparison purposes.
#define	MPACK_VERSION_AT_LEAST(major, minor, patch)
	A macro to test for a minimum version of MPack.
#define	MPACK_VERSION_STRING
	A string containing the MPack version.
#define	MPACK_LIBRARY_STRING
	A string describing MPack, containing the library name, version and debug mode.

Typedefs
typedef enum mpack_error_t	mpack_error_t
	Error states for MPack objects.
typedef enum mpack_type_t	mpack_type_t
	Defines the type of a MessagePack tag.
typedef struct mpack_tag_t	mpack_tag_t
	An MPack tag is a MessagePack object header.

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 }
	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.
const char *	mpack_type_to_string (mpack_type_t type)
	Converts an MPack type to a string.

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

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

Other tag functions
int	mpack_tag_cmp (mpack_tag_t left, mpack_tag_t right)
	Compares two tags with an arbitrary fixed ordering.
MPACK_INLINE bool	mpack_tag_equal (mpack_tag_t left, mpack_tag_t right)
	Compares two tags for equality.

Deprecated Tag Generators
MPACK_INLINE mpack_tag_t	mpack_tag_nil (void)
MPACK_INLINE mpack_tag_t	mpack_tag_bool (bool value)
MPACK_INLINE mpack_tag_t	mpack_tag_true (void)
MPACK_INLINE mpack_tag_t	mpack_tag_false (void)
MPACK_INLINE mpack_tag_t	mpack_tag_int (int64_t value)
MPACK_INLINE mpack_tag_t	mpack_tag_uint (uint64_t value)
MPACK_INLINE mpack_tag_t	mpack_tag_array (int32_t count)
MPACK_INLINE mpack_tag_t	mpack_tag_map (int32_t count)
MPACK_INLINE mpack_tag_t	mpack_tag_str (int32_t length)
MPACK_INLINE mpack_tag_t	mpack_tag_bin (int32_t length)

Detailed Description

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

Macro Definition Documentation

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

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

Value:

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

typedef enum mpack_error_t 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.

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.

mpack_type_t

typedef enum mpack_type_t 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.

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.

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_INLINE mpack_tag_t mpack_tag_array

(

int32_t

count

)

Deprecated

Renamed to mpack_tag_make_array().

mpack_tag_array_count()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_bin

(

int32_t

length

)

Deprecated

Renamed to mpack_tag_make_bin().

mpack_tag_bin_length()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_bool

(

bool

value

)

Deprecated

Renamed to mpack_tag_make_bool().

mpack_tag_bool_value()

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

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

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

MPACK_INLINE mpack_tag_t mpack_tag_false

(

void

)

Deprecated

Renamed to mpack_tag_make_false().

mpack_tag_int()

MPACK_INLINE mpack_tag_t mpack_tag_int

(

int64_t

value

)

Deprecated

Renamed to mpack_tag_make_int().

mpack_tag_int_value()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_make_array

(

uint32_t

count

)

Generates an array tag.

mpack_tag_make_bin()

MPACK_INLINE mpack_tag_t mpack_tag_make_bin

(

uint32_t

length

)

Generates a bin tag.

mpack_tag_make_bool()

MPACK_INLINE mpack_tag_t mpack_tag_make_bool

(

bool

value

)

Generates a bool tag.

mpack_tag_make_false()

MPACK_INLINE mpack_tag_t mpack_tag_make_false

(

void

)

Generates a bool tag with value false.

mpack_tag_make_int()

MPACK_INLINE mpack_tag_t mpack_tag_make_int

(

int64_t

value

)

Generates a signed int tag.

mpack_tag_make_map()

MPACK_INLINE mpack_tag_t mpack_tag_make_map

(

uint32_t

count

)

Generates a map tag.

mpack_tag_make_nil()

MPACK_INLINE mpack_tag_t mpack_tag_make_nil

(

void

)

Generates a nil tag.

mpack_tag_make_raw_double()

MPACK_INLINE mpack_tag_t mpack_tag_make_raw_double

(

uint64_t

value

)

Generates a double tag from a raw uint64_t.

mpack_tag_make_raw_float()

MPACK_INLINE mpack_tag_t mpack_tag_make_raw_float

(

uint32_t

value

)

Generates a float tag from a raw uint32_t.

mpack_tag_make_str()

MPACK_INLINE mpack_tag_t mpack_tag_make_str

(

uint32_t

length

)

Generates a str tag.

mpack_tag_make_true()

MPACK_INLINE mpack_tag_t mpack_tag_make_true

(

void

)

Generates a bool tag with value true.

mpack_tag_make_uint()

MPACK_INLINE mpack_tag_t mpack_tag_make_uint

(

uint64_t

value

)

Generates an unsigned int tag.

mpack_tag_map()

MPACK_INLINE mpack_tag_t mpack_tag_map

(

int32_t

count

)

Deprecated

Renamed to mpack_tag_make_map().

mpack_tag_map_count()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_nil

(

void

)

Deprecated

Renamed to mpack_tag_make_nil().

mpack_tag_raw_double_value()

MPACK_INLINE uint64_t mpack_tag_raw_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_raw_float_value()

MPACK_INLINE uint32_t mpack_tag_raw_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_str()

MPACK_INLINE mpack_tag_t mpack_tag_str

(

int32_t

length

)

Deprecated

Renamed to mpack_tag_make_str().

mpack_tag_str_length()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_true

(

void

)

Deprecated

Renamed to mpack_tag_make_true().

mpack_tag_type()

MPACK_INLINE mpack_type_t mpack_tag_type

(

mpack_tag_t *

tag

)

Gets the type of a tag.

mpack_tag_uint()

MPACK_INLINE mpack_tag_t mpack_tag_uint

(

uint64_t

value

)

Deprecated

Renamed to mpack_tag_make_uint().

mpack_tag_uint_value()

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