toml namespace

The root namespace for all toml++ functions and types.

Namespaces

namespace literals inline
Convenience literal operators for working with toml++.

Classes

class array
A TOML array.
struct date
A local date.
struct date_time
A date-time.
template <typename T>
struct inserter
Helper class for suppressing move-construction in single-argument array constructors.
class json_formatter
A wrapper for printing TOML objects out to a stream as formatted JSON.
class key
A key parsed from a TOML document.
class node
A TOML node.
template <typename ViewedType>
class node_view
A view of a node.
class parse_error
An error generated when parsing fails.
class parse_result
The result of a parsing operation.
class path
A TOML path.
class path_component
Represents a single component of a complete 'TOML-path': either a key or an array index.
struct source_position
A source document line-and-column pair.
struct source_region
A source document region.
class table
A TOML table.
struct time
A local time-of-day.
struct time_offset
A timezone offset.
class toml_formatter
A wrapper for printing TOML objects out to a stream as formatted TOML.
template <typename ValueType>
class value
A TOML value.
class yaml_formatter
A wrapper for printing TOML objects out to a stream as formatted YAML.

Enums

enum class format_flags: uint64_t { none, quote_dates_and_times = (1ull << 0), quote_infinities_and_nans = (1ull << 1), allow_literal_strings = (1ull << 2), allow_multi_line_strings = (1ull << 3), allow_real_tabs_in_strings = (1ull << 4), allow_unicode_strings = (1ull << 5), allow_binary_integers = (1ull << 6), allow_octal_integers = (1ull << 7), allow_hexadecimal_integers = (1ull << 8), indent_sub_tables = (1ull << 9), indent_array_elements = (1ull << 10), indentation = indent_sub_tables | indent_array_elements, relaxed_float_precision = (1ull << 11), terse_key_value_pairs = (1ull << 12) }
Format flags for modifying how TOML data is printed to streams.
enum class node_type: uint8_t { none, table, array, string, integer, floating_point, boolean, date, time, date_time }
TOML node type identifiers.
enum class path_component_type: uint8_t { key = 0x1, array_index = 0x2 }
Indicates type of path component, either a key, an index in an array, or invalid.
enum class value_flags: uint16_t { none, format_as_binary = 1, format_as_octal = 2, format_as_hexadecimal = 3 }
Metadata associated with TOML values.

Typedefs

using array_iterator = /* ... */
A RandomAccessIterator for iterating over elements in a toml::array.
using const_array_iterator = /* ... */
A RandomAccessIterator for iterating over const elements in a toml::array.
using const_table_iterator = /* ... */
A BidirectionalIterator for iterating over const key-value pairs in a toml::table.
using default_formatter = toml_formatter
The 'default' formatter used by TOML objects when they are printed to a stream.
template <typename T>
using inserted_type_of = /* ... */
Metafunction for determining which node type would be constructed if an object of this type was inserted into a toml::table or toml::array.
template <typename T>
using optional = std::optional<T>
The 'optional' type used throughout the library.
using source_index = uint32_t
The integer type used to tally line numbers and columns.
using source_path_ptr = std::shared_ptr<const std::string>
A pointer to a shared string resource containing a source path.
using table_iterator = /* ... */
A BidirectionalIterator for iterating over key-value pairs in a toml::table.

Functions

