toml::array class final

A TOML array.

The interface of this type is modeled after std::vector, with some additional considerations made for the heterogeneous nature of a TOML array.

auto tbl = toml::parse("arr = [1, 2, 3, 4, 'five']"sv);
auto& arr = *tbl.get_as<toml::array>("arr");
std::cout << arr << std::endl;

for (size_t i = 0; i < arr.size(); i++)
{
    arr[i].visit([](auto&& el) noexcept
    {
        if constexpr (toml::is_number<decltype(el)>)
            (*el)++;
        else if constexpr (toml::is_string<decltype(el)>)
            el = "six"sv;
    });
}
std::cout << arr << std::endl;

arr.push_back(7);
arr.push_back(8.0f);
arr.push_back("nine"sv);
arr.erase(arr.cbegin());
std::cout << arr << std::endl;

arr.emplace_back<toml::array>(10, 11.0);
std::cout << arr << std::endl;
[1, 2, 3, 4, "five"]
[2, 3, 4, 5, "six"]
[3, 4, 5, "six", 7, 8.0, "nine"]
[3, 4, 5, "six", 7, 8.0, "nine", [10, 11.0]]

Base classes

class node
A TOML node.

Public types

using const_iterator = const_array_iterator
A RandomAccessIterator for iterating over const nodes in a toml::array.
using iterator = array_iterator
A RandomAccessIterator for iterating over nodes in a toml::array.

Constructors, destructors, conversion operators

array() noexcept
Default constructor.
array(array&& other) noexcept
Move constructor.
template<typename U, typename... V>
array(U&& val, V && ... vals) explicit
Constructs an array with one or more initial values.

Public functions

auto as_array() -> array* override noexcept
Returns a pointer to the node as a toml::array, if it is one.
auto back() const -> const node& noexcept
Returns a reference to the last node in the array.
auto back() -> node& noexcept
Returns a reference to the last node in the array.
auto begin() const -> const_iterator noexcept
Returns an iterator to the first node.
auto begin() -> iterator noexcept
Returns an iterator to the first node.
auto capacity() const -> size_t noexcept
Returns the current max number of nodes that may be held in the array's internal storage.
auto cbegin() const -> const_iterator noexcept
Returns an iterator to the first node.
auto cend() const -> const_iterator noexcept
Returns an iterator to one-past-the-last node.
void clear() noexcept
Removes all nodes from the array.
template<typename U, typename... V>
auto emplace(const_iterator pos, V && ... args) -> iterator noexcept
Emplaces a new value at a specific position in the array.
template<typename U, typename... V>
auto emplace_back(V && ... args) -> decltype(auto) noexcept
Emplaces a new value at the end of the array.
auto empty() const -> bool noexcept
Returns true if the array is empty.
auto end() const -> const_iterator noexcept
Returns an iterator to one-past-the-last node.
auto end() -> iterator noexcept
Returns an iterator to one-past-the-last node.
auto erase(const_iterator first, const_iterator last) -> iterator noexcept
Removes the nodes in the range [first, last) from the array.
auto erase(const_iterator pos) -> iterator noexcept
Removes the specified node from the array.
auto flatten() & -> array&
Flattens this array, recursively hoisting the contents of child arrays up into itself.
auto flatten() && -> array&&
Flattens this array, recursively hoisting the contents of child arrays up into itself (rvalue overload).
auto front() const -> const node& noexcept
Returns a reference to the first node in the array.
auto front() -> node& noexcept
Returns a reference to the first node in the array.
auto get(size_t index) const -> const node* noexcept
Gets the node at a specific index (const overload).
auto get(size_t index) -> node* noexcept
Gets the node at a specific index.
template<typename T>
auto get_as(size_t index) const -> const impl::node_of<T>* noexcept
Gets the node at a specific index if it is a particular type (const overload).
template<typename T>
auto get_as(size_t index) -> impl::node_of<T>* noexcept
Gets the node at a specific index if it is a particular type.
template<typename Iter>
auto insert(const_iterator pos, Iter first, Iter last) -> iterator noexcept
Inserts a range of values into the array at a specific position.
template<typename U>
auto insert(const_iterator pos, size_t count, U&& val) -> iterator noexcept
Repeatedly inserts a value starting at a specific position in the array.
template<typename U>
auto insert(const_iterator pos, std::initializer_list<U> ilist) -> iterator noexcept
Inserts a range of values into the array at a specific position.
template<typename U>
auto insert(const_iterator pos, U&& val) -> iterator noexcept
Inserts a new node at a specific position in the array.
auto is_array() const -> bool override noexcept
Always returns true for array nodes.
auto is_array_of_tables() const -> bool override noexcept
Returns true if this array contains only tables.
template<typename T = void>
auto is_homogeneous() const -> bool noexcept
Checks if the array contains nodes of only one type.
auto is_table() const -> bool override noexcept
Always returns false for array nodes.
auto is_value() const -> bool override noexcept
Always returns false for array nodes.
auto max_size() const -> size_t noexcept
Returns the maximum number of nodes that can be stored in an array on the current platform.
auto operator=(array&& rhs) -> array& noexcept
Move-assignment operator.
auto operator[](size_t index) const -> const node& noexcept
Gets a reference to the node at a specific index.
auto operator[](size_t index) -> node& noexcept
Gets a reference to the node at a specific index.
void pop_back() noexcept
Removes the last node from the array.
template<typename U>
auto push_back(U&& val) -> decltype(auto) noexcept
Appends a new value to the end of the array.
void reserve(size_t new_capacity)
Reserves internal storage capacity up to a pre-determined number of nodes.
template<typename U>
void resize(size_t new_size, U&& default_init_val) noexcept
Resizes the array.
void shrink_to_fit()
Requests the removal of any unused internal storage capacity.
auto size() const -> size_t noexcept
Returns the number of nodes in the array.
void truncate(size_t new_size)
Shrinks the array to the given size.
auto type() const -> node_type override noexcept
Always returns node_type::array for array nodes.

