Writer implements an O(1)-space, O(1)-granular output JSON writer. More...

#include <Writer.h>

Collaboration diagram for json::Writer:

[legend]

Classes
class	Impl

Public Types
enum class	CollectionType { Array , Object }

Public Member Functions
	Writer (Output const &output)
	Writer (Writer &&) noexcept
Writer &	operator= (Writer &&) noexcept
	~Writer ()
void	startRoot (CollectionType)
	Start a new collection at the root level.
void	startAppend (CollectionType)
	Start a new collection inside an array.
void	startSet (CollectionType, std::string const &key)
	Start a new collection inside an object.
void	finish ()
	Finish the collection most recently started.
void	finishAll ()
	Finish all objects and arrays.
template<typename Scalar>
void	append (Scalar t)
	Append a value to an array.
void	rawAppend ()
	Add a comma before this next item if not the first item in an array.
template<typename Type>
void	set (std::string const &tag, Type t)
	Add a key, value assignment to an object.
void	rawSet (std::string const &key)
	Emit just "tag": as part of an object.
void	output (std::string const &)
void	output (char const *)
void	output (json::Value const &)
void	output (std::nullptr_t)
	Output a null.
void	output (float)
	Output a float.
void	output (double)
	Output a double.
void	output (bool)
	Output a bool.
template<typename Type>
void	output (Type t)
	Output numbers or booleans.
void	output (json::StaticString const &t)

Private Member Functions
void	implOutput (std::string const &)

Private Attributes
std::unique_ptr< Impl >	impl_

Detailed Description

Writer implements an O(1)-space, O(1)-granular output JSON writer.

O(1)-space means that it uses a fixed amount of memory, and that there are no heap allocations at each step of the way.

O(1)-granular output means the writer only outputs in small segments of a bounded size, using a bounded number of CPU cycles in doing so. This is very helpful in scheduling long jobs.

The tradeoff is that you have to fill items in the JSON tree as you go, and you can never go backward.

Writer can write single JSON tokens, but the typical use is to write out an entire JSON object. For example:

{
    Writer w (out);

    w.startObject ();          // Start the root object.
    w.set ("hello", "world");
    w.set ("goodbye", 23);
    w.finishObject ();         // Finish the root object.
}

which outputs the string

{"hello":"world","goodbye":23}

There can be an object inside an object:

{
    Writer w (out);

    w.startObject ();                // Start the root object.
    w.set ("hello", "world");

    w.startObjectSet ("subobject");  // Start a sub-object.
    w.set ("goodbye", 23);           // Add a key, value assignment.
    w.finishObject ();               // Finish the sub-object.

    w.finishObject ();               // Finish the root-object.
}

which outputs the string

{"hello":"world","subobject":{"goodbye":23}}.

Arrays work similarly

{
    Writer w (out);
    w.startObject ();           // Start the root object.

    w.startArraySet ("hello");  // Start an array.
    w.append (23)               // Append some items.
    w.append ("skidoo")
    w.finishArray ();           // Finish the array.

    w.finishObject ();          // Finish the root object.
}

which outputs the string

{"hello":[23,"skidoo"]}.

If you've reached the end of a long object, you can just use finishAll() which finishes all arrays and objects that you have started.

{
    Writer w (out);
    w.startObject ();           // Start the root object.

    w.startArraySet ("hello");  // Start an array.
    w.append (23)               // Append an item.

    w.startArrayAppend ()       // Start a sub-array.
    w.append ("one");
    w.append ("two");

    w.startObjectAppend ();     // Append a sub-object.
    w.finishAll ();             // Finish everything.
}

which outputs the string

{"hello":[23,["one","two",{}]]}.

For convenience, the destructor of Writer calls w.finishAll() which makes sure that all arrays and objects are closed. This means that you can throw an exception, or have a coroutine simply clean up the stack, and be sure that you do in fact generate a complete JSON object.

Definition at line 109 of file json/Writer.h.

Member Enumeration Documentation

◆ CollectionType

enum class json::Writer::CollectionType

strong

Enumerator
Array
Object

Definition at line 112 of file json/Writer.h.

Constructor & Destructor Documentation

◆ Writer() [1/2]

json::Writer::Writer ( Output const & output )

explicit

Definition at line 229 of file libxrpl/json/Writer.cpp.

◆ Writer() [2/2]

json::Writer::Writer ( Writer && w )

noexcept

Definition at line 239 of file libxrpl/json/Writer.cpp.

◆ ~Writer()

json::Writer::~Writer ( )

Definition at line 233 of file libxrpl/json/Writer.cpp.

Member Function Documentation

◆ operator=()

Writer & json::Writer::operator= ( Writer && w )

noexcept

Definition at line 244 of file libxrpl/json/Writer.cpp.

◆ startRoot()

void json::Writer::startRoot ( CollectionType type )

Start a new collection at the root level.

Definition at line 324 of file libxrpl/json/Writer.cpp.

◆ startAppend()

void json::Writer::startAppend ( CollectionType type )

Start a new collection inside an array.

Definition at line 330 of file libxrpl/json/Writer.cpp.

◆ startSet()

void json::Writer::startSet	(	CollectionType	type,
		std::string const &	key )

Start a new collection inside an object.

Definition at line 337 of file libxrpl/json/Writer.cpp.

◆ finish()

void json::Writer::finish ( )

Finish the collection most recently started.

Definition at line 345 of file libxrpl/json/Writer.cpp.

◆ finishAll()

void json::Writer::finishAll ( )

Finish all objects and arrays.

After finishArray() has been called, no more operations can be performed.

Definition at line 302 of file libxrpl/json/Writer.cpp.

◆ append()

template<typename Scalar>

void json::Writer::append ( Scalar t )

Append a value to an array.

Scalar must be a scalar - that is, a number, boolean, string, string literal, nullptr or json::Value

Definition at line 158 of file json/Writer.h.

◆ rawAppend()

void json::Writer::rawAppend ( )

Add a comma before this next item if not the first item in an array.

Useful if you are writing the actual array yourself.

Definition at line 309 of file libxrpl/json/Writer.cpp.

◆ set()

template<typename Type>

void json::Writer::set	(	std::string const &	tag,
		Type	t )

Add a key, value assignment to an object.

Scalar must be a scalar - that is, a number, boolean, string, string literal, or nullptr.

While the JSON spec doesn't explicitly disallow this, you should avoid calling this method twice with the same tag for the same object.

If CHECK_JSON_WRITER is defined, this function throws an exception if the tag you use has already been used in this object.

Definition at line 185 of file json/Writer.h.

◆ rawSet()

void json::Writer::rawSet ( std::string const & key )

Emit just "tag": as part of an object.

Useful if you are writing the actual value data yourself.

Definition at line 315 of file libxrpl/json/Writer.cpp.

◆ output() [1/9]

void json::Writer::output ( std::string const & s )

Definition at line 257 of file libxrpl/json/Writer.cpp.

◆ output() [2/9]

void json::Writer::output ( char const * s )

Definition at line 251 of file libxrpl/json/Writer.cpp.

◆ output() [3/9]

void json::Writer::output ( json::Value const & value )

Definition at line 263 of file libxrpl/json/Writer.cpp.

◆ output() [4/9]

void json::Writer::output ( std::nullptr_t )

Output a null.

Definition at line 284 of file libxrpl/json/Writer.cpp.

◆ output() [5/9]

void json::Writer::output ( float f )

Output a float.

Definition at line 270 of file libxrpl/json/Writer.cpp.

◆ output() [6/9]

void json::Writer::output ( double f )

Output a double.

Definition at line 277 of file libxrpl/json/Writer.cpp.

◆ output() [7/9]

void json::Writer::output ( bool b )

Output a bool.

Definition at line 290 of file libxrpl/json/Writer.cpp.

◆ output() [8/9]

template<typename Type>

void json::Writer::output ( Type t )

Output numbers or booleans.

Definition at line 241 of file json/Writer.h.

◆ output() [9/9]

void json::Writer::output ( json::StaticString const & t )

Definition at line 247 of file json/Writer.h.

◆ implOutput()

void json::Writer::implOutput ( std::string const & s )

private

Definition at line 296 of file libxrpl/json/Writer.cpp.

Member Data Documentation

◆ impl_

std::unique_ptr<Impl> json::Writer::impl_

private

Definition at line 254 of file json/Writer.h.

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ CollectionType

Constructor & Destructor Documentation

◆ Writer() [1/2]

◆ Writer() [2/2]

◆ ~Writer()

Member Function Documentation

◆ operator=()

◆ startRoot()

◆ startAppend()

◆ startSet()

◆ finish()

◆ finishAll()

◆ append()

◆ rawAppend()

◆ set()

◆ rawSet()

◆ output() [1/9]

◆ output() [2/9]

◆ output() [3/9]

◆ output() [4/9]

◆ output() [5/9]

◆ output() [6/9]

◆ output() [7/9]

◆ output() [8/9]

◆ output() [9/9]

◆ implOutput()

Member Data Documentation

◆ impl_