auto at_path(node& root, std::string_view path) -> node_view<node> noexcept
Returns a view of the node matching a fully-qualified "TOML path".
auto at_path(const node& root, std::string_view path) -> node_view<const node> noexcept
Returns a const view of the node matching a fully-qualified "TOML path".
auto at_path(node& root, std::wstring_view path) -> node_view<node>
Returns a view of the node matching a fully-qualified "TOML path".
auto at_path(const node& root, std::wstring_view path) -> node_view<const node>
Returns a const view of the node matching a fully-qualified "TOML path".
auto at_path(node& root, const toml::path& path) -> node_view<node> noexcept
Returns a view of the node matching a fully-qualified "TOML path".
auto at_path(const node& root, const toml::path& path) -> node_view<const node> noexcept
Returns a const view of the node matching a fully-qualified "TOML path".
auto operator""_toml(const char* str, size_t len) -> parse_result
Parses TOML data from a string literal.
auto operator""_toml(const char8_t* str, size_t len) -> parse_result
Parses TOML data from a UTF-8 string literal.
auto operator""_tpath(const char* str, size_t len) -> path
Parses a TOML path from a string literal.
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, node_type rhs) -> std::basic_ostream<Char>&
Pretty-prints the value of a node_type to a stream.
auto parse(std::string_view doc, std::string_view source_path = {}) -> parse_result
Parses a TOML document from a string view.
auto parse(std::string_view doc, std::string&& source_path) -> parse_result
Parses a TOML document from a string view.
auto parse(std::u8string_view doc, std::string_view source_path = {}) -> parse_result
Parses a TOML document from a char8_t string view.
auto parse(std::u8string_view doc, std::string&& source_path) -> parse_result
Parses a TOML document from a char8_t string view.
auto parse(std::string_view doc, std::wstring_view source_path) -> parse_result
Parses a TOML document from a string view.
auto parse(std::istream& doc, std::wstring_view source_path) -> parse_result
Parses a TOML document from a stream.
auto parse(std::u8string_view doc, std::wstring_view source_path) -> parse_result
Parses a TOML document from a char8_t string view.
auto parse(std::istream& doc, std::string_view source_path = {}) -> parse_result
Parses a TOML document from a stream.
auto parse(std::istream& doc, std::string&& source_path) -> parse_result
Parses a TOML document from a stream.
auto parse_file(std::string_view file_path) -> parse_result
Parses a TOML document from a file.
auto parse_file(std::u8string_view file_path) -> parse_result
Parses a TOML document from a file.
auto parse_file(std::wstring_view file_path) -> parse_result
Parses a TOML document from a file.

Variables

template <typename T>
bool is_array constexpr
Metafunction for determining if a type is, or is a reference to, a toml::array.
template <typename T>
bool is_boolean constexpr
Metafunction for determining if a type is, or is a reference to, a bool or toml::value<bool>.
template <typename T>
bool is_chronological constexpr
Metafunction for determining if a type satisfies any of toml::is_date, toml::is_time or toml::is_date_time.
template <typename T>
bool is_container constexpr
Metafunction for determining if a type satisfies either toml::is_table or toml::is_array.
template <typename T>
bool is_date constexpr
Metafunction for determining if a type is, or is a reference to, a toml::date or toml::value<date>.
template <typename T>
bool is_date_time constexpr
Metafunction for determining if a type is, or is a reference to, a toml::date_time or toml::value<date_time>.
template <typename T>
bool is_floating_point constexpr
Metafunction for determining if a type is, or is a reference to, a double or toml::value<double>.
template <typename T>
bool is_integer constexpr
Metafunction for determining if a type is, or is a reference to, a int64_t or toml::value<int64_t>.
template <typename T>
bool is_key constexpr
Metafunction for determining if a type is, or is a reference to, a toml::key.
template <typename T>
bool is_key_or_convertible constexpr
Metafunction for determining if a type is, or is a reference to, a toml::key, or is implicitly or explicitly convertible to one.
template <typename T>
bool is_node constexpr
Metafunction for determining if a type is, or is a reference to, a toml::node (or one of its subclasses).
template <typename T>
bool is_node_view constexpr
Metafunction for determining if a type is, or is a reference to, a toml::node_view.
template <typename T>
bool is_number constexpr
Metafunction for determining if a type satisfies either toml::is_integer or toml::is_floating_point.
template <typename T>
bool is_string constexpr
Metafunction for determining if a type is, or is a reference to, a std::string or toml::value<std::string>.
template <typename T>
bool is_table constexpr
Metafunction for determining if a type is, or is a reference to, a toml::table.
template <typename T>
bool is_time constexpr
Metafunction for determining if a type is, or is a reference to, a toml::time or toml::value<time>.
template <typename T>
bool is_value constexpr
Metafunction for determining if a type is, or is a reference to, any of the toml value types. Excludes tables and arrays.
value_flags preserve_source_value_flags constexpr
Special toml::value_flags constant used for array + table insert functions to specify that any value nodes being copied should not have their flags property overridden by the inserting function's flags argument.

