nlib
nn::nlib::msgpack::MpObject Class Referencefinal

Object created when MessagePack or JSON is read. More...

#include "nn/nlib/msgpack/MpObject.h"

Public Types

enum  ObjectType {
  kNil = 0,
  kBoolean,
  kUint64,
  kInt64,
  kFloat,
  kDouble,
  kString,
  kArray,
  kMap,
  kBinary,
  kExt
}
 Data type of the object stored in MpObject. More...
 

Public Member Functions

errno_t Resize (uint32_t n)
 Resizes an array and associative array. More...
 
MpObjectClone () const noexcept
 Creates a duplicate of the object. More...
 
uint32_t GetSize () const noexcept
 Returns the size of the array, associative array, string, or binary. More...
 
Use of Type-Specific Accessor Classes

An array, associative array, etc. can be accessed via a dedicated accessor class. Iterators, etc. are defined.

MpObjectAsArray AsArray () noexcept
 Returns an object for accessing arrays. IsArray() must be true.
 
const MpObjectAsArray AsArray () const noexcept
 The const decoration version of the above function.
 
MpObjectAsMap AsMap () noexcept
 Returns an object for accessing associative arrays. IsMap() must be true.
 
const MpObjectAsMap AsMap () const noexcept
 The const decoration version of the above function.
 
MpObjectAsString AsString () noexcept
 Returns an object for accessing strings. IsString() must be true.
 
const MpObjectAsString AsString () const noexcept
 The const decoration version of the above function.
 
MpObjectAsBinary AsBinary () noexcept
 Returns an object for accessing binary. IsBinary() must be true.
 
const MpObjectAsBinary AsBinary () const noexcept
 The const decoration version of the above function.
 
MpObjectAsExt AsExt () noexcept
 Returns an object for accessing the extended data type. IsExt() must be true.
 
const MpObjectAsExt AsExt () const noexcept
 The const decoration version of the above function.
 
Using the Array Type (kArray Type)
MpObjectGetArrayItem (size_t n) noexcept
 Specifies an index and gets the object in the array. More...
 
const MpObjectGetArrayItem (size_t n) const noexcept
 The const decoration version of the above function.
 
MpObjectoperator[] (size_t n)
 For an array, returns a reference to an element of the array. More...
 
const MpObjectoperator[] (size_t n) const
 The const decoration version of the above function.
 
MpObjectAppendArrayItem () noexcept
 If the object contains an array, adds an element to the end of the array. More...
 
MpObjectInsertArrayItem (size_t n) noexcept
 If the object contains an array, inserts an element into the location with the specified index in the array. More...
 
errno_t GetArrayItem (size_t n, MpObject **obj) noexcept
 Specifies an index and gets the object in the array. More...
 
errno_t GetArrayItem (size_t n, const MpObject **obj) const noexcept
 The const decoration version of the above function.
 
errno_t RemoveArrayItem (size_t n, MpObject *obj) noexcept
 Specifies an index and deletes the corresponding object in the array. More...
 
errno_t InitArray (uint32_t n) noexcept
 Initializes as an object with an n element array. More...
 
Using the Associative Array Type (kMap Type)
const MpObjectGetMapItem (const nlib_utf8_t *str) const noexcept
 The const decoration version of the above function.
 
MpObjectGetMapItem (const nlib_utf8_t *str) noexcept
 Specifies a string and gets the object in the associative array. More...
 
template<class STDSTRING >
const MpObjectGetMapItem (const STDSTRING &str) const noexcept
 The const decoration version of the above function.
 
template<class STDSTRING >
MpObjectGetMapItem (const STDSTRING &str) noexcept
 Specifies a string and gets the object in the associative array. More...
 
MpObjectKvAppendMapItem () noexcept
 Adds an element to the end if the object is storing an associative array. More...
 
errno_t GetMapItem (size_t n, MpObjectKv **obj) noexcept
 Specifies an index and gets the object in the associative array. More...
 
errno_t GetMapItem (size_t n, const MpObjectKv **obj) const noexcept
 The const decoration version of the above function.
 
errno_t GetMapItem (const nlib_utf8_t *str, size_t n, MpObjectKv **obj) noexcept
 Obtains the pair of a key and value from the associative array by specifying a non-null terminated string as the key. More...
 
errno_t GetMapItem (const nlib_utf8_t *str, size_t n, const MpObjectKv **obj) const noexcept
 Obtains the pair of a key and value from the associative array by specifying a non-null terminated string as the key.
 
errno_t RemoveMapItem (size_t n, MpObjectKv *kv) noexcept
 Specifies an index and deletes the corresponding key and object in the associative array. More...
 
errno_t RemoveMapItem (const nlib_utf8_t *key, MpObjectKv *kv) noexcept
 Specifies a key and deletes the corresponding key and object in the associative array. More...
 
template<class STDSTRING >
errno_t RemoveMapItem (const STDSTRING &str, MpObjectKv *kv) noexcept
 Specifies a key and deletes the corresponding key and object in the associative array. More...
 
errno_t InitMap (uint32_t n) noexcept
 Initializes the object as an n element associative array. More...
 
Constructor, Destructor, and Initialization
 MpObject () noexcept
 Instantiates the object with default parameters (default constructor). Set to the nil type.
 
 ~MpObject () noexcept
 Destructor.
 
 MpObject (MpObject &&rhs) noexcept
 Instantiates the object (move constructor).
 
MpObjectoperator= (MpObject &&rhs) noexcept
 Move assignment operator.
 
 MpObject (MpObject &rhs, move_tag) noexcept
 Corresponds to a move constructor.
 
