77 lines
2.6 KiB
Plaintext
77 lines
2.6 KiB
Plaintext
|
[/
|
||
|
|
Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
|
||
|
|
|
||
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||
|
|
|
||
|
|
Official repository: https://github.com/cppalliance/json
|
||
|
|
]
|
||
|
|
|
||
|
|
[/-----------------------------------------------------------------------------]
|
||
|
|
|
||
|
|
[section 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 Serialization Functions and Types
|
||
|
|
[ [Name] [Description ]]
|
||
|
|
[
|
||
|
|
[[link json.ref.boost__json__operator_lt__lt_ `operator<<`]]
|
||
|
|
[
|
||
|
|
Serialize a
|
||
|
|
__value__, __array__, __object__, or __string__
|
||
|
|
to a
|
||
|
|
[@https://en.cppreference.com/w/cpp/io/basic_ostream `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:
|
||
|
|
|
||
|
|
[doc_serializing_1]
|
||
|
|
|
||
|
|
The __serialize__ function converts a __value__ into a __std_string__:
|
||
|
|
|
||
|
|
[doc_serializing_2]
|
||
|
|
|
||
|
|
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
|
||
|
|
[link json.ref.boost__json__operator_lt__lt_ `operator<<`]
|
||
|
|
may be implemented using a __serializer__:
|
||
|
|
|
||
|
|
[example_operator_lt__lt_]
|
||
|
|
|
||
|
|
As with the parser, the serializer may be reused by calling
|
||
|
|
[link json.ref.boost__json__serializer.reset `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.
|
||
|
|
|
||
|
|
[endsect]
|