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.
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(table&& other) noexcept
Move constructor.

Public functions

auto as_table() -> table* override noexcept
Returns a pointer to the node as a toml::table, if it is one.
auto begin() const -> const_iterator noexcept
Returns an iterator to the first key-value pair.
auto begin() -> 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(string_view key) const -> bool noexcept
Returns true if the table contains a node at the given key.
template<typename U, typename K, typename... V>
auto emplace(K&& key, V && ... 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() const -> const_iterator noexcept
Returns an iterator to one-past-the-last key-value pair.
auto end() -> iterator noexcept
Returns an iterator to one-past-the-last key-value pair.
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(const_iterator pos) -> iterator noexcept
Removes the specified key-value pair from the table (const iterator overload).
auto erase(iterator pos) -> iterator noexcept
Removes the specified key-value pair from the table.
auto erase(string_view key) -> bool noexcept
Removes the value with the given key from the table.
auto get(string_view key) const -> const node* noexcept
Gets the node at a specific key (const overload).
auto get(string_view key) -> node* noexcept
Gets the node at a specific key.
template<typename T>
auto get_as(string_view key) const -> const impl::node_of<T>* noexcept
Gets the node at a specific key if it is a particular type (const overload).
template<typename T>
auto get_as(string_view key) -> impl::node_of<T>* noexcept
Gets the node at a specific key if it is a particular type.
template<typename Iter, typename = std::enable_if_t<...!std::is_convertible_v<Iter && , string_view> >>
void insert(Iter first, Iter last) noexcept
Inserts a series of key-value pairs into the table.
template<typename K, typename V, typename = std::enable_if_t<...std::is_convertible_v<K && , string_view> >>
auto insert(K&& key, V&& val) -> std::pair<iterator, bool> noexcept
Inserts a new value at a specific key if one did not already exist.
template<typename K, typename V>
auto insert_or_assign(K&& key, V&& val) -> std::pair<iterator, bool> noexcept
Inserts or assigns a value at a specific key.
auto is_array() const -> bool override noexcept
Always returns false for table nodes.
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 is_table() const -> bool override noexcept
Always returns true for table nodes.
auto is_value() const -> bool override noexcept
Always returns false for table nodes.
auto operator=(table&& rhs) -> table& noexcept
Move-assignment operator.
auto operator[](string_view key) const -> node_view<const node> noexcept
Gets a node_view for the selected key-value pair (const overload).
auto operator[](string_view key) -> node_view<node> noexcept
Gets a node_view for the selected key-value pair.
auto size() const -> size_t noexcept
Returns the number of key-value pairs in the table.
auto type() const -> node_type override noexcept
Always returns node_type::table for table nodes.

Friends

auto operator!=(const table& lhs, const table& rhs) -> bool noexcept
Inequality operator.
auto operator==(const table& lhs, const table& rhs) -> bool noexcept
Equality operator.

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 << std::endl;
{ foo = 1, bar = 2.0, kek = "three" }

template<typename U, typename K, typename... V>
std::pair<iterator, bool> toml::table::emplace(K&& key, V && ... args) noexcept

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

Template parameters
U One of the TOML node or value types.
K toml::string (or a type convertible to it).
V 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 << std::endl;

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 << std::endl;
}
std::cout << tbl << std::endl;
{ 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(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 << std::endl;

tbl.erase(tbl.cbegin() + 1, tbl.cbegin() + 3);
std::cout << tbl << std::endl;
{ a = 1, b = "bad", c = "karma", d = 2 }
{ a = 1, d = 2 }

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

tbl.erase(tbl.cbegin() + 1);
std::cout << tbl << std::endl;
{ a = 1, b = 2, c = 3 }
{ a = 1, c = 3 }

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

tbl.erase(tbl.begin() + 1);
std::cout << tbl << std::endl;
{ a = 1, b = 2, c = 3 }
{ a = 1, c = 3 }

bool toml::table::erase(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 << std::endl;

std::cout << tbl.erase("b") << std::endl;
std::cout << tbl.erase("not an existing key") << std::endl;
std::cout << tbl << std::endl;
{ a = 1, b = 2, c = 3 }
true
false
{ a = 1, c = 3 }

const node* toml::table::get(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(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") << std::endl;
std::cout << R"(node ["b"] exists: )"sv << !!arr.get("b") << std::endl;
std::cout << R"(node ["c"] exists: )"sv << !!arr.get("c") << std::endl;
if (auto val = arr.get("a"))
    std::cout << R"(node ["a"] was an )"sv << val->type() << std::endl;
node ["a"] exists: true
node ["b"] exists: true
node ["c"] exists: false
node ["a"] was an integer

template<typename T>
const impl::node_of<T>* toml::table::get_as(string_view key) const noexcept

Gets the node at a specific key if it is a particular type (const overload).

Template parameters
T The node's type.
Parameters
key The node's key.
Returns A pointer to the node at the specified key if it was of the given type, or nullptr.

template<typename T>
impl::node_of<T>* toml::table::get_as(string_view key) noexcept

Gets the node at a specific key if it is a particular type.

Template parameters
T The node's type.
Parameters
key The node's key.
Returns A pointer to the node at the specified key if it was of the given type, or nullptr.
auto tbl = toml::table{{
    { "a", 42, },
    { "b", "is the meaning of life, apparently." }
}};
if (auto val = arr.get_as<int64_t>("a"))
    std::cout << R"(node ["a"] was an integer with value )"sv << **val << std::endl;
node ["a"] was an integer with value 42

template<typename Iter, typename = std::enable_if_t<...!std::is_convertible_v<Iter && , string_view> >>
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.
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << std::endl;

auto kvps = std::array<std::pair<toml::string, int>>{{
    { "d", 42 },
    { "a", 43 }
}};
tbl.insert(kvps.begin(), kvps.end());
std::cout << tbl << std::endl;
{ a = 1, b = 2, c = 3 }
{ a = 1, b = 2, c = 3, d = 42 } //"a" already existed

template<typename K, typename V, typename = std::enable_if_t<...std::is_convertible_v<K && , string_view> >>
std::pair<iterator, bool> toml::table::insert(K&& key, V&& val) noexcept

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

Template parameters
K toml::string (or a type convertible to it).
V One of the TOML value types (or a type promotable to one).
Parameters
key The key at which to insert the new value.
val The new value to insert.
Returns

A std::pair containing:

  • An iterator to the insertion position (or the position of the value that prevented insertion)
  • A boolean indicating if the insertion was successful.
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << std::endl;

for (auto k : { "a", "d" })
{
    auto result = tbl.insert(k, 42);
    std::cout << "inserted with key '"sv << k << "': "sv << result.second << std::endl;
}
std::cout << tbl << std::endl;
{ 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 K, typename V>
std::pair<iterator, bool> toml::table::insert_or_assign(K&& key, V&& val) noexcept

Inserts or assigns a value at a specific key.

Template parameters
K toml::string (or a type convertible to it).
V One of the TOML value types (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

A std::pair containing:

  • An iterator to the value's position
  • A boolean containing true if the value was inserted, false if it was assigned.
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 }
}};
std::cout << tbl << std::endl;

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) << std::endl;
}
std::cout << tbl << std::endl;
{ 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_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'.
auto tbl = toml::table{{
    { "a", 1 },
    { "b", 2 },
    { "c", 3 },
    { "d", toml::table{{ { "e", 4 } }} }
}};
std::cout << "is inline? "sv << tbl.is_inline() << std::endl;
std::cout << tbl << std::endl << std::endl;

tbl.is_inline(!tbl.is_inline());
std::cout << "is inline? "sv << tbl.is_inline() << std::endl;
std::cout << tbl << std::endl;
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[](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.

bool 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 values.

bool 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 values.