toml::table class final

A TOML table.

Base classes

class node: A TOML node.

Public types

using const_iterator = const_table_iterator: A BidirectionalIterator for iterating over const key-value pairs in a toml::table.
using iterator = table_iterator: A BidirectionalIterator for iterating over key-value pairs in a toml::table.

Constructors, destructors, conversion operators

table() noexcept: Default constructor.
table(const table&) noexcept: Copy constructor.
table(table&& other) noexcept: Move constructor.
template <size_t N> table(impl::table_init_pair( && arr)[N]) explicit noexcept: Constructs a table with one or more initial key-value pairs.
~table() override noexcept: Destructor.

Public functions

auto operator=(const table&) → table& noexcept: Copy-assignment operator.
auto operator=(table&& rhs) → table& noexcept: Move-assignment operator.

Equality

auto operator!=(const table& lhs, const table& rhs) → bool noexcept: Inequality operator.
template <typename Char> auto operator<<(std::basic_ostream<Char>&, const table&) → std::basic_ostream<Char>&: Prints the table out to a stream as formatted TOML.
auto operator==(const table& lhs, const table& rhs) → bool noexcept: Equality operator.

Metadata

auto is_inline() const → bool noexcept: Returns true if this table is an inline table.
void is_inline(bool val) noexcept: Sets whether this table is a TOML inline table.
auto source() const → const source_region& noexcept: Returns the source region responsible for generating this node during parsing.

Node views

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[](std::string_view key) → node_view<node> noexcept: Gets a node_view for the selected key-value pair.
auto operator[](std::string_view key) const → node_view<const node> noexcept: Gets a node_view for the selected key-value pair (const overload).
auto operator[](std::wstring_view key) → node_view<node> noexcept: Gets a node_view for the selected key-value pair.
auto operator[](std::wstring_view key) const → node_view<const node> noexcept: Gets a node_view for the selected key-value pair (const overload).

Table operations

auto begin() → iterator noexcept: Returns an iterator to the first key-value pair.
auto begin() const → const_iterator noexcept: Returns an iterator to the first key-value pair.
auto cbegin() const → const_iterator noexcept: Returns an iterator to the first key-value pair.
auto cend() const → const_iterator noexcept: Returns an iterator to one-past-the-last key-value pair.
void clear() noexcept: Removes all key-value pairs from the table.
auto contains(std::string_view key) const → bool noexcept: Returns true if the table contains a node at the given key.
auto contains(std::wstring_view key) const → bool noexcept: Returns true if the table contains a node at the given key.
template <typename ValueType, typename KeyType, typename... ValueArgs> auto emplace(KeyType&& key, ValueArgs && ... args) → std::pair<iterator, bool> noexcept: Emplaces a new value at a specific key if one did not already exist.
auto empty() const → bool noexcept: Returns true if the table is empty.
auto end() → iterator noexcept: Returns an iterator to one-past-the-last key-value pair.
auto end() const → const_iterator noexcept: Returns an iterator to one-past-the-last key-value pair.
auto erase(iterator pos) → iterator noexcept: Removes the specified key-value pair from the table.
auto erase(const_iterator pos) → iterator noexcept: Removes the specified key-value pair from the table (const iterator overload).
auto erase(const_iterator first, const_iterator last) → iterator noexcept: Removes the key-value pairs in the range [first, last) from the table.
auto erase(std::string_view key) → bool noexcept: Removes the value with the given key from the table.
auto erase(std::wstring_view key) → bool noexcept: Removes the value with the given key from the table.
auto find(std::string_view key) → iterator noexcept: Gets an iterator to the node at a specific key.
auto find(std::string_view key) const → const_iterator noexcept: Gets an iterator to the node at a specific key (const overload)
auto find(std::wstring_view key) → iterator noexcept: Gets an iterator to the node at a specific key.
auto find(std::wstring_view key) const → const_iterator noexcept: Gets an iterator to the node at a specific key (const overload).
template <typename KeyType, typename ValueType, typename = std::enable_if_t< std::is_convertible_v<KeyType && , std::string_view> || impl::is_wide_string<KeyType> >> auto insert(KeyType&& key, ValueType&& val) → std::pair<iterator, bool> noexcept: Inserts a new value at a specific key if one did not already exist.
template <typename Iter, typename = std::enable_if_t< !std::is_convertible_v<Iter, std::string_view> && !impl::is_wide_string<Iter> >> void insert(Iter first, Iter last) noexcept: Inserts a series of key-value pairs into the table.
template <typename KeyType, typename ValueType> auto insert_or_assign(KeyType&& key, ValueType&& val) → std::pair<iterator, bool> noexcept: Inserts or assigns a value at a specific key.
auto size() const → size_t noexcept: Returns the number of key-value pairs in the table.

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* 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* override 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.

