Serialization components are responsible for conversion between a C++ type and a JSON value. More...

Classes
class	jsonv::reader
	A reader instance reads from some form of JSON source (probably a string) and converts it into a JSON ast_node sequence. More...

class	jsonv::serialization_context

class	jsonv::adapter
	An `adapter` is both an `extractor` and a `serializer`. More...

class	jsonv::adapter_for< T >
	An adapter for the type `T`. More...

class	jsonv::value_adapter_for< T >
	A base for adapters written against the older `value` -based extraction interface. More...

class	jsonv::container_adapter< TContainer >
	An adapter for container types. More...

class	jsonv::context
	Provides extra information to routines used for extraction and serialization. More...

class	jsonv::enum_adapter< TEnum, FEnumComp, FValueComp >
	An adapter for enumeration types. More...

class	jsonv::extraction_error
	Exception thrown if there is any problem running `extract`. More...

class	jsonv::extract_options
	Configuration for various extraction options. This becomes part of the `extraction_context`. More...

class	jsonv::extractor
	An `extractor` holds the method for converting JSON source into an arbitrary C++ type. More...

class	jsonv::extraction_context
	Provides extra information to routines used for extraction, collects the problems they encounter, and tracks where in the document they are. More...

class	jsonv::extractor_construction< T >
	An `extractor` for a type `T` with an extracting constructor. More...

class	jsonv::extractor_for< T >
	An `extractor` for type `T`. More...

class	jsonv::duplicate_type_error
	Exception thrown if an insertion of an extractor or serializer into a formats is attempted, but there is already an extractor or serializer for that type. More...

class	jsonv::no_extractor
	Thrown when `formats::extract` does not have an `extractor` for the provided type. More...

class	jsonv::no_serializer
	Thrown when `formats::to_json` does not have a `serializer` for the provided type. More...

class	jsonv::formats
	Simply put, this class is a collection of `extractor` and `serializer` instances. More...

class	jsonv::function_adapter< T, FExtract, FToJson >

class	jsonv::function_extractor< T, FExtract >
	An `extractor` which calls a function to perform extraction. More...

class	jsonv::function_serializer< T, FToJson >

class	jsonv::optional_adapter< TOptional >
	An adapter for optional-like types. More...

class	jsonv::polymorphic_adapter< TPointer >
	An adapter which can create polymorphic types. More...

class	jsonv::serializer
	A `serializer` holds the method for converting an arbitrary C++ type into a `value`. More...

class	jsonv::serializer_for< T >

class	jsonv::wrapper_adapter< TWrapper >
	An adapter for "wrapper" types. More...

Typedefs
using	jsonv::demangle_function = std::function< std::string(std::string_view source)>
	Type of function used in setting a custom demangler.

template<typename TEnum , typename FEnumComp = std::less<TEnum>>
using	jsonv::enum_adapter_icase = enum_adapter< TEnum, FEnumComp, value_less_icase >
	An adapter for enumeration types which ignores the case when extracting from JSON.

Enumerations
enum class	jsonv::duplicate_type_action : unsigned char { duplicate_type_action::ignore , duplicate_type_action::replace , duplicate_type_action::exception }
	The action to take when an insertion of an extractor or serializer into a formats is attempted, but there is alredy an extractor or serializer for that type. More...

enum class	jsonv::keyed_subtype_action : unsigned char { keyed_subtype_action::none , keyed_subtype_action::check , keyed_subtype_action::insert }
	What to do when serializing a keyed subtype of a `polymorphic_adapter`. More...

Functions
JSONV_PUBLIC std::string	jsonv::demangle (std::string_view source)
	Convert the input source from a mangled type into a human-friendly version.

JSONV_PUBLIC void	jsonv::set_demangle_function (demangle_function func)
	Sets the global demangle function.

JSONV_PUBLIC void	jsonv::reset_demangle_function ()
	Resets the demangle function to the default.

