template <typename ViewedType>
toml::node_view class

A view of a node.

A node_view is like a std::optional<toml::node&> (if such a construct were legal), with lots of toml-specific stuff built-in. It may represent a node, and allows you to do many of the same operations that you'd do on nodes directly, as well as easily traversing the node tree by creating subviews (via node_view::operator[]).

auto tbl = toml::parse(R"(

    title = "my hardware store"

    [[products]]
    name = "Hammer"
    sku = 738594937
    keywords = [ "hammer", "construction", "build" ]

    [[products]]
    name = "Nail"
    sku = 284758393
    color = "gray"

)"sv);

std::cout << tbl["title"] << "\n";
std::cout << tbl["products"][0]["name"] << "\n";
std::cout << tbl["products"][0]["keywords"] << "\n";
std::cout << tbl["products"][0]["keywords"][2] << "\n";

tbl["products"][0]["keywords"].as_array()->push_back("heavy");
std::cout << tbl["products"][0]["keywords"] << "\n";
std::cout << "has product[2]: "sv << !!tbl["products"][2] << "\n";
std::cout << "product[2]: "sv << tbl["products"][2] << "\n";
"my hardware store"
"Hammer"
[ "hammer", "construction", "build" ]
"build"
[ "hammer", "construction", "build", "heavy" ]
has product[2]: false
product[2]:

Public types

using viewed_type = ViewedType
The node type being viewed - either node or const node.

Constructors, destructors, conversion operators

node_view() defaulted noexcept
Constructs an empty node view.
node_view(viewed_type* node) explicit noexcept
Constructs node_view of a specific node.
node_view(viewed_type& node) explicit noexcept
Constructs node_view of a specific node.
node_view(const node_view&) defaulted noexcept
Copy constructor.
node_view(node_view&&) defaulted noexcept
Move constructor.
operator bool() const explicit noexcept
Returns true if the view references a node.

Public functions

auto node() const →  viewed_type* noexcept
Returns the node that's being referenced by the view.
auto operator=(const node_view&) & →  node_view& defaulted noexcept
Copy-assignment operator.
auto operator=(node_view&&) & →  node_view& defaulted noexcept
Move-assignment operator.

Equality

template <typename T>
auto operator!=(const node_view& lhs, const node_view<T>& rhs) →  bool noexcept
Returns true if the two views do not refer to nodes of the same type and value.
template <typename T>
auto operator==(const node_view& lhs, const node_view<T>& rhs) →  bool noexcept
Returns true if the two views refer to nodes of the same type and value.
auto operator==(const node_view& lhs, const table& rhs) →  bool noexcept
Returns true if the viewed node is a table with the same contents as RHS.
auto operator==(const node_view& lhs, const array& rhs) →  bool noexcept
Returns true if the viewed node is an array with the same contents as RHS.
template <typename T>
auto operator==(const node_view& lhs, const toml::value<T>& rhs) →  bool noexcept
Returns true if the viewed node is a value with the same value as RHS.
template <typename T>
auto operator==(const node_view& lhs, const T& rhs) →  bool noexcept(…)
Returns true if the viewed node is a value with the same value as RHS.
template <typename T>
auto operator==(const node_view& lhs, const std::initializer_list<T>& rhs) →  bool noexcept(…)
Returns true if the viewed node is an array with the same contents as the RHS initializer list.
template <typename T>
auto operator==(const node_view& lhs, const std::vector<T>& rhs) →  bool noexcept(…)
Returns true if the viewed node is an array with the same contents as the RHS vector.

Subviews

auto at_path(std::string_view path) const →  node_view noexcept
Returns a view of the subnode matching a fully-qualified "TOML path".
auto at_path(std::wstring_view path) const →  node_view
Returns a view of the subnode matching a fully-qualified "TOML path".
auto operator[](std::string_view key) const →  node_view noexcept
Returns a view of the selected subnode.
auto operator[](std::wstring_view key) const →  node_view
Returns a view of the selected subnode.
auto operator[](size_t index) const →  node_view noexcept
Returns a view of the selected subnode.

Type casts

