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.

Try this code on Compiler Explorer
toml::table tbl = toml::parse(R"(
    arr = [1, 2, 3, 4, 'five']
)"sv);

// get the element as an array
toml::array& arr = *tbl.get_as<toml::array>("arr");
std::cout << arr << "\n";

// increment each element with visit()
for (auto&& elem : arr)
{
    elem.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 << "\n";

// add and remove elements
arr.push_back(7);
arr.push_back(8.0f);
arr.push_back("nine"sv);
arr.erase(arr.cbegin());
std::cout << arr << "\n";

// emplace elements
arr.emplace_back<std::string>("ten");
arr.emplace_back<toml::array>(11, 12.0);
std::cout << arr << "\n";

[ 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', 'ten', [ 11, 12.0 ] ]

Base classes

class node: A TOML node.

Public types

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

Constructors, destructors, conversion operators

array() noexcept: Default constructor.
array(const array&) noexcept: Copy constructor.
array(array&& other) noexcept: Move constructor.
template <typename ElemType, typename... ElemTypes, typename = std::enable_if_t< (sizeof...(ElemTypes)> 0_sz) || !std::is_same_v<impl::remove_cvref_t<ElemType>, array> >> array(ElemType&& val, ElemTypes && ... vals) explicit: Constructs an array with one or more initial elements.
~array() override noexcept: Destructor.

Public functions

auto operator=(const array&) -> array& noexcept: Copy-assignment operator.
auto operator=(array&& rhs) -> array& noexcept: Move-assignment operator.

Array operations

auto back() -> node& noexcept: Returns a reference to the last element in the array.
auto back() const -> const node& noexcept: Returns a reference to the last element in the array.
auto begin() -> iterator noexcept: Returns an iterator to the first element.
auto begin() const -> const_iterator noexcept: Returns an iterator to the first element.
auto capacity() const -> size_t noexcept: Returns the current max number of elements that may be held in the array's internal storage.
auto cbegin() const -> const_iterator noexcept: Returns an iterator to the first element.
auto cend() const -> const_iterator noexcept: Returns an iterator to one-past-the-last element.
void clear() noexcept: Removes all elements from the array.
template <typename ElemType, typename... Args> auto emplace(const_iterator pos, Args && ... args) -> iterator noexcept: Emplaces a new element at a specific position in the array.
template <typename ElemType, typename... Args> auto emplace_back(Args && ... args) -> decltype(auto) noexcept: Emplaces a new element at the end of the array.
auto empty() const -> bool noexcept: Returns true if the array is empty.
auto end() -> iterator noexcept: Returns an iterator to one-past-the-last element.
auto end() const -> const_iterator noexcept: Returns an iterator to one-past-the-last element.
auto erase(const_iterator pos) -> iterator noexcept: Removes the specified element from the array.
auto erase(const_iterator first, const_iterator last) -> iterator noexcept: Removes the elements in the range [first, last) 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() -> node& noexcept: Returns a reference to the first element in the array.
auto front() const -> const node& noexcept: Returns a reference to the first element in the array.
auto get(size_t index) -> node* noexcept: Gets the element at a specific index.
auto get(size_t index) const -> const node* noexcept: Gets the element at a specific index (const overload).
template <typename ElemType> auto get_as(size_t index) -> impl::wrap_node<ElemType>* noexcept: Gets the element at a specific index if it is a particular type.
template <typename ElemType> auto get_as(size_t index) const -> const impl::wrap_node<ElemType>* noexcept: Gets the element at a specific index if it is a particular type (const overload).
template <typename ElemType> auto insert(const_iterator pos, ElemType&& val) -> iterator noexcept: Inserts a new element at a specific position in the array.
template <typename ElemType> auto insert(const_iterator pos, size_t count, ElemType&& val) -> iterator noexcept: Repeatedly inserts a new element starting at a specific position in the array.
template <typename Iter> auto insert(const_iterator pos, Iter first, Iter last) -> iterator noexcept: Inserts a range of elements into the array at a specific position.
template <typename ElemType> auto insert(const_iterator pos, std::initializer_list<ElemType> ilist) -> iterator noexcept: Inserts a range of elements into the array at a specific position.
auto max_size() const -> size_t noexcept: Returns the maximum number of elements that can be stored in an array on the current platform.
auto operator[](size_t index) -> node& noexcept: Gets a reference to the element at a specific index.
auto operator[](size_t index) const -> const node& noexcept: Gets a reference to the element at a specific index.
void pop_back() noexcept: Removes the last element from the array.
template <typename ElemType> void push_back(ElemType&& val) noexcept: Appends a new element to the end of the array.
void reserve(size_t new_capacity): Reserves internal storage capacity up to a pre-determined number of elements.
template <typename ElemType> void resize(size_t new_size, ElemType&& 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 elements in the array.
void truncate(size_t new_size): Shrinks the array to the given size.

Equality

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.

Metadata

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.

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_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.

Type checks

auto as_array() -> array* override noexcept: Returns a pointer to the node as a toml::array, 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 override noexcept: Returns true if this node is an array.
auto is_array_of_tables() const -> bool override 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

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).

Friends

template <typename Char> auto operator<<(std::basic_ostream<Char>&, const array&) -> std::basic_ostream<Char>&: Prints the array out to a stream as formatted TOML.

Function documentation

template <typename ElemType, typename... ElemTypes, typename = std::enable_if_t< (sizeof...(ElemTypes)> 0_sz) || !std::is_same_v<impl::remove_cvref_t<ElemType>, array> >>
toml::array::array(ElemType&& val, ElemTypes && ... vals) explicit

Constructs an array with one or more initial elements.

Template parameters
ElemType	One of the TOML node or value types (or a type promotable to one).
ElemTypes	One of the TOML node or value types (or a type promotable to one).
Parameters
val	The node or value used to initialize element 0.
vals	The nodes or values used to initialize elements 1...N.

auto arr = toml::array{ 1, 2.0, "three"sv, toml::array{ 4, 5 } };
std::cout << arr << "\n";

[ 1, 2.0, 'three', [ 4, 5 ] ]

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

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

Template parameters
ElemType	toml::table, toml::array, or any native TOML value type.
Args	Value constructor argument types.
Parameters
pos	The insertion position.
args	Arguments to forward to the value's constructor.
Returns	An iterator to the inserted element.

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 << "\n";

[ 1, 'drill', 2 ]

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

Emplaces a new element at the end of the array.

Template parameters
ElemType	toml::table, toml::array, or a native TOML value type
Args	Value constructor argument types.
Parameters
args	Arguments to forward to the value's constructor.
Returns	A reference to the newly-constructed element.

auto arr = toml::array{ 1, 2 };
arr.emplace_back<toml::array>(3, "four"sv);
std::cout << arr << "\n";

[ 1, 2, [ 3, 'four' ] ]

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

Removes the specified element from the array.

Parameters
pos	Iterator to the element being erased.
Returns	Iterator to the first element immediately following the removed element.

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

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

[ 1, 2, 3 ]
[ 1, 3 ]

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

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

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

auto arr = toml::array{ 1, "bad", "karma" 2 };
std::cout << arr << "\n";

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

[ 1, 'bad', 'karma', 3 ]
[ 1, 3 ]

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

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

Returns	A reference to the array.

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

arr.flatten();
std::cout << arr << "\n";

[ 1, 2, [ 3, 4, [ 5 ] ], 6, [] ]
[ 1, 2, 3, 4, 5, 6 ]

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

Flattens this array, recursively hoisting the contents of child arrays up into itself (rvalue overload).

Returns	An rvalue reference to the array.

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

Gets the element at a specific index.

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

auto arr = toml::array{ 99, "bottles of beer on the wall" };
std::cout << "element [0] exists: "sv << !!arr.get(0) << "\n";
std::cout << "element [1] exists: "sv << !!arr.get(1) << "\n";
std::cout << "element [2] exists: "sv << !!arr.get(2) << "\n";
if (toml::node* val = arr.get(0))
    std::cout << "element [0] is an "sv << val->type() << "\n";

element [0] exists: true
element [1] exists: true
element [2] exists: false
element [0] is an integer

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

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

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

template <typename ElemType>
impl::wrap_node<ElemType>* toml::array::get_as(size_t index) noexcept

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

Template parameters
ElemType	toml::table, toml::array, or a native TOML value type
Parameters
index	The element's index.
Returns	A pointer to the selected element if it existed and was of the specified type, or nullptr.

auto arr = toml::array{ 42, "is the meaning of life, apparently."sv };
if (toml::value<int64_t>* val = arr.get_as<int64_t>(0))
    std::cout << "element [0] is an integer with value "sv << *val << "\n";

element [0] is an integer with value 42

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

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

Template parameters
ElemType	toml::table, toml::array, or a native TOML value type
Parameters
index	The element's index.
Returns	A pointer to the selected element if it existed and was of the specified type, or nullptr.

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

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

Template parameters
ElemType	toml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
pos	The insertion position.
val	The node or value being inserted.
Returns	*Valid input:* An iterator to the newly-inserted element. *Input is an empty toml::node_view:* end()

auto arr = toml::array{ 1, 3 };
arr.insert(arr.cbegin() + 1, "two");
arr.insert(arr.cend(), toml::array{ 4, 5 });
std::cout << arr << "\n";

[ 1, 'two', 3, [ 4, 5 ] ]

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

Repeatedly inserts a new element starting at a specific position in the array.

Template parameters
ElemType	toml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
pos	The insertion position.
count	The number of times the node or value should be inserted.
val	The node or value being inserted.
Returns	*Valid input:* An iterator to the newly-inserted element. *count == 0:* A copy of pos *Input is an empty toml::node_view:* end()

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 << "\n";

[
    'with an evil twinkle in its eye the goose said',
    'honk',
    'honk',
    'honk',
    'and immediately we knew peace was never an option.'
]

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

Inserts a range of elements 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 node or value being inserted.
last	Iterator to the one-past-the-last node or value being inserted.
Returns	*Valid input:* An iterator to the first newly-inserted element. *first >= last:* A copy of pos *All objects in the range were empty toml::node_views:* A copy of pos

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

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

Template parameters
ElemType	toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
pos	The insertion position.
ilist	An initializer list containing the values to be inserted.
Returns	*Valid input:* An iterator to the first newly-inserted element. *Input list is empty:* A copy of pos *All objects in the list were empty toml::node_views:* A copy of pos

template <typename ElemType>
void toml::array::push_back(ElemType&& val) noexcept

Appends a new element to the end of the array.

Template parameters
ElemType	toml::node, toml::node_view, toml::table, toml::array, or a native TOML value type
Parameters
val	The node or value being added.

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 << "\n";

[ 1, 2, 3, 4.0, [ 5, 'six' ] ]

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

Resizes the array.

Template parameters
ElemType	toml::node, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
new_size	The number of elements the array will have after resizing.
default_init_val	The node or value used to initialize new elements if the array needs to grow.

Try this code on Compiler Explorer
auto arr = toml::array{ 1, 2, 3 };
std::cout << arr << "\n";

arr.resize(6, 42);
std::cout << arr << "\n";

arr.resize(2, 0);
std::cout << arr << "\n";

[ 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.

Try this code on Compiler Explorer
auto arr = toml::array{ 1, 2, 3 };
std::cout << arr << "\n";

arr.truncate(5); // no-op
std::cout << arr << "\n";

arr.truncate(1);
std::cout << arr << "\n";

[ 1, 2, 3 ]
[ 1, 2, 3 ]
[ 1]

bool toml::array::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 elements.

bool toml::array::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 elements.

bool toml::array::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::array::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