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 T>
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 T>
class value
A TOML value.

Enums

enum class format_flags: uint8_t { none, quote_dates_and_times = 1 }
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.

Typedefs

using array_iterator = impl::array_iterator<false>
A RandomAccessIterator for iterating over nodes in a toml::array.
using const_array_iterator = impl::array_iterator<true>
A RandomAccessIterator for iterating over const nodes 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.
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 string = std::string
The string type for keys and string values.
using string_char = char
The base character type for keys and string values.
using string_view = std::string_view
The string type for keys and string values.
using table_iterator = impl::table_iterator<false>
A BidirectionalIterator for iterating over key-value pairs in a toml::table.

Functions

auto operator!=(const array& lhs, const array& rhs) -> bool noexcept
auto operator!=(const table& lhs, const table& rhs) -> bool noexcept
auto operator""_toml(const char* str, size_t len) -> parse_result
Parses TOML data from a string.
auto operator""_toml(const char8_t* str, size_t len) -> parse_result
Parses TOML data from a string.
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 date_time& rhs) -> std::basic_ostream<Char>&
Prints a date_time out to a stream in RFC 3339 format.
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.
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, typename T>
auto operator<<(std::basic_ostream<Char>&, const value<T>&) -> std::basic_ostream<Char>&
Prints the value out to a stream.
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, typename T>
auto operator<<(std::basic_ostream<Char>&, const node_view<T>&) -> std::basic_ostream<Char>&
Prints the viewed node out to a stream.
template<typename T, typename U>
auto operator<<(std::basic_ostream<T>&, default_formatter<U>&&) -> 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>&, default_formatter<U>&) -> 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>&, json_formatter<U>&&) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as JSON (rvalue overload).
template<typename T, typename U>
auto operator<<(std::basic_ostream<T>&, json_formatter<U>&) -> std::basic_ostream<T>&
Prints the bound TOML object out to the stream as JSON.
auto operator==(const array& lhs, const array& rhs) -> bool noexcept
auto operator==(const table& lhs, const table& rhs) -> bool noexcept
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::string_view source_path = {}) -> parse_result
Parses a TOML document from a stream.
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::string_view source_path = {}) -> parse_result
Parses a TOML document from a 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::u8string_view doc, std::string_view source_path = {}) -> parse_result
Parses a TOML document from a char8_t string view.
template<typename Char, typename StreamChar = char>
auto parse_file(std::basic_string_view<Char> 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_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 toml::string or toml::value<toml::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::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<toml::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>.

Typedef documentation

using toml::source_index = uint16_t

The integer type used to tally line numbers and columns.

using toml::string = std::string

The string type for keys and string values.

using toml::string_char = char

The base character type for keys and string values.

using toml::string_view = std::string_view

The string type for keys and string values.

Function documentation

bool toml::operator!=(const array& lhs, const array& rhs) noexcept

Parameters
lhs The LHS array.
rhs The RHS array.
Returns True if the arrays did not contain the same values.

bool toml::operator!=(const table& lhs, const table& rhs) noexcept

Parameters
lhs The LHS table.
rhs The RHS table.
Returns True if the tables did not contain the same keys and values.

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 } << std::endl;
1987-03-16

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 } } << std::endl;
std::cout << toml::date_time{ { 1987, 3, 16 }, { 10, 20, 34 }, { -2, -30 } } << std::endl;
std::cout << toml::date_time{ { 1987, 3, 16 }, { 10, 20, 34 }, {} } << std::endl;
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 << std::endl;
}
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()
    << std::endl;
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()
    << std::endl;
The value for 'bar' was found on line 1, column 7 of 'config.toml'

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 } << std::endl;
std::cout << toml::time{ 10, 20, 34, 500000000 } << std::endl;
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 } << std::endl;
std::cout << toml::time_offset{ 2, -30 } << std::endl;
std::cout << toml::time_offset{} << std::endl;
std::cout << toml::time_offset{ -2, 30 } << std::endl;
std::cout << toml::time_offset{ -2, -30 } << std::endl;
+02:30
+01:30
Z
-01:30
-02:30

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() << std::endl;
Element [0] is: integer
Element [1] is: floating-point
Element [2] is: string
Element [3] is: boolean

bool toml::operator==(const array& lhs, const array& rhs) noexcept

Parameters
lhs The LHS array.
rhs The RHS array.
Returns True if the arrays contained the same values.

bool toml::operator==(const table& lhs, const table& rhs) noexcept

Parameters
lhs The LHS table.
rhs The RHS table.
Returns True if the tables contained the same keys and values.

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.
Returns With exceptions: A toml::table.
Without exceptions: A toml::parse_result detailing the parsing outcome.
std::stringstream ss;
ss << "a = 3"sv;

auto tbl = toml::parse(ss, "foo.toml");
std::cout << tbl["a"] << std::endl;
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 detailing the parsing outcome.
std::stringstream ss;
ss << "a = 3"sv;

auto tbl = toml::parse(ss);
std::cout << tbl["a"] << std::endl;
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.
Returns With exceptions: A toml::table.
Without exceptions: A toml::parse_result detailing the parsing outcome.
auto tbl = toml::parse("a = 3"sv, "foo.toml");
std::cout << tbl["a"] << std::endl;
3

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 detailing the parsing outcome.
auto tbl = toml::parse("a = 3"sv);
std::cout << tbl["a"] << std::endl;
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.
Returns With exceptions: A toml::table.
Without exceptions: A toml::parse_result detailing the parsing outcome.
auto tbl = toml::parse(u8"a = 3"sv, "foo.toml");
std::cout << tbl["a"] << std::endl;
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 detailing the parsing outcome.
auto tbl = toml::parse(u8"a = 3"sv);
std::cout << tbl["a"] << std::endl;
3

template<typename Char, typename StreamChar = char>
parse_result toml::parse_file(std::basic_string_view<Char> file_path)

Parses a TOML document from a file.

Template parameters
Char The path's character type. Must be 1 byte in size.
StreamChar
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 detailing the parsing outcome.
#include <fstream>

toml::parse_result get_foo_toml()
{
    return toml::parse_file("foo.toml");
}