toml::path class

A TOML path.

This type parses and represents a path to a TOML node. It validates the syntax of the path but does not ensure that the path refers to a valid node in any particular TOML document. If parsing fails, the object will evaluate as 'falsy', and will be empty.

toml::path the_path("animals.cats[1]");

// can use with tbl.at_path or operator[]
std::cout << "second cat: " << tbl[the_path] << "\n";
std::cout << "cats: " << tbl.at_path(the_path.parent_path()) << "\n";

second cat: lion
cats: ['tiger', 'lion', 'puma']

Constructors, destructors, conversion operators

operator bool() const explicit noexcept: Returns true if the path has one or more components.
path() defaulted noexcept: Default constructor.
path(std::string_view) explicit: Construct a path by parsing from a string.
path(std::wstring_view) explicit: Construct a path by parsing from a string.
path(const path&) defaulted: Copy constructor.
path(path&&) defaulted noexcept: Move constructor.
~path() defaulted noexcept: Default destructor.

Public functions

auto empty() const -> bool noexcept: Whether (true) or not (false) the path is empty.
auto operator[](size_t index) -> path_component& noexcept: Fetch a path component by index.
auto operator[](size_t index) const -> const path_component& noexcept: Fetch a path component by index (const overload).
auto size() const -> size_t noexcept: Returns the number of components in the path.

Appending

auto append(const path& p) -> path&: Appends another path onto the end of this one.
auto append(path&& p) -> path&: Appends another path onto the end of this one.
auto append(std::string_view str) -> path&: Parses a path and appends it onto the end of this one.
auto append(std::wstring_view str) -> path&: Parses a path and appends it onto the end of this one.
auto operator+=(const path&) -> path&: Appends another path onto the end of this one.
auto operator+=(path&&) -> path&: Appends another path onto the end of this one.
auto operator+=(std::string_view) -> path&: Parses a path and appends it onto the end of this one.
auto operator+=(std::wstring_view) -> path&: Parses a path and appends it onto the end of this one.

Assignment

auto assign(const path& p) -> path&: Replaces the contents of the path with that of another.
auto assign(path&& p) -> path& noexcept: Replaces the contents of the path with that of another.
auto assign(std::string_view str) -> path&: Replaces the contents of the path object by a new path.
auto assign(std::wstring_view str) -> path&: Replaces the contents of the path object by a new path.
auto operator=(const path&) -> path& defaulted: Copy-assignment operator.
auto operator=(path&&) -> path& defaulted noexcept: Move-assignment operator.
auto operator=(std::string_view) -> path&: Replaces the contents of the path by parsing from a string.
auto operator=(std::wstring_view) -> path&: Replaces the contents of the path by parsing from a string.

Concatenation

auto operator+(const path& lhs, const path& rhs) -> path: Concatenates two paths.
auto operator+(const path& lhs, std::string_view rhs) -> path: Concatenates two paths.
auto operator+(std::string_view lhs, const path& rhs) -> path: Concatenates two paths.
auto operator+(const path& lhs, std::wstring_view rhs) -> path: Concatenates two paths.
auto operator+(std::wstring_view lhs, const path& rhs) -> path: Concatenates two paths.

Equality

auto operator!=(const path& lhs, const path& rhs) -> bool noexcept: Returns whether two paths are not the same.
auto operator!=(const path& lhs, std::string_view rhs) -> bool: Returns whether two paths are not the same.
auto operator!=(std::string_view lhs, const path& rhs) -> bool: Returns whether two paths are not the same.
auto operator!=(const path& lhs, std::wstring_view rhs) -> bool: Returns whether two paths are not the same.
auto operator!=(std::wstring_view lhs, const path& rhs) -> bool: Returns whether two paths are not the same.
auto operator==(const path& lhs, const path& rhs) -> bool noexcept: Returns whether two paths are the same.
auto operator==(const path& lhs, std::string_view rhs) -> bool: Returns whether two paths are the same.
auto operator==(std::string_view lhs, const path& rhs) -> bool: Returns whether two paths are the same.
auto operator==(const path& lhs, std::wstring_view rhs) -> bool: Returns whether two paths are the same.
auto operator==(std::wstring_view lhs, const path& rhs) -> bool: Returns whether two paths are the same.

Iteration

using const_iterator = std::vector<path_component>::const_iterator
using iterator = std::vector<path_component>::iterator
auto begin() -> iterator noexcept: Returns an iterator to the first component in the path.
auto begin() const -> const_iterator noexcept: Returns a const iterator to the first component in the path.
auto cbegin() const -> const_iterator noexcept: Returns a const iterator to the first component in the path.
auto cend() const -> const_iterator noexcept: Returns a const iterator to one-past-the-last component in the path.
auto end() -> iterator noexcept: Returns an iterator to one-past-the-last component in the path.
auto end() const -> const_iterator noexcept: Returns a const iterator to one-past-the-last component in the path.

Prepending

auto prepend(const path&) -> path&: Prepends another path onto the beginning of this one.
auto prepend(path&&) -> path&: Prepends another path onto the beginning of this one.
auto prepend(std::string_view) -> path&: Parses a path and prepends it onto the beginning of this one.
auto prepend(std::wstring_view) -> path&: Parses a path and prepends it onto the beginning of this one.

String conversion

operator std::string() const explicit: Returns a string representation of this path.
operator std::wstring() const explicit: Returns a string representation of this path.
auto str() const -> std::string: Returns a string representation of this path.
auto wide_str() const -> std::wstring: Returns a string representation of this path.
auto operator<<(std::ostream& os, const path& rhs) -> std::ostream&: Prints the string representation of a toml::path out to a stream.

Subpaths and Truncation

void clear() noexcept: Erases the contents of the path.
auto leaf(size_t n = 1) const -> path: Returns a toml::path object representing terminal n-parts of a TOML path.
auto parent() const -> path: Returns a toml::path object representing the path of the parent node.
auto subpath(const_iterator start, const_iterator end) const -> path: Returns a toml::path object that is a specified subpath of the current path, representing the range of path components from [start, end).
auto subpath(size_t start, size_t length) const -> path: Returns a toml::path object that is a specified subpath of the current path, representing the range of path components with indexes from [start, start + length].
auto truncate(size_t n) -> path&: Removes the number of terminal path components specified by n.
auto truncated(size_t n) const -> path: Returns a toml::path object which has had n terminal path components removed.