NeBuild dev
Loading...
Searching...
No Matches
table Class Reference

A TOML table. More...

#include <table.hpp>

Inheritance diagram for table:

Public Member Functions

TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table () noexcept
 Default constructor.
 
TOML_EXPORTED_MEMBER_FUNCTION ~table () noexcept
 
TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table (const table &)
 Copy constructor.
 
TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table (table &&other) noexcept
 Move constructor.
 
TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table (std::initializer_list< impl::table_init_pair > kvps)
 Constructs a table with one or more initial key-value pairs.
 
TOML_EXPORTED_MEMBER_FUNCTION tableoperator= (const table &)
 Copy-assignment operator.
 
TOML_EXPORTED_MEMBER_FUNCTION tableoperator= (table &&rhs) noexcept
 Move-assignment operator.
 
Type checks
TOML_CONST_INLINE_GETTER node_type type () const noexcept final
 Returns #toml::node_type::table.
 
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool is_homogeneous (node_type ntype) const noexcept final
 
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool is_homogeneous (node_type ntype, node *&first_nonmatch) noexcept final
 
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool is_homogeneous (node_type ntype, const node *&first_nonmatch) const noexcept final
 
TOML_CONST_INLINE_GETTER bool is_table () const noexcept final
 Returns true.
 
TOML_CONST_INLINE_GETTER bool is_array () const noexcept final
 Returns false.
 
TOML_PURE_GETTER bool is_array_of_tables () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_value () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_string () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_integer () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_floating_point () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_number () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_boolean () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_date () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_time () const noexcept final
 Returns false.
 
TOML_CONST_INLINE_GETTER bool is_date_time () const noexcept final
 Returns false.
 
Type casts
TOML_CONST_INLINE_GETTER tableas_table () noexcept final
 Returns a pointer to the table.
 
TOML_CONST_INLINE_GETTER arrayas_array () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< std::string > * as_string () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< int64_t > * as_integer () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< double > * as_floating_point () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< bool > * as_boolean () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< date > * as_date () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< time > * as_time () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER toml::value< date_time > * as_date_time () noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const tableas_table () const noexcept final
 Returns a const-qualified pointer to the table.
 
TOML_CONST_INLINE_GETTER const arrayas_array () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< std::string > * as_string () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< int64_t > * as_integer () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< double > * as_floating_point () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< bool > * as_boolean () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< date > * as_date () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< time > * as_time () const noexcept final
 Returns nullptr.
 
TOML_CONST_INLINE_GETTER const toml::value< date_time > * as_date_time () const noexcept final
 Returns nullptr.
 
Metadata
TOML_PURE_INLINE_GETTER bool is_inline () const 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.
 
Value retrieval
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION node * get (std::string_view key) noexcept
 Gets the node at a specific key.
 
TOML_PURE_INLINE_GETTER const node * get (std::string_view key) const noexcept
 Gets the node at a specific key (const overload).
 
TOML_NODISCARD node * get (std::wstring_view key)
 Gets the node at a specific key.
 
TOML_NODISCARD const node * get (std::wstring_view key) const
 Gets the node at a specific key (const overload).
 
template<typename T >
TOML_PURE_GETTER impl::wrap_node< T > * get_as (std::string_view key) noexcept
 Gets the node at a specific key if it is a particular type.
 
template<typename T >
TOML_PURE_GETTER const impl::wrap_node< T > * get_as (std::string_view key) const noexcept
 Gets the node at a specific key if it is a particular type (const overload).
 
template<typename T >
TOML_NODISCARD impl::wrap_node< T > * get_as (std::wstring_view key)
 Gets the node at a specific key if it is a particular type.
 
template<typename T >
TOML_NODISCARD const impl::wrap_node< T > * get_as (std::wstring_view key) const
 Gets the node at a specific key if it is a particular type (const overload).
 
TOML_NODISCARD TOML_EXPORTED_MEMBER_FUNCTION node & at (std::string_view key)
 Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.
 
TOML_NODISCARD const node & at (std::string_view key) const
 Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.
 
TOML_NODISCARD node & at (std::wstring_view key)
 Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.
 
TOML_NODISCARD const node & at (std::wstring_view key) const
 Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.
 
Size and Capacity
TOML_PURE_INLINE_GETTER bool empty () const noexcept
 Returns true if the table is empty.
 
TOML_PURE_INLINE_GETTER size_t size () const noexcept
 Returns the number of key-value pairs in the table.
 
Searching
TOML_PURE_GETTER iterator lower_bound (std::string_view key) noexcept
 Returns an iterator to the first key-value pair with key that is not less than the given key.
 