Friends

auto operator!=(const array& lhs, const array& rhs) -> bool noexcept
Inequality operator.
auto operator==(const array& lhs, const array& rhs) -> bool noexcept
Equality operator.
template<typename T>
auto operator==(const array& lhs, const std::initializer_list<T>& rhs) -> bool noexcept
Initializer list equality operator.
template<typename T>
auto operator==(const array& lhs, const std::vector<T>& rhs) -> bool noexcept
Vector equality operator.

Function documentation

template<typename U, typename... V>
toml::array::array(U&& val, V && ... vals) explicit

Constructs an array with one or more initial values.

Template parameters
U One of the TOML node or value types (or a type promotable to one).
V One of the TOML node or value types (or a type promotable to one).
Parameters
val The value used to initialize node 0.
vals The values used to initialize nodes 1...N.
auto arr = toml::array{ 1, 2.0, "three"sv, toml::array{ 4, 5 } };
std::cout << arr << std::endl;
[1, 2.0, "three", [4, 5]]

template<typename U, typename... V>
iterator toml::array::emplace(const_iterator pos, V && ... args) noexcept

Emplaces a new value at a specific position in the array.

Template parameters
U One of the TOML node or value types.
V Value constructor argument types.
Parameters
pos The insertion position.
args Arguments to forward to the value's constructor.
Returns An iterator to the inserted value.
auto arr = toml::array{ 1, 2 };

//add a string using std::string's substring constructor
arr.emplace<std::string>(arr.cbegin() + 1, "this is not a drill"sv, 14, 5);
std::cout << arr << std::endl;
[1, "drill", 2]

template<typename U, typename... V>
decltype(auto) toml::array::emplace_back(V && ... args) noexcept

Emplaces a new value at the end of the array.