template <typename T>
auto as() const →  auto* noexcept
Gets a pointer to the viewed node as a more specific node type.
auto as_array() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::array, if it is one.
auto as_boolean() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<bool>, if it is one.
auto as_date() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<date>, if it is one.
auto as_date_time() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<date_time>, if it is one.
auto as_floating_point() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<double>, if it is one.
auto as_integer() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<int64_t>, if it is one.
auto as_string() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<string>, if it is one.
auto as_table() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::table, if it is one.
auto as_time() const →  auto* noexcept
Returns a pointer to the viewed node as a toml::value<time>, if it is one.

Type checks

template <typename T>
auto is() const →  bool noexcept
Checks if this view references a node of a specific type.
auto is_array() const →  bool noexcept
Returns true if the viewed node is a toml::array.
auto is_array_of_tables() const →  bool noexcept
Returns true if the viewed node is a toml::array that contains only tables.
auto is_boolean() const →  bool noexcept
Returns true if the viewed node is a toml::value<bool>.
auto is_date() const →  bool noexcept
Returns true if the viewed node is a toml::value<date>.
auto is_date_time() const →  bool noexcept
Returns true if the viewed node is a toml::value<date_time>.
auto is_floating_point() const →  bool noexcept
Returns true if the viewed node is a toml::value<double>.
auto is_homogeneous(node_type ntype, viewed_type*& first_nonmatch) const →  bool noexcept
Checks if the viewed node contains values/elements of only one type.
auto is_homogeneous(node_type ntype) const →  bool noexcept
Checks if the viewed node contains values/elements of only one type.
template <typename ElemType = void>
auto is_homogeneous() const →  bool noexcept
Checks if the viewed node contains values/elements of only one type.
auto is_integer() const →  bool noexcept
Returns true if the viewed node is a toml::value<int64_t>.
auto is_number() const →  bool noexcept
Returns true if the viewed node is a toml::value<int64_t> or toml::value<double>.
auto is_string() const →  bool noexcept
Returns true if the viewed node is a toml::value<string>.
auto is_table() const →  bool noexcept
Returns true if the viewed node is a toml::table.
auto is_time() const →  bool noexcept
Returns true if the viewed node is a toml::value<time>.
auto is_value() const →  bool noexcept
Returns true if the viewed node is a toml::value<>.
auto type() const →  node_type noexcept
Returns the type identifier for the viewed node.

Value retrieval

template <typename T>
auto ref() const →  decltype(auto) noexcept
Gets a raw reference to the viewed node's underlying data.
template <typename T>
auto value() const →  optional<T> noexcept(…)
Gets the value contained by the referenced node.
template <typename T>
auto value_exact() const →  optional<T> noexcept(…)
Gets the value contained by the referenced node.
template <typename T>
auto value_or(T&& default_value) const →  auto noexcept(…)
Gets the raw value contained by the referenced node, or a default.

Visitation

template <typename Func>
auto visit(Func&& visitor) const →  decltype(auto) noexcept(…)
Invokes a visitor on the viewed node based on its concrete type.

Friends

auto operator<<(std::ostream& os, const node_view& nv) →  std::ostream&
Prints the viewed node out to a stream.

Function documentation

template <typename ViewedType>
node_view toml::node_view::at_path(std::string_view path) const noexcept

Returns a view of the subnode matching a fully-qualified "TOML path".

template <typename ViewedType>
node_view toml::node_view::at_path(std::wstring_view path) const

Returns a view of the subnode matching a fully-qualified "TOML path".

template <typename ViewedType>
node_view toml::node_view::operator[](std::string_view key) const noexcept

Returns a view of the selected subnode.

Parameters
key The key of the node to retrieve
Returns A view of the selected node if this node represented a table and it contained a value at the given key, or an empty view.

template <typename ViewedType>
node_view toml::node_view::operator[](std::wstring_view key) const

Returns a view of the selected subnode.

Parameters
key The key of the node to retrieve
Returns A view of the selected node if this node represented a table and it contained a value at the given key, or an empty view.

template <typename ViewedType>
node_view toml::node_view::operator[](size_t index) const noexcept

Returns a view of the selected subnode.

Parameters
index The index of the node to retrieve
Returns A view of the selected node if this node represented an array and it contained a value at the given index, or an empty view.

template <typename ViewedType>
template <typename T>
auto* toml::node_view::as() const noexcept

Gets a pointer to the viewed node as a more specific node type.

Template parameters
T The node type or TOML value type to cast to.
Returns A pointer to the node as the given type, or nullptr if it was a different type.

template <typename ViewedType>
template <typename T>
bool toml::node_view::is() const noexcept

