toml::node class

A TOML node.

Contents

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 final
A TOML array.
class table final
A TOML table.
template<typename T>
class value final
A TOML value.

Public functions

template<typename T>
auto as() const -> const impl::node_of<T>* noexcept
Gets a pointer to the node as a more specific node type (const overload).
template<typename T>
auto as() -> impl::node_of<T>* noexcept
Gets a pointer to the node as a more specific node type.
auto as_array() -> array* virtual noexcept
Returns a pointer to the node as a toml::array, if it is one.
auto as_boolean() -> toml::value<bool>* virtual noexcept
Returns a pointer to the node as a toml::value<bool>, if it is one.
auto as_date() -> toml::value<date>* virtual noexcept
Returns a pointer to the node as a toml::value<date>, if it is one.
auto as_date_time() -> toml::value<date_time>* virtual noexcept
Returns a pointer to the node as a toml::value<date_time>, if it is one.
auto as_floating_point() -> toml::value<double>* virtual noexcept
Returns a pointer to the node as a toml::value<double>, if it is one.
auto as_integer() -> toml::value<int64_t>* virtual noexcept
Returns a pointer to the node as a toml::value<int64_t>, if it is one.
auto as_string() -> toml::value<string>* virtual noexcept
Returns a pointer to the node as a toml::value<string>, if it is one.
auto as_table() -> table* virtual noexcept
Returns a pointer to the node as a toml::table, if it is one.
auto as_time() -> toml::value<time>* virtual noexcept
Returns a pointer to the node as a toml::value<time>, if it is one.
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 virtual noexcept
Returns true if this node is an array containing only tables.
auto is_boolean() const -> bool virtual noexcept
Returns true if this node is a boolean value.
auto is_date() const -> bool virtual noexcept
Returns true if this node is a local date value.
auto is_date_time() const -> bool virtual noexcept
Returns true if this node is a date-time value.
auto is_floating_point() const -> bool virtual noexcept
Returns true if this node is an floating-point value.
auto is_integer() const -> bool virtual noexcept
Returns true if this node is an integer value.
auto is_number() const -> bool virtual noexcept
Returns true if this node is an integer or floating-point value.
auto is_string() const -> bool 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 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.
template<typename T>
auto ref() && -> impl::unwrapped<T>&& noexcept
Gets a raw reference to a value node's underlying data (rvalue overload).
template<typename T>
auto ref() & -> impl::unwrapped<T>& noexcept
Gets a raw reference to a value node's underlying data.
template<typename T>
auto ref() const & -> const impl::unwrapped<T>& noexcept
Gets a raw reference to a value node's underlying data (const lvalue overload).
auto source() const -> const source_region& noexcept
Returns the source region responsible for generating this node during parsing.
auto type() const -> node_type pure virtual noexcept
Returns the node's type identifier.
template<typename T>
auto value() const -> optional<T> noexcept
Gets the raw 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.
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) & -> decltype(auto) noexcept(…)
Invokes a visitor on the node based on the node's concrete type.
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).

Function documentation

template<typename T>
impl::node_of<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>" << std::endl;
else if (tbl)
    std::cout << "Node is a table" << std::endl;

// 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>" << std::endl;

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.

template<typename T>
impl::unwrapped<T>& toml::node::ref() & noexcept

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

Template parameters
T 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 raw value contained by this node.

Template parameters
T One of the TOML value types. Can also be a string_view.
Returns The underlying value if the node was a value of the matching type (or convertible to it), or an empty optional.

The optional returned by this function will only contain a value if the node was an instance of toml::value with the same value type as the template argument. Additionally, some type are allowed to convert to each other, for instance asking for an integer when the value exists as a double, or requesting a string value as a string_view:

auto tbl = toml::parse(R"(
    int_val = 10
    float_val = 25.6
    string_val = "kek"
)"sv);

if (auto val = tbl.get("int_val"sv)->value<int64_t>())
    std::cout << "'int_val' as int64_t: "sv << *val << std::endl;
    
if (auto val = tbl.get("int_val"sv)->value<double>())
    std::cout << "'int_val' as double: "sv << *val << std::endl;
    
if (auto val = tbl.get("float_val"sv)->value<int64_t>())
    std::cout << "'float_val' as int64_t: "sv << *val << std::endl;
    
if (auto val = tbl.get("float_val"sv)->value<double>())
    std::cout << "'float_val' as double: "sv << *val << std::endl;
    
if (auto val = tbl.get("string_val"sv)->value<std::string>())
    std::cout << "'string_val' as std::string: "sv << *val << std::endl;
    
if (auto val = tbl.get("string_val"sv)->value<std::string_view>())
    std::cout << "'string_val' as std::string_view: "sv << *val << std::endl;
    
if (auto val = tbl.get("string_val"sv)->value<int64_t>())
    std::cout << "this line won't be printed because string_val wasn't an int."sv << std::endl;
'int_val' as int64_t: 10
'int_val' as double: 10
'float_val' as int64_t: 25
'float_val' as double: 25.6
'string_val' as std::string: kek
'string_val' as std::string_view: kek

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 (or be promotable to) one of the TOML value types.
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 node's underlying value, or the default if the node wasn't a value, wasn't the correct type, or no conversion was possible.

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<toml::string>
    else if constexpr (toml::is_integer<decltype(n)>)
        do_something_with_an_int(*n); //n is a toml::value<int64_t>
    else
        throw std::exception{ "Expected string or integer" };
});