MpObjectassign (MpObject &rhs, move_tag) noexcept
 Assigns the object by using swap for a move.
 
template<class T >
 MpObject (const T &x)
 The constructor for boxing a T-type object. More...
 
Using the String Type (STRING Type)
nlib_utf8_tGetString () noexcept
 Gets a string from an object.
 
const nlib_utf8_tGetString () const noexcept
 The const decoration version of the above function.
 
errno_t InitString (uint32_t n) noexcept
 Initializes the object as a string. More...
 
errno_t InitString (const nlib_utf8_t *str, uint32_t n) noexcept
 Initializes the object as a string. More...
 
errno_t InitString (const nlib_utf8_t *str) noexcept
 Initializes the object as a string. More...
 
Using the Binary Type (BINARY Type)
void * GetBinary (uint32_t *n) noexcept
 Gets binary from an object.
 
const void * GetBinary (uint32_t *n) const noexcept
 Gets binary from an object.
 
std::tuple< errno_t, const nlib_byte_t *, uint32_t > GetBinary () const noexcept
 Extracts the binary data. If it is not the binary type, EACCES is set as the error value. More...
 
errno_t InitBinary (uint32_t n) noexcept
 Initializes the object as binary. More...
 
errno_t InitBinary (const void *p, uint32_t n) noexcept
 Initializes the object as binary. More...
 
