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 Char = char>
class default_formatter
A wrapper for printing TOML objects out to a stream as formatted TOML.
template <typename T>
struct inserter
Helper class for suppressing move-construction in single-argument array constructors.
template <typename Char = char>
class json_formatter
A wrapper for printing TOML objects out to a stream as formatted JSON.
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.
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.
template <typename ValueType>
class value
A TOML value.

Enums

enum class format_flags: uint8_t { none, quote_dates_and_times = 1, allow_literal_strings = 2, allow_multi_line_strings = 4, allow_value_format_flags = 8 }
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 value_flags: uint8_t { none, format_as_binary = 1, format_as_octal = 2, format_as_hexadecimal = 3 }
Metadata associated with TOML values.

Typedefs

using array_iterator = impl::array_iterator<false>
A RandomAccessIterator for iterating over elements in a toml::array.
using const_array_iterator = impl::array_iterator<true>
A RandomAccessIterator for iterating over const elements in a toml::array.
using const_table_iterator = impl::table_iterator<true>
A BidirectionalIterator for iterating over const key-value pairs in a toml::table.
template <typename T>
using optional = std::optional<T>
The 'optional' type used throughout the library.
using source_index = uint16_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 = impl::table_iterator<false>
A BidirectionalIterator for iterating over key-value pairs in a toml::table.

Functions