Template parameters
U One of the TOML value types.
V Value constructor argument types.
Parameters
args Arguments to forward to the value's constructor.
Returns A reference to the newly-constructed value node.
auto arr = toml::array{ 1, 2 };
arr.emplace_back<toml::array>(3, "four"sv);
std::cout << arr << std::endl;
[1, 2, [3, "four"]]

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

Removes the nodes in the range [first, last) from the array.

Parameters
first Iterator to the first node being erased.
last Iterator to the one-past-the-last node being erased.
Returns Iterator to the first node immediately following the last removed node.
auto arr = toml::array{ 1, "bad", "karma" 2 };
std::cout << arr << std::endl;

arr.erase(arr.cbegin() + 1, arr.cbegin() + 3);
std::cout << arr << std::endl;
[1, "bad", "karma", 3]
[1, 3]

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

Removes the specified node from the array.

Parameters
pos Iterator to the node being erased.
Returns Iterator to the first node immediately following the removed node.
auto arr = toml::array{ 1, 2, 3 };
std::cout << arr << std::endl;

arr.erase(arr.cbegin() + 1);
std::cout << arr << std::endl;
[1, 2, 3]
[1, 3]

array& toml::array::flatten() &

Flattens this array, recursively hoisting the contents of child arrays up into itself.

auto arr = toml::array{ 1, 2, toml::array{ 3, 4, toml::array{ 5 } }, 6, toml::array{} };
std::cout << arr << std::endl;

arr.flatten();
std::cout << arr << std::endl;
[1, 2, [3, 4, [5]], 6, []]
[1, 2, 3, 4, 5, 6]

A reference to the array.

const node* toml::array::get(size_t index) const noexcept

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

Parameters
index The node's index.
Returns A pointer to the node at the specified index if one existed, or nullptr.

node* toml::array::get(size_t index) noexcept

Gets the node at a specific index.

Parameters
index The node's index.
Returns A pointer to the node at the specified index if one existed, or nullptr.
auto arr = toml::array{ 99, "bottles of beer on the wall" };
std::cout << "node [0] exists: "sv << !!arr.get(0) << std::endl;
std::cout << "node [1] exists: "sv << !!arr.get(1) << std::endl;
std::cout << "node [2] exists: "sv << !!arr.get(2) << std::endl;
if (auto val = arr.get(0))
    std::cout << "node [0] was an "sv << val->type() << std::endl;
node [0] exists: true
node [1] exists: true
node [2] exists: false
node [0] was an integer

template<typename T>
const impl::node_of<T>* toml::array::get_as(size_t index) const noexcept

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

Template parameters
T The node's type.
Parameters
index The node's index.
Returns A pointer to the selected node if it existed and was of the specified type, or nullptr.

template<typename T>
impl::node_of<T>* toml::array::get_as(size_t index) noexcept

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

Template parameters
T The node's type.
Parameters
index The node's index.
Returns A pointer to the selected node if it existed and was of the specified type, or nullptr.
auto arr = toml::array{ 42, "is the meaning of life, apparently."sv };
if (auto val = arr.get_as<int64_t>(0))
    std::cout << "node [0] was an integer with value "sv << **val << std::endl;
node [0] was an integer with value 42

template<typename Iter>
iterator toml::array::insert(const_iterator pos, Iter first, Iter last) noexcept

Inserts a range of values into the array at a specific position.

Template parameters
Iter An iterator type. Must satisfy ForwardIterator.
Parameters
pos The insertion position.
first Iterator to the first value being inserted.
last Iterator to the one-past-the-last value being inserted.
Returns An iterator to the first inserted value (or a copy of pos if first == last).

template<typename U>
iterator toml::array::insert(const_iterator pos, size_t count, U&& val) noexcept

Repeatedly inserts a value starting at a specific position in the array.

