Configuration for various extraction options. This becomes part of the extraction_context. More...

#include <jsonv/serialization/extract.hpp>

Public Types
enum class	on_error { fail_immediately , collect_all }
	When an error is encountered during extraction, what should happen? More...

enum class	duplicate_key_action { replace , ignore , exception }
	When an object key has the same value as a previously-seen key, what should happen? More...

using	size_type = extraction_error::problem_list::size_type

Public Member Functions
	extract_options () noexcept
	Create an instance with the default options.


on_error	failure_mode () const noexcept

extract_options &	failure_mode (on_error mode)


size_type	max_failures () const

extract_options &	max_failures (size_type limit)


duplicate_key_action	on_duplicate_key () const

extract_options &	on_duplicate_key (duplicate_key_action action)

Static Public Member Functions
static extract_options	create_default ()
	Create a default set of options.

Detailed Description

Configuration for various extraction options. This becomes part of the extraction_context.

Definition at line 212 of file extract.hpp.

Member Typedef Documentation

◆ size_type

using jsonv::extract_options::size_type = extraction_error::problem_list::size_type

Definition at line 215 of file extract.hpp.

Member Enumeration Documentation

◆ duplicate_key_action

enum class jsonv::extract_options::duplicate_key_action

strong

When an object key has the same value as a previously-seen key, what should happen?

Enumerator

replace

Replace the previous value with the new one.

The final value of the key in the object will be the last-encountered one.

For example: { "a": 1, "a": 2, "a": 3 } will end with { "a": 3 }.

ignore

Ignore the new values.

The final value of the key in the object will be the first-encountered one.

    For example: `{ "a": 1, "a": 2, "a": 3 }` will end with `{ "a": 1 }`.

exception

Repeated keys should raise an extraction_error.

Definition at line 238 of file extract.hpp.

◆ on_error

enum class jsonv::extract_options::on_error

strong

When an error is encountered during extraction, what should happen?

Enumerator

fail_immediately

Report the first problem and stop, so the extraction_error thrown describes one thing that went wrong.

collect_all

Keep extracting past a problem wherever something knows how to resume, so the extraction_error thrown at the end describes as many of them as it can.

Resuming is only possible where a composite knows where its next element begins – the next element of an array, the next key of an object – which is why extraction_context::recover is asked rather than told. A failure with no enclosing composite to resume into still ends extraction with a single problem.

Collecting gathers diagnostics; it does not produce partially-extracted objects. An extraction which recovered from anything still throws, so this changes how much the error explains and never whether one happens.

See also: extract_options::max_failures

Definition at line 218 of file extract.hpp.

Member Function Documentation

◆ failure_mode()

on_error jsonv::extract_options::failure_mode ( ) const

inlinenoexcept

See on_error. The default failure mode is fail_immediately.

Definition at line 266 of file extract.hpp.

◆ max_failures()

size_type jsonv::extract_options::max_failures ( ) const

inline

The number of problems to collect before giving up. This is only applicable if the failure_mode is on_error::collect_all. By default, this value is 10.

This is a threshold extraction stops at rather than a cap on the list it reports. A single failure which reports several problems at once – an adapter recording a batch of them before returning, or throwing an extraction_error carrying several – is taken whole rather than torn in half, so the final list can exceed the limit by that batch. Truncating would drop diagnostics to enforce a bound whose purpose is to stop the walk, not to edit the report.

A limit of 0 or 1 makes the first problem the last, which is on_error::fail_immediately in all but name.

You should probably not set this value to an unreasonably high number, as each error encountered must be stored in memory for some period of time.

Definition at line 286 of file extract.hpp.

◆ on_duplicate_key()

duplicate_key_action jsonv::extract_options::on_duplicate_key ( ) const

inline

See duplicate_key_action. The default action is replace.

Definition at line 293 of file extract.hpp.

The documentation for this class was generated from the following file:

jsonv/serialization/extract.hpp

Public Types

Public Member Functions

Static Public Member Functions