Enum documentation

enum class toml::format_flags: uint64_t

Format flags for modifying how TOML data is printed to streams.

Enumerators
none

None.

quote_dates_and_times

Dates and times will be emitted as quoted strings.

quote_infinities_and_nans

Infinities and NaNs will be emitted as quoted strings.

allow_literal_strings

Strings will be emitted as single-quoted literal strings where possible.

allow_multi_line_strings

Strings containing newlines will be emitted as triple-quoted 'multi-line' strings where possible.

allow_real_tabs_in_strings

Allow real tab characters in string literals (as opposed to the escaped form \t).

allow_unicode_strings

Allow non-ASCII characters in strings (as opposed to their escaped form, e.g. \u00DA).

allow_binary_integers

Allow integers with value_flags::format_as_binary to be emitted as binary.

allow_octal_integers

Allow integers with value_flags::format_as_octal to be emitted as octal.

allow_hexadecimal_integers

Allow integers with value_flags::format_as_hexadecimal to be emitted as hexadecimal.

indent_sub_tables

Apply indentation to tables nested within other tables/arrays.

indent_array_elements

Apply indentation to array elements when the array is forced to wrap over multiple lines.

indentation

Combination mask of all indentation-enabling flags.

relaxed_float_precision

Emit floating-point values with relaxed (human-friendly) precision.

terse_key_value_pairs

Avoids the use of whitespace around key-value pairs.

enum class toml::node_type: uint8_t

TOML node type identifiers.

Enumerators
none

Not-a-node.

table

The node is a toml::table.

array

The node is a toml::array.

string

The node is a toml::value<std::string>.

integer

The node is a toml::value<int64_t>.

floating_point

The node is a toml::value<double>.

boolean

The node is a toml::value<bool>.

date

The node is a toml::value<date>.

time

The node is a toml::value<time>.

date_time

The node is a toml::value<date_time>.

enum class toml::value_flags: uint16_t

Metadata associated with TOML values.

Enumerators
none

None.

format_as_binary

Format integer values as binary.

format_as_octal

Format integer values as octal.

format_as_hexadecimal

Format integer values as hexadecimal.

Typedef documentation

using toml::default_formatter = toml_formatter

The 'default' formatter used by TOML objects when they are printed to a stream.

This is an alias for toml::toml_formatter.

template <typename T>
using toml::inserted_type_of = /* ... */

Metafunction for determining which node type would be constructed if an object of this type was inserted into a toml::table or toml::array.

static_assert(std::is_same_v<toml::inserted_type_of<const char*>, toml::value<std::string>);
static_assert(std::is_same_v<toml::inserted_type_of<int>,         toml::value<int64_t>);
static_assert(std::is_same_v<toml::inserted_type_of<float>,       toml::value<double>);
static_assert(std::is_same_v<toml::inserted_type_of<bool>,        toml::value<bool>);

template <typename T>
using toml::optional = std::optional<T>

The 'optional' type used throughout the library.

Function documentation

node_view<node> toml::at_path(node& root, std::string_view path) noexcept

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

Parameters
root The root node from which the path will be traversed.
path The "TOML path" to traverse.
auto config = toml::parse(R"(

[foo]
bar = [ 0, 1, 2, [ 3 ], { kek = 4 } ]

)"sv);

std::cout << toml::at_path(config, "foo.bar[2]") << "\n";
std::cout << toml::at_path(config, "foo.bar[3][0]") << "\n";
std::cout << toml::at_path(config, "foo.bar[4].kek") << "\n";
2
3
4

node_view<const node> toml::at_path(const node& root, std::string_view path) noexcept

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

node_view<node> toml::at_path(node& root, std::wstring_view path)

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

