toml::node class

A TOML node.

A parsed TOML document forms a tree made up of tables, arrays and values. This type is the base of each of those, providing a lot of the polymorphic plumbing.

Derived classes

class array: A TOML array.
class table: A TOML table.
template <typename ValueType> class value: A TOML value.

Metadata

auto source() const -> const source_region& noexcept: Returns the source region responsible for generating this node during parsing.

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".
operator node_view<const node>() const explicit noexcept: Creates a node_view pointing to this node (const overload).
operator node_view<node>() explicit noexcept: Creates a node_view pointing to this node.
auto operator[](const toml::path& path) -> node_view<node> noexcept: Returns a const 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".

Type casts

template <typename T> auto as() -> impl::wrap_node<T>* noexcept: Gets a pointer to the node as a more specific node type.
template <typename T> auto as() const -> const impl::wrap_node<T>* noexcept: Gets a pointer to the node as a more specific node type (const overload).
auto as_array() -> array* pure virtual noexcept: Returns a pointer to the node as a toml::array, if it is one.
auto as_array() const -> const array* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::array, if it is one.
auto as_boolean() -> toml::value<bool>* pure virtual noexcept: Returns a pointer to the node as a toml::value<bool>, if it is one.
auto as_boolean() const -> const toml::value<bool>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<bool>, if it is one.
auto as_date() -> toml::value<date>* pure virtual noexcept: Returns a pointer to the node as a toml::value<toml::date>, if it is one.
auto as_date() const -> const toml::value<date>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<toml::date>, if it is one.
auto as_date_time() -> toml::value<date_time>* pure virtual noexcept: Returns a pointer to the node as a toml::value<toml::date_time>, if it is one.
auto as_date_time() const -> const toml::value<date_time>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<toml::date_time>, if it is one.
auto as_floating_point() -> toml::value<double>* pure virtual noexcept: Returns a pointer to the node as a toml::value<double>, if it is one.
auto as_floating_point() const -> const toml::value<double>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<double>, if it is one.
auto as_integer() -> toml::value<int64_t>* pure virtual noexcept: Returns a pointer to the node as a toml::value<int64_t>, if it is one.
auto as_integer() const -> const toml::value<int64_t>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<int64_t>, if it is one.
auto as_string() -> toml::value<std::string>* pure virtual noexcept: Returns a pointer to the node as a toml::value<std::string>, if it is one.
auto as_string() const -> const toml::value<std::string>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<std::string>, if it is one.
auto as_table() -> table* pure virtual noexcept: Returns a pointer to the node as a toml::table, if it is one.
auto as_table() const -> const table* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::table, if it is one.
auto as_time() -> toml::value<time>* pure virtual noexcept: Returns a pointer to the node as a toml::value<toml::time>, if it is one.
auto as_time() const -> const toml::value<time>* pure virtual noexcept: Returns a const-qualified pointer to the node as a toml::value<toml::time>, if it is one.

Type checks

template <typename T> auto is() const -> bool noexcept: Checks if a node is a specific type.
auto is_array() const -> bool pure virtual noexcept: Returns true if this node is an array.
auto is_array_of_tables() const -> bool pure virtual noexcept: Returns true if this node is an array containing only tables.
auto is_boolean() const -> bool pure virtual noexcept: Returns true if this node is a boolean value.
auto is_date() const -> bool pure virtual noexcept: Returns true if this node is a local date value.
auto is_date_time() const -> bool pure virtual noexcept: Returns true if this node is a date-time value.
auto is_floating_point() const -> bool pure virtual noexcept: Returns true if this node is an floating-point value.
auto is_homogeneous(node_type ntype, node*& first_nonmatch) -> bool pure virtual noexcept: Checks if a node contains values/elements of only one type.
auto is_homogeneous(node_type ntype, const node*& first_nonmatch) const -> bool pure virtual noexcept: Checks if a node contains values/elements of only one type (const overload).
auto is_homogeneous(node_type ntype) const -> bool pure virtual noexcept: Checks if the node contains values/elements of only one type.
template <typename ElemType = void> auto is_homogeneous() const -> bool noexcept: Checks if the node contains values/elements of only one type.
auto is_integer() const -> bool pure virtual noexcept: Returns true if this node is an integer value.
auto is_number() const -> bool pure virtual noexcept: Returns true if this node is an integer or floating-point value.
auto is_string() const -> bool pure virtual noexcept: Returns true if this node is a string value.
auto is_table() const -> bool pure virtual noexcept: Returns true if this node is a table.
auto is_time() const -> bool pure virtual noexcept: Returns true if this node is a local time value.
auto is_value() const -> bool pure virtual noexcept: Returns true if this node is a value.
auto type() const -> node_type pure virtual noexcept: Returns the node's type identifier.

