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 ValueType>
class value final
A TOML value.

Public functions

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).
template<typename T>
auto as() -> impl::wrap_node<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<std::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::unwrap_node<T>&& noexcept
Gets a raw reference to a value node's underlying data (rvalue overload).
template<typename T>
auto ref() & -> impl::unwrap_node<T>& noexcept
Gets a raw reference to a value node's underlying data.
template<typename T>
auto ref() const & -> const impl::unwrap_node<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 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.
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::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>" << 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::unwrap_node<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 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.

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 << "'" << key << "' as " << type_name << ": ";
        using type = std::remove_pointer_t<decltype(dummy)>;
        if (std::optional<type> val = tbl.get(key)->value<type>())
            std::cout << *val << "\n";
        else
            std::cout << "No conversion path or out-of-range\n";
    };

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

print_value("int", bool);
print_value("int", int);
print_value("int", unsigned int);
print_value("int", long long);
print_value("int", float);
print_value("int", double);
std::cout << "\n";

print_value("flt", bool);
print_value("flt", int);
print_value("flt", unsigned int);
print_value("flt", long long);
print_value("flt", float);
print_value("flt", double);
std::cout << "\n";

print_value("pi", bool);
print_value("pi", int);
print_value("pi", unsigned int);
print_value("pi", long long);
print_value("pi", float);
print_value("pi", double);
std::cout << "\n";

print_value("bool", bool);
print_value("bool", int);
print_value("bool", unsigned int);
print_value("bool", long long);
print_value("bool", float);
print_value("bool", double);
std::cout << "\n";

print_value("huge", bool);
print_value("huge", int);
print_value("huge", unsigned int);
print_value("huge", long long);
print_value("huge", float);
print_value("huge", double);
std::cout << "\n";

print_value("str", std::string);
print_value("str", std::string_view);
print_value("str", const char*);
std::cout << "\n";
'int' as bool: true
'int' as int: -10
'int' as unsigned int: No conversion path or out-of-range
'int' as long long: -10
'int' as float: -10
'int' as double: -10

'flt' as bool: No conversion path or out-of-range
'flt' as int: 25
'flt' as unsigned int: 25
'flt' as long long: 25
'flt' as float: 25
'flt' as double: 25

'pi' as bool: No conversion path or out-of-range
'pi' as int: No conversion path or out-of-range
'pi' as unsigned int: No conversion path or out-of-range
'pi' as long long: No conversion path or out-of-range
'pi' as float: 3.14159
'pi' as double: 3.14159

'bool' as bool: false
'bool' as int: 0
'bool' as unsigned int: 0
'bool' as long long: 0
'bool' as float: No conversion path or out-of-range
'bool' as double: No conversion path or out-of-range

'huge' as bool: true
'huge' as int: No conversion path or out-of-range
'huge' as unsigned int: No conversion path or out-of-range
'huge' as long long: 9223372036854775807
'huge' as float: No conversion path or out-of-range
'huge' as double: No conversion path or out-of-range

'str' as std::string: foo
'str' as std::string_view: foo
'str' as 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>
    else
        throw std::exception{ "Expected string or integer" };
});