toml::parse_result class

The result of a parsing operation.

Conditional availability

This type only exists when exceptions are disabled. Otherwise parse_result is just an alias for toml::table:

#if TOML_EXCEPTIONS
    using parse_result = table;
#else
    class parse_result { // ...
#endif

A parse_result is effectively a discriminated union containing either a toml::table or a toml::parse_error. Most member functions assume a particular one of these two states, and calling them when in the wrong state will cause errors (e.g. attempting to access the error object when parsing was successful).

toml::parse_result result = toml::parse_file("config.toml");
if (result)
    do_stuff_with_a_table(result); //implicitly converts to table&
else
    std::cerr << "Parse failed:\n"sv << result.error() << "\n";

example output:

Parse failed:
Encountered unexpected character while parsing boolean; expected 'true', saw 'trU'
    (error occurred at line 1, column 13 of 'config.toml')

Getting node_views (operator[], at_path()) and using the iterator accessor functions (begin(), end() etc.) are unconditionally safe; when parsing fails these just return 'empty' values. A ranged-for loop on a failed parse_result is also safe since begin() and end() return the same iterator and will not lead to any dereferences and iterations.

Constructors, destructors, conversion operators

parse_result() noexcept: Default constructs an 'error' result.
parse_result(parse_result&& res) noexcept: Move constructor.
~parse_result() noexcept: Destructor.

Public functions

auto operator=(parse_result&& rhs) -> parse_result& noexcept: Move-assignment operator.

Failed parses

auto error() & -> parse_error& noexcept: Returns the internal toml::parse_error.
auto error() && -> parse_error&& noexcept: Returns the internal toml::parse_error (rvalue overload).
auto error() const & -> const parse_error& noexcept: Returns the internal toml::parse_error (const lvalue overload).
operator const parse_error&() const explicit noexcept: Returns the internal toml::parse_error (const lvalue overload).
operator parse_error&() explicit noexcept: Returns the internal toml::parse_error.
operator parse_error&&() explicit noexcept: Returns the internal toml::parse_error (rvalue overload).

Iteration

using const_iterator = const_table_iterator: A BidirectionalIterator for iterating over const key-value pairs in a wrapped toml::table.
using iterator = table_iterator: A BidirectionalIterator for iterating over key-value pairs in a wrapped toml::table.
auto begin() -> table_iterator noexcept: Returns an iterator to the first key-value pair in the wrapped table.
auto begin() const -> const_table_iterator noexcept: Returns an iterator to the first key-value pair in the wrapped table.
auto cbegin() const -> const_table_iterator noexcept: Returns an iterator to the first key-value pair in the wrapped table.
auto cend() const -> const_table_iterator noexcept: Returns an iterator to one-past-the-last key-value pair in the wrapped table.
auto end() -> table_iterator noexcept: Returns an iterator to one-past-the-last key-value pair in the wrapped table.
auto end() const -> const_table_iterator noexcept: Returns an iterator to one-past-the-last key-value pair in the wrapped table.

Node views

auto at_path(std::string_view path) -> node_view<node> noexcept: Returns a view of the subnode matching a fully-qualified "TOML path".
auto at_path(std::string_view path) const -> node_view<const node> noexcept: Returns a const view of the subnode matching a fully-qualified "TOML path".
auto at_path(const toml::path& path) -> node_view<node> noexcept: Returns a view of the subnode matching a fully-qualified "TOML path".
auto at_path(const toml::path& path) const -> node_view<const node> noexcept: Returns a const view of the subnode matching a fully-qualified "TOML path".
auto at_path(std::wstring_view path) -> node_view<node>: Returns a view of the subnode matching a fully-qualified "TOML path".
auto at_path(std::wstring_view path) const -> node_view<const node>: Returns a const view of the subnode matching a fully-qualified "TOML path".
auto operator[](const toml::path& path) -> node_view<node> noexcept: Returns a view of the subnode matching a fully-qualified "TOML path".
auto operator[](const toml::path& path) const -> node_view<const node> noexcept: Returns a const view of the subnode matching a fully-qualified "TOML path".
auto operator[](std::string_view key) -> node_view<node> noexcept: Gets a node_view for the selected key-value pair in the wrapped table.
auto operator[](std::string_view key) const -> node_view<const node> noexcept: Gets a node_view for the selected key-value pair in the wrapped table (const overload).
auto operator[](std::wstring_view key) -> node_view<node>: Gets a node_view for the selected key-value pair in the wrapped table.
auto operator[](std::wstring_view key) const -> node_view<const node>: Gets a node_view for the selected key-value pair in the wrapped table (const overload).

Result state

auto failed() const -> bool noexcept: Returns true if parsing failed.
operator bool() const explicit noexcept: Returns true if parsing succeeded.
auto succeeded() const -> bool noexcept: Returns true if parsing succeeeded.

Successful parses

operator const toml::table&() const noexcept: Returns the internal toml::table (const lvalue overload).
operator toml::table&() noexcept: Returns the internal toml::table.
operator toml::table&&() noexcept: Returns the internal toml::table (rvalue overload).
auto table() & -> toml::table& noexcept: Returns the internal toml::table.
auto table() && -> toml::table&& noexcept: Returns the internal toml::table (rvalue overload).
auto table() const & -> const toml::table& noexcept: Returns the internal toml::table (const lvalue overload).

Friends

auto operator<<(std::ostream& os, const parse_result& result) -> std::ostream&: Prints the held error or table object out to a text stream.

Function documentation

table_iterator toml::parse_result::begin() noexcept

Returns an iterator to the first key-value pair in the wrapped table.

const_table_iterator toml::parse_result::begin() const noexcept

Returns an iterator to the first key-value pair in the wrapped table.

const_table_iterator toml::parse_result::cbegin() const noexcept

Returns an iterator to the first key-value pair in the wrapped table.

node_view<node> toml::parse_result::at_path(std::string_view path) noexcept

Returns a view of the subnode matching a fully-qualified "TOML path".

node_view<const node> toml::parse_result::at_path(std::string_view path) const noexcept

Returns a const view of the subnode matching a fully-qualified "TOML path".

node_view<node> toml::parse_result::at_path(const toml::path& path) noexcept

Returns a view of the subnode matching a fully-qualified "TOML path".

node_view<const node> toml::parse_result::at_path(const toml::path& path) const noexcept

Returns a const view of the subnode matching a fully-qualified "TOML path".

node_view<node> toml::parse_result::at_path(std::wstring_view path)

Returns a view of the subnode matching a fully-qualified "TOML path".

node_view<const node> toml::parse_result::at_path(std::wstring_view path) const

Returns a const view of the subnode matching a fully-qualified "TOML path".

node_view<node> toml::parse_result::operator[](const toml::path& path) noexcept

Returns a view of the subnode matching a fully-qualified "TOML path".

node_view<const node> toml::parse_result::operator[](const toml::path& path) const noexcept

Returns a const view of the subnode matching a fully-qualified "TOML path".

node_view<node> toml::parse_result::operator[](std::string_view key) noexcept

Gets a node_view for the selected key-value pair in the wrapped table.

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if parsing was successful and a matching key existed, or an empty node view.

node_view<const node> toml::parse_result::operator[](std::string_view key) const noexcept

Gets a node_view for the selected key-value pair in the wrapped table (const overload).

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if parsing was successful and a matching key existed, or an empty node view.

node_view<node> toml::parse_result::operator[](std::wstring_view key)

Gets a node_view for the selected key-value pair in the wrapped table.

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if parsing was successful and a matching key existed, or an empty node view.

node_view<const node> toml::parse_result::operator[](std::wstring_view key) const

Gets a node_view for the selected key-value pair in the wrapped table (const overload).

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if parsing was successful and a matching key existed, or an empty node view.

std::ostream& operator<<(std::ostream& os, const parse_result& result)

Prints the held error or table object out to a text stream.