Value retrieval

template <typename T> auto ref() & -> decltype(auto) noexcept: Gets a raw reference to a node's underlying data.
template <typename T> auto ref() && -> decltype(auto) noexcept: Gets a raw reference to a node's underlying data (rvalue overload).
template <typename T> auto ref() const & -> decltype(auto) noexcept: Gets a raw reference to a node's underlying data (const lvalue overload).
template <typename T> auto ref() const && -> decltype(auto) noexcept: Gets a raw reference to a node's underlying data (const rvalue overload).
template <typename T> auto value() const -> optional<T> noexcept(…): Gets the value contained by this node.
template <typename T> auto value_exact() const -> optional<T> noexcept(…): Gets the value contained by this node.
template <typename T> auto value_or(T&& default_value) const -> auto noexcept(…): Gets the raw value contained by this node, or a default.

Visitation

template <typename Func> auto visit(Func&& visitor) & -> decltype(auto) noexcept(…): Invokes a visitor on the node based on the node's concrete type.
template <typename Func> auto visit(Func&& visitor) && -> decltype(auto) noexcept(…): Invokes a visitor on the node based on the node's concrete type (rvalue overload).
template <typename Func> auto visit(Func&& visitor) const & -> decltype(auto) noexcept(…): Invokes a visitor on the node based on the node's concrete type (const lvalue overload).
template <typename Func> auto visit(Func&& visitor) const && -> decltype(auto) noexcept(…): Invokes a visitor on the node based on the node's concrete type (const rvalue overload).

Function documentation

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

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

Parameters
path	The "TOML path" to traverse.

auto config = toml::parse(R"(

[foo]
bar = [ 0, 1, 2, [ 3 ], { kek = 4 } ]

)"sv);

std::cout << config.at_path("foo.bar[2]") << "\n";
std::cout << config.at_path("foo.bar[3][0]") << "\n";
std::cout << config.at_path("foo.bar[4].kek") << "\n";

2
3
4

Note

Keys in paths are interpreted literally, so whitespace (or lack thereof) matters:

config.at_path( "foo.bar")  // same as node_view{ config }["foo"]["bar"]
config.at_path( "foo. bar") // same as node_view{ config }["foo"][" bar"]
config.at_path( "foo..bar") // same as node_view{ config }["foo"][""]["bar"]
config.at_path( ".foo.bar") // same as node_view{ config }[""]["foo"]["bar"]

Additionally, TOML allows '.' (period) characters to appear in keys if they are quoted strings. This function makes no allowance for this, instead treating all period characters as sub-table delimiters. If you have periods in your table keys, first consider:

Not doing that
Using node_view::operator[] instead.

node_view<const node> toml::node::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::node::at_path(const toml::path& path) noexcept

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

Parameters
path	The "TOML path" to traverse.

auto config = toml::parse(R"(

[foo]
bar = [ 0, 1, 2, [ 3 ], { kek = 4 } ]

)"sv);

toml::path path1("foo.bar[2]");
toml::path path2("foo.bar[4].kek");
std::cout << config.at_path(path1) << "\n";
std::cout << config.at_path(path1.parent_path()) << "\n";
std::cout << config.at_path(path2) << "\n";
std::cout << config.at_path(path2.parent_path()) << "\n";

2
[ 0, 1, 2, [ 3 ], { kek = 4 } ]
4
{ kek  = 4 }