TOML_PURE_GETTER const_iterator lower_bound (std::string_view key) const noexcept
 Returns a const iterator to the first key-value pair with key that is not less than the given key.
 
TOML_NODISCARD iterator lower_bound (std::wstring_view key)
 Returns an iterator to the first key-value pair with key that is not less than the given key.
 
TOML_NODISCARD const_iterator lower_bound (std::wstring_view key) const
 Returns a const iterator to the first key-value pair with key that is not less than the given key.
 
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION iterator find (std::string_view key) noexcept
 Gets an iterator to the node at a specific key.
 
TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION const_iterator find (std::string_view key) const noexcept
 Gets an iterator to the node at a specific key (const overload)
 
TOML_PURE_GETTER bool contains (std::string_view key) const noexcept
 Returns true if the table contains a node at the given key.
 
TOML_NODISCARD iterator find (std::wstring_view key)
 Gets an iterator to the node at a specific key.
 
TOML_NODISCARD const_iterator find (std::wstring_view key) const
 Gets an iterator to the node at a specific key (const overload).
 
TOML_NODISCARD bool contains (std::wstring_view key) const
 Returns true if the table contains a node at the given key.
 
Erasure
iterator erase (iterator pos) noexcept
 Removes the specified key-value pair from the table.
 
iterator erase (const_iterator pos) noexcept
 Removes the specified key-value pair from the table (const iterator overload).
 
iterator erase (const_iterator begin, const_iterator end) noexcept
 Removes the key-value pairs in the range [first, last) from the table.
 
TOML_EXPORTED_MEMBER_FUNCTION size_t erase (std::string_view key) noexcept
 Removes the value with the given key from the table.
 
size_t erase (std::wstring_view key)
 Removes the value with the given key from the table.
 
TOML_EXPORTED_MEMBER_FUNCTION tableprune (bool recursive=true) &noexcept
 Removes empty child arrays and tables.
 
table && prune (bool recursive=true) &&noexcept
 Removes empty child arrays and tables (rvalue overload).
 
TOML_EXPORTED_MEMBER_FUNCTION void clear () noexcept
 Removes all key-value pairs from the table.
 
Node views
TOML_NODISCARD node_view< node > operator[] (std::string_view key) noexcept
 Gets a node_view for the selected value.
 
TOML_NODISCARD node_view< const node > operator[] (std::string_view key) const noexcept
 Gets a node_view for the selected value (const overload).
 
TOML_NODISCARD node_view< node > operator[] (std::wstring_view key)
 Gets a node_view for the selected value.
 
TOML_NODISCARD node_view< const node > operator[] (std::wstring_view key) const
 Gets a node_view for the selected value (const overload).
 

Friends

std::ostream & operator<< (std::ostream &lhs, const table &rhs)
 Prints the table out to a stream as formatted TOML.
 
Equality
TOML_NODISCARD friend bool operator== (const table &lhs, const table &rhs) noexcept
 Equality operator.
 
TOML_NODISCARD friend bool operator!= (const table &lhs, const table &rhs) noexcept
 Inequality operator.
 

Iteration

using iterator = toml::table_iterator
 A BidirectionalIterator for iterating over key-value pairs in a toml::table.
 
using const_iterator = toml::const_table_iterator
 A BidirectionalIterator for iterating over const key-value pairs in a toml::table.
 
TOML_PURE_INLINE_GETTER iterator begin () noexcept
 Returns an iterator to the first key-value pair.
 
TOML_PURE_INLINE_GETTER const_iterator begin () const noexcept
 Returns an iterator to the first key-value pair.
 
TOML_PURE_INLINE_GETTER const_iterator cbegin () const noexcept
 Returns an iterator to the first key-value pair.
 
TOML_PURE_INLINE_GETTER iterator end () noexcept
 Returns an iterator to one-past-the-last key-value pair.
 
TOML_PURE_INLINE_GETTER const_iterator end () const noexcept
 Returns an iterator to one-past-the-last key-value pair.
 
TOML_PURE_INLINE_GETTER const_iterator cend () const noexcept
 Returns an iterator to one-past-the-last key-value pair.
 
template<typename Func >
tablefor_each (Func &&visitor) &noexcept(for_each_is_nothrow< Func &&, table & >::value)
 Invokes a visitor on each key-value pair in the table.
 
template<typename Func >
table && for_each (Func &&visitor) &&noexcept(for_each_is_nothrow< Func &&, table && >::value)
 Invokes a visitor on each key-value pair in the table (rvalue overload).
 
template<typename Func >
const tablefor_each (Func &&visitor) const &noexcept(for_each_is_nothrow< Func &&, const table & >::value)
 Invokes a visitor on each key-value pair in the table (const lvalue overload).
 