JSONV_PUBLIC std::string	jsonv::current_exception_type_name ()
	Get the demangled type name of the current exception.

template<typename T >
value	jsonv::to_json (const T &from, const formats &fmts)
	Encode a JSON `value` from from using the provided fmts.

template<typename T >
value	jsonv::to_json (const T &from)
	Encode a JSON `value` from from using `jsonv::formats::global()`.

JSONV_PUBLIC value	jsonv::read_value (reader &from)
	Consume the JSON subtree under from starting at `reader::current` and return it as a fully materialised `value` tree.

JSONV_PUBLIC value	jsonv::read_value (extraction_context &context, reader &from)
	read_value for an extractor.

template<typename T >
T	jsonv::extract (const value &from, const formats &fmts)
	Extract a C++ value from from using the provided fmts.

template<typename T >
T	jsonv::extract (const value &from, const formats &fmts, const extract_options &options)
	Extract a C++ value from from using the provided fmts and options.

template<typename T >
T	jsonv::extract (const value &from)
	Extract a C++ value from from using `jsonv::formats::global()`.

template<typename T >
T	jsonv::extract (const value &from, const extract_options &options)
	Extract a C++ value from from using `jsonv::formats::global()` and the provided options.

template<typename FExtract , typename FToJson >
auto	jsonv::make_adapter (FExtract extract, FToJson to_json_) -> function_adapter< detail::extract_function_result_t< FExtract >, FExtract, FToJson >
	Create an `adapter` from extract and to_json_, deducing the adapted type from what extract returns.

template<typename FExtract >
auto	jsonv::make_extractor (FExtract func) -> function_extractor< detail::extract_function_result_t< FExtract >, FExtract >
	Create an `extractor` from func, deducing what it extracts from its return type.

template<typename T , typename FToJson >
function_serializer< T, FToJson >	jsonv::make_serializer (FToJson to_json_)

template<typename T >
T	jsonv::extraction_context::extract (const value &from)
	Attempt to extract a `T` from the in-memory from using the `formats` associated with this context.

template<typename T >
T	jsonv::extract (reader &from, const formats &fmts=formats::global(), const extract_options &options=extract_options())
	Extract a C++ value from a reader using fmts (by default `jsonv::formats::global()`) and options.

template<typename T >
T	jsonv::extract (reader &from, const extract_options &options)
	Extract a C++ value from a reader using `jsonv::formats::global()` and the provided options.

template<typename T >
T	jsonv::extract (reader &&from, const formats &fmts=formats::global(), const extract_options &options=extract_options())
	Extract a C++ value from a reader which may own its source, using fmts and options.

template<typename T >
T	jsonv::extract (reader &&from, const extract_options &options)
	Extract a C++ value from a reader which may own its source, using `jsonv::formats::global()` and the provided options.

template<typename T >
T	jsonv::extract (reader &from, extraction_context &context)
	Extract a C++ value from a reader through a context the caller built, exactly as the overloads above do with one built from `formats` and `extract_options`.

template<typename T >
T	jsonv::extract (reader &&from, extraction_context &context)
	Extract a C++ value from a reader through a context the caller built, exactly as the overloads above do with one built from `formats` and `extract_options`.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, const formats &fmts=formats::global(), const extract_options &options=extract_options())
	Extract a C++ value directly from JSON source text, parsed with parse_opts, using fmts (by default `jsonv::formats::global()`) and options.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, const extract_options &options)
	Extract a C++ value from JSON source text using `jsonv::formats::global()` and the provided options.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, const parse_options &parse_opts, const formats &fmts=formats::global(), const extract_options &options=extract_options())
	Extract a C++ value from JSON source text parsed with parse_opts, using fmts and options.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, const parse_options &parse_opts, const extract_options &options)
	Extract a C++ value from JSON source text parsed with parse_opts, using `jsonv::formats::global()` and the provided options.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, extraction_context &context)
	Extract a C++ value directly from JSON source text, parsed with parse_opts where they are given, through a context the caller built.