Note

Keys in paths are interpreted literally, so whitespace (or lack thereof) matters:

config.at_path(toml::path("foo.bar")) // same as node_view{ config }["foo"]["bar"]
config.at_path(toml::path("foo. bar")) // same as node_view{ config }["foo"][" bar"]
config.at_path(toml::path("foo..bar")) // same as node_view{ config }["foo"][""]["bar"]
config.at_path(toml::path(".foo.bar")) // same as node_view{ config }[""]["foo"]["bar"]

node_view<const node> toml::node::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::node::at_path(std::wstring_view path)

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

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

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

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

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

Parameters
path	The "TOML path" to the desired child.
Returns	A view of the child node at the given path if one existed, or an empty node view.

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

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

Parameters
path	The "TOML path" to the desired child.
Returns	A view of the child node at the given path if one existed, or an empty node view.

template <typename T>
impl::wrap_node<T>* toml::node::as() noexcept

Gets a pointer to the node as a more specific node type.

Template parameters
T	The node type or TOML value type to cast to.
Returns	A pointer to the node as the given type, or nullptr if it was a different type.

toml::value<int64_t>* int_value = node->as<int64_t>();
toml::table* tbl = node->as<toml::table>();
if (int_value)
    std::cout << "Node is a value<int64_t>\n";
else if (tbl)
    std::cout << "Node is a table\n";

// fully-qualified value node types also work (useful for template code):
toml::value<int64_t>* int_value2 = node->as<toml::value<int64_t>>();
if (int_value2)
    std::cout << "Node is a value<int64_t>\n";

template <typename T>
bool toml::node::is() const noexcept

Checks if a node is a specific type.

Template parameters
T	A TOML node or value type.
Returns	Returns true if this node is an instance of the specified type.

bool toml::node::is_homogeneous(node_type ntype, node*& first_nonmatch) pure virtual noexcept

Checks if a node contains values/elements of only one type.

Parameters
ntype	A TOML node type. *toml::node_type::none:* "is every element the same type?" *Anything else:* "is every element one of these?"
first_nonmatch	Reference to a pointer in which the address of the first non-matching element will be stored if the return value is false.
Returns	True if the node was homogeneous.

auto cfg = toml::parse("arr = [ 1, 2, 3, 4.0 ]");
toml::array& arr = *cfg["arr"].as_array();

toml::node* nonmatch{};
if (arr.is_homogeneous(toml::node_type::integer, nonmatch))
    std::cout << "array was homogeneous"sv << "\n";
else
    std::cout << "array was not homogeneous!\n"
    << "first non-match was a "sv << nonmatch->type() << " at " << nonmatch->source() << "\n";

array was not homogeneous!
first non-match was a floating-point at line 1, column 18

bool toml::node::is_homogeneous(node_type ntype) const pure virtual noexcept

Checks if the node contains values/elements of only one type.

Parameters
ntype	A TOML node type. *toml::node_type::none:* "is every element the same type?" *Anything else:* "is every element one of these?"
Returns	True if the node was homogeneous.

auto arr = toml::array{ 1, 2, 3 };
std::cout << "homogenous: "sv << arr.is_homogeneous(toml::node_type::none) << "\n";
std::cout << "all floats: "sv << arr.is_homogeneous(toml::node_type::floating_point) << "\n";
std::cout << "all arrays: "sv << arr.is_homogeneous(toml::node_type::array) << "\n";
std::cout << "all ints:   "sv << arr.is_homogeneous(toml::node_type::integer) << "\n";

homogeneous: true
all floats:  false
all arrays:  false
all ints:    true

template <typename ElemType = void>
bool toml::node::is_homogeneous() const noexcept

Checks if the node contains values/elements of only one type.

Template parameters
ElemType	A TOML node or value type. *Left as `void`:* "is every element the same type?" *Explicitly specified:* "is every element a T?"
Returns	True if the node was homogeneous.

