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(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.

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

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(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".

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.

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)); });