Type checks

template <typename T> auto is() const → bool noexcept: Checks if a node is a specific type.
auto is_array() const → bool override 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_homogeneous(node_type ntype) const → bool override noexcept: Checks if the node contains values/elements of only one type.
auto is_homogeneous(node_type ntype, node*& first_nonmatch) → bool override noexcept: Checks if a node contains values/elements of only one type.
auto is_homogeneous(node_type ntype, const node*& first_nonmatch) const → bool override noexcept: Checks if a node contains values/elements of only one type (const overload).
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 override 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 override noexcept: Returns true if this node is a value.
auto type() const → node_type override noexcept: Returns the node's type identifier.

Value retrieval

auto get(std::string_view key) → node* noexcept: Gets the node at a specific key.
auto get(std::string_view key) const → const node* noexcept: Gets the node at a specific key (const overload).
auto get(std::wstring_view key) → node* noexcept: Gets the node at a specific key.
auto get(std::wstring_view key) const → const node* noexcept: Gets the node at a specific key (const overload).
template <typename ValueType> auto get_as(std::string_view key) → impl::wrap_node<ValueType>* noexcept: Gets the node at a specific key if it is a particular type.
template <typename ValueType> auto get_as(std::string_view key) const → const impl::wrap_node<ValueType>* noexcept: Gets the node at a specific key if it is a particular type (const overload).
template <typename ValueType> auto get_as(std::wstring_view key) → impl::wrap_node<ValueType>* noexcept: Gets the node at a specific key if it is a particular type.
template <typename ValueType> auto get_as(std::wstring_view key) const → const impl::wrap_node<ValueType>* noexcept: Gets the node at a specific key if it is a particular type (const 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() && → impl::unwrap_node<T>&& noexcept: Gets a raw reference to a value node's underlying data (rvalue overload).
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).
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).

Function documentation

template <size_t N>
toml::table::table(impl::table_init_pair( && arr)[N]) explicit noexcept

Constructs a table with one or more initial key-value pairs.

Template parameters
N	Number of key-value pairs used to initialize the table.
Parameters
arr	An array of key-value pairs used to initialize the table.

auto tbl = toml::table{{ // double braces required :( - see remark
    { "foo", 1 },
    { "bar", 2.0 },
    { "kek", "three" }
}};
std::cout << tbl << "\n";

{ foo = 1, bar = 2.0, kek = "three" }

bool toml::table::operator!=(const table& lhs, const table& rhs) noexcept

Inequality operator.

Parameters
lhs	The LHS table.
rhs	The RHS table.
Returns	True if the tables did not contain the same keys and map.

bool toml::table::operator==(const table& lhs, const table& rhs) noexcept

Equality operator.

Parameters
lhs	The LHS table.
rhs	The RHS table.
Returns	True if the tables contained the same keys and map.

bool toml::table::is_inline() const noexcept

Returns true if this table is an inline table.

void toml::table::is_inline(bool val) noexcept

Sets whether this table is a TOML inline table.

Parameters
val	The new value for 'inline'.

Try this code on Compiler Explorer
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 },
    { "d", toml::table{{ { "e", 4 } }} }
}};
std::cout << "is inline? "sv << tbl.is_inline() << "\n";
std::cout << tbl << "\n\n";

tbl.is_inline(!tbl.is_inline());
std::cout << "is inline? "sv << tbl.is_inline() << "\n";
std::cout << tbl << "\n";

is inline? false
a = 1
b = 2
c = 3

[d]
e = 4


is inline? true
{ a = 1, b = 2, c = 3, d = { e = 4 } }

node_view<node> toml::table::operator[](std::string_view key) noexcept

Gets a node_view for the selected key-value pair.

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if one existed, or an empty node view.

node_view<const node> toml::table::operator[](std::string_view key) const noexcept

Gets a node_view for the selected key-value pair (const overload).

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if one existed, or an empty node view.