auto arr = toml::array{ 1, 2, 3 };
std::cout << "homogenous:   "sv << arr.is_homogeneous() << "\n";
std::cout << "all doubles:  "sv << arr.is_homogeneous<double>() << "\n";
std::cout << "all arrays:   "sv << arr.is_homogeneous<toml::array>() << "\n";
std::cout << "all integers: "sv << arr.is_homogeneous<int64_t>() << "\n";

homogeneous: true
all floats:  false
all arrays:  false
all ints:    true

template <typename T>
decltype(auto) toml::node::ref() & noexcept

Gets a raw reference to a node's underlying data.

Template parameters
T	toml::table, toml::array, or one of the TOML value types.
Returns	A reference to the underlying data.

Warning

This function is dangerous if used carelessly and WILL break your code if the chosen value type doesn't match the node's actual type. In debug builds an assertion will fire when invalid accesses are attempted:

auto tbl = toml::parse(R"(
    min = 32
    max = 45
)"sv);

int64_t& min_ref = tbl.at("min").ref<int64_t>(); // matching type
double& max_ref = tbl.at("max").ref<double>();  // mismatched type, hits assert()

Note

Specifying explicit ref qualifiers acts as an explicit ref-category cast, whereas specifying explicit cv-ref qualifiers merges them with whatever the cv qualification of the node is (to ensure cv-correctness is propagated), e.g.:

node	T	return type
node&	std::string	std::string&
node&	std::string&&	std::string&&
const node&	volatile std::string	const volatile std::string&
const node&	volatile std::string&&	const volatile std::string&&

template <typename T>
optional<T> toml::node::value() const noexcept(…)

Gets the value contained by this node.

Template parameters
T	One of the native TOML value types, or a type capable of converting to one.
Returns	The underlying value if the node was a value of the matching type (or convertible to it) and within the range of the output type, or an empty optional.

This function has 'permissive' retrieval semantics; some value types are allowed to convert to others (e.g. retrieving a boolean as an integer), and the specified return value type can be any type where a reasonable conversion from a native TOML value exists (e.g. std::wstring on Windows). If the source value cannot be represented by the destination type, an empty optional is returned.

Try this code on Compiler Explorer
auto tbl = toml::parse(R"(
    int = -10
    flt = 25.0
    pi  = 3.14159
    bool = false
    huge = 9223372036854775807
    str = "foo"
)"sv);

const auto print_value_with_typename =
    [&](std::string_view key, std::string_view type_name, auto* dummy)
    {
        std::cout << "- " << std::setw(18) << std::left << type_name;
        using type = std::remove_pointer_t<decltype(dummy)>;
        if (auto val = tbl.get(key)->value<type>(); val)
            std::cout << *val << "\n";
        else
            std::cout << "n/a\n";
    };

#define print_value(key, T) print_value_with_typename(key, #T, (T*)nullptr)

for (auto key : { "int", "flt", "pi", "bool", "huge", "str" })
{
    std::cout << tbl[key].type() << " value '" << key << "' as:\n";
    print_value(key, bool);
    print_value(key, int);
    print_value(key, unsigned int);
    print_value(key, long long);
    print_value(key, float);
    print_value(key, double);
    print_value(key, std::string);
    print_value(key, std::string_view);
    print_value(key, const char*);
    std::cout << "\n";
}

integer value 'int' as:
- bool              true
- int               -10
- unsigned int      n/a
- long long         -10
- float             -10
- double            -10
- std::string       n/a
- std::string_view  n/a
- const char*       n/a

floating-point value 'flt' as:
- bool              n/a
- int               25
- unsigned int      25
- long long         25
- float             25
- double            25
- std::string       n/a
- std::string_view  n/a
- const char*       n/a

floating-point value 'pi' as:
- bool              n/a
- int               n/a
- unsigned int      n/a
- long long         n/a
- float             3.14159
- double            3.14159
- std::string       n/a
- std::string_view  n/a
- const char*       n/a

boolean value 'bool' as:
- bool              false
- int               0
- unsigned int      0
- long long         0
- float             n/a
- double            n/a
- std::string       n/a
- std::string_view  n/a
- const char*       n/a