Template parameters
U One of the TOML value types (or a type promotable to one).
Parameters
pos The insertion position.
count The number of times the value should be inserted.
val The value being inserted.
Returns An iterator to the first inserted value (or a copy of pos if count was 0).
auto arr = toml::array{
    "with an evil twinkle in its eye the goose said",
    "and immediately we knew peace was never an option."
};
arr.insert(arr.cbegin() + 1, 3, "honk");
std::cout << arr << std::endl;
[
    "with an evil twinkle in its eye the goose said",
    "honk",
    "honk",
    "honk",
    "and immediately we knew peace was never an option."
]

template<typename U>
iterator toml::array::insert(const_iterator pos, std::initializer_list<U> ilist) noexcept

Inserts a range of values into the array at a specific position.

Template parameters
U One of the TOML value types (or a type promotable to one).
Parameters
pos The insertion position.
ilist An initializer list containing the values to be inserted.
Returns An iterator to the first inserted value (or a copy of pos if ilist was empty).

template<typename U>
iterator toml::array::insert(const_iterator pos, U&& val) noexcept

Inserts a new node at a specific position in the array.

Template parameters
U One of the TOML node or value types (or a type promotable to one).
Parameters
pos The insertion position.
val The value being inserted.
Returns An iterator to the inserted value.
auto arr = toml::array{ 1, 3 };
arr.insert(arr.cbegin() + 1, "two");
arr.insert(arr.cend(), toml::array{ 4, 5 });
std::cout << arr << std::endl;
[1, "two", 3, [4, 5]]

template<typename T = void>
bool toml::array::is_homogeneous() const noexcept

Checks if the array contains nodes of only one type.

Template parameters
T A TOML node type.
Explicitly specified: "is every node a T?"
Left as void: "is every node the same type?"
Returns True if the array was homogeneous.
auto arr = toml::array{ 1, 2, 3 };
std::cout << "homogenous: "sv << arr.is_homogeneous() << std::endl;
std::cout << "all doubles: "sv << arr.is_homogeneous<double>() << std::endl;
std::cout << "all arrays: "sv << arr.is_homogeneous<toml::array>() << std::endl;
std::cout << "all integers: "sv << arr.is_homogeneous<int64_t>() << std::endl;
homogeneous: true
all doubles: false
all arrays: false
all integers: true

template<typename U>
decltype(auto) toml::array::push_back(U&& val) noexcept

Appends a new value to the end of the array.

Template parameters
U One of the TOML value types (or a type promotable to one).
Parameters
val The value being added.
Returns A reference to the newly-constructed value node.
auto arr = toml::array{ 1, 2 };
arr.push_back(3);
arr.push_back(4.0);
arr.push_back(toml::array{ 5, "six"sv });
std::cout << arr << std::endl;
[1, 2, 3, 4.0, [5, "six"]]

template<typename U>
void toml::array::resize(size_t new_size, U&& default_init_val) noexcept

Resizes the array.

Template parameters
U One of the TOML value types (or a type promotable to one).
Parameters
new_size New number of elements the array will have.
default_init_val The value used to initialize new elements if the array needs to grow.
auto arr = toml::array{ 1, 2, 3 };
std::cout << arr << std::endl;

arr.resize(6, 42);
std::cout << arr << std::endl;

arr.resize(2, 0);
std::cout << arr << std::endl;
[1, 2, 3]
[1, 2, 3, 42, 42, 42]
[1, 2]

void toml::array::truncate(size_t new_size)

Shrinks the array to the given size.

auto arr = toml::array{ 1, 2, 3 };
std::cout << arr << std::endl;

arr.truncate(5); // no-op
std::cout << arr << std::endl;

arr.truncate(1);
std::cout << arr << std::endl;
[1, 2, 3]
[1, 2, 3]
[1]

bool operator!=(const array& lhs, const array& rhs) noexcept

Inequality operator.

Parameters
lhs The LHS array.
rhs The RHS array.
Returns True if the arrays did not contain the same values.

bool operator==(const array& lhs, const array& rhs) noexcept

Equality operator.

Parameters
lhs The LHS array.
rhs The RHS array.
Returns True if the arrays contained the same values.