template<typename Func >
const table && for_each (Func &&visitor) const &&noexcept(for_each_is_nothrow< Func &&, const table && >::value)
 Invokes a visitor on each key-value pair in the table (const rvalue overload).
 

Insertion and Emplacement

using raw_value_type = impl::remove_cvref< ValueType >
 
using value_type = std::conditional_t< std::is_void_v< raw_value_type >, impl::emplaced_type_of< ValueArgs &&... >, raw_value_type >
 
using unwrapped_type = impl::remove_cvref< impl::unwrap_node< value_type > >
 
KeyType && key
 
KeyType ValueArgs && args
 
 else
 
map_iterator ipos = insert_with_hint(hint, toml::key{ static_cast<KeyType&&>(key) }, nullptr)
 
return iterator { ipos }
 
 TOML_CONSTRAINED_TEMPLATE ((is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >), typename ValueType=void, typename KeyType, typename... ValueArgs) iterator emplace_hint(const_iterator hint
 Emplaces a new value at a specific key if one did not already exist.
 
if constexpr (impl::is_wide_string< KeyType >)
 
 if (!ipos->second)
 
 TOML_CONSTRAINED_TEMPLATE ((is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >), typename KeyType, typename ValueType) std
 Inserts a new value at a specific key if one did not already exist.
 
void insert (Iter begin, Iter end, value_flags flags=preserve_source_value_flags)
 Inserts a series of key-value pairs into the table.
 
 TOML_CONSTRAINED_TEMPLATE ((is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >), typename KeyType, typename ValueType) std
 Inserts or assigns a value at a specific key.
 
 TOML_CONSTRAINED_TEMPLATE ((is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >), typename ValueType=void, typename KeyType, typename... ValueArgs) std
 Emplaces a new value at a specific key if one did not already exist.
 

Detailed Description

A TOML table.

\detail The interface of this type is modeled after std::map, with some additional considerations made for the heterogeneous nature of a TOML table.

\cpp toml::table tbl = toml::parse(R"( @iverbatim [animals] cats = [ "tiger", "lion", "puma" ] birds = [ "macaw", "pigeon", "canary" ] fish = [ "salmon", "trout", "carp" ] @endiverbatim )"sv);

// operator[] retrieves node-views std::cout << "cats: " << tbl["animals"]["cats"] << "\n"; std::cout << "fish[1]: " << tbl["animals"]["fish"][1] << "\n";

// at_path() does fully-qualified "toml path" lookups std::cout << "cats: " << tbl.at_path("animals.cats") << "\n"; std::cout << "fish[1]: " << tbl.at_path("animals.fish[1]") << "\n"; \ecpp

\out cats: ['tiger', 'lion', 'puma'] fish[1] : 'trout' cats : ['tiger', 'lion', 'puma'] fish[1] : 'trout' \eout

Member Typedef Documentation

◆ const_iterator

using table::const_iterator = toml::const_table_iterator

A BidirectionalIterator for iterating over const key-value pairs in a toml::table.

◆ iterator

using table::iterator = toml::table_iterator

A BidirectionalIterator for iterating over key-value pairs in a toml::table.

◆ raw_value_type

using table::raw_value_type = impl::remove_cvref<ValueType>

◆ unwrapped_type

using table::unwrapped_type = impl::remove_cvref<impl::unwrap_node<value_type> >

◆ value_type

using table::value_type = std:: conditional_t<std::is_void_v<raw_value_type>, impl::emplaced_type_of<ValueArgs&&...>, raw_value_type>

Constructor & Destructor Documentation

◆ table() [1/4]

Default constructor.

◆ ~table()

TOML_EXPORTED_MEMBER_FUNCTION table::~table ( )
noexcept

◆ table() [2/4]

Copy constructor.

◆ table() [3/4]

TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table::table ( table &&  other)
noexcept

Move constructor.

◆ table() [4/4]

TOML_NODISCARD_CTOR TOML_EXPORTED_MEMBER_FUNCTION table::table ( std::initializer_list< impl::table_init_pair >  kvps)
inlineexplicit

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

\detail \cpp auto tbl = toml::table{ { "foo", 1 }, { "bar", 2.0 }, { "kek", "three" } }; std::cout << tbl << "\n"; \ecpp

\out { foo = 1, bar = 2.0, kek = "three" } \eout

Parameters
kvpsA list of key-value pairs used to initialize the table.

Member Function Documentation

◆ as_array() [1/2]

TOML_CONST_INLINE_GETTER const array * table::as_array ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_array() [2/2]

TOML_CONST_INLINE_GETTER array * table::as_array ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_boolean() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< bool > * table::as_boolean ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_boolean() [2/2]

TOML_CONST_INLINE_GETTER toml::value< bool > * table::as_boolean ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_date() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< date > * table::as_date ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_date() [2/2]

TOML_CONST_INLINE_GETTER toml::value< date > * table::as_date ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_date_time() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< date_time > * table::as_date_time ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_date_time() [2/2]

TOML_CONST_INLINE_GETTER toml::value< date_time > * table::as_date_time ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_floating_point() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< double > * table::as_floating_point ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_floating_point() [2/2]

TOML_CONST_INLINE_GETTER toml::value< double > * table::as_floating_point ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_integer() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< int64_t > * table::as_integer ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_integer() [2/2]

TOML_CONST_INLINE_GETTER toml::value< int64_t > * table::as_integer ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_string() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< std::string > * table::as_string ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_string() [2/2]

TOML_CONST_INLINE_GETTER toml::value< std::string > * table::as_string ( )
inlinefinalnoexcept

Returns nullptr.

◆ as_table() [1/2]

TOML_CONST_INLINE_GETTER const table * table::as_table ( ) const
inlinefinalnoexcept

Returns a const-qualified pointer to the table.

◆ as_table() [2/2]

TOML_CONST_INLINE_GETTER table * table::as_table ( )
inlinefinalnoexcept

Returns a pointer to the table.

◆ as_time() [1/2]

TOML_CONST_INLINE_GETTER const toml::value< time > * table::as_time ( ) const
inlinefinalnoexcept

Returns nullptr.

◆ as_time() [2/2]

TOML_CONST_INLINE_GETTER toml::value< time > * table::as_time ( )
inlinefinalnoexcept

Returns nullptr.

◆ at() [1/4]

TOML_NODISCARD TOML_EXPORTED_MEMBER_FUNCTION node & table::at ( std::string_view  key)

Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.

◆ at() [2/4]

TOML_NODISCARD const node & table::at ( std::string_view  key) const
inline

Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.

◆ at() [3/4]

TOML_NODISCARD node & table::at ( std::wstring_view  key)
inline

Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

◆ at() [4/4]

TOML_NODISCARD const node & table::at ( std::wstring_view  key) const
inline

Gets a reference to the element at a specific key, throwing std::out_of_range if none existed.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

◆ begin() [1/2]

TOML_PURE_INLINE_GETTER const_iterator table::begin ( ) const
inlinenoexcept

Returns an iterator to the first key-value pair.

◆ begin() [2/2]

TOML_PURE_INLINE_GETTER iterator table::begin ( )
inlinenoexcept

Returns an iterator to the first key-value pair.

◆ cbegin()

TOML_PURE_INLINE_GETTER const_iterator table::cbegin ( ) const
inlinenoexcept

Returns an iterator to the first key-value pair.

◆ cend()

TOML_PURE_INLINE_GETTER const_iterator table::cend ( ) const
inlinenoexcept

Returns an iterator to one-past-the-last key-value pair.

◆ clear()

TOML_EXPORTED_MEMBER_FUNCTION void table::clear ( )
noexcept

Removes all key-value pairs from the table.

◆ constexpr()

if table::constexpr ( impl::is_wide_string< KeyType >  )
inlineconstexpr

◆ contains() [1/2]

TOML_PURE_GETTER bool table::contains ( std::string_view  key) const
inlinenoexcept

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

◆ contains() [2/2]

TOML_NODISCARD bool table::contains ( std::wstring_view  key) const
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

◆ empty()

TOML_PURE_INLINE_GETTER bool table::empty ( ) const
inlinenoexcept

Returns true if the table is empty.

◆ end() [1/2]

TOML_PURE_INLINE_GETTER const_iterator table::end ( ) const
inlinenoexcept

Returns an iterator to one-past-the-last key-value pair.

◆ end() [2/2]

TOML_PURE_INLINE_GETTER iterator table::end ( )
inlinenoexcept

Returns an iterator to one-past-the-last key-value pair.

◆ erase() [1/5]

iterator table::erase ( const_iterator  begin,
const_iterator  end 
)
inlinenoexcept

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

\detail \cpp 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"; \ecpp

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

Parameters
beginIterator to the first key-value pair being erased.
endIterator 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.

◆ erase() [2/5]

iterator table::erase ( const_iterator  pos)
inlinenoexcept

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

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

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

\out { a = 1, b = 2, c = 3 } { a = 1, c = 3 } \eout

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

◆ erase() [3/5]

iterator table::erase ( iterator  pos)
inlinenoexcept

Removes the specified key-value pair from the table.

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

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

\out { a = 1, b = 2, c = 3 } { a = 1, c = 3 } \eout

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

◆ erase() [4/5]

TOML_EXPORTED_MEMBER_FUNCTION size_t table::erase ( std::string_view  key)
noexcept

Removes the value with the given key from the table.

\detail \cpp 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"; \ecpp

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

Parameters
keyKey to erase.
Returns
Number of elements removed (0 or 1).

◆ erase() [5/5]

size_t table::erase ( std::wstring_view  key)
inline

Removes the value with the given key from the table.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Parameters
keyKey to erase.
Returns
Number of elements removed (0 or 1).

◆ find() [1/4]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION const_iterator table::find ( std::string_view  key) const
noexcept

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

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

◆ find() [2/4]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION iterator table::find ( std::string_view  key)
noexcept

Gets an iterator to the node at a specific key.

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

◆ find() [3/4]

TOML_NODISCARD iterator table::find ( std::wstring_view  key)
inline

Gets an iterator to the node at a specific key.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

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

◆ find() [4/4]

TOML_NODISCARD const_iterator table::find ( std::wstring_view  key) const
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

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

◆ for_each() [1/4]

template<typename Func >
table && table::for_each ( Func &&  visitor) &&
inlinenoexcept

Invokes a visitor on each key-value pair in the table (rvalue overload).

◆ for_each() [2/4]

template<typename Func >
table & table::for_each ( Func &&  visitor) &
inlinenoexcept

Invokes a visitor on each key-value pair in the table.

Template Parameters
FuncA callable type invocable with one of the following signatures:
  • func(key, val)
  • func(val)
Where:
  • key will recieve a const reference to a toml::key
  • val will recieve the value as it's concrete type with cvref-qualifications matching the table
Visitors returning bool (or something convertible to bool) will cause iteration to stop if they return false.
Parameters
visitorThe visitor object.
Returns
A reference to the table.

\cpp toml::table tbl{ { "0", 0 }, { "1", 1 }, { "2", 2 }, { "3", 3.0 }, { "4", "four" }, { "5", "five" }, { "6", 6 } };

// select only the integers using a strongly-typed visitor tbl.for_each([](toml::value<int64_t>& val) { std::cout << val << ", "; }); std::cout << "\n";

// select all the numeric values using a generic visitor + is_number<> metafunction tbl.for_each([](auto&& val) { if constexpr (toml::is_number<decltype(val)>) std::cout << val << ", "; }); std::cout << "\n";

// select all the numeric values until we encounter something non-numeric tbl.for_each([](auto&& val) { if constexpr (toml::is_number<decltype(val)>) { std::cout << val << ", "; return true; // "keep going" } else return false; // "stop!"

}); std::cout << "\n\n";