node_view<const node> toml::at_path(const node& root, std::wstring_view path)

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

node_view<node> toml::at_path(node& root, const toml::path& path) noexcept

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

Parameters
root The root node from which the path will be traversed.
path The "TOML path" to traverse.
auto config = toml::parse(R"(

[foo]
bar = [ 0, 1, 2, [ 3 ], { kek = 4 } ]

)"sv);

toml::path path1("foo.bar[2]");
toml::path path2("foo.bar[4].kek");
std::cout << toml::at_path(config, path1) << "\n";
std::cout << toml::at_path(config, path1.parent_path()) << "\n";
std::cout << toml::at_path(config, path2) << "\n";
std::cout << toml::at_path(config, path2.parent_path()) << "\n";
2
[ 0, 1, 2, [ 3 ], { kek = 4 } ]
4
{ kek  = 4 }

node_view<const node> toml::at_path(const node& root, const toml::path& path) noexcept

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

template <typename Char>
std::basic_ostream<Char>& toml::operator<<(std::basic_ostream<Char>& lhs, node_type rhs)

Pretty-prints the value of a node_type to a stream.

auto arr = toml::array{ 1, 2.0, "3", false };
for (size_t i = 0; i < arr.size() i++)
    std::cout << "Element ["sv << i << "] is: "sv << arr[i].type() << "\n";
Element [0] is: integer
Element [1] is: floating-point
Element [2] is: string
Element [3] is: boolean

parse_result toml::parse(std::string_view doc, std::string_view source_path = {})

Parses a TOML document from a string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse("a = 3"sv);
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::string_view doc, std::string&& source_path)

Parses a TOML document from a string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse("a = 3"sv, "foo.toml");
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::u8string_view doc, std::string_view source_path = {})

Parses a TOML document from a char8_t string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse(u8"a = 3"sv);
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::u8string_view doc, std::string&& source_path)

Parses a TOML document from a char8_t string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse(u8"a = 3"sv, "foo.toml");
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::string_view doc, std::wstring_view source_path)

Parses a TOML document from a string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse("a = 3"sv, L"foo.toml");
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::istream& doc, std::wstring_view source_path)

Parses a TOML document from a stream.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
std::stringstream ss;
ss << "a = 3"sv;

auto tbl = toml::parse(ss);
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::u8string_view doc, std::wstring_view source_path)

Parses a TOML document from a char8_t string view.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
auto tbl = toml::parse(u8"a = 3"sv, L"foo.toml");
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::istream& doc, std::string_view source_path = {})

Parses a TOML document from a stream.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
std::stringstream ss;
ss << "a = 3"sv;

auto tbl = toml::parse(ss);
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse(std::istream& doc, std::string&& source_path)

Parses a TOML document from a stream.

Parameters
doc The TOML document to parse. Must be valid UTF-8.
source_path The path used to initialize each node's source().path. If you don't have a path (or you have no intention of using paths in diagnostics) then this parameter can safely be left blank.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
std::stringstream ss;
ss << "a = 3"sv;

auto tbl = toml::parse(ss, "foo.toml");
std::cout << tbl["a"] << "\n";
3

parse_result toml::parse_file(std::string_view file_path)

Parses a TOML document from a file.

Parameters
file_path The TOML document to parse. Must be valid UTF-8.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
toml::parse_result get_foo_toml()
{
    return toml::parse_file("foo.toml");
}

parse_result toml::parse_file(std::u8string_view file_path)

Parses a TOML document from a file.

Parameters
file_path The TOML document to parse. Must be valid UTF-8.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
toml::parse_result get_foo_toml()
{
    return toml::parse_file(u8"foo.toml");
}

parse_result toml::parse_file(std::wstring_view file_path)

Parses a TOML document from a file.

Parameters
file_path The TOML document to parse. Must be valid UTF-8.
Returns With exceptions: A toml::table. Without exceptions: A toml::parse_result.
toml::parse_result get_foo_toml()
{
    return toml::parse_file(L"foo.toml");
}