nlib
nn::nlib::msgpack Namespace Reference

The library used to implement the MessagePack serializer, the JSON parser/writer, and the CSV parser. More...

Namespaces

 jsonrpc
 Implements JSON-RPC 2.0.
 

Classes

class  CsvReader
 CSV parser. Reads and parses the CSV string from the stream. More...
 
class  JsonReader
 JSON parser. Reads and parses the JSON string from the stream. More...
 
struct  JsonReaderSettings
 Data structure used to store the JsonReader settings parameters. More...
 
class  JsonWriter
 JSON generator. Converts an MpObject to JSON and writes it to the stream. More...
 
class  MpObject
 Object created when MessagePack or JSON is read. More...
 
struct  MpObjectKv
 A pair consisting of an MpObject-type key and value. Used to store an associative array. More...
 
class  MpReader
 Reads the MessagePack-formatted data from the stream. More...
 
struct  MpReaderSettings
 Data structure used to store the MpReader settings parameters. More...
 
class  MpWalker
 Quickly accesses MessagePack expanded in memory. More...
 
class  MpWriter
 Writes the MessagePack formatted data to the stream. More...
 
struct  nil
 Class that corresponds to nil in MessagePack and null in JSON. More...
 

Functions

template<class T >
bool operator== (const nil &lhs, const T &rhs) noexcept
 Returns false if rhs is a non-nil object.
 
template<class T >
bool operator== (const T &lhs, const nil &rhs) noexcept
 Returns false if lhs is a non-nil object.
 
bool operator== (const nil &lhs, const nil &rhs) noexcept
 Returns true.
 
template<class T >
bool operator!= (const nil &rhs, const T &lhs) noexcept
 Returns true if rhs is a non-nil object.
 
template<class T >
bool operator!= (const T &rhs, const nil &lhs) noexcept
 Returns true if lhs is a non-nil object.
 
bool operator!= (const nil &rhs, const nil &lhs) noexcept
 Returns false.
 
bool operator== (const MpObjectKv &lhs, const MpObjectKv &rhs) noexcept
 Recursively compares lhs and rhs and returns true if they are equal.
 
bool operator!= (const MpObject &lhs, const MpObject &rhs) noexcept
 Recursively compares lhs and rhs and returns false if they are equal.
 
bool operator!= (const MpObjectKv &lhs, const MpObjectKv &rhs) noexcept
 Recursively compares lhs and rhs and returns false if they are equal.
 
template<class T1 , class T2 >
bool MpRead (MpReader *r, std::pair< T1, T2 > *v)
 Reads the data into pair.
 
template<class T , class Alloc >
bool MpRead (MpReader *r, std::vector< T, Alloc > *v)
 Reads the data into vector.
 
template<class T , class Alloc >
bool MpRead (MpReader *r, Nlist< T, Alloc > *v)
 Reads the data into Nlist.
 
template<class K , class V , class Pr , class Alloc >
bool MpRead (MpReader *r, std::map< K, V, Pr, Alloc > *m)
 Reads the data into map.
 
template<class T1 , class T2 >
uint32_t uint64_t nlib_ulong_compatible_t bool MpWrite (MpWriter *w, const std::pair< T1, T2 > &v)
 Writes the contents of v via MpWriter.
 
bool MpWrite (MpWriter *w, const char *str)
 Writes str via MpWriter.
 
template<class T , class Alloc >
bool MpWrite (MpWriter *w, const std::vector< T, Alloc > &vec)
 Writes vec via MpWriter.
 
template<class T , class Alloc >
bool MpWrite (MpWriter *w, const Nlist< T, Alloc > &vec)
 Writes vec via MpWriter.
 
template<class K , class V , class Pr , class Alloc >
bool MpWrite (MpWriter *w, const std::map< K, V, Pr, Alloc > &m)
 Writes m via MpWriter.
 
MpObject

Free function that handles MpObject.

template<class T >
errno_t Box (MpObject *obj, const T &v)
 This function template can be specialized to define boxing the user type. More...
 
template<class T >
errno_t Unbox (const MpObject *obj, T *v)
 This function template can be specialized to define unboxing the user type. More...
 
bool operator== (const MpObject &lhs, const MpObject &rhs)
 The two MpObjects are recursively compared. Returns true if they are equivalent. More...
 
MpRead

Free function that handles MpReader.

template<class T >
bool MpRead (MpReader *obj, T *v)
 This function template can be made special to define unboxing the user type. More...
 
MpWrite

Free function that handles MpWriter.