// visitors may also recieve the key tbl.for_each([](const toml::key& key, auto&& val) { std::cout << key << ": " << val << "\n"; });

\ecpp \out 0, 1, 2, 6, 0, 1, 2, 3.0, 6, 0, 1, 2, 3.0,

0: 0 1: 1 2: 2 3: 3.0 4: 'four' 5: 'five' 6: 6 \eout

See also
node::visit()

◆ for_each() [3/4]

template<typename Func >
const table && table::for_each ( Func &&  visitor) const &&
inlinenoexcept

Invokes a visitor on each key-value pair in the table (const rvalue overload).

◆ for_each() [4/4]

template<typename Func >
const table & table::for_each ( Func &&  visitor) const &
inlinenoexcept

Invokes a visitor on each key-value pair in the table (const lvalue overload).

◆ get() [1/4]

TOML_PURE_INLINE_GETTER const node * table::get ( std::string_view  key) const
inlinenoexcept

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

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

◆ get() [2/4]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION node * table::get ( std::string_view  key)
noexcept

Gets the node at a specific key.

\detail \cpp 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"; \ecpp

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

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

◆ get() [3/4]

TOML_NODISCARD node * table::get ( std::wstring_view  key)
inline

Gets the node at a specific key.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

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

◆ get() [4/4]

