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

Member Enumeration Documentation

◆ CollectionType

enum Json::Writer::CollectionType

Enumerator
array
object

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

Constructor & Destructor Documentation

◆ Writer() [1/2]

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

explicit

Definition at line 241 of file Writer.cpp.

◆ Writer() [2/2]

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

noexcept

Definition at line 251 of file Writer.cpp.

◆ ~Writer()

Json::Writer::~Writer ( )

Definition at line 245 of file Writer.cpp.

Member Function Documentation

◆ operator=()

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

noexcept

Definition at line 257 of file Writer.cpp.

◆ startRoot()

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

Start a new collection at the root level.

Definition at line 337 of file Writer.cpp.

◆ startAppend()

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

Start a new collection inside an array.

Definition at line 343 of file Writer.cpp.

◆ startSet()

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

Start a new collection inside an object.

Definition at line 350 of file Writer.cpp.

◆ finish()

void Json::Writer::finish ( )

Finish the collection most recently started.

Definition at line 358 of file 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 315 of file 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 165 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 322 of file 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 189 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 328 of file Writer.cpp.

◆ output() [1/9]

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

Definition at line 270 of file Writer.cpp.

◆ output() [2/9]

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

Definition at line 264 of file Writer.cpp.

◆ output() [3/9]

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

Definition at line 276 of file Writer.cpp.

◆ output() [4/9]

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

Output a null.

Definition at line 297 of file Writer.cpp.

◆ output() [5/9]

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

Output a float.

Definition at line 283 of file Writer.cpp.

◆ output() [6/9]

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

Output a double.

Definition at line 290 of file Writer.cpp.

◆ output() [7/9]

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

Output a bool.

Definition at line 303 of file Writer.cpp.

◆ output() [8/9]

template<typename Type >

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

Output numbers or booleans.

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

◆ output() [9/9]

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

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

◆ implOutput()

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

private

Definition at line 309 of file Writer.cpp.

Member Data Documentation

◆ impl_

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

private

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