template<typename T , typename TSource > requires std::convertible_to<TSource, std::string_view>
T	jsonv::extract (TSource &&source, const parse_options &parse_opts, extraction_context &context)
	Extract a C++ value directly from JSON source text, parsed with parse_opts where they are given, through a context the caller built.

Detailed Description

Serialization components are responsible for conversion between a C++ type and a JSON value.

Typedef Documentation

◆ demangle_function

using jsonv::demangle_function = typedef std::function<std::string (std::string_view source)>

Type of function used in setting a custom demangler.

See also: demangle; set_demangle_function

Definition at line 39 of file demangle.hpp.

◆ enum_adapter_icase

template<typename TEnum , typename FEnumComp = std::less<TEnum>>

using jsonv::enum_adapter_icase = typedef enum_adapter<TEnum, FEnumComp, value_less_icase>

An adapter for enumeration types which ignores the case when extracting from JSON.

See also: enum_adapter

Definition at line 292 of file enum_adapter.hpp.

Enumeration Type Documentation

◆ duplicate_type_action

enum class jsonv::duplicate_type_action : unsigned char

strong

The action to take when an insertion of an extractor or serializer into a formats is attempted, but there is alredy an extractor or serializer for that type.

Enumerator
ignore	The existing extractor or serializer should be kept, but no exception should be thrown.
replace	The new extractor or serializer should be inserted, and no exception should be thrown.
exception	A duplicate_type_error should be thrown.

Definition at line 32 of file formats.hpp.

◆ keyed_subtype_action

enum class jsonv::keyed_subtype_action : unsigned char

strong

What to do when serializing a keyed subtype of a polymorphic_adapter.

See polymorphic_adapter::add_subtype_keyed.

Enumerator

none

Don't do any checking or insertion of the expected key/value pair.

check

Ensure the correct key/value pair was inserted by serialization. Throws std::runtime_error if it wasn't.

insert

Insert the correct key/value pair as part of serialization.

Throws std::runtime_error if the key is already present.

Definition at line 36 of file polymorphic_adapter.hpp.

Function Documentation

◆ current_exception_type_name()

JSONV_PUBLIC std::string jsonv::current_exception_type_name ( )

Get the demangled type name of the current exception.

This is meant to be called from catch (...) blocks to attempt to get more information about the exception type when it doesn't derive from a known entity.

Returns: The demangled type name of the current exception or "unknown" if this cannot be discovered. Failure to discover is not an error – this can happen if the exception is foreign to C++ (it does not have a std::type_info implementation) or if discovery is not known for this platform.

◆ demangle()

JSONV_PUBLIC std::string jsonv::demangle ( std::string_view source )

Convert the input source from a mangled type into a human-friendly version.

This is used by formats (and the associated serialization functions) to give more user-friendly names in type errors.

See also: demangle_function; set_demangle_function

◆ extract() [1/17]

template<typename T >

T jsonv::extraction_context::extract ( const value & from )

Attempt to extract a T from the in-memory from using the formats associated with this context.

This runs the same pipeline as the reader overload by walking from through a reader::from_value, and reports failure by throwing rather than by returning. It is how an adapter written against the older value-based interface reaches the rest of the pipeline. To extract part of from, name the part – extract<T>(from.at("a")) – under a path_scope saying where it is.

Exceptions

extraction_error if anything goes wrong when attempting to extract a value.

See also: value_adapter_for

Definition at line 1290 of file extract.hpp.

◆ extract() [2/17]

template<typename T >

T jsonv::extract ( const value & from )

Extract a C++ value from from using jsonv::formats::global().

Definition at line 1317 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [3/17]

template<typename T >

T jsonv::extract	(	const value &	from,
		const extract_options &	options
	)

Extract a C++ value from from using jsonv::formats::global() and the provided options.