TOML_NODISCARD const node * table::get ( std::wstring_view  key) const
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

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

◆ get_as() [1/4]

template<typename T >
TOML_PURE_GETTER const impl::wrap_node< T > * table::get_as ( std::string_view  key) const
inlinenoexcept

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

Template Parameters
TOne of the TOML node or value types.
Parameters
keyThe node's key.
Returns
A pointer to the node at the specified key if it was of the given type, or nullptr.

◆ get_as() [2/4]

template<typename T >
TOML_PURE_GETTER impl::wrap_node< T > * table::get_as ( std::string_view  key)
inlinenoexcept

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

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

\out node ["a"] was an integer with value 42 \eout

Template Parameters
TOne of the TOML node or value types.
Parameters
keyThe node's key.
Returns
A pointer to the node at the specified key if it was of the given type, or nullptr.

◆ get_as() [3/4]

template<typename T >
TOML_NODISCARD impl::wrap_node< T > * table::get_as ( std::wstring_view  key)
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Template Parameters
TOne of the TOML node or value types.
Parameters
keyThe node's key.
Returns
A pointer to the node at the specified key if it was of the given type, or nullptr.

◆ get_as() [4/4]

template<typename T >
TOML_NODISCARD const impl::wrap_node< T > * table::get_as ( std::wstring_view  key) const
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Template Parameters
TOne of the TOML node or value types.
Parameters
keyThe node's key.
Returns
A pointer to the node at the specified key if it was of the given type, or nullptr.