node_view<node> toml::table::operator[](std::wstring_view key) noexcept

Gets a node_view for the selected key-value pair.

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if one existed, or an empty node view.

node_view<const node> toml::table::operator[](std::wstring_view key) const noexcept

Gets a node_view for the selected key-value pair (const overload).

Parameters
key	The key used for the lookup.
Returns	A view of the value at the given key if one existed, or an empty node view.

bool toml::table::contains(std::wstring_view key) const noexcept

Returns true if the table contains a node at the given key.

template <typename ValueType, typename KeyType, typename... ValueArgs>
std::pair<iterator, bool> toml::table::emplace(KeyType&& key, ValueArgs && ... args) noexcept

Emplaces a new value at a specific key if one did not already exist.

Template parameters
ValueType	toml::table, toml::array, or any native TOML value type.
KeyType	std::string (or a type convertible to it).
ValueArgs	Value constructor argument types.
Parameters
key	The key at which to emplace the new value.
args	Arguments to forward to the value's constructor.
Returns	A std::pair containing: An iterator to the emplacement position (or the position of the value that prevented emplacement) A boolean indicating if the emplacement was successful.

auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

for (auto k : { "a", "d" })
{
    // add a string using std::string's substring constructor
    auto result = tbl.emplace<std::string>(k, "this is not a drill"sv, 14, 5);
    std::cout << "emplaced with key '"sv << k << "': "sv << result.second << "\n";
}
std::cout << tbl << "\n";

{ a = 1, b = 2, c = 3 }
emplaced with key 'a': false
emplaced with key 'd': true
{ a = 1, b = 2, c = 3, d = "drill" }

iterator toml::table::erase(iterator pos) noexcept

Removes the specified key-value pair from the table.

Parameters
pos	Iterator to the key-value pair being erased.
Returns	Iterator to the first key-value pair immediately following the removed key-value pair.

auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

tbl.erase(tbl.begin() + 1);
std::cout << tbl << "\n";

{ a = 1, b = 2, c = 3 }
{ a = 1, c = 3 }

iterator toml::table::erase(const_iterator pos) noexcept

Removes the specified key-value pair from the table (const iterator overload).

Parameters
pos	Iterator to the key-value pair being erased.
Returns	Iterator to the first key-value pair immediately following the removed key-value pair.

auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

tbl.erase(tbl.cbegin() + 1);
std::cout << tbl << "\n";

{ a = 1, b = 2, c = 3 }
{ a = 1, c = 3 }

iterator toml::table::erase(const_iterator first, const_iterator last) noexcept

Removes the key-value pairs in the range [first, last) from the table.

Parameters
first	Iterator to the first key-value pair being erased.
last	Iterator to the one-past-the-last key-value pair being erased.
Returns	Iterator to the first key-value pair immediately following the last removed key-value pair.

auto tbl = toml::table{{
    { "a", 1 },
    { "b", "bad" },
    { "c", "karma" },
    { "d", 2 }
}};
std::cout << tbl << "\n";

tbl.erase(tbl.cbegin() + 1, tbl.cbegin() + 3);
std::cout << tbl << "\n";

{ a = 1, b = "bad", c = "karma", d = 2 }
{ a = 1, d = 2 }

bool toml::table::erase(std::string_view key) noexcept

Removes the value with the given key from the table.

Parameters
key	Key to erase.
Returns	True if any values with matching keys were found and erased.

auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

std::cout << tbl.erase("b") << "\n";
std::cout << tbl.erase("not an existing key") << "\n";
std::cout << tbl << "\n";

{ a = 1, b = 2, c = 3 }
true
false
{ a = 1, c = 3 }

bool toml::table::erase(std::wstring_view key) noexcept

Removes the value with the given key from the table.

Parameters
key	Key to erase.
Returns	True if any values with matching keys were found and erased.

iterator toml::table::find(std::string_view key) noexcept

Gets an iterator to the node at a specific key.

Parameters
key	The node's key.
Returns	An iterator to the node at the specified key, or end().

const_iterator toml::table::find(std::string_view key) const noexcept

Gets an iterator to the node at a specific key (const overload)

Parameters
key	The node's key.
Returns	A const iterator to the node at the specified key, or cend().

iterator toml::table::find(std::wstring_view key) noexcept

Gets an iterator to the node at a specific key.

Parameters
key	The node's key.
Returns	An iterator to the node at the specified key, or end().