Definition at line 1326 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [4/17]

template<typename T >

T jsonv::extract	(	const value &	from,
		const formats &	fmts
	)

Extract a C++ value from from using the provided fmts.

Definition at line 1299 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [5/17]

template<typename T >

T jsonv::extract	(	const value &	from,
		const formats &	fmts,
		const extract_options &	options
	)

Extract a C++ value from from using the provided fmts and options.

Definition at line 1308 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [6/17]

template<typename T >

T jsonv::extract	(	reader &&	from,
		const extract_options &	options
	)

Extract a C++ value from a reader which may own its source, using jsonv::formats::global() and the provided options.

Definition at line 1384 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [7/17]

template<typename T >

T jsonv::extract	(	reader &&	from,
		const formats &	fmts = `formats::global()`,
		const extract_options &	options = `extract_options()`
	)

Extract a C++ value from a reader which may own its source, using fmts and options.

Definition at line 1370 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [8/17]

template<typename T >

T jsonv::extract	(	reader &&	from,
		extraction_context &	context
	)

Extract a C++ value from a reader through a context the caller built, exactly as the overloads above do with one built from formats and extract_options.

Everything context was created with applies: its formats and extract_options, and also what the overloads above have no way to be given – the version, user data and base path its extractors see, and the extraction_context::source_name its problems are reported in. A failed call throws the problems it recorded and takes them off context, which is left holding what it held before.

An extraction_context is single-use, so build one for each document and do not hand this the one an extractor was given – whatever that extraction has in progress would be applied to a document it knows nothing about.

Exceptions

extraction_error for the same reasons as the overloads above.

Definition at line 1413 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [9/17]

template<typename T >

T jsonv::extract	(	reader &	from,
		const extract_options &	options
	)

Extract a C++ value from a reader using jsonv::formats::global() and the provided options.

Definition at line 1362 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [10/17]

template<typename T >

T jsonv::extract	(	reader &	from,
		const formats &	fmts = `formats::global()`,
		const extract_options &	options = `extract_options()`
	)

Extract a C++ value from a reader using fmts (by default jsonv::formats::global()) and options.

A reader on ast_node_type::document_start – a freshly-created one – is read as a whole document. It is checked with reader::validate first, so a source which did not parse is reported as that rather than as whatever an extractor made of the ast_node_type::error node it ran into; its document_start is stepped over, so neither the caller nor any extractor has to; and the value read must be the whole document, so the reader is left on ast_node_type::document_end. A reader the caller has already positioned gets none of this: the value under its cursor is extracted and the cursor left one past it, as reader::next_value would, whatever surrounds it. The exception is a reader on an ast_node_type::error node, which has no value to extract and is reported as the parse failure it is.

Anything extracted as a view of the source – a std::string_view – views the reader's storage. Through the rvalue overloads, a reader which reader::owns_source dies with the call, so such views are refused; one over storage the caller owns, like reader(std::string_view), is viewed as usual.

Exceptions

extraction_error if the source did not parse, the value could not be extracted or, for a whole document, something follows the value.

Definition at line 1353 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [11/17]

template<typename T >

T jsonv::extract	(	reader &	from,
		extraction_context &	context
	)

Extract a C++ value from a reader through a context the caller built, exactly as the overloads above do with one built from formats and extract_options.

Everything context was created with applies: its formats and extract_options, and also what the overloads above have no way to be given – the version, user data and base path its extractors see, and the extraction_context::source_name its problems are reported in. A failed call throws the problems it recorded and takes them off context, which is left holding what it held before.

An extraction_context is single-use, so build one for each document and do not hand this the one an extractor was given – whatever that extraction has in progress would be applied to a document it knows nothing about.

Exceptions

extraction_error for the same reasons as the overloads above.

Definition at line 1406 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [12/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		const extract_options &	options
	)

Extract a C++ value from JSON source text using jsonv::formats::global() and the provided options.

