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 {
  NIL = 0,
  BOOLEAN,
  UINT64,
  INT64,
  FLOAT,
  DOUBLE,
  RAW,
  ARRAY,
  MAP
}
 Data type of the object stored in MpObject. More...
 

Public Member Functions

errno_t Resize (uint32_t n)
 Resizes the array, associative array, or Raw data (string). More...
 
MpObjectClone () noexcept
 Creates a duplicate of the object. More...
 
uint32_t GetSize () const noexcept
 Returns the size of the array, associative array, or Raw data (string). More...
 
Using the ARRAY 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 same as GetArrayItem(size_t n).
 
MpObjectoperator[] (size_t n)
 For an array, returns a reference to an element of the array. More...
 
MpObjectSwapArrayItem (size_t n, MpObject *obj) noexcept
 Swaps the content of obj and the content of the object within an 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 same as GetArrayItem(size_t n, MpObject** obj).
 
errno_t InitArray (uint32_t n) noexcept
 Initializes as an object with an n element array. More...
 
Using the Associative Array Type (MAP Type)
MpObjectGetMapItem (const char *str) noexcept
 Specifies a string and gets the object in the associative array. More...
 
const MpObjectGetMapItem (const char *str) const noexcept
 The same as GetMapItem(const char* str).
 
MpObjectGetMapItem (const std::string &str) noexcept
 Specifies a string and gets the object in the associative array. More...
 
const MpObjectGetMapItem (const std::string &str) const noexcept
 The same as GetMapItem(const std::string& str).
 
MpObjectSwapMapItem (const std::string &key, MpObject *obj) noexcept
 Swaps the content of obj and the content of the object within an associative array. More...
 
MpObjectSwapMapItem (const char *str, MpObject *obj) noexcept
 Swaps the content of obj and the content of the object within an associative array. More...
 
MpObjectAppendArrayItem () noexcept
 Adds an element to the end if the object is storing an 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 same as GetMapItem(size_t n, MpObjectKv** obj).
 
errno_t InitMap (uint32_t n) noexcept
 Initializes the object as an n element associative array. More...
 
Basic Member Functions
 MpObject () noexcept
 Instantiates the object with default parameters (default constructor). Set to the nil type.
 
 ~MpObject () noexcept
 Destructor.
 
MpObjectassign (MpObject &rhs, move_tag)
 Assigns the object by using swap for a move.
 
 MpObject (MpObject &rhs, move_tag)
 Instantiates the object by using swap for a move.
 
 MpObject (MpObject &&rhs)
 Instantiates the object (move constructor). This function is useful when using C++11.
 
MpObjectoperator= (MpObject &&rhs)
 Move assignment operator. This function is useful when using C++11.
 
template<class T >
 MpObject (const T &x)
 The constructor for boxing a T-type object. More...
 
void swap (MpObject &rhs) noexcept
 Swaps the content of the object. More...
 
Using the Byte Array Type (RAW Type)
void * GetRaw ()
 Gets the byte array from the object. More...
 
const void * GetRaw () const
 The same as GetRaw.
 
errno_t InitRaw (uint32_t n) noexcept
 Initializes the object as an n byte region. More...
 
errno_t InitRaw (const void *p, uint32_t n) noexcept
 Initializes the object as an n byte region copied from the p parameter. More...
 
Boxing

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

errno_t Box (const char *str) noexcept
 Boxes the string. More...
 