const_iterator toml::table::find(std::wstring_view key) const noexcept

Gets an iterator to the node at a specific key (const overload).

Parameters
key	The node's key.
Returns	A const iterator to the node at the specified key, or cend().

template <typename KeyType, typename ValueType, typename = std::enable_if_t< std::is_convertible_v<KeyType && , std::string_view> || impl::is_wide_string<KeyType> >>
std::pair<iterator, bool> toml::table::insert(KeyType&& key, ValueType&& val) noexcept

Inserts a new value at a specific key if one did not already exist.

Template parameters
KeyType	std::string (or a type convertible to it).
ValueType	toml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
key	The key at which to insert the new value.
val	The new value to insert.
Returns	*Valid input:* An iterator to the insertion position (or the position of the value that prevented insertion) A boolean indicating if the insertion was successful. *Input is an empty toml::node_view:* `{ end(), false }`

Try this code on Compiler Explorer
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

for (auto k : { "a", "d" })
{
    auto result = tbl.insert(k, 42);
    std::cout << "inserted with key '"sv << k << "': "sv << result.second << "\n";
}
std::cout << tbl << "\n";

a = 1
b = 2
c = 3

inserted with key 'a': false
inserted with key 'd': true
a = 1
b = 2
c = 3
d = 42

template <typename Iter, typename = std::enable_if_t< !std::is_convertible_v<Iter, std::string_view> && !impl::is_wide_string<Iter> >>
void toml::table::insert(Iter first, Iter last) noexcept

Inserts a series of key-value pairs into the table.

Template parameters
Iter	An InputIterator to a collection of key-value pairs.
Parameters
first	An iterator to the first value in the input collection.
last	An iterator to one-past-the-last value in the input collection.

Try this code on Compiler Explorer
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

auto kvps = std::array<std::pair<std::string, int>, 2>{{
    { "d", 42 },
    { "a", 43 } // won't be inserted, 'a' already exists
}};
tbl.insert(kvps.begin(), kvps.end());
std::cout << tbl << "\n";

a = 1
b = 2
c = 3

a = 1
b = 2
c = 3
d = 42

template <typename KeyType, typename ValueType>
std::pair<iterator, bool> toml::table::insert_or_assign(KeyType&& key, ValueType&& val) noexcept

Inserts or assigns a value at a specific key.

Template parameters
KeyType	std::string (or a type convertible to it).
ValueType	toml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
key	The key at which to insert or assign the value.
val	The value to insert/assign.
Returns	*Valid input:* An iterator to the value's position `true` if the value was inserted, `false` if it was assigned. *Input is an empty toml::node_view:* `{ end(), false }`

Try this code on Compiler Explorer
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << "\n";

for (auto k : { "a", "d" })
{
    auto result = tbl.insert_or_assign(k, 42);
    std::cout << "value at key '"sv << k
        << "' was "sv << (result.second ? "inserted"sv : "assigned"sv) << "\n";
}
std::cout << tbl << "\n";

a = 1
b = 2
c = 3

value at key 'a' was assigned
value at key 'd' was inserted
a = 42
b = 2
c = 3
d = 42

bool toml::table::is_homogeneous(node_type ntype) const override 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

bool toml::table::is_homogeneous(node_type ntype, node*& first_nonmatch) override 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

node* toml::table::get(std::string_view key) noexcept

Gets the node at a specific key.

Parameters
key	The node's key.
Returns	A pointer to the node at the specified key, or nullptr.

auto tbl = toml::table{{
    { "a", 42, },
    { "b", "is the meaning of life, apparently." }
}};
std::cout << R"(node ["a"] exists: )"sv << !!arr.get("a") << "\n";
std::cout << R"(node ["b"] exists: )"sv << !!arr.get("b") << "\n";
std::cout << R"(node ["c"] exists: )"sv << !!arr.get("c") << "\n";
if (auto val = arr.get("a"))
    std::cout << R"(node ["a"] was an )"sv << val->type() << "\n";

node ["a"] exists: true
node ["b"] exists: true
node ["c"] exists: false
node ["a"] was an integer

const node* toml::table::get(std::string_view key) const noexcept

Gets the node at a specific key (const overload).

Parameters
key	The node's key.
Returns	A pointer to the node at the specified key, or nullptr.

node* toml::table::get(std::wstring_view key) noexcept