Definition at line 1457 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [13/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		const formats &	fmts = `formats::global()`,
		const extract_options &	options = `extract_options()`
	)

Extract a C++ value directly from JSON source text, parsed with parse_opts, using fmts (by default jsonv::formats::global()) and options.

source is anything which converts to std::string_view: a string literal, a std::string, a std::string_view. Note what that means for a C++ string: it is JSON text to be parsed, not a JSON string, so extract<std::string>(R"("fire")") is "fire" and extract<std::string>("fire") is a parse failure. Wrap it in a value – extract<std::string>(value("fire")) – to mean the string.

A std::string rvalue is taken over for the call and freed when it returns, so views of it are refused, as for a tree materialised during extraction (see extraction_context::source_is_temporary). Every other source is read where it is, without copying, and a std::string_view extracted from it points into it.

This reads the whole document, exactly as the reader overloads do given a fresh reader.

Exceptions

extraction_error	if source is not valid JSON, the value could not be extracted, or something follows it.
std::invalid_argument	if parse_opts asks for a `parse_options::max_structure_depth` beyond the limit, as `jsonv::parse` does.

Definition at line 1445 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [14/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		const parse_options &	parse_opts,
		const extract_options &	options
	)

Extract a C++ value from JSON source text parsed with parse_opts, using jsonv::formats::global() and the provided options.

Definition at line 1484 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [15/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		const parse_options &	parse_opts,
		const formats &	fmts = `formats::global()`,
		const extract_options &	options = `extract_options()`
	)

Extract a C++ value from JSON source text parsed with parse_opts, using fmts and options.

Definition at line 1470 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [16/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		const parse_options &	parse_opts,
		extraction_context &	context
	)

Extract a C++ value directly from JSON source text, parsed with parse_opts where they are given, through a context the caller built.

source is read exactly as the overloads above read it, a std::string rvalue included, and context is used as the reader overload taking an extraction_context uses it: everything it was created with applies, and the problems a failed call throws are taken off it. Build one for each document.

Exceptions

extraction_error	if source is not valid JSON, the value could not be extracted, or something follows it.
std::invalid_argument	if parse_opts asks for a `parse_options::max_structure_depth` beyond the limit, as `jsonv::parse` does.

Definition at line 1513 of file extract.hpp.

Here is the call graph for this function:

◆ extract() [17/17]

template<typename T , typename TSource >
requires std::convertible_to<TSource, std::string_view>

T jsonv::extract	(	TSource &&	source,
		extraction_context &	context
	)

Extract a C++ value directly from JSON source text, parsed with parse_opts where they are given, through a context the caller built.

source is read exactly as the overloads above read it, a std::string rvalue included, and context is used as the reader overload taking an extraction_context uses it: everything it was created with applies, and the problems a failed call throws are taken off it. Build one for each document.

Exceptions

extraction_error	if source is not valid JSON, the value could not be extracted, or something follows it.
std::invalid_argument	if parse_opts asks for a `parse_options::max_structure_depth` beyond the limit, as `jsonv::parse` does.

Definition at line 1505 of file extract.hpp.

Here is the call graph for this function:

◆ make_adapter()

template<typename FExtract , typename FToJson >

auto jsonv::make_adapter	(	FExtract	extract,
		FToJson	to_json_
	)		-> function_adapter<detail::extract_function_result_t<FExtract>, FExtract, FToJson>

Create an adapter from extract and to_json_, deducing the adapted type from what extract returns.

Definition at line 73 of file function_adapter.hpp.

Here is the call graph for this function:

◆ make_extractor()

template<typename FExtract >

auto jsonv::make_extractor ( FExtract func ) -> function_extractor<detail::extract_function_result_t<FExtract>, FExtract>

Create an extractor from func, deducing what it extracts from its return type.

Definition at line 59 of file function_extractor.hpp.

◆ make_serializer()

template<typename T , typename FToJson >