auto operator""_toml(const char* str, size_t len) -> parse_result
Parses TOML data 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.
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const date& rhs) -> std::basic_ostream<Char>&
Prints a date out to a stream as YYYY-MM-DD (per RFC 3339).
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const time& rhs) -> std::basic_ostream<Char>&
Prints a time out to a stream as HH:MM:SS.FFFFFF (per RFC 3339).
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const time_offset& rhs) -> std::basic_ostream<Char>&
Prints a time_offset out to a stream as +-HH:MM or Z (per RFC 3339).
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const date_time& rhs) -> std::basic_ostream<Char>&
Prints a date_time out to a stream in RFC 3339 format.
template <typename T, typename U>
auto operator<<(std::basic_ostream<T>& lhs, default_formatter<U>& rhs) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as formatted TOML.
template <typename T, typename U>
auto operator<<(std::basic_ostream<T>& lhs, default_formatter<U>&& rhs) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as formatted TOML (rvalue overload).
template <typename T, typename U>
auto operator<<(std::basic_ostream<T>& lhs, json_formatter<U>& rhs) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as JSON.
template <typename T, typename U>
auto operator<<(std::basic_ostream<T>& lhs, json_formatter<U>&& rhs) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as JSON (rvalue overload).
template <typename Char, typename T>
auto operator<<(std::basic_ostream<Char>& os, const node_view<T>& nv) -> std::basic_ostream<Char>&
Prints the viewed node out to a stream.
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const parse_error& rhs) -> std::basic_ostream<Char>&
Prints a parse_error to a stream.
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const source_position& rhs) -> std::basic_ostream<Char>&
Prints a source_position to a stream.
template <typename Char>
auto operator<<(std::basic_ostream<Char>& lhs, const source_region& rhs) -> std::basic_ostream<Char>&
Prints a source_region 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::string_view doc, std::wstring_view source_path) -> parse_result
Parses a TOML document from a string view.
template <typename Char>
auto parse(std::basic_istream<Char>& doc, std::string_view source_path = {}) -> parse_result
Parses a TOML document from a stream.
template <typename Char>
auto parse(std::basic_istream<Char>& doc, std::string&& source_path) -> parse_result
Parses a TOML document from a stream.
template <typename Char>
auto parse(std::basic_istream<Char>& doc, std::wstring_view 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::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 a toml::array.
template <typename T>
bool is_boolean constexpr
Metafunction for determining if a type is a bool toml::value<bool>.
template <typename T>
bool is_date constexpr
Metafunction for determining if a type is a toml::date or toml::value<date>.
template <typename T>
bool is_date_time constexpr
Metafunction for determining if a type is a toml::date_time or toml::value<date_time>.
template <typename T>
bool is_floating_point constexpr
Metafunction for determining if a type is a double or toml::value<double>.
template <typename T>
bool is_integer constexpr
Metafunction for determining if a type is an int64_t or toml::value<int64_t>.
template <typename T>
bool is_node_view constexpr
Metafunction for determining if a type is a toml::node_view.
template <typename T>
bool is_number constexpr
Metafunction for determining if a type satisfies toml::is_integer || toml::is_floating_point.
template <typename T>
bool is_string constexpr
Metafunction for determining if a type is a std::string or toml::value<std::string>.
template <typename T>
bool is_table constexpr
Metafunction for determining if a type is a toml::table.
template <typename T>
bool is_time constexpr
Metafunction for determining if a type is a toml::time or toml::value<time>.

Enum documentation

enum class toml::format_flags: uint8_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.
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_value_format_flags

Values with special format flags will be formatted accordingly.

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: uint8_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

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

The 'optional' type used throughout the library.

using toml::source_index = uint16_t

The integer type used to tally line numbers and columns.

Function documentation

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

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

Prints a date out to a stream as YYYY-MM-DD (per RFC 3339).

std::cout << toml::date{ 1987, 3, 16 } << "\n";
1987-03-16

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

Prints a time out to a stream as HH:MM:SS.FFFFFF (per RFC 3339).

std::cout << toml::time{ 10, 20, 34 } << "\n";
std::cout << toml::time{ 10, 20, 34, 500000000 } << "\n";
10:20:34
10:20:34.5

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

Prints a time_offset out to a stream as +-HH:MM or Z (per RFC 3339).

std::cout << toml::time_offset{ 2, 30 } << "\n";
std::cout << toml::time_offset{ 2, -30 } << "\n";
std::cout << toml::time_offset{} << "\n";
std::cout << toml::time_offset{ -2, 30 } << "\n";
std::cout << toml::time_offset{ -2, -30 } << "\n";
+02:30
+01:30
Z
-01:30
-02:30

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

Prints a date_time out to a stream in RFC 3339 format.

std::cout << toml::date_time{ { 1987, 3, 16 }, { 10, 20, 34 } } << "\n";
std::cout << toml::date_time{ { 1987, 3, 16 }, { 10, 20, 34 }, { -2, -30 } } << "\n";
std::cout << toml::date_time{ { 1987, 3, 16 }, { 10, 20, 34 }, {} } << "\n";
1987-03-16T10:20:34
1987-03-16T10:20:34-02:30
1987-03-16T10:20:34Z

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

Prints a parse_error to a stream.

Template parameters
Char The output stream's underlying character type. Must be 1 byte in size.
Parameters
lhs The stream.
rhs The parse_error.
Returns The input stream. 
try
{
    auto tbl = toml::parse("enabled = trUe"sv);
}
catch (const toml::parse_error & err)
{
    std::cerr << "Parsing failed:\n"sv << err << "\n";
}
Parsing failed:
Encountered unexpected character while parsing boolean; expected 'true', saw 'trU'
    (error occurred at line 1, column 13)

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

Prints a source_position to a stream.

Template parameters
Char The output stream's underlying character type. Must be 1 byte in size.
Parameters
lhs The stream.
rhs The source_position.
Returns The input stream. 
auto tbl = toml::parse("bar = 42"sv);

std::cout << "The value for 'bar' was found on "sv
    << tbl.get("bar")->source().begin()
    << "\n";
The value for 'bar' was found on line 1, column 7

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

Prints a source_region to a stream.

Template parameters
Char The output stream's underlying character type. Must be 1 byte in size.
Parameters
lhs The stream.
rhs The source_position.
Returns The input stream. 
auto tbl = toml::parse("bar = 42", "config.toml");

std::cout << "The value for 'bar' was found on "sv
    << tbl.get("bar")->source()
    << "\n";
The value for 'bar' was found on line 1, column 7 of 'config.toml'

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

template <typename Char>
parse_result toml::parse(std::basic_istream<Char>& doc, std::string_view source_path = {})

Parses a TOML document from a stream.

Template parameters
Char The stream's underlying character type. Must be 1 byte in size.
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

template <typename Char>
parse_result toml::parse(std::basic_istream<Char>& doc, std::string&& source_path)

Parses a TOML document from a stream.

Template parameters
Char The stream's underlying character type. Must be 1 byte in size.
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

template <typename Char>
parse_result toml::parse(std::basic_istream<Char>& doc, std::wstring_view source_path)

Parses a TOML document from a stream.

Template parameters
Char The stream's underlying character type. Must be 1 byte in size.
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_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::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");
}