template<class T >
bool MpWrite (MpWriter *obj, const T &v)
 This function template can be specialized to define serializing a user type. More...
 

Detailed Description

The library used to implement the MessagePack serializer, the JSON parser/writer, and the CSV parser.

About MessagePack

MessagePack(http://msgpack.org/) is one format for binary-based object serialization. MessagePack can make data transfers smaller, faster, and more flexible. The data format is similar to JSON translated into binary. MessagePack is commonly used to speed up JSON processing. Like JSON, MessagePack can be written and read in various environments such as Perl, Python, and Ruby. As a result, MessagePack can be used to communicate between different environments and languages.

About This Library

nn::nlib::msgpack contains the serializer and deserializer, the JSON parser, and the JSON generator that supports MessagePack. MessagePack data and JSON data is converted into the same data format after being read. This allows you to read JSON data and save it as MessagePack, or vice versa.

About the Compatibility of the JSON Parser With RFC 4627

This section describes the compatabilty of this library's JSON parser with the RFC 4627 reference design. JSON is defined in RFC 4627 https://tools.ietf.org/html/rfc4627.html).
About encoding
RFC 4627 defines the ability to understand UTF-8, UTF-16, and UTF-32. The ::msgpack library only understands UTF-8.
About strings containing null characters
Strings that contain null characters, such as "A\u0000Z", do not cause a parsing error. This behavior is as defined in the RFC, but reading the same string as a C character string produces "A".
About values
JSON does not distinguish real numbers from integers, but attempts to read values in the order of unsigned integer (uint64_t), signed integer (int64_t), and floating point value (double). Any value that is over 19 digits long, not including the sign, is read as a floating point type. Reading the actual value is implemented using the nn::nlib::StrTo function.
We suggest handling values as strings instead of numerical values, as different JSON processors may not have uniform behavior handling very large values in JSON.

Reference Materials

Reference materials are linked below.
RFCs and Other References

Function Documentation

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

This function template can be specialized to define boxing the user type.

Template Parameters
TType of object to be boxed.
Parameters
[in]objObject to store the boxed data.
[in]vObject to be boxed.
Returns
Returns 0 on success.
Description
The boxing behavior can be customized using MpObject.
The following list describes implementation notes.
  • obj is passed a non-NULL value.
  • 0 must be returned when boxing is successful, and a non-zero value must be returned when it is not successful.
  • While it is possible to recursively box from this function, the return value error check must be made.
template<class T >
nn::nlib::msgpack::MpRead ( MpReader obj,
T *  v 
)

This function template can be made special to define unboxing the user type.

Template Parameters
TThe ype of user-defined object being deserialized.
Parameters
[in]objPointer to the MpReader object.
[out]vUser-defined object to be deserialized.
Returns
Returns true when successful.
template<class T >
nn::nlib::msgpack::MpWrite ( MpWriter obj,
const T &  v 
)

This function template can be specialized to define serializing a user type.

Template Parameters
TThe type of user-defined object being serialized.
Parameters
[in]objPointer to the MpWriter object.
[in]vObject being boxed.
Returns
Returns true when successful.
Description
The behavior of MpWriter can be customized by specializing this function template.
The following list describes implementation notes.
  • obj is passed a non-NULL value.
  • Must return true when serialization is successful, and false when it is not.
  • While it is possible to recursively serialize from this function, the return value error check must be made.
nn::nlib::msgpack::operator== ( const MpObject lhs,
const MpObject rhs 
)

The two MpObjects are recursively compared. Returns true if they are equivalent.

Recursively compares lhs and rhs and returns true if they are equal.

Parameters
[in]lhsMpObject being compared.
[in]rhsMpObject being compared.
Returns
true if they are equivalent.
Description
Usage notes are described below.
  • Slower than comparing static objects.
  • Associative arrays are not equivalent if the key order is different.
  • An error is not considered when comparing floating point types.
template<class T >
nn::nlib::msgpack::Unbox ( const MpObject obj,
T *  v 
)

This function template can be specialized to define unboxing the user type.

Template Parameters
TObject to store the data that has been unboxed.
Parameters
[in]objObject that stores the boxed data.
[in]vObject to store the unboxed data.
Returns
Returns 0 on success.
Description
The following list describes implementation notes.
  • obj and v are passed a non-NULL value.
  • 0 must be returned when unboxing is successful, and a non-zero value must be returned when it is not successful.
  • While it is possible to recursively unbox from this function, the return value error check must be made.
  • Implement in a way that does not depend on the key order when unboxing an associative array.