Entended Data Type (<tt>kExt</tt>
void * GetExt (int8_t *tp, uint32_t *n) noexcept
 Gets an extended data type from an object. More...
 
const void * GetExt (int8_t *tp, uint32_t *n) const noexcept
 Gets an extended data type from an object.
 
std::tuple< errno_t, int8_t, const nlib_byte_t *, uint32_t > GetExt () const noexcept
 Extracts the extended data. If it is not the extended data type, EACCES is set as the error value. More...
 
std::pair< errno_t, nlib_timeGetTimestamp () const noexcept
 Obtains a timestamp from an object. More...
 
errno_t InitExt (int8_t tp, uint32_t n) noexcept
 Initializes an object as the extended data type. More...
 
errno_t InitExt (int8_t tp, const void *p, uint32_t n) noexcept
 Initializes an object as the extended data type. More...
 
errno_t InitTimestamp (nlib_time t) noexcept
 Initializes an object as a timestamp of the extended data type. More...
 
Boxing

Boxes numerical values, strings, vectors, and other values, and stores the result as an instance of MpObject.

errno_t Box (const nlib_utf8_t *str) noexcept
 Boxes the string. More...
 
template<uint32_t n>
errno_t Box (const nlib_utf8_t(&str)[n]) noexcept
 Boxes the string. More...
 
template<class T , uint32_t n>
errno_t Box (const T(&vec)[n])
 Boxes the array. More...
 
template<class T >
errno_t Box (const T &v)
 Boxes the object. More...
 
template<class T >
MpObjectoperator= (const T &x)
 The value is passed into MpObject. More...
 
Unboxing

Unboxes numerical values, string, vectors, and other values, and stores the result as an instance of MpObject.

template<class T , size_t n>
errno_t Unbox (T(&a)[n]) const
 Unboxes the object value. More...
 
template<size_t n>
errno_t Unbox (nlib_utf8_t(&str)[n]) const noexcept
 See Unbox(T (&a)[n]).
 
template<class T >
errno_t Unbox (T *a, size_t n) const
 Unboxes the array data. More...
 
errno_t Unbox (nlib_utf8_t *str, size_t n) const noexcept
 See the description of Unbox(T* a, size_t n).
 
template<class T >
errno_t Unbox (T v) const
 Unboxes the object. More...
 
Obtaining and Determining the Type
ObjectType GetType () const noexcept
 Returns the object type. More...
 
bool IsNil () const noexcept
 Determines whether the stored value is nil.
 
bool IsBoolean () const noexcept
 Determines whether the stored value is a boolean.
 
bool IsInteger () const noexcept
 Determines whether the stored value is an integer.
 
bool IsFloat () const noexcept
 Determines whether the stored value is a single precision float.
 
bool IsDouble () const noexcept
 Determines whether the stored value is a double.
 
bool IsString () const noexcept
 Determines whether the stored value is a string.
 
bool IsBinary () const noexcept
 Determines whether the stored value is binary.
 
bool IsExt () const noexcept
 Determines whether the stored value is extended data.
 
bool IsArray () const noexcept
 Determines whether the stored value is an array.
 
bool IsMap () const noexcept
 Determines whether the stored value is an associative array.
 

Static Public Member Functions

static bool IsJsonPointer (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Specify a string to determine whether the string is JSON Pointer. More...
 
static bool IsJsonPointer (const nlib_utf8_t *str) noexcept
 A parameter omitted version of the above function which receives a null terminated string.
 
static errno_t ResolveJsonPointer (MpObject **result, MpObject *root, const nlib_utf8_t *json_pointer) noexcept
 Stores MpObject referenced by json_pointer in *result. More...
 
static errno_t DigByJsonPointer (MpObject **result, MpObject *root, const nlib_utf8_t *json_pointer) noexcept
 Although MpObject is referenced by json_pointer, new MpObject may be added. More...
 
static errno_t RemoveByJsonPointer (MpObjectKv *removed, MpObject *root, const nlib_utf8_t *json_pointer) noexcept
 Deletes MpObject referenced by json_pointer and stores it in removed. More...
 

Detailed Description

Object created when MessagePack or JSON is read.

Description
Active object created by boxing using the Box method, or reading JSON or MessagePack data. The Unbox method is used to convert to the static object. The various numerical value types, arrays, strings, bool, nil, std::pair, std::vector, std::map, and std::string support the Box and Unbox methods by default. C++11 also supports std::array, std::unordered_map, and std::tuple.
You must specialize the following function templates when using Box on a user-defined type.
A code sample is shown below. If an error occurs, a value other than 0 must be returned.
bool BoxCustomData() {
Vec3 vec = { 1.f, 2.f, 3.f };
MpObject obj;
SUCCEED_IF(obj.Box(vec) == 0);
float x, y, z;
auto ar = obj.AsArray();
ar[0].Unbox(&x);
ar[1].Unbox(&y);
ar[2].Unbox(&z);
nlib_printf("obj[0]: %f, obj[1]: %f, obj[2]: %f\n", x, y, z);
return true;
/*
Output:
obj[0]: 1.000000, obj[1]: 2.000000, obj[2]: 3.000000
*/
}
bool UnboxCustomData() {
Vec3 vec;
MpObject obj;
obj.InitArray(3);
auto ar = obj.AsArray();
ar[0].Box(1.f);
ar[1].Box(2.f);
ar[2].Box(3.f);
SUCCEED_IF(obj.Unbox(&vec) == 0);
nlib_printf("Vec.x: %f, Vec.y: %f, Vec.z: %f\n", vec.x, vec.y, vec.z);
return true;
/*
Output:
Vec.x: 1.000000, Vec.y: 2.000000, Vec.z: 3.000000
*/
}
A function that returns an errno_t type may return 0 or the following values.
  • EINVAL: The argument is invalid.
  • ENOMEM: Failed to allocate memory.
  • EACCES: Failed to convert the type.
  • ERANGE: The index of the array or similar is out of range.
  • EILSEQ: Data contains an error.

Definition at line 96 of file MpObject.h.

Member Enumeration Documentation

◆ ObjectType

Data type of the object stored in MpObject.

Description
Obtained by using GetType.
Enumerator
kNil 

Represents a nil type.

kBoolean 

Represents a boolean type. The internal representation is a bool.

kUint64 

Represents an unsigned integer type. The internal representation is uint64_t.

kInt64 

Represents an integer type. The internal representation is int64_t.

kFloat 

Represents a floating point type. The internal representation is float.

kDouble 

Represents a floating point type. The internal representation is double.

kString 

Respresents a byte array (string).

kArray 

Represents an array. The internal representation is an array of MpObject.

kMap 

Represents an associative array. The internal representation is an array of MpObject pairs.

kBinary 

Represents binary data only for msgpack.

kExt 

Represents the extended data type only for msgpack.

Definition at line 336 of file MpObject.h.

Constructor & Destructor Documentation

◆ MpObject()

template<class T >
nn::nlib::msgpack::MpObject::MpObject ( const T &  x)
inline

The constructor for boxing a T-type object.

Template Parameters
TThe type being boxed.
Parameters
[in]xThe value to box into an MpObject.

Definition at line 197 of file MpObject.h.

Member Function Documentation

◆ AppendArrayItem()

nn::nlib::msgpack::MpObject::AppendArrayItem ( )
noexcept

If the object contains an array, adds an element to the end of the array.

Returns
If successful, returns the pointer to the added element. NULL if process fails.

◆ AppendMapItem()

nn::nlib::msgpack::MpObject::AppendMapItem ( )
noexcept

Adds an element to the end if the object is storing an associative array.

Returns
If successful, returns the pointer to the added element. NULL if process fails.

◆ Box() [1/4]

nn::nlib::msgpack::MpObject::Box ( const nlib_utf8_t str)
noexcept

Boxes the string.

Parameters
[in]strString.
Returns
Returns 0 on success. All other values are an error.
Description
Strings are stored as kString type data.

◆ Box() [2/4]

template<uint32_t n>
errno_t nn::nlib::msgpack::MpObject::Box ( const nlib_utf8_t(&)  str[n])
noexcept

Boxes the string.

Template Parameters
nThe size of the array.
Parameters
[in]strA null-terminated string.
Returns
Returns 0 on success. All other values are an error.
Description
Strings are stored as kString type data.

Definition at line 1258 of file MpObject.h.

◆ Box() [3/4]

template<class T, uint32_t n>
errno_t nn::nlib::msgpack::MpObject::Box ( const T(&)  vec[n])

Boxes the array.

Parameters
[in]vecObject being boxed.
Template Parameters
TElement type.
nNumber of elements.
Returns
Returns 0 on success.
Description
Boxing behavior differs depending on the data type of T. The following table illustrates the difference in behavior.
Type of T Descr
char Characters up to the NULL character are boxed in an MpObject::kString type as a string.
All others Boxed into an MpObject::kArray type as an array.

Definition at line 1267 of file MpObject.h.

◆ Box() [4/4]

template<class T >
nn::nlib::msgpack::MpObject::Box ( const T &  v)
inline

Boxes the object.

Template Parameters
TType of object being boxed.
Parameters
[in]vObject being boxed.
Returns
Returns 0 on success. All other values are an error.
Description
Boxes a static object and converts it to a dynamic object. Returns a nonzero value when memory allocation fails in the box process.
Behavior differs according to the type of T. The following table illustrates the difference in behavior.
Type of T Descr
nil Stored as an MpObject::kNil type. This process never returns an error.
bool Stored as an MpObject::kBoolean type. This process never returns an error.
Signed Integer Stored as an MpObject::kInt64 type. This process never returns an error.
Unsigned Integer Stored as an MpObject::kUint64 type. This process never returns an error.
float Stored as an MpObject::kFloat type. This process never returns an error.
double Stored as an MpObject::kDouble type. This process never returns an error.
std::string Stored as an MpObject::kString type.
std::vector Stored as an MpObject::kArray type.
Nlist Stored as an MpObject::kArray type.
std::pair Stored as an MpObject::kArray type with a size of 2.
std::map Stored as an MpObject::kMap type.
std::array Stored as an MpObject::kArray type.
std::tuple Stored as an MpObject::kArray type.
std::unordered_map Stored as an MpObject::kMap type.
Arrays are boxed as arrays, except for char type arrays. A char array is boxed as a string. Sample code is provided below.
int ar[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
MpObject ar_obj;
SUCCEED_IF(ar_obj.Box(ar) == 0);
NLIB_ASSERT(ar_obj.IsArray());
NLIB_ASSERT(ar_obj.GetSize() == 10);
std::vector<int> vec(&ar[0], &ar[0] + 10);
MpObject vec_obj;
SUCCEED_IF(vec_obj.Box(vec) == 0);
NLIB_ASSERT(vec_obj.IsArray());
NLIB_ASSERT(vec_obj.GetSize() == 10);
MpObject str_obj;
const char str[] = "string data";
SUCCEED_IF(str_obj.Box(str) == 0);
SUCCEED_IF(str_obj.IsString());
SUCCEED_IF(str_obj.GetSize() == 11);

Definition at line 288 of file MpObject.h.

◆ Clone()

nn::nlib::msgpack::MpObject::Clone ( ) const
noexcept

Creates a duplicate of the object.

Returns
Pointer to the duplicate object.
Description
Releases all memory allocated for duplication and returns NULL when duplication fails mid-process.

◆ DigByJsonPointer()

nn::nlib::msgpack::MpObject::DigByJsonPointer ( MpObject **  result,
MpObject root,
const nlib_utf8_t json_pointer 
)
staticnoexcept

Although MpObject is referenced by json_pointer, new MpObject may be added.

Parameters
[in,out]resultAn object referenced by json_pointer.
[in]rootA root object that serves as the starting point for reference with json_pointer.
[in]json_pointerJSON pointer string.
Return values
0Indicates that the last reference token for json_pointer could not be traced and new MpObject is created so that it can be traced.
EEXISTIndicates that MpObject pointed with json_pointer already exists.
EINVALIndicates that result, root, or json_pointer is NULL.
EILSEQIndicates that the syntax for json_pointer is incorrect.
ENOENTIndicates that the reference token other than the last one within json_pointer could not be traced.
ENOMEMIndicates memory allocation failed.
Description
Obtains MpObject by drilling down the JSON tree structure based on a string defined by JSON Pointer (RFC6901). However, if no MpObject that corresponds to the end of json_pointer exists, new MpObject will be created. If the function returns 0 or EEXIST, a pointer to MpObject that tracing json_pointer has eventually reached is set to *result.
Note the following:
  • If an array is referenced by the reference token at the end of json_pointer, MpObject should be inserted into the array.
  • If no reference token other than the one at the end of json_pointer can be traced, the ENOENT error occurs.
A code example and the execution result are shown below.
const char* json1 = R"({ "a": { "foo": 1 } })";
auto obj = ToMpObject(json1);
e = MpObject::DigByJsonPointer(&node, obj.get(), "/a/b");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
nlib_printf("Dig(%s, '/a/b') --> %s\n", json1, to);
obj = ToMpObject(json1);
e = MpObject::DigByJsonPointer(&node, obj.get(), "/a/foo");
ToJson(to, *obj);
nlib_printf("Dig(%s, '/a/foo') --> %s(err = %s)\n", json1, to, nlib_error_string(e));
const char* json2 = R"([0,1,2])";
obj = ToMpObject(json2);
e = MpObject::DigByJsonPointer(&node, obj.get(), "/-");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
nlib_printf("Dig(%s, '/-') --> %s\n", json2, to);
obj = ToMpObject(json2);
e = MpObject::DigByJsonPointer(&node, obj.get(), "/1");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
nlib_printf("Dig(%s, '/1') --> %s\n", json2, to);
const char* json3 = R"({ "q": { "bar": 2 } })";
obj = ToMpObject(json3);
e = MpObject::DigByJsonPointer(&node, obj.get(), "/a/b");
ToJson(to, *obj);
nlib_printf("Dig(%s, '/a/b') --> %s(err = %s)\n", json3, to, nlib_error_string(e));
/*
Output:
Dig({ "a": { "foo": 1 } }, '/a/b') --> {"a":{"foo":1,"b":null}}
Dig({ "a": { "foo": 1 } }, '/a/foo') --> {"a":{"foo":1}}(err = EEXIST)
Dig([0,1,2], '/-') --> [0,1,2,null]
Dig([0,1,2], '/1') --> [0,null,1,2]
Dig({ "q": { "bar": 2 } }, '/a/b') --> {"q":{"bar":2}}(err = ENOENT)
*/
This function performs the add operations specified in JSON Patch (RFC6902) except for those for setting values. For more information, see the RFC:
See also
https://tools.ietf.org/html/rfc6901
https://tools.ietf.org/html/rfc6902
https://triple-underscore.github.io/RFC6901-ja.html
https://triple-underscore.github.io/RFC6902-ja.html

◆ GetArrayItem() [1/2]

MpObject * nn::nlib::msgpack::MpObject::GetArrayItem ( size_t  n)
inlinenoexcept

Specifies an index and gets the object in the array.

Parameters
[in]nThe array index.
Returns
Pointer to the object (MpObject) corresponding to the index.
Description
Returns NULL if processing failed.

Definition at line 521 of file MpObject.h.

◆ GetArrayItem() [2/2]

nn::nlib::msgpack::MpObject::GetArrayItem ( size_t  n,
MpObject **  obj 
)
noexcept

Specifies an index and gets the object in the array.

Parameters
[in]nThe array index.
[out]objPointer that stores the pointer to the object (MpObject).
Returns
Returns 0 on success. All other values are an error.

◆ GetBinary()

std::tuple< errno_t, const nlib_byte_t *, uint32_t > nn::nlib::msgpack::MpObject::GetBinary ( ) const
inlinenoexcept

Extracts the binary data. If it is not the binary type, EACCES is set as the error value.

Returns
A tupple of the error value, a pointer to the binary retained by MpObject, and the size.

Definition at line 755 of file MpObject.h.

◆ GetExt() [1/2]

void * nn::nlib::msgpack::MpObject::GetExt ( int8_t *  tp,
uint32_t *  n 
)
inlinenoexcept

Gets an extended data type from an object.

Parameters
[out]tpInteger indicating the data type.
[out]nSize of the binary.
Returns
Pointer to the extended data type binary.

Definition at line 783 of file MpObject.h.

◆ GetExt() [2/2]

std::tuple< errno_t, int8_t, const nlib_byte_t *, uint32_t > nn::nlib::msgpack::MpObject::GetExt ( ) const
inlinenoexcept

Extracts the extended data. If it is not the extended data type, EACCES is set as the error value.

Returns
A tupple of the error value, the data type of extended data, a pointer to the binary retained by MpObject, and the size.

Definition at line 792 of file MpObject.h.

◆ GetMapItem() [1/4]

nn::nlib::msgpack::MpObject::GetMapItem ( const nlib_utf8_t str)
noexcept

Specifies a string and gets the object in the associative array.

Parameters
[in]strAssociative array key string.
Returns
Pointer to the corresponding object (MpObject).
Description
Gets the value object in the associative array corresponding to the key string. The search is linearly made and NULL is retuned if the search has failed.

◆ GetMapItem() [2/4]

template<class STDSTRING >
nn::nlib::msgpack::MpObject::GetMapItem ( const STDSTRING &  str)
inlinenoexcept

Specifies a string and gets the object in the associative array.

Template Parameters
STDSTRINGA type compatible with std::string
Parameters
[in]strAssociative array key string.
Returns
Pointer to the corresponding object (MpObject).
Description
Gets the value object in the associative array corresponding to the key string. GetMapItem(size_t n, MpObjectKv** obj) must be used when the key is not a string. The search is linear. Returns NULL if processing failed.

Definition at line 160 of file MpObject.h.

◆ GetMapItem() [3/4]

nn::nlib::msgpack::MpObject::GetMapItem ( size_t  n,
MpObjectKv **  obj 
)
noexcept

Specifies an index and gets the object in the associative array.

Parameters
[in]nAssociative array index.
[out]objThe pointer that contains the pair, MpObjectKv*, of the key and value from the associative array
Returns
Returns 0 on success. All other values are an error.

◆ GetMapItem() [4/4]

nn::nlib::msgpack::MpObject::GetMapItem ( const nlib_utf8_t str,
size_t  n,
MpObjectKv **  obj 
)
inlinenoexcept

Obtains the pair of a key and value from the associative array by specifying a non-null terminated string as the key.

Parameters
[in]strAssociative array key string.
[in]nLength of the string.
[out]objThe pointer that contains the pair, MpObjectKv*, of the key and value from the associative array
Return values
0Success.
EINVALIndicates that str or obj is NULL.
EACCESIndicates that this object is not an associative array.
ENOENTIndicates that no value corresponding to the given key string has been found.

Definition at line 205 of file MpObject.h.

◆ GetSize()

nn::nlib::msgpack::MpObject::GetSize ( ) const
inlinenoexcept

Returns the size of the array, associative array, string, or binary.

Returns
Size of the array or associative array.
Description
The return value is undefined if the object is not an array, associative array, string, or binary. This return value generally matches strlen for a string, except when there is a null character mid-string.

Definition at line 354 of file MpObject.h.

◆ GetTimestamp()

nn::nlib::msgpack::MpObject::GetTimestamp ( ) const
noexcept

Obtains a timestamp from an object.

Returns
A pair of the error value and the timestamp. Success if the error value is 0.
See also
https://github.com/msgpack/msgpack/blob/master/spec.md#formats-timestamp

◆ GetType()

nn::nlib::msgpack::MpObject::GetType ( ) const
inlinenoexcept

Returns the object type.

Returns
Object type.

Definition at line 353 of file MpObject.h.

◆ InitArray()

nn::nlib::msgpack::MpObject::InitArray ( uint32_t  n)
noexcept

Initializes as an object with an n element array.

Parameters
[in]nSize of the array to initialize.
Returns
Returns 0 on success. All other values are an error.

◆ InitBinary() [1/2]

nn::nlib::msgpack::MpObject::InitBinary ( uint32_t  n)
noexcept

Initializes the object as binary.

Parameters
[in]nSize of the binary.
Returns
Returns 0 on success. All other values cause an error.

◆ InitBinary() [2/2]

nn::nlib::msgpack::MpObject::InitBinary ( const void *  p,
uint32_t  n 
)
noexcept

Initializes the object as binary.

Parameters
[in]pPointer to the binary.
[in]nSize of the binary.
Returns
Returns 0 on success. All other values cause an error.

◆ InitExt() [1/2]

nn::nlib::msgpack::MpObject::InitExt ( int8_t  tp,
uint32_t  n 
)
noexcept

Initializes an object as the extended data type.

Parameters
[in]tpInteger indicating the data type.
[in]nSize of the binary.
Returns
Returns 0 on success. All other values cause an error.

◆ InitExt() [2/2]

nn::nlib::msgpack::MpObject::InitExt ( int8_t  tp,
const void *  p,
uint32_t  n 
)
noexcept

Initializes an object as the extended data type.

Parameters
[in]tpInteger indicating the data type.
[in]pPointer to the binary.
[in]nSize of the binary.
Returns
Returns 0 on success. All other values cause an error.

◆ InitMap()

nn::nlib::msgpack::MpObject::InitMap ( uint32_t  n)
noexcept

Initializes the object as an n element associative array.

Parameters
[in]nSize of the associative array to initialize.
Returns
Returns 0 on success. All other values are an error.

◆ InitString() [1/3]

nn::nlib::msgpack::MpObject::InitString ( uint32_t  n)
noexcept

Initializes the object as a string.

Parameters
[in]nLength of the string to be initialized (not including the terminating character).
Returns
Returns 0 on success. All other values cause an error.

◆ InitString() [2/3]

nn::nlib::msgpack::MpObject::InitString ( const nlib_utf8_t str,
uint32_t  n 
)
noexcept

Initializes the object as a string.

Parameters
[in]strString
[in]nLength of the string to be initialized (not including the terminating character).
Returns
Returns 0 on success. All other values cause an error.

◆ InitString() [3/3]

nn::nlib::msgpack::MpObject::InitString ( const nlib_utf8_t str)
inlinenoexcept

Initializes the object as a string.

Parameters
[in]strString
Returns
Returns 0 on success. All other values cause an error.

Definition at line 267 of file MpObject.h.

◆ InitTimestamp()

nn::nlib::msgpack::MpObject::InitTimestamp ( nlib_time  t)
noexcept

Initializes an object as a timestamp of the extended data type.

Parameters
[in]tThe time.
Returns
Returns 0 on success. All other values cause an error.
See also
https://github.com/msgpack/msgpack/blob/master/spec.md#formats-timestamp

◆ InsertArrayItem()

nn::nlib::msgpack::MpObject::InsertArrayItem ( size_t  n)
noexcept

If the object contains an array, inserts an element into the location with the specified index in the array.

Parameters
[in]nThe array index.
Returns
If successful, returns the pointer to the inserted element. NULL if process fails.

◆ IsJsonPointer()

nn::nlib::msgpack::MpObject::IsJsonPointer ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Specify a string to determine whether the string is JSON Pointer.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Returns
If true is returned, the string is JSON Pointer.
Description
Although the JSON Pointer syntax is simple, empty strings and other strings that end with '/' require attention. Corner cases are summarized in the following code:
const char* valid[] = {
"", // the whole document
"/foo",
"/foo/0",
"/foo/", // keys = ["foo", ""]
"/", // key=""
"/a~1b", // key="a/b"
"/ ", // key=" "
"/m~0n" // key="m~n"
};
for (auto& str : valid) {
SUCCEED_IF(MpObject::IsJsonPointer(str));
}
const char* invalid[] = {
"foo", // no relative path
"/m~2n" // only ~0 and ~1
"/m~xn" // use "/m~0xn"
};
for (auto& str : invalid) {
SUCCEED_IF(!MpObject::IsJsonPointer(str));
}

◆ operator=()

template<class T >
nn::nlib::msgpack::MpObject::operator= ( const T &  x)
inline

The value is passed into MpObject.

Template Parameters
TType of object being assigned.
Parameters
[in]xValue being passed.
Returns
Returns the reference of *this.
Description
Only value types that cannot cause errors in boxing may be passed. All other types must be boxed or use swapping.
obj = 1; // same as obj.Box(1)
obj = 1.2f; // same as obj.Box(1.2f)
// obj = "abc"; // error
obj.Box("abc"); // ok

Definition at line 328 of file MpObject.h.

◆ operator[]()

nn::nlib::msgpack::MpObject::operator[] ( size_t  n)
inline

For an array, returns a reference to an element of the array.

Parameters
[in]nThe array index.
Returns
Reference to the array element MpObject.
Description
The behavior is undefined when not an array, or if the index is out of range of the array.

Definition at line 135 of file MpObject.h.

◆ RemoveArrayItem()

nn::nlib::msgpack::MpObject::RemoveArrayItem ( size_t  n,
MpObject obj 
)
noexcept

Specifies an index and deletes the corresponding object in the array.

Parameters
[in]nThe array index.
[in,out]objIf not NULL, the deleted object is stored.
Returns
Returns 0 on success. All other values represent an error.

◆ RemoveByJsonPointer()

nn::nlib::msgpack::MpObject::RemoveByJsonPointer ( MpObjectKv removed,
MpObject root,
const nlib_utf8_t json_pointer 
)
staticnoexcept

Deletes MpObject referenced by json_pointer and stores it in removed.

Parameters
[in,out]removedA pair of the key and value referenced by json_pointer.
[in]rootA root object that serves as the starting point for reference with json_pointer.
[in]json_pointerJSON pointer string.
Return values
0Success.
ECHILDIndicates that json_pointer was an empty string, and thus root was deleted.
EINVALIndicates that removed, root, or json_pointer is NULL.
EILSEQIndicates that the syntax for json_pointer is incorrect.
ENOENTIndicates that the object referenced by json_pointer cannot be found.
Description
Deletes MpObject by drilling down the JSON tree structure based on a string defined by JSON Pointer (RFC6901). The pair of the deleted key and value is stored in removed. Note that when deleting an element from the array, its index is boxed and stored in removed->first, and each element after that index is shifted toward the beginning of the array to fill the deleted element.
A code example and the execution result are shown below.
const char* json1 = R"({ "a": { "foo": 1 } })";
auto obj = ToMpObject(json1);
e = MpObject::RemoveByJsonPointer(&kv, obj.get(), "/a/foo");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
ToJson(key, kv.first);
ToJson(value, kv.second);
nlib_printf("Remove(%s, '/a/foo') --> %s, key=%s, value=%s\n", json1, to, key, value);
obj = ToMpObject(json1);
e = MpObject::RemoveByJsonPointer(&kv, obj.get(), "/a");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
ToJson(key, kv.first);
ToJson(value, kv.second);
nlib_printf("Remove(%s, '/a') --> %s, key=%s, value=%s\n", json1, to, key, value);
const char* json2 = R"([0, 1, 2])";
obj = ToMpObject(json2);
e = MpObject::RemoveByJsonPointer(&kv, obj.get(), "/1");
SUCCEED_IF(e == 0);
ToJson(to, *obj);
ToJson(key, kv.first);
ToJson(value, kv.second);
nlib_printf("Remove(%s, '/1') --> %s, key=%s, value=%s\n", json1, to, key, value);
/*
Output:
Remove({ "a": { "foo": 1 } }, '/a/foo') --> {"a":{}}, key="foo", value=1
Remove({ "a": { "foo": 1 } }, '/a') --> {}, key="a", value={"foo":1}
Remove({ "a": { "foo": 1 } }, '/1') --> [0,2], key=1, value=1
*/
This function performs the remove operations specified in JSON Patch (RFC6902). For more information, see the RFC:
See also
https://tools.ietf.org/html/rfc6901
https://tools.ietf.org/html/rfc6902
https://triple-underscore.github.io/RFC6901-ja.html
https://triple-underscore.github.io/RFC6902-ja.html

◆ RemoveMapItem() [1/3]

nn::nlib::msgpack::MpObject::RemoveMapItem ( size_t  n,
MpObjectKv kv 
)
noexcept

Specifies an index and deletes the corresponding key and object in the associative array.

Parameters
[in]nAssociative array index.
[in,out]kvIf not NULL, a pair of the deleted key and value is stored.
Returns
Returns 0 on success. All other values represent an error.

◆ RemoveMapItem() [2/3]

nn::nlib::msgpack::MpObject::RemoveMapItem ( const nlib_utf8_t key,
MpObjectKv kv 
)
noexcept

Specifies a key and deletes the corresponding key and object in the associative array.

Parameters
[in]keyAssociative array key string.
[in,out]kvIf not NULL, a pair of the deleted key and value is stored.
Returns
Returns 0 on success. All other values represent an error.

◆ RemoveMapItem() [3/3]

template<class STDSTRING >
nn::nlib::msgpack::MpObject::RemoveMapItem ( const STDSTRING &  key,
MpObjectKv kv 
)
inlinenoexcept

Specifies a key and deletes the corresponding key and object in the associative array.

Template Parameters
STDSTRINGA type compatible with std::string
Parameters
[in]keyAssociative array key string.
[in,out]kvIf not NULL, a pair of the deleted key and value is stored.
Returns
Returns 0 on success. All other values represent an error.

Definition at line 223 of file MpObject.h.

◆ Resize()

nn::nlib::msgpack::MpObject::Resize ( uint32_t  n)

Resizes an array and associative array.

Parameters
[in]nSize after resizing.
Returns
Returns 0 on success. Any value other than 0 indicates an error.
Description
Sample code is provided below.
// array
SUCCEED_IF(obj.InitArray(10) == 0);
auto ar = obj.AsArray();
nlib_printf("array size: %" PRIuS "\n", ar.GetSize());
SUCCEED_IF(ar.Resize(100) == 0);
nlib_printf("array size: %" PRIuS "\n", ar.GetSize());
ar[99] = 1;
// map
SUCCEED_IF(obj.InitMap(10) == 0);
nlib_printf("map size: %u\n", obj.GetSize());
SUCCEED_IF(obj.Resize(100) == 0);
nlib_printf("map size: %u\n", obj.GetSize());
auto& kv = obj.AsMap()[99];
SUCCEED_IF(kv.first.Box("key") == 0);
SUCCEED_IF(kv.second.Box("value") == 0);
// string
SUCCEED_IF(obj.InitString("mystring") == 0);
e = obj.Resize(100);
nlib_printf("cannot resize string: err=%s\n", nlib_error_string(e));
// binary
SUCCEED_IF(obj.InitBinary("test", 4) == 0);
e = obj.Resize(100);
nlib_printf("cannot resize binary: err=%s\n", nlib_error_string(e));
/*
Output:
array size: 10
array size: 100
map size: 10
map size: 100
cannot resize string: err=EACCES
cannot resize binary: err=EACCES
*/

◆ ResolveJsonPointer()

nn::nlib::msgpack::MpObject::ResolveJsonPointer ( MpObject **  result,
MpObject root,
const nlib_utf8_t json_pointer 
)
staticnoexcept

Stores MpObject referenced by json_pointer in *result.

Parameters
[in,out]resultAn object referenced by json_pointer.
[in]rootA root object that serves as the starting point for reference with json_pointer.
[in]json_pointerJSON pointer string.
Return values
0if successful.
EINVALIndicates that result, root, or json_pointer is NULL.
EILSEQIndicates that the syntax for json_pointer is incorrect.
ENOENTIndicates that the object referenced by json_pointer cannot be found.
Description
Obtains MpObject by drilling down the JSON tree structure based on a string defined by JSON Pointer (RFC6901). A string comprising strings delimited with '/' is called a reference token, which specifies a location in JSON with a string resembling a file path.
The following shows a program that displays a partial JSON string by using JSON Pointer from JSON:
const char* json = R"({
"foo": ["bar", "baz"],
"": 0,
"a/b": 1,
"c%d": 2,
"e^f": 3,
"g|h": 4,
"i\\j": 5,
"k\"l": 6,
" ": 7,
"m~n": 8
})";
auto obj = ToMpObject(json);
const char* json_pointers[] = {
"", "/foo", "/foo/0", "/", "/a~1b", "/c%d", "/e^f", "/g|h", "/i\\j", "/k\"l", "/ ", "/m~0n"
};
for (auto& str : json_pointers) {
SUCCEED_IF(MpObject::ResolveJsonPointer(&target, obj.get(), str) == 0);
ToJson(buf, *target);
nlib_printf("Resolve('%s') --> %s\n", str, buf);
}
/*
Output:
Resolve('') --> {"foo":["bar","baz"],"":0,"a\/b":1,"c%d":2,"e^f":3,"g|h":4,"i\\j":5,"k\"l":6," ":7,"m~n":8}
Resolve('/foo') --> ["bar","baz"]
Resolve('/foo/0') --> "bar"
Resolve('/') --> 0
Resolve('/a~1b') --> 1
Resolve('/c%d') --> 2
Resolve('/e^f') --> 3
Resolve('/g|h') --> 4
Resolve('/i\j') --> 5
Resolve('/k"l') --> 6
Resolve('/ ') --> 7
Resolve('/m~0n') --> 8
*/
For more information, see the RFC:
See also
https://tools.ietf.org/html/rfc6901
https://triple-underscore.github.io/RFC6901-ja.html

◆ Unbox() [1/3]

template<class T , size_t n>
nn::nlib::msgpack::MpObject::Unbox ( T(&)  a[n]) const
inline

Unboxes the object value.

Parameters
[out]aArray to store the unboxed data.
Template Parameters
TType of object after being unboxed.
nNumber of elements in the array.
Returns
Returns 0 on success.
Description
Unboxing behavior differs depending on the data type of T. The following table illustrates the difference in behavior.
Type of T Descr
nlib_utf8_t Objects of the MpObject::kString type are unboxed to strings. Space to store the terminating null character is required.
All others Boxed into an MpObject::kArray type as an array.
Sample code is provided below.
// Unbox byte data array.
unsigned char data[N];
MpObject mpobj;
....
mpobj.Unbox(&data[0], N);

Definition at line 297 of file MpObject.h.

◆ Unbox() [2/3]

template<class T>
errno_t nn::nlib::msgpack::MpObject::Unbox ( T *  a,
size_t  n 
) const

Unboxes the array data.

Template Parameters
TType of the pointer to the object the unboxed array data is written to.
Parameters
[out]aPointer to the object the unboxed data is written to.
[in]nNumber of elements.
Returns
Returns 0 on success. Nonzero when the type is incorrect or an overflow has occurred.
Description
Type of T Descr
void Unboxed as byte array data.
nlib_utf8_t Unboxed as character string data. A null character is added, and requires space for null termination.
Others Unboxed as an array of objects.

Definition at line 1295 of file MpObject.h.

◆ Unbox() [3/3]

template<class T >
nn::nlib::msgpack::MpObject::Unbox ( v) const
inline

Unboxes the object.

Template Parameters
TType of the pointer to the object the unboxed data is written to.
Parameters
[out]vPointer to the object the unboxed data is written to.
Returns
Returns 0 on success. All other values are an error.
Description
Unboxes a dynamic object and converts it to a static object. Returns a nonzero value when unboxing fails.
Behavior differs according to the type of T. The following table illustrates the difference in behavior.
Type of T Description
bool* Stored as bool if the type is MpObject::kBoolean.
Pointer to an integer Stores as an integer if the type is MpObject::kInt64 or MpObject::kUint64. Does not check for overflows.
float*, double* Stores a float value if the types are MpObject::kFloat or MpObject::kDouble. Does not check for overflows.
std::string* Set as string object if the type is MpObject::kString. Returns ENOMEM if an exception occurs in assigning the string.
std::vector* Stores a vector object if the type is MpObject::kArray. Returns ENOMEM if an exception occurs while resizing the vector.
Nlist* Stores an Nlist object if the type is MpObject::kArray. Returns ENOMEM when there is insufficient memory.
std::pair* Stores a pair object if the type is MpObject::kArray and has a size of 2-.
std::map* Stores a map object if the type is MpObject::kMap. Returns ENOMEM if an exception occurs when adding a map element.
std::array* Stores an array object if the type is MpObject::kArray.
std::tuple* Stores a tuple object if the type is MpObject::kArray.
std::unordered_map* Stores an unordered_map object if the type is MpObject::kMap. Returns ENOMEM if an exception occurs when adding a unordered_map element.
Returns EACCESS when conversion to any type is not possible. If unboxing an array or similar type fails, the conversion results up to the failure are stored. Unboxing to a user-defined data type follows the specification of the type's unboxing function.
Arrays are unboxed as arrays, except for nlib_utf8_t-type arrays. A nlib_utf8_t array is unboxed as a string.
Sample code is provided below.
int intval;
MpObject intobj = 1;
intobj.Unbox(&intval);
NLIB_ASSERT(intval == 1);
std::vector<int> vec;
auto x = JsonStreamParser::Parse("[1, 2, 3, 4, 5]");
SUCCEED_IF(x.first == 0);
x.second->Unbox(&vec);
NLIB_ASSERT(vec.size() == 5);

Definition at line 316 of file MpObject.h.


The documentation for this class was generated from the following files: