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	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 108 of file json/Writer.h.

Member Enumeration Documentation

◆ CollectionType

enum Json::Writer::CollectionType

Enumerator
array
object

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

Constructor & Destructor Documentation

◆ Writer() [1/2]

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

explicit

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

◆ Writer() [2/2]

Json::Writer::Writer ( Writer && w )

noexcept

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

◆ ~Writer()

Json::Writer::~Writer ( )

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

Member Function Documentation

◆ operator=()

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

noexcept

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

◆ startRoot()

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

Start a new collection at the root level.

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

◆ startAppend()

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

Start a new collection inside an array.

Definition at line 324 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 331 of file libxrpl/json/Writer.cpp.

◆ finish()

void Json::Writer::finish ( )

Finish the collection most recently started.

Definition at line 339 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 296 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 146 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 303 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 if the tag you use has already been used in this object.

Definition at line 170 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 309 of file libxrpl/json/Writer.cpp.

◆ output() [1/9]

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

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

◆ output() [2/9]

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

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

◆ output() [3/9]

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

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

◆ output() [4/9]

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

Output a null.

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

◆ output() [5/9]

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

Output a float.

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

◆ output() [6/9]

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

Output a double.

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

◆ output() [7/9]

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

Output a bool.

Definition at line 284 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 214 of file json/Writer.h.

◆ output() [9/9]

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

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

◆ implOutput()

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

private

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

Member Data Documentation

◆ impl_

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

private

Definition at line 227 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_