template<uint32_t n>
errno_t Box (const char(&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...
 
errno_t Box (const void *p, uint32_t n) noexcept
 Boxes the byte array. 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 (char(&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 (char *str, size_t n) const noexcept
 See the description of Unbox(T* a, size_t n).
 
errno_t Unbox (void *p, 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. More...
 
bool IsBoolean () const noexcept
 Determines whether the stored value is a boolean. More...
 
bool IsInteger () const noexcept
 Determines whether the stored value is an integer. More...
 
bool IsFloat () const noexcept
 Determines whether the stored value is a single precision float. More...
 
bool IsDouble () const noexcept
 Determines whether the stored value is a double. More...
 
bool IsRaw () const noexcept
 Determines whether the stored value is a byte string (character string). More...
 
bool IsArray () const noexcept
 Determines whether the stored value is an array. More...
 
bool IsMap () const noexcept
 Determines whether the stored value is an associative array. 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.
struct UserType {
....
};
template<> errno_t Box(MpObject* obj, const UserType& v) {
// UserType can be mapped to MpObject in a variety of methods.
// - Write the values in order.
// - Write the variable name and value as an associative array.
// - Write with metadata such as version numbers.
// - etc.
// Implement in a way that accounts for reading using Unbox.
....
}
template<> errno_t Unbox(const MpObject* obj, UserType* v) {
....
}
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 83 of file MpObject.h.

Member Enumeration Documentation

Data type of the object stored in MpObject.

Description
Obtained by using GetType.
Enumerator
NIL 

Represents a nil type.

BOOLEAN 

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

UINT64 

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

INT64 

Represents an integer type. The internal representation is int64_t.

FLOAT 

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

DOUBLE 

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

RAW 

Respresents a byte array (string).

ARRAY 

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

MAP 

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

Definition at line 230 of file MpObject.h.

Constructor & Destructor Documentation

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

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 141 of file MpObject.h.

Member Function Documentation

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

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

Returns
If successful, returns the pointer to the added element. NULL if process fails.
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.
nn::nlib::msgpack::MpObject::Box ( const char *  str)
noexcept

Boxes the string.

Parameters
[in]strString.
Returns
Returns 0 on success. All other values are an error.
Description
Strings are stored as RAW type data.
template<uint32_t n>
errno_t nn::nlib::msgpack::MpObject::Box ( const char(&)  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 RAW type data.

Definition at line 720 of file MpObject.h.

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 Description
char Characters up to the NULL character are boxed in an MpObject::RAW type as a string.
All others Boxed into an MpObject::ARRAY type as an array.

Definition at line 729 of file MpObject.h.

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 Description
nil Stored as an MpObject::NIL type. This process never returns an error.
bool Stored as an MpObject::BOOLEAN type. This process never returns an error.
Signed IntegerStored as an MpObject::INT64 type. This process never returns an error.
Unsigned IntegerStored as an MpObject::UINT64 type. This process never returns an error.
float Stored as an MpObject::FLOAT type. This process never returns an error.
double Stored as an MpObject::DOUBLE type. This process never returns an error.
std::string Stored as an MpObject::RAW type.
std::vector Stored as an MpObject::ARRAY type.
Nlist Stored as an MpObject::ARRAY type.
std::pair Stored as an MpObject::ARRAY type with a size of 2.
std::map Stored as an MpObject::ARRAY type.
std::array Stored as an MpObject::ARRAY type.
std::tuple Stored as an MpObject::ARRAY type.
std::unordered_map Stored as an MpObject::ARRAY type.
Arrays are boxed as arrays, except for char type arrays. A char array is boxed as a string.
std::vector<int> intvec;
int a[...];
char str[...];
...
mpObj.Box(1); // Boxes value 1.
mpObj.Box(intvec); // Boxed into an array.
mpObj.Box(a); // Boxed into an array.
mpObj.Box(str); // Boxed into an array.

Definition at line 176 of file MpObject.h.

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

Boxes the byte array.

Parameters
[in]pPointer to the byte array to be boxed.
[in]nSize of the byte array.
Returns
Returns 0 on success. All other values are an error.
Description
Boxes a byte array, and converts it to a dynamic object. A nonzero value is returned if the boxing fails to allocate dynamic memory. A byte array less than 8 bytes long is directly stored without dynamically allocating memory, making it immune to errors.
nn::nlib::msgpack::MpObject::Clone ( )
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.
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 96 of file MpObject.h.

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.
nn::nlib::msgpack::MpObject::GetMapItem ( const char *  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 (MpObjectKv).
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.
nn::nlib::msgpack::MpObject::GetMapItem ( const std::string &  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 (MpObjectKv).
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.
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]objPointer that stores the pointer to the object (MpObjectKv).
Returns
Returns 0 on success. All other values are an error.
nn::nlib::msgpack::MpObject::GetRaw ( )
inline

Gets the byte array from the object.

Returns
Pointer to the byte data array (string).
Description
Returns NULL when the data stored in the object is not a byte array.

Definition at line 150 of file MpObject.h.

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

Returns the size of the array, associative array, or Raw data (string).

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

Definition at line 247 of file MpObject.h.

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

Returns the object type.

Returns
Object type.

Definition at line 244 of file MpObject.h.

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.
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.
nn::nlib::msgpack::MpObject::InitRaw ( uint32_t  n)
noexcept

Initializes the object as an n byte region.

Parameters
[in]nSize of the byte data array (string) to initialize.
Returns
Returns 0 on success. All other values are an error.
Description
Specifies a byte count that does not include the terminating null character.
nn::nlib::msgpack::MpObject::InitRaw ( const void *  p,
uint32_t  n 
)
noexcept

Initializes the object as an n byte region copied from the p parameter.

Parameters
[in]pThe data region to initialize.
[in]nSize of the byte data array (string) to initialize.
Returns
Returns 0 on success. All other values are an error.
nn::nlib::msgpack::MpObject::IsArray ( ) const
inlinenoexcept

Determines whether the stored value is an array.

Returns
true if the value is an array.

Definition at line 259 of file MpObject.h.

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

Determines whether the stored value is a boolean.

Returns
true if the value is boolean.

Definition at line 251 of file MpObject.h.

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

Determines whether the stored value is a double.

Returns
true if the value is a double precision float.

Definition at line 257 of file MpObject.h.

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

Determines whether the stored value is a single precision float.

Returns
true if the value is a single precision float.

Definition at line 256 of file MpObject.h.

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

Determines whether the stored value is an integer.

Returns
true if the value is an integer.

Definition at line 252 of file MpObject.h.

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

Determines whether the stored value is an associative array.

Returns
true if the value is an associative array.

Definition at line 260 of file MpObject.h.

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

Determines whether the stored value is nil.

Returns
true if the value is nil.

Definition at line 250 of file MpObject.h.

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

Determines whether the stored value is a byte string (character string).

Returns
true if it is a byte string (character string).

Definition at line 258 of file MpObject.h.

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.
mpObj = 1; // Same as mpObj.box(1).
mpObj = 1.2f; // Same as mpObj.box(1.2f).
mpObj = "abc"; // error: This code is an example of a bad implementation. Avoid using code like this.

Definition at line 213 of file MpObject.h.

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 104 of file MpObject.h.

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

Resizes the array, associative array, or Raw data (string).

Parameters
[in]nSize after resizing.
Returns
Returns 0 on success. Any value other than 0 indicates an error.
Description
// When you want to set an obj separately generated to mpOnj.
mpObj.swap(obj); // A swap that places the contents of mpObj in obj.
nn::nlib::msgpack::MpObject::swap ( MpObject rhs)
inlinenoexcept

Swaps the content of the object.

Parameters
[in,out]rhsObject to swap.
Description
MpObject does not have a defined copy constructor or assignment operator, and requires using swap to set the object.

Definition at line 219 of file MpObject.h.

nn::nlib::msgpack::MpObject::SwapArrayItem ( size_t  n,
MpObject obj 
)
inlinenoexcept

Swaps the content of obj and the content of the object within an array.

Parameters
[in]nThe array index.
[in,out]objPointer to the object to swap.
Returns
Pointer to the object within the array.
Description
MpObject does not have a defined copy constructor or assignment operator, and requires using swap to set the object. The return value is the pointer to the object in the array. (It contains the original content of the obj parameter.) NULL is returned if the corresponding element of the array does not exist.

Definition at line 114 of file MpObject.h.

nn::nlib::msgpack::MpObject::SwapMapItem ( const std::string &  key,
MpObject obj 
)
inlinenoexcept

Swaps the content of obj and the content of the object within an associative array.

Parameters
[in]keyKey string.
[in,out]objPointer to the object to swap.
Returns
Pointer to the object within the associative array.
Description
MpObject does not have a defined copy constructor or assignment operator, and requires using swap to set the object. The return value is the pointer to the object in the array. (It contains the original content of the obj parameter.) NULL is returned if the corresponding element of the associative array does not exist.

Definition at line 119 of file MpObject.h.

nn::nlib::msgpack::MpObject::SwapMapItem ( const char *  key,
MpObject obj 
)
inlinenoexcept

Swaps the content of obj and the content of the object within an associative array.

Parameters
[in]keyKey string.
[in,out]objPointer to the object to swap.
Returns
Pointer to the object within the associative array.
Description
MpObject does not have a defined copy constructor or assignment operator, and requires using swap to set the object. The return value is the pointer to the object in the array. (It contains the original content of the obj parameter.) NULL is returned if the corresponding element of the associative array does not exist.

Definition at line 125 of file MpObject.h.

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 Description
char Objects of the MpObject::RAW type are unboxed to strings. Space to store the terminating null character is required.
All others Boxed into an MpObject::ARRAY 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 183 of file MpObject.h.

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 Description
void Unboxed as byte array data.
char 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 757 of file MpObject.h.

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::BOOLEAN.
Pointer to an integer Stores as an integer if the type is MpObject::INT64 or MpObject::UINT64. Does not check for overflows.
float*, double* Stores a float value if the types are MpObject::FLOAT or MpObject::DOUBLE. Does not check for overflows.
std::string* Set as string object if the type is MpObject::RAW. Returns ENOMEM if an exception occurs in assigning the string.
std::vector* Stores a vector object if the type is MpObject::ARRAY. Returns ENOMEM if an exception occurs while resizing the vector.
Nlist* Stores an Nlist object if the type is MpObject::ARRAY. Returns ENOMEM when there is insufficient memory.
std::pair* Stores a pair object if the type is MpObject::ARRAY and has a size of 2-.
std::map* Stores a map object if the type is MpObject::MAP. Returns ENOMEM if an exception occurs when adding a map element.
std::array* Stores an array object if the type is MpObject::ARRAY.
std::tuple* Stores a tuple object if the type is MpObject::ARRAY.
std::unordered_map* Stores an unordered_map object if the type is MpObject::MAP. 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 char-type arrays. A char array is unboxed as a string.
// Unbox integer.
int intval;
MpObject mpobj = 1;
mpobj.Unbox(&intval); // intval == 1
// Unbox array vector.
vector<int> vec;
MpObject mpobj;
JsonReader::Read(&mpobj, "[1, 2, 3, 4, 5]");
mpobj.Unbox(&vec); // Stored in std::vector.

Definition at line 201 of file MpObject.h.


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