![]() |
Home | Libraries | People | FAQ | More |
Serialization is the process where a JSON document represented in memory
by a value
is turned into a sequence of characters. The library provides the following
free functions and types for serialization:
Table 1.9. Serialization Functions and Types
To facilitate debugging and ease of output, library container types may be written to standard output streams using the stream operator:
value jv = { 1, 2, 3, 4, 5 }; std::cout << jv << "\n";
The serialize
function converts a value
into a std::string
:
value jv = { 1, 2, 3, 4, 5 }; std::string s = serialize( jv );
In situations where serializing a value
in its entirety is inefficient
or even impossible, serializer
can be used to incrementally
serialize a value
incrementally. This may be done for a variety of reasons, such as to avoid
buffering the entire output, or to ensure that a fixed amount of work is
performed in each cycle. Instances of serializer
maintain an output state
using internal dynamically allocated structures, with an interface to retrieve
successive buffers of the serialized output into a caller provided buffer.
Here is an example, demonstrating how operator<<
may be implemented using a serializer
:
// Serialize a value into an output stream std::ostream& operator<<( std::ostream& os, value const& jv ) { // Create a serializer serializer sr; // Set the serializer up for our value sr.reset( &jv ); // Loop until all output is produced. while( ! sr.done() ) { // Use a local buffer to avoid allocation. char buf[ BOOST_JSON_STACK_BUFFER_SIZE ]; // Fill our buffer with serialized characters and write it to the output stream. os << sr.read( buf ); } return os; }
As with the parser, the serializer may be reused by calling serializer::reset
. This sets up the object to
serialize a new instance and retains previously allocated memory. This can
result in performance improvements when multiple variables are serialized.