Loading...
Searching...
No Matches
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)
MPACK_VERSION_PATCH
#define MPACK_VERSION_PATCH
The patch version number of MPack.
Definition: mpack-common.h:55
MPACK_VERSION_MINOR
#define MPACK_VERSION_MINOR
The minor version number of MPack.
Definition: mpack-common.h:54
MPACK_VERSION_MAJOR
#define MPACK_VERSION_MAJOR
The major version number of MPack.
Definition: mpack-common.h:53

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.