integer value 'huge' as:
- bool              true
- int               n/a
- unsigned int      n/a
- long long         9223372036854775807
- float             n/a
- double            n/a
- std::string       n/a
- std::string_view  n/a
- const char*       n/a

string value 'str' as:
- bool              n/a
- int               n/a
- unsigned int      n/a
- long long         n/a
- float             n/a
- double            n/a
- std::string       foo
- std::string_view  foo
- const char*       foo

template <typename T>
optional<T> toml::node::value_exact() const noexcept(…)

Gets the value contained by this node.

Template parameters
T	One of the native TOML value types, or a type capable of losslessly representing one.
Returns	The underlying value if the node was a value of the matching type (or losslessly convertible to it), or an empty optional.

This function has 'exact' retrieval semantics; the only return value types allowed are the TOML native value types, or types that can losslessly represent a native value type (e.g. std::wstring on Windows).

template <typename T>
auto toml::node::value_or(T&& default_value) const noexcept(…)

Gets the raw value contained by this node, or a default.

Template parameters
T	Default value type. Must be one of the native TOML value types, or convertible to it.
Parameters
default_value	The default value to return if the node wasn't a value, wasn't the correct type, or no conversion was possible.
Returns	The underlying value if the node was a value of the matching type (or convertible to it) and within the range of the output type, or the provided default.

template <typename Func>
decltype(auto) toml::node::visit(Func&& visitor) & noexcept(…)

Invokes a visitor on the node based on the node's concrete type.

Template parameters
Func	A callable type invocable with one or more of the toml++ node types.
Parameters
visitor	The visitor object.
Returns	The return value of the visitor. Can be void. Non-exhaustive visitors must return a default-constructible type.

Visitation is useful when you expect a node to be one of a set number of types and need to handle these types differently. Using visit() allows you to eliminate some of the casting/conversion boilerplate:

node.visit([](auto&& n)
{
    if constexpr (toml::is_string<decltype(n)>)
        do_something_with_a_string(*n)); //n is a toml::value<std::string>
    else if constexpr (toml::is_integer<decltype(n)>)
        do_something_with_an_int(*n); //n is a toml::value<int64_t>
});

Visitor functions need not be generic; specifying a concrete node type as the input argument type effectively acts a 'filter', only invoking the visitor if the concrete type is compatible. Thus the example above can be re-written as:

node.visit([](toml::value<std::string>& s) { do_something_with_a_string(*s)); });
node.visit([](toml::value<int64_t>& i)     { do_something_with_an_int(*i)); });

toml::node class

Derived classes

Metadata

Node views

Type casts

Type checks

Value retrieval

Visitation

Function documentation

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

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

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

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

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

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

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

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

template <typename T> impl::wrap_node<T>* toml::node::as() noexcept

template <typename T> bool toml::node::is() const noexcept

bool toml::node::is_homogeneous(node_type ntype, node*& first_nonmatch) pure virtual noexcept

bool toml::node::is_homogeneous(node_type ntype) const pure virtual noexcept

template <typename ElemType = void> bool toml::node::is_homogeneous() const noexcept

template <typename T> decltype(auto) toml::node::ref() & noexcept

template <typename T> optional<T> toml::node::value() const noexcept(…)

template <typename T> optional<T> toml::node::value_exact() const noexcept(…)

template <typename T> auto toml::node::value_or(T&& default_value) const noexcept(…)

template <typename Func> decltype(auto) toml::node::visit(Func&& visitor) & noexcept(…)

template <typename T>
impl::wrap_node<T>* toml::node::as() noexcept

template <typename T>
bool toml::node::is() const noexcept

template <typename ElemType = void>
bool toml::node::is_homogeneous() const noexcept

template <typename T>
decltype(auto) toml::node::ref() & noexcept

template <typename T>
optional<T> toml::node::value() const noexcept(…)

template <typename T>
optional<T> toml::node::value_exact() const noexcept(…)

template <typename T>
auto toml::node::value_or(T&& default_value) const noexcept(…)

template <typename Func>
decltype(auto) toml::node::visit(Func&& visitor) & noexcept(…)