toml::array class final

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(array&& other) noexcept

Move constructor.

array(const array&) noexcept

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

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 element in the array.

auto back() -> node& noexcept

Returns a reference to the last element in the array.

auto begin() const -> const_iterator noexcept

Returns an iterator to the first element.

auto begin() -> 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() const -> const_iterator noexcept

Returns an iterator to one-past-the-last element.

auto end() -> iterator noexcept

Returns an iterator to one-past-the-last element.

auto erase(const_iterator first, const_iterator last) -> iterator noexcept

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

auto erase(const_iterator pos) -> iterator noexcept

Removes the specified element 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 element in the array.

auto front() -> node& noexcept

Returns a reference to the first element in the array.

auto get(size_t index) const -> const node* noexcept

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

auto get(size_t index) -> node* noexcept

Gets the element at a specific index.

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 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 insert(const_iterator pos, ElemType&& val) -> iterator noexcept

Inserts a new element 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, size_t count, ElemType&& val) -> iterator noexcept

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

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 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 ElemType = void>

auto is_homogeneous() const -> bool noexcept

Checks if the array contains elements of only one type.

auto is_homogeneous(node_type type) const -> bool noexcept

Checks if the array contains elements 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 elements that can be stored in an array on the current platform.

auto operator=(array&& rhs) -> array& noexcept

Move-assignment operator.

auto operator=(const array&) -> array& noexcept

Copy-assignment operator.

auto operator[](size_t index) const -> const node& noexcept

Gets a reference to the element at a specific index.

auto operator[](size_t index) -> 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>

auto push_back(ElemType&& val) -> decltype(auto) 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.

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.

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.

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

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

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

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 ]

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

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

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 ]

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 ]

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 ]

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

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

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 ] ]

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.'
]

auto arr = toml::array{ 1, 2, 3 };
std::cout << "homogenous:   "sv << arr.is_homogeneous() << "\n";
std::cout << "all doubles:  "sv << arr.is_homogeneous<double>() << "\n";
std::cout << "all arrays:   "sv << arr.is_homogeneous<toml::array>() << "\n";
std::cout << "all integers: "sv << arr.is_homogeneous<int64_t>() << "\n";

homogeneous:  true
all doubles:  false
all arrays:   false
all integers: true

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

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' ] ]

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 ]

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]