Writer

Writer is an incremental generator that outputs C data types in a JSON format. The output is generated piece by piece as C data types are inserted. The writer keeps track of the context and inserts the appropriate separators between values where needed.

Writer Accessors
Writer member function	Description
`size_type level()`	Returns the current level of nested containers.
`error_code error()`	Returns the current error code.
`size_type literal(const view_type&)`	Write a literal value directly into the JSON output without formatting it. Returns the number of characters written. Returns zero if an error occurred.
`size_type value<T>()`	Write a formatted tag into the JSON output. Returns the number of characters written. Returns zero if an error occurred.
`size_type value(T)`	Write a formatted value into the JSON output. Returns the number of characters written. Returns zero if an error occurred.

Values are properly formatted and written into the JSON output with writer::value(T). The parameter T can be a boolean, a number, or a string. Writing a nullable value or the opening and closing brackets of containers is done by passing special tags as the parameter to the parameter-less version writer::value<T>().

Literal values can also be inserted unconverted into the JSON output with writer::literal(). These can be useful useful for adding whitespaces, but special care should be exerted to not violate the JSON format.

As writer has been designed for wire protocols, it does not insert whitespaces into the output.^[1].

The following examples assume that you have included the following header files:

#include <trial/protocol/buffer/ostream.hpp>
#include <trial/protocol/json/writer.hpp>

Boolean

Boolean values are output via writer::value(bool).

std::ostringstream result;
json::writer writer(result);

writer.value(true); // Write boolean value
assert(result.str() == "true");

Number

Numbers can either be integer values or floating-point values.

String

Strings are written by passing an std::string or a string literal to writer::value(T). All strings will be quoted in the JSON output, and special characters will be escaped. Strings must be UTF-8 encoded.

std::ostringstream result;
json::writer writer(result);

writer.value("alpha"); // Write string
assert(result.str() == "\"alpha\"");

Null

Nullable value are output with writer::value<token::null>().

std::ostringstream result;
json::writer writer(result);

writer.value<json::token::null>(); // Write nullable value
assert(result.str() == "null");

Array

An array is initiated by passing the json::begin_array tag to writer::value(T), and terminated by passing the json::end_array. These tags must be properly balanced, otherwise an error will be raised.

Value separators are automatically inserted between values.

std::ostringstream result;
json::writer writer(result);

writer.value(json::begin_array); // Write beginning of array
assert(result.str() == "[");

writer.value(42);
assert(result.str() == "[42"); // Write number

writer.value(43);
assert(result.str() == "[42,43"); // Write number

writer.value(json::end_array);
assert(result.str() == "[42,43]"); // Write ending of array

Associative array

Name separators are automatically inserted between the key and the value, and value separators are automatically inserted between key-value pairs.

1. See example/json/pretty_printer for an example of how to produce an indented output.