## Serializing

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 5. Serialization Functions and Types
Name | Description
--- | ---
`operator<<` | Serialize a `value`, `array`, `object`, or `string` to a `std::ostream`.
`serialize` | Return a `std::string` representing a serialized `value`, `array`, `object`, or `string`.
`serializer` | A stateful object which may be used to efficiently serialize one or more instances of `value`, `array`, `object`, or `string`.

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 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( get_stream_flags(os) );

        // 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.

Edit this page