◆ if()

table::if ( !ipos->  second)
inline

◆ insert()

void table::insert ( Iter  begin,
Iter  end,
value_flags  flags = preserve_source_value_flags 
)
inline

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

\detail \godbolt{bzYcce}

\cpp 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"; \ecpp

\out a = 1 b = 2 c = 3

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

Template Parameters
IterAn InputIterator to a collection of key-value pairs.
Parameters
beginAn iterator to the first value in the input collection.
endAn iterator to one-past-the-last value in the input collection.
flagsValue flags to apply to new values.
Remarks
This function is morally equivalent to calling insert(key, value) for each key-value pair covered by the iterator range, so any values with keys already found in the table will not be replaced.

◆ is_array()

TOML_CONST_INLINE_GETTER bool table::is_array ( ) const
inlinefinalnoexcept

Returns false.

◆ is_array_of_tables()

TOML_PURE_GETTER bool table::is_array_of_tables ( ) const
inlinefinalnoexcept

Returns false.

◆ is_boolean()

TOML_CONST_INLINE_GETTER bool table::is_boolean ( ) const
inlinefinalnoexcept

Returns false.

◆ is_date()

TOML_CONST_INLINE_GETTER bool table::is_date ( ) const
inlinefinalnoexcept

Returns false.

◆ is_date_time()

TOML_CONST_INLINE_GETTER bool table::is_date_time ( ) const
inlinefinalnoexcept

Returns false.

◆ is_floating_point()

TOML_CONST_INLINE_GETTER bool table::is_floating_point ( ) const
inlinefinalnoexcept

Returns false.

◆ is_homogeneous() [1/3]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool table::is_homogeneous ( node_type  ntype) const
finalnoexcept

◆ is_homogeneous() [2/3]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool table::is_homogeneous ( node_type  ntype,
const node *&  first_nonmatch 
) const
finalnoexcept

◆ is_homogeneous() [3/3]

TOML_PURE_GETTER TOML_EXPORTED_MEMBER_FUNCTION bool table::is_homogeneous ( node_type  ntype,
node *&  first_nonmatch 
)
finalnoexcept

◆ is_inline() [1/2]

TOML_PURE_INLINE_GETTER bool table::is_inline ( ) const
inlinenoexcept

Returns true if this table is an inline table.

Remarks
Runtime-constructed tables (i.e. those not created during parsing) are not inline by default.

◆ is_inline() [2/2]

void table::is_inline ( bool  val)
inlinenoexcept

Sets whether this table is a TOML inline table.

\detail \godbolt{an9xdj}

\cpp 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"; \ecpp

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

[d] e = 4

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

Remarks
A table being 'inline' is only relevent during printing; it has no effect on the general functionality of the table object.
Parameters
valThe new value for 'inline'.

◆ is_integer()

TOML_CONST_INLINE_GETTER bool table::is_integer ( ) const
inlinefinalnoexcept

Returns false.

◆ is_number()

TOML_CONST_INLINE_GETTER bool table::is_number ( ) const
inlinefinalnoexcept

Returns false.

◆ is_string()

TOML_CONST_INLINE_GETTER bool table::is_string ( ) const
inlinefinalnoexcept

Returns false.

◆ is_table()

TOML_CONST_INLINE_GETTER bool table::is_table ( ) const
inlinefinalnoexcept

Returns true.

◆ is_time()

TOML_CONST_INLINE_GETTER bool table::is_time ( ) const
inlinefinalnoexcept

Returns false.

◆ is_value()

TOML_CONST_INLINE_GETTER bool table::is_value ( ) const
inlinefinalnoexcept

Returns false.

◆ lower_bound() [1/4]

TOML_PURE_GETTER const_iterator table::lower_bound ( std::string_view  key) const
inlinenoexcept