Checks if this view references a node of a specific type.

Template parameters
T A TOML node or value type.
Returns Returns true if the viewed node is an instance of the specified type.

template <typename ViewedType>
bool toml::node_view::is_homogeneous(node_type ntype, viewed_type*& first_nonmatch) const noexcept

Checks if the viewed 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 viewed node was homogeneous. 
auto cfg = toml::parse("arr = [ 1, 2, 3, 4.0 ]");

toml::node* nonmatch{};
if (cfg["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

template <typename ViewedType>
bool toml::node_view::is_homogeneous(node_type ntype) const noexcept

Checks if the viewed 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 viewed node was homogeneous. 
auto cfg = toml::parse("arr = [ 1, 2, 3 ]");
std::cout << "homogenous: "sv << cfg["arr"].is_homogeneous(toml::node_type::none) << "\n";
std::cout << "all floats: "sv << cfg["arr"].is_homogeneous(toml::node_type::floating_point) << "\n";
std::cout << "all arrays: "sv << cfg["arr"].is_homogeneous(toml::node_type::array) << "\n";
std::cout << "all ints:   "sv << cfg["arr"].is_homogeneous(toml::node_type::integer) << "\n";
homogeneous: true
all floats:  false
all arrays:  false
all ints:    true

template <typename ViewedType>
template <typename ElemType = void>
bool toml::node_view::is_homogeneous() const noexcept

Checks if the viewed node contains values/elements of only one type.

Template parameters
ElemType A TOML node or value type.
Left as void: "is every element the same type?"
Explicitly specified: "is every element a T?"
Returns True if the viewed node was homogeneous. 
auto cfg = toml::parse("arr = [ 1, 2, 3 ]");
std::cout << "homogenous:   "sv << cfg["arr"].is_homogeneous() << "\n";
std::cout << "all doubles:  "sv << cfg["arr"].is_homogeneous<double>() << "\n";
std::cout << "all arrays:   "sv << cfg["arr"].is_homogeneous<toml::array>() << "\n";
std::cout << "all integers: "sv << cfg["arr"].is_homogeneous<int64_t>() << "\n";
homogeneous: true
all floats:  false
all arrays:  false
all ints:    true

template <typename ViewedType>
template <typename T>
decltype(auto) toml::node_view::ref() const noexcept

Gets a raw reference to the viewed node's underlying data.

Template parameters
T One of the TOML value types.
Returns A reference to the underlying data.

template <typename ViewedType>
template <typename T>
optional<T> toml::node_view::value() const noexcept(…)

Gets the value contained by the referenced node.

Template parameters
T One of the native TOML value types, or a type capable of convertible to one.
Returns The underlying value if the node was a value of the matching type (or convertible to it) and within the range of the output type, or an empty optional.

This function has 'permissive' retrieval semantics; some value types are allowed to convert to others (e.g. retrieving a boolean as an integer), and the specified return value type can be any type where a reasonable conversion from a native TOML value exists (e.g. std::wstring on Windows). If the source value cannot be represented by the destination type, an empty optional is returned. See node::value() for examples.

template <typename ViewedType>
template <typename T>
optional<T> toml::node_view::value_exact() const noexcept(…)

Gets the value contained by the referenced node.

Template parameters
T One of the native TOML value types, or a type capable of losslessly representing one.
Returns The underlying value if the node was a value of the matching type (or losslessly convertible to it), or an empty optional.

This function has 'exact' retrieval semantics; the only return value types allowed are the TOML native value types, or types that can losslessly represent a native value type (e.g. std::wstring on Windows).

template <typename ViewedType>
template <typename T>
auto toml::node_view::value_or(T&& default_value) const noexcept(…)

Gets the raw value contained by the referenced node, or a default.

Template parameters
T Default value type. Must be one of the native TOML value types, or convertible to it.
Parameters
default_value The default value to return if the node wasn't a value, wasn't the correct type, or no conversion was possible.
Returns The underlying value if the node was a value of the matching type (or convertible to it) and within the range of the output type, or the provided default.

template <typename ViewedType>
template <typename Func>
decltype(auto) toml::node_view::visit(Func&& visitor) const noexcept(…)

Invokes a visitor on the viewed node based on its concrete type.

template <typename ViewedType>
std::ostream& operator<<(std::ostream& os, const node_view& nv)

Prints the viewed node out to a stream.