WPILibC++ 2024.3.2
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. 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
 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_STRING
 A string containing the MPack version. More...
 
#define MPACK_LIBRARY_STRING
 A string describing MPack, containing the library name, version and debug mode. More...
 

Typedefs

typedef enum mpack_error_t mpack_error_t
 Error states for MPack objects. More...
 
typedef enum mpack_type_t mpack_type_t
 Defines the type of a MessagePack tag. More...
 
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
}
 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...
 
const char * mpack_type_to_string (mpack_type_t type)
 Converts an MPack type to a string. More...
 

Tag Generators

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

Tag Querying Functions

MPACK_INLINE mpack_type_t mpack_tag_type (mpack_tag_t *tag)
 Gets the type of a tag. More...
 
MPACK_INLINE bool mpack_tag_bool_value (mpack_tag_t *tag)
 Gets the boolean value of a bool-type tag. More...
 
MPACK_INLINE int64_t mpack_tag_int_value (mpack_tag_t *tag)
 Gets the signed integer value of an int-type tag. More...
 
MPACK_INLINE uint64_t mpack_tag_uint_value (mpack_tag_t *tag)
 Gets the unsigned integer value of a uint-type tag. More...
 
MPACK_INLINE float mpack_tag_float_value (mpack_tag_t *tag)
 Gets the float value of a float-type tag. More...
 
MPACK_INLINE double mpack_tag_double_value (mpack_tag_t *tag)
 Gets the double value of a double-type tag. More...
 
MPACK_INLINE uint32_t mpack_tag_array_count (mpack_tag_t *tag)
 Gets the number of elements in an array tag. More...
 
MPACK_INLINE uint32_t mpack_tag_map_count (mpack_tag_t *tag)
 Gets the number of key-value pairs in a map tag. More...
 
MPACK_INLINE uint32_t mpack_tag_str_length (mpack_tag_t *tag)
 Gets the length in bytes of a str-type tag. More...
 
MPACK_INLINE uint32_t mpack_tag_bin_length (mpack_tag_t *tag)
 Gets the length in bytes of a bin-type tag. More...
 
MPACK_INLINE 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...
 
MPACK_INLINE bool mpack_tag_equal (mpack_tag_t left, mpack_tag_t right)
 Compares two tags for equality. More...
 

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_float (float value)
 
MPACK_INLINE mpack_tag_t mpack_tag_double (double 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) + \
#define MPACK_VERSION_PATCH
The patch version number of MPack.
Definition: mpack.h:1902
#define MPACK_VERSION_MINOR
The minor version number of MPack.
Definition: mpack.h:1901
#define MPACK_VERSION_MAJOR
The major version number of MPack.
Definition: mpack.h:1900

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

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

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)

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

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

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

MPACK_INLINE mpack_tag_t mpack_tag_double ( double  value)

◆ mpack_tag_double_value()

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

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  )

◆ mpack_tag_float()

MPACK_INLINE mpack_tag_t mpack_tag_float ( float  value)

◆ mpack_tag_float_value()

MPACK_INLINE 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_INLINE mpack_tag_t mpack_tag_int ( int64_t  value)

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

MPACK_INLINE mpack_tag_t mpack_tag_make_double ( double  value)

Generates a double 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_float()

MPACK_INLINE mpack_tag_t mpack_tag_make_float ( float  value)

Generates a float tag.

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

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

◆ mpack_tag_str()

MPACK_INLINE mpack_tag_t mpack_tag_str ( int32_t  length)

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

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

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