nlib
nn::nlib::msgpack::JsonStreamGenerator Class Referencefinal

The class for outputting JSON or msgpack. More...

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

Public Member Functions

errno_t Open (OutputStream *stream) noexcept
 Specifies a stream and starts generating data. More...
 
bool Flush () noexcept
 Writes data to the stream and flushes the stream. More...
 
errno_t Close () noexcept
 Closes the generator and sets it to the state immediately after it is initialized. More...
 
JsonStreamGeneratorNull () noexcept
 Outputs null. More...
 
JsonStreamGeneratorBoolean (bool value) noexcept
 Outputs true or false. More...
 
JsonStreamGeneratorInt8 (int8_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorUint8 (uint8_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorInt16 (int16_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorUint16 (uint16_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorInt32 (int32_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorUint32 (uint32_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorInt64 (int64_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorUint64 (uint64_t num) noexcept
 Outputs an integer value. More...
 
JsonStreamGeneratorFloat (float num) noexcept
 Outputs a floating-point number. More...
 
JsonStreamGeneratorDouble (double num) noexcept
 Outputs a floating-point number. More...
 
JsonStreamGeneratorString (const nlib_utf8_t *str) noexcept
 Outputs a string. More...
 
JsonStreamGeneratorBinary (const void *bin, size_t n) noexcept
 Outputs binary data. Currently, only outputting msgpack is supported. More...
 
JsonStreamGeneratorExt (int8_t tp, const void *bin, size_t n) noexcept
 Outputs extended data. More...
 
JsonStreamGeneratorTimestamp (nlib_time t) noexcept
 Outputs a timestamp. For JSON, it is output as a string. More...
 
JsonStreamGeneratorObject (const MpObject &obj) noexcept
 Outputs MpObject. More...
 
Constructor, Destructor, and Initialization
constexpr JsonStreamGenerator () noexcept
 Instantiates the object with default parameters (default constructor).
 
 ~JsonStreamGenerator () noexcept
 Destructor.
 
 JsonStreamGenerator (JsonStreamGenerator &&rhs)
 Instantiates the object (move constructor).
 
JsonStreamGeneratoroperator= (JsonStreamGenerator &&rhs)
 Move assignment operator.
 
void Reset () noexcept
 Resets this object to the state immediately after the default constructor was executed.
 
errno_t Init (const JsonStreamGeneratorSettings &settings) noexcept
 Initializes by specifying the behavior option. Returns 0 if successful. More...
 
errno_t Init () noexcept
 A parameter omitted version of the above function which passes settings as the default value.
 
Outputting Arrays
JsonStreamGeneratorStartArray (size_t count) noexcept
 Starts outputting the array. More...
 
JsonStreamGeneratorEndArray () noexcept
 Finishes the array. More...
 
JsonStreamGeneratorEmptyArray () noexcept
 Outputs an empty array. More...
 
JsonStreamGeneratorInt8Array (const int8_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorUint8Array (const uint8_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorInt16Array (const int16_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorUint16Array (const uint16_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorInt32Array (const int32_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorUint32Array (const uint32_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorInt64Array (const int64_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorUint64Array (const uint64_t *p, size_t count) noexcept
 Outputs an integer array. More...
 
JsonStreamGeneratorFloatArray (const float *p, size_t count) noexcept
 Outputs a single-precision floating point number array. More...
 
JsonStreamGeneratorDoubleArray (const double *p, size_t count) noexcept
 Outputs a double-precision floating point number array. More...
 
Outputting Associative Arrays
JsonStreamGeneratorStartMap (size_t count) noexcept
 Starts outputting the map. More...
 
JsonStreamGeneratorKey (const nlib_utf8_t *key) noexcept
 Outputs keys for the associative array. More...
 
JsonStreamGeneratorEndMap () noexcept
 Finishes the map. More...
 
JsonStreamGeneratorEmptyMap () noexcept
 Outputs an empty map. More...
 
Error Checking
Error GetError () const noexcept
 Gets an error. More...
 
 operator bool () const
 Returns true if the object has been initialized and an error has not occurred inside, or returns false if an error has occurred inside.
 

Static Public Member Functions

static errno_t Generate (size_t *written, nlib_utf8_t *str, size_t n, const MpObject &obj, const JsonStreamGeneratorSettings &settings) noexcept
 Outputs the content of obj in JSON or msgpack. More...
 
static errno_t Generate (size_t *written, nlib_utf8_t *str, size_t n, const MpObject &obj) noexcept
 A parameter omitted version of the above function which passes settings as the default value.
 
template<size_t N>
static errno_t Generate (size_t *written, nlib_utf8_t(&str)[N], const MpObject &obj, const JsonStreamGeneratorSettings &settings) noexcept
 A template overload of the above function.
 
template<size_t N>
static errno_t Generate (size_t *written, nlib_utf8_t(&str)[N], const MpObject &obj) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > Generate (nlib_utf8_t *str, size_t n, const MpObject &obj, const JsonStreamGeneratorSettings &settings) noexcept
 Outputs the content of obj in JSON or msgpack. More...
 
template<size_t N>
static std::pair< errno_t, size_t > Generate (nlib_utf8_t(&str)[N], const MpObject &obj, const JsonStreamGeneratorSettings &settings) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > Generate (nlib_utf8_t *str, size_t n, const MpObject &obj) noexcept
 A parameter omitted version of the above function which passes settings as the default value.
 
template<size_t N>
static std::pair< errno_t, size_t > Generate (nlib_utf8_t(&str)[N], const MpObject &obj) noexcept
 A template overload of the above function.
 

Detailed Description

The class for outputting JSON or msgpack.

Description
After finishing initialization, writing a method chain with the following code allow JSON or msgpack to be output.
// make {"key1" : "value", "key2" : [1,2,3], "key3" : [true, null]}
MemoryOutputStream stream(buf);
SUCCEED_IF(gen.Init() == 0);
SUCCEED_IF(gen.Open(&stream) == 0);
gen.StartMap(3);
gen.Key("key1").String("value");
gen.Key("key2").StartArray(3).Int32(1).Int32(2).Int32(3).EndArray();
gen.Key("key3").StartArray(2).Boolean(true).Null().EndArray();
gen.EndMap();
SUCCEED_IF(gen.Close() == 0);
size_t n = stream.Pos();
SUCCEED_IF(stream.Close());
buf[n] = '\0'; // note that JsonStreamGenerator does not append '\0'
nlib_printf("%s\n", buf);
/*
Output:
{"key1":"value","key2":[1,2,3],"key3":[true,null]}
*/
It is also possible to easily output it from MpObject by using a static member function.
auto r = JsonStreamGenerator::Generate(buf, obj);
SUCCEED_IF(r.first == 0);
nlib_printf("output size = %" PRIdS "\n", r.second);
nlib_printf("%s\n", buf);
/*
Output:
output size = 50
{"key1":"value","key2":[1,2,3],"key3":[true,null]}
*/

Definition at line 42 of file JsonStreamGenerator.h.

Member Function Documentation

◆ Binary()

nn::nlib::msgpack::JsonStreamGenerator::Binary ( const void *  bin,
size_t  n 
)
noexcept

Outputs binary data. Currently, only outputting msgpack is supported.

Parameters
[in]binBinary data.
[in]nSize of the binary data.
Returns
JsonStreamGenerator object.
See also
https://github.com/msgpack/msgpack/blob/master/spec.md#formats-bin

◆ Boolean()

nn::nlib::msgpack::JsonStreamGenerator::Boolean ( bool  value)
noexcept

Outputs true or false.

Parameters
[in]valueA boolean value.
Returns
JsonStreamGenerator object.

◆ Close()

nn::nlib::msgpack::JsonStreamGenerator::Close ( )
noexcept

Closes the generator and sets it to the state immediately after it is initialized.

Return values
0Success.
EINVALOpen() is not running.
Othererrors the stream returns.
Description
The stream is flushed when closing the generator, but the stream is not closed.

◆ Double()

nn::nlib::msgpack::JsonStreamGenerator::Double ( double  num)
noexcept

Outputs a floating-point number.

Parameters
[in]numA double-precision floating-point number.
Returns
JsonStreamGenerator object.

◆ DoubleArray()

nn::nlib::msgpack::JsonStreamGenerator::DoubleArray ( const double *  p,
size_t  count 
)
noexcept

Outputs a double-precision floating point number array.

Parameters
[in]pPointer to a double-precision floating point number array.
[in]countNumber of double-precision floating point numbers.
Returns
JsonStreamGenerator object.

◆ EmptyArray()

nn::nlib::msgpack::JsonStreamGenerator::EmptyArray ( )
inlinenoexcept

Outputs an empty array.

Returns
JsonStreamGenerator object.

Definition at line 149 of file JsonStreamGenerator.h.

◆ EmptyMap()

nn::nlib::msgpack::JsonStreamGenerator::EmptyMap ( )
inlinenoexcept

Outputs an empty map.

Returns
JsonStreamGenerator object.

Definition at line 150 of file JsonStreamGenerator.h.

◆ EndArray()

nn::nlib::msgpack::JsonStreamGenerator::EndArray ( )
noexcept

Finishes the array.

Returns
JsonStreamGenerator object.

◆ EndMap()

nn::nlib::msgpack::JsonStreamGenerator::EndMap ( )
noexcept

Finishes the map.

Returns
JsonStreamGenerator object.

◆ Ext()

nn::nlib::msgpack::JsonStreamGenerator::Ext ( int8_t  tp,
const void *  bin,
size_t  n 
)
noexcept

Outputs extended data.

Parameters
[in]tpExtended data type.
[in]binBinary data.
[in]nSize of the binary data.
Returns
JsonStreamGenerator object.
Description
When outputting JSON, a string such as '2001-02-03T04:05:06' is output when the extended data is a timestamp.
See also
https://github.com/msgpack/msgpack/blob/master/spec.md#formats-ext

◆ Float()

nn::nlib::msgpack::JsonStreamGenerator::Float ( float  num)
noexcept

Outputs a floating-point number.

Parameters
[in]numA single-precision floating-point number.
Returns
JsonStreamGenerator object.

◆ FloatArray()

nn::nlib::msgpack::JsonStreamGenerator::FloatArray ( const float *  p,
size_t  count 
)
noexcept

Outputs a single-precision floating point number array.

Parameters
[in]pPointer to a single-precision floating point number array.
[in]countNumber of single-precision floating point numbers.
Returns
JsonStreamGenerator object.

◆ Flush()

nn::nlib::msgpack::JsonStreamGenerator::Flush ( )
noexcept

Writes data to the stream and flushes the stream.

Returns
Success if true.

◆ Generate() [1/2]

nn::nlib::msgpack::JsonStreamGenerator::Generate ( size_t *  written,
nlib_utf8_t str,
size_t  n,
const MpObject obj,
const JsonStreamGeneratorSettings settings 
)
staticnoexcept

Outputs the content of obj in JSON or msgpack.

Parameters
[out]writtenSize of the output data.
[out]strThe buffer that stores the output.
[in]nThe size of the output buffer.
[in]objMpObject to be serialized to JSON or msgpack.
[in]settingsParameters for setting the generator.
Returns
Returns 0 on success.
Description
When outputting JSON, the string is null-terminated. In this case, written stores the string length.

◆ Generate() [2/2]

nn::nlib::msgpack::JsonStreamGenerator::Generate ( nlib_utf8_t str,
size_t  n,
const MpObject obj,
const JsonStreamGeneratorSettings settings 
)
inlinestaticnoexcept

Outputs the content of obj in JSON or msgpack.

Parameters
[out]strThe buffer that stores the output.
[in]nThe size of the output buffer.
[in]objMpObject to be serialized to JSON or msgpack.
[in]settingsParameters for setting the generator.
Returns
A pair of the error value and the output data size.
Description
When outputting JSON, the string is null-terminated. In this case, written stores the string length.

Definition at line 84 of file JsonStreamGenerator.h.

◆ GetError()

nn::nlib::msgpack::JsonStreamGenerator::GetError ( ) const
inlinenoexcept

Gets an error.

Returns
An error value defined by JsonStreamGenerator.
Description
Returns one of the following values.
Value
kOk An error has not occurred.
kErrorKeyRequired A key must be output.
kErrorKeyForbidden Do not output any key.
kErrorEndArrayRequired The array must be finished.
kErrorEndArrayForbidden Do not finish the array.
kErrorEndMapRequired The map must be finished.
kErrorEndMapForbidden Do not finish the map.
kErrorStringUtf8 The string or key contains one or more non-UTF-8 characters.
kErrorStream An error has occurred in the output stream.
kErrorOutOfMemory Failed to allocate memory.
kErrorArrayOrMapRequired An array or map must be started.
kErrorDocumentEnd The JSON/msgpack document has already finished.
kErrorBinaryNotAvailable Binary() is unavailable.
kErrorExtNotAvailable Ext() is unavailable,
kErrorInvalidParam One or more input parameters are invalid.

Definition at line 161 of file JsonStreamGenerator.h.

◆ Init()

nn::nlib::msgpack::JsonStreamGenerator::Init ( const JsonStreamGeneratorSettings settings)
noexcept

Initializes by specifying the behavior option. Returns 0 if successful.

Parameters
[in]settingsBehavior options.
Return values
0Success.
EALREADYAlready initialized.
ENOMEMIndicates that internal memory allocation failed.
EINVALIndicates that the specification of behavior options was invalid.

◆ Int16()

nn::nlib::msgpack::JsonStreamGenerator::Int16 ( int16_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Int16Array()

nn::nlib::msgpack::JsonStreamGenerator::Int16Array ( const int16_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Int32()

nn::nlib::msgpack::JsonStreamGenerator::Int32 ( int32_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Int32Array()

nn::nlib::msgpack::JsonStreamGenerator::Int32Array ( const int32_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Int64()

nn::nlib::msgpack::JsonStreamGenerator::Int64 ( int64_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Int64Array()

nn::nlib::msgpack::JsonStreamGenerator::Int64Array ( const int64_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Int8()

nn::nlib::msgpack::JsonStreamGenerator::Int8 ( int8_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Int8Array()

nn::nlib::msgpack::JsonStreamGenerator::Int8Array ( const int8_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Key()

nn::nlib::msgpack::JsonStreamGenerator::Key ( const nlib_utf8_t key)
noexcept

Outputs keys for the associative array.

Parameters
[in]keyAssociative array key.
Returns
JsonStreamGenerator object.

◆ Null()

nn::nlib::msgpack::JsonStreamGenerator::Null ( )
noexcept

Outputs null.

Returns
JsonStreamGenerator object.

◆ Object()

nn::nlib::msgpack::JsonStreamGenerator::Object ( const MpObject obj)
noexcept

Outputs MpObject.

Parameters
[in]objMpObject to be output.
Returns
JsonStreamGenerator object.

◆ Open()

nn::nlib::msgpack::JsonStreamGenerator::Open ( OutputStream stream)
noexcept

Specifies a stream and starts generating data.

Parameters
[in]streamThe stream to write JSON or msgpack.
Return values
0Success.
EINVALstream is NULL or JsonStreamGenerator is uninitialized.
ENOMEMMemory allocation has failed.

◆ StartArray()

nn::nlib::msgpack::JsonStreamGenerator::StartArray ( size_t  count)
noexcept

Starts outputting the array.

Parameters
[in]countSize of the array.
Returns
JsonStreamGenerator object.
Description
When outputting msgpack, you must specify appropriate count. When outputting JSON, count is ignored.

◆ StartMap()

nn::nlib::msgpack::JsonStreamGenerator::StartMap ( size_t  count)
noexcept

Starts outputting the map.

Parameters
[in]countSize of the map.
Returns
JsonStreamGenerator object.
Description
When outputting msgpack, you must specify appropriate count. When outputting JSON, count is ignored.

◆ String()

nn::nlib::msgpack::JsonStreamGenerator::String ( const nlib_utf8_t str)
noexcept

Outputs a string.

Parameters
[in]strString
Returns
JsonStreamGenerator object.
Template Parameters
STDSTRINGClass that contains the c_str() member function that returns a C string.
Parameters
[in]strstd::string and other class objects.
Returns
JsonStreamGenerator object.

◆ Timestamp()

nn::nlib::msgpack::JsonStreamGenerator::Timestamp ( nlib_time  t)
noexcept

Outputs a timestamp. For JSON, it is output as a string.

Parameters
[in]tThe time.
Returns
JsonStreamGenerator object.
Description
When outputting JSON, a string such as '2001-02-03T04:05:06' is output when the extended data is a timestamp.
See also
https://github.com/msgpack/msgpack/blob/master/spec.md#formats-timestamp

◆ Uint16()

nn::nlib::msgpack::JsonStreamGenerator::Uint16 ( uint16_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Uint16Array()

nn::nlib::msgpack::JsonStreamGenerator::Uint16Array ( const uint16_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Uint32()

nn::nlib::msgpack::JsonStreamGenerator::Uint32 ( uint32_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Uint32Array()

nn::nlib::msgpack::JsonStreamGenerator::Uint32Array ( const uint32_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Uint64()

nn::nlib::msgpack::JsonStreamGenerator::Uint64 ( uint64_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Uint64Array()

nn::nlib::msgpack::JsonStreamGenerator::Uint64Array ( const uint64_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

◆ Uint8()

nn::nlib::msgpack::JsonStreamGenerator::Uint8 ( uint8_t  num)
noexcept

Outputs an integer value.

Parameters
[in]numAn integer value.
Returns
JsonStreamGenerator object.

◆ Uint8Array()

nn::nlib::msgpack::JsonStreamGenerator::Uint8Array ( const uint8_t *  p,
size_t  count 
)
noexcept

Outputs an integer array.

Parameters
[in]pPointer to an integer array.
[in]countNumber of integer values.
Returns
JsonStreamGenerator object.

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