Returns a const iterator to the first key-value pair with key that is not less than the given key.

Returns
An iterator to the first matching key-value pair, or end().

◆ lower_bound() [2/4]

TOML_PURE_GETTER iterator table::lower_bound ( std::string_view  key)
inlinenoexcept

Returns an iterator to the first key-value pair with key that is not less than the given key.

Returns
An iterator to the first matching key-value pair, or end().

◆ lower_bound() [3/4]

TOML_NODISCARD iterator table::lower_bound ( std::wstring_view  key)
inline

Returns an iterator to the first key-value pair with key that is not less than the given key.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Returns
An iterator to the first matching key-value pair, or end().

◆ lower_bound() [4/4]

TOML_NODISCARD const_iterator table::lower_bound ( std::wstring_view  key) const
inline

Returns a const iterator to the first key-value pair with key that is not less than the given key.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Returns
An iterator to the first matching key-value pair, or end().

◆ operator=() [1/2]

TOML_EXPORTED_MEMBER_FUNCTION table & table::operator= ( const table )

Copy-assignment operator.

◆ operator=() [2/2]

TOML_EXPORTED_MEMBER_FUNCTION table & table::operator= ( table &&  rhs)
noexcept

Move-assignment operator.

◆ operator[]() [1/4]

TOML_NODISCARD node_view< const node > table::operator[] ( std::string_view  key) const
inlinenoexcept

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

Parameters
keyThe key used for the lookup.
Returns
A view of the value at the given key if one existed, or an empty node view.
Remarks
std::map::operator[]'s behaviour of default-constructing a value at a key if it didn't exist is a crazy bug factory so I've deliberately chosen not to emulate it. This is not an error.
See also
toml::node_view

◆ operator[]() [2/4]

TOML_NODISCARD node_view< node > table::operator[] ( std::string_view  key)
inlinenoexcept

Gets a node_view for the selected value.

Parameters
keyThe key used for the lookup.
Returns
A view of the value at the given key if one existed, or an empty node view.
Remarks
std::map::operator[]'s behaviour of default-constructing a value at a key if it didn't exist is a crazy bug factory so I've deliberately chosen not to emulate it. This is not an error.
See also
toml::node_view

◆ operator[]() [3/4]

TOML_NODISCARD node_view< node > table::operator[] ( std::wstring_view  key)
inline

Gets a node_view for the selected value.

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Parameters
keyThe key used for the lookup.
Returns
A view of the value at the given key if one existed, or an empty node view.
Remarks
std::map::operator[]'s behaviour of default-constructing a value at a key if it didn't exist is a crazy bug factory so I've deliberately chosen not to emulate it. This is not an error.
See also
toml::node_view

◆ operator[]() [4/4]

TOML_NODISCARD node_view< const node > table::operator[] ( std::wstring_view  key) const
inline

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

\availability This overload is only available when TOML_ENABLE_WINDOWS_COMPAT is enabled.

Parameters
keyThe key used for the lookup.
Returns
A view of the value at the given key if one existed, or an empty node view.
Remarks
std::map::operator[]'s behaviour of default-constructing a value at a key if it didn't exist is a crazy bug factory so I've deliberately chosen not to emulate it. This is not an error.
See also
toml::node_view

◆ prune() [1/2]

table && table::prune ( bool  recursive = true) &&
inlinenoexcept

Removes empty child arrays and tables (rvalue overload).

Parameters
recursiveShould child arrays and tables themselves be pruned?
Returns
An rvalue reference to the table.

◆ prune() [2/2]

TOML_EXPORTED_MEMBER_FUNCTION table & table::prune ( bool  recursive = true) &
noexcept

Removes empty child arrays and tables.

\detail \cpp

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

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

\out { a = 1, b = [], c = [ {}, [] ] } { a = 1 } \eout

Parameters
recursiveShould child arrays and tables themselves be pruned?
Returns
A reference to the table.

◆ size()

TOML_PURE_INLINE_GETTER size_t table::size ( ) const
inlinenoexcept

Returns the number of key-value pairs in the table.

◆ TOML_CONSTRAINED_TEMPLATE() [1/4]

table::TOML_CONSTRAINED_TEMPLATE ( (is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >)  ,
typename KeyType  ,
typename ValueType   
)
inline

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

\detail \godbolt{bMnW5r}

\cpp 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"; \ecpp

\out a = 1 b = 2 c = 3

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