function_serializer< T, FToJson > jsonv::make_serializer ( FToJson to_json_ )

Definition at line 69 of file function_serializer.hpp.

◆ read_value() [1/2]

JSONV_PUBLIC value jsonv::read_value	(	extraction_context &	context,
		reader &	from
	)

read_value for an extractor.

When a structure fails, which leaves the cursor past it, this also says so to context with extraction_context::note_value_consumed – which is what lets a composite recovering from the failure resume at the next sibling rather than one sibling too far.

A repeated key is settled by context's extract_options::on_duplicate_key, as parse settles it for the same options: replace keeps the last value, ignore the first, and exception refuses the object.

Exceptions

extraction_error for a repeated key under extract_options::duplicate_key_action::exception, as well as for everything read_value throws it for.

Here is the call graph for this function:

◆ read_value() [2/2]

JSONV_PUBLIC value jsonv::read_value ( reader & from )

Consume the JSON subtree under from starting at reader::current and return it as a fully materialised value tree.

On return from has advanced one position past the consumed subtree, exactly as reader::next_value would have left it for the same input. Every adapter reading a subtree has to agree on this, or subtrees get consumed twice or not at all. A leading ast_node_type::document_start is stepped over first, so this works on a freshly-created reader as well as on one positioned mid-document.

This is the bridge which lets adapters written against the older value -based interface keep working while the surrounding pipeline runs against a streaming reader.

A structure which fails part-way through is still stepped over, so from is left one past it just as success would have left it; a scalar which fails leaves from on it. An extractor which lets the failure of a structure out has to say that the value is behind the cursor, or a composite recovering from it steps over the following sibling as well – which is what the overload taking an extraction_context is for.

An object which repeats a key keeps the last of its values, which is extract_options::duplicate_key_action's default. The overload taking an extraction_context does what its options say instead.

Exceptions

extraction_error	if from is not positioned on a value or the document ends part-way through one.
std::invalid_argument	if a number has no finite `double` to round to, such as `1e400`.
parse_error	if a string holds an escape which does not decode, such as an unpaired `\uD800`.

See also: value_adapter_for

◆ reset_demangle_function()

JSONV_PUBLIC void jsonv::reset_demangle_function ( )

Resets the demangle function to the default.

See also: set_demangle_function

◆ set_demangle_function()

JSONV_PUBLIC void jsonv::set_demangle_function ( demangle_function func )

Sets the global demangle function.

This controls the behavior of demangle – the provided func will be called by demangle.

See also: demangle

◆ to_json() [1/2]

template<typename T >

value jsonv::to_json ( const T & from )

Encode a JSON value from from using jsonv::formats::global().

Definition at line 76 of file serialization.hpp.

◆ to_json() [2/2]

template<typename T >

value jsonv::to_json	(	const T &	from,
		const formats &	fmts
	)

Encode a JSON value from from using the provided fmts.

Definition at line 67 of file serialization.hpp.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ demangle_function

◆ enum_adapter_icase

Enumeration Type Documentation

◆ duplicate_type_action

◆ keyed_subtype_action

Function Documentation

◆ current_exception_type_name()

◆ demangle()

◆ extract() [1/17]

◆ extract() [2/17]

◆ extract() [3/17]

◆ extract() [4/17]

◆ extract() [5/17]

◆ extract() [6/17]

◆ extract() [7/17]

◆ extract() [8/17]

◆ extract() [9/17]

◆ extract() [10/17]

◆ extract() [11/17]

◆ extract() [12/17]

◆ extract() [13/17]

◆ extract() [14/17]

◆ extract() [15/17]

◆ extract() [16/17]

◆ extract() [17/17]

◆ make_adapter()

◆ make_extractor()

◆ make_serializer()

◆ read_value() [1/2]

◆ read_value() [2/2]

◆ reset_demangle_function()

◆ set_demangle_function()

◆ to_json() [1/2]

◆ to_json() [2/2]