Json::Collection Class Reference

Inheritance diagram for Json::Collection:

Collaboration diagram for Json::Collection:

Public Member Functions
	Collection (Collection &&c) noexcept
Collection &	operator= (Collection &&c) noexcept
	Collection ()=delete
	~Collection ()

Protected Member Functions
	Collection (Collection *parent, Writer *)
void	checkWritable (std::string const &label)

Protected Attributes
Collection *	parent_
Writer *	writer_
bool	enabled_

Detailed Description

Collection is a base class for Array and Object, classes which provide the
facade of JSON collections for the O(1) JSON writer, while still using no
heap memory and only a very small amount of stack.

From http://json.org, JSON has two types of collection: array, and object.
Everything else is a *scalar* - a number, a string, a boolean, the special
value null, or a legacy Json::Value.

Collections must write JSON "as-it-goes" in order to get the strong
performance guarantees.  This puts restrictions upon API users:

1. Only one collection can be open for change at any one time.

   This condition is enforced automatically and a std::logic_error thrown if

it is violated.

1. A tag may only be used once in an Object.

   Some objects have many tags, so this condition might be a little expensive. Enforcement of this condition is turned on in debug builds and a std::logic_error is thrown when the tag is added for a second time.

Code samples:

Writer writer;

An empty object. { Object::Root (writer); } Outputs {}

An object with one scalar value. { Object::Root root (writer); write["hello"] = "world"; } Outputs {"hello":"world"}

Same, using chaining. { Object::Root (writer)["hello"] = "world"; } Output is the same.

Add several scalars, with chaining. { Object::Root (writer) .set ("hello", "world") .set ("flag", false) .set ("x", 42); } Outputs {"hello":"world","flag":false,"x":42}

Add an array. { Object::Root root (writer); { auto array = root.setArray ("hands"); array.append ("left"); array.append ("right"); } } Outputs {"hands":["left", "right"]}

Same, using chaining. { Object::Root (writer) .setArray ("hands") .append ("left") .append ("right"); } Output is the same.

Add an object. { Object::Root root (writer); { auto object = root.setObject ("hands"); object["left"] = false; object["right"] = true; } } Outputs {"hands":{"left":false,"right":true}}

Same, using chaining. { Object::Root (writer) .setObject ("hands") .set ("left", false) .set ("right", true); } } Outputs {"hands":{"left":false,"right":true}}

Typical ways to make mistakes and get a std::logic_error:

 Writer writer;
 Object::Root root (writer);

Repeat a tag. { root ["hello"] = "world"; root ["hello"] = "there"; // THROWS! in a debug build. }

Open a subcollection, then set something else. { auto object = root.setObject ("foo"); root ["hello"] = "world"; // THROWS! }

Open two subcollections at a time. { auto object = root.setObject ("foo"); auto array = root.setArray ("bar"); // THROWS!! }

For more examples, check the unit tests.

Definition at line 151 of file Object.h.

Constructor & Destructor Documentation

Collection() [1/3]

Json::Collection::Collection ( Collection &&  c )

noexcept

Definition at line 59 of file Object.cpp.

Collection() [2/3]

Json::Collection::Collection ( )

delete

~Collection()

Json::Collection::~Collection

(

)

Definition at line 37 of file Object.cpp.

Collection() [3/3]

Json::Collection::Collection ( Collection *  parent, Writer *  writer  )

protected

Definition at line 26 of file Object.cpp.

Member Function Documentation

operator=()

Collection & Json::Collection::operator= ( Collection &&  c )

noexcept

Definition at line 46 of file Object.cpp.

checkWritable()

void Json::Collection::checkWritable ( std::string const &  label )

protected

Definition at line 65 of file Object.cpp.

Member Data Documentation

parent_

Collection* Json::Collection::parent_

protected

Definition at line 168 of file Object.h.

writer_

Writer* Json::Collection::writer_

protected

Definition at line 169 of file Object.h.

enabled_

bool Json::Collection::enabled_

protected

Definition at line 170 of file Object.h.