Template Parameters
KeyTypeA toml::key or any compatible string type.
ValueTypetoml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
keyThe key at which to insert the new value.
valThe new value to insert.
flagsValue flags to apply to new values.
Returns
\conditional_return{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.
\conditional_return{Input is a null toml::node_view} { end(), false }
Attention
The return value will always be { end(), false } if the input value was an null toml::node_view, because no insertion can take place. This is the only circumstance in which this can occur.

◆ TOML_CONSTRAINED_TEMPLATE() [2/4]

table::TOML_CONSTRAINED_TEMPLATE ( (is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >)  ,
typename KeyType  ,
typename ValueType   
)
inline

Inserts or assigns a value at a specific key.

\detail \godbolt{ddK563}

\cpp 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"; \ecpp

\out 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 \eout

Template Parameters
KeyTypeA toml::key or any compatible string type.
ValueTypetoml::node, toml::node_view, toml::table, toml::array, or a native TOML value type (or a type promotable to one).
Parameters
keyThe key at which to insert or assign the value.
valThe value to insert/assign.
flagsValue flags to apply to new values.
Returns
\conditional_return{Valid input}
  • An iterator to the value's position
  • true if the value was inserted, false if it was assigned.
\conditional_return{Input is a null toml::node_view} { end(), false }
Attention
The return value will always be { end(), false } if the input value was a null toml::node_view, because no insertion or assignment can take place. This is the only circumstance in which this can occur.

◆ TOML_CONSTRAINED_TEMPLATE() [3/4]

table::TOML_CONSTRAINED_TEMPLATE ( (is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >)  ,
typename ValueType  = void,
typename KeyType  ,
typename...  ValueArgs 
)

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

Template Parameters
ValueTypetoml::table, toml::array, or any native TOML value type.
KeyTypeA toml::key or any compatible string type.
ValueArgsValue constructor argument types.
Parameters
hintIterator to the position before which the new element will be emplaced.
keyThe key at which to emplace the new value.
argsArguments to forward to the value's constructor.
Returns
An iterator to the emplacement position (or the position of the value that prevented emplacement)
Note
This function has exactly the same semantics as std::map::emplace_hint().

◆ TOML_CONSTRAINED_TEMPLATE() [4/4]

table::TOML_CONSTRAINED_TEMPLATE ( (is_key_or_convertible< KeyType && >||impl::is_wide_string< KeyType >)  ,
typename ValueType  = void,
typename KeyType  ,
typename...  ValueArgs 
)
inline

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

\detail \cpp 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"; \ecpp

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

Template Parameters
ValueTypetoml::table, toml::array, or any native TOML value type.
KeyTypeA toml::key or any compatible string type.
ValueArgsValue constructor argument types.
Parameters
keyThe key at which to emplace the new value.
argsArguments 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.
Remarks
There is no difference between insert() and emplace() for trivial value types (floats, ints, bools).

◆ type()

TOML_CONST_INLINE_GETTER node_type table::type ( ) const
inlinefinalnoexcept

Returns #toml::node_type::table.

Friends And Related Symbol Documentation

◆ operator!=

TOML_NODISCARD friend bool operator!= ( const table lhs,
const table rhs 
)
friend

Inequality operator.

Parameters
lhsThe LHS table.
rhsThe RHS table.
Returns
True if the tables did not contain the same keys and map.

◆ operator<<

std::ostream & operator<< ( std::ostream &  lhs,
const table rhs 
)
friend

Prints the table out to a stream as formatted TOML.

\availability This operator is only available when TOML_ENABLE_FORMATTERS is enabled.

◆ operator==

TOML_NODISCARD friend bool operator== ( const table lhs,
const table rhs 
)
friend

Equality operator.

Parameters
lhsThe LHS table.
rhsThe RHS table.
Returns
True if the tables contained the same keys and map.

Member Data Documentation

◆ args

KeyType ValueArgs&& table::args
Initial value:
{
static_assert(!impl::is_wide_string<KeyType> || TOML_ENABLE_WINDOWS_COMPAT,
"Emplacement using wide-character keys is only supported on Windows with "
"TOML_ENABLE_WINDOWS_COMPAT enabled.")
#define TOML_ENABLE_WINDOWS_COMPAT
Enables the use of wide strings (wchar_t, std::wstring) in various places throughout the library when...
Definition preprocessor.hpp:1074

◆ else

table::else
Initial value:
{
static constexpr auto moving_node_ptr = std::is_same_v<value_type, impl::node_ptr>
&& sizeof...(ValueArgs) == 1u
&& impl::first_is_same<impl::node_ptr&&, ValueArgs&&...>

◆ ipos

map_iterator table::ipos = insert_with_hint(hint, toml::key{ static_cast<KeyType&&>(key) }, nullptr)

◆ iterator

return table::iterator { ipos }

◆ key

KeyType&& table::key

The documentation for this class was generated from the following file: