toml::parse_result class

The result of a parsing operation.

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.