toml11

toml::ordered_map is a map type that preserves the insertion order of values, allowing you to iterate over elements in the order they were defined in the TOML file.

Key Characteristics:

• Order Preservation: It maintains the order of keys within the same table. However, order is not maintained across different tables.
• Performance: As a linear container, search operations require O(n) time relative to the number of elements.

When to use: Use ordered_map when maintaining the original order of values is important and search operations are infrequent.

In toml11 v4, the toml::basic_value template signature has changed to allow for more flexible type customization. Instead of taking separate template arguments for comments, tables, and arrays, it now accepts a single TypeConfig template parameter.

v3 Signature (Deprecated):

template<typename Comment,
         template<typename ...> class Table = std::unordered_map,
         template<typename ...> class Array = std::vector>
class basic_value;

v4 Signature:

template<typename TypeConfig>
class basic_value;

By default, toml::value uses the standard types. If you need to customize types (like integer_type), refer to the type_config documentation.

In TOML, a string like [1] is interpreted as a table definition where 1 is the key. If you intend for a numeric-looking string to be parsed as an array instead of a table, you must use a trailing comma (e.g., [1,]).

#include <toml.hpp>

int main()
{
    using namespace toml::literals::toml_literals;

    const auto t = "[1]"_toml;  // Interpreted as a table: {1 = {}}
    const auto a = "[1,]"_toml; // Interpreted as an array: [1]

    assert(t.is_table());
    assert(t.at("1").is_table());

    assert(a.is_array());
    assert(a.at(0).as_integer() == 1);

    return 0;
}

The toml::result<T, E> type is a container that holds either a success value of type T or a failure value of type E. It is primarily used as the return type for functions like toml::try_parse to provide error handling without relying on exceptions for control flow.

Key characteristics:

• It can be checked for success using .is_ok() or by using it in a boolean context (operator bool()).
• It can be checked for failure using .is_err().
• It provides methods to safely or unsafely access the underlying values.

You can change the underlying STL containers used by toml::value (like table_type or array_type) by providing a custom type_config. For example, to preserve the insertion order of keys, use toml::ordered_type_config to change the table type to an ordered_map.

Note: If you parse into a standard toml::value (which uses std::unordered_map), the order will be lost. To maintain order, you must parse directly into a toml::ordered_value.

The toml::preserve_comments class is a container used to store and preserve comments when working with TOML data. It behaves similarly to a std::vector<std::string> and provides all its member functions (e.g., push_back, insert, size, begin, end).

Key behaviors:

• Comments are stored as std::string.
• Automatic # prefixing: If a stored string does not start with #, the library will automatically prepend # during output. However, this prefix is not added when the string is first added to the container.
• Spacing: The library does not automatically add spaces after the #. To ensure a space exists after the comment symbol (e.g., # comment), you must either include the space in the string you provide or include the # symbol itself in the string.

Searching a Table

Use toml::find(value, key) where key is a toml::value::key_type. This treats the value as a toml::table.

Searching an Array

Use toml::find(value, index) where index is a std::size_t. This treats the value as a toml::array.

Recursive Path Search

Pass a sequence of keys to traverse deep structures: toml::find(value, key1, key2, index, key3) This will look for key1 in the root, key2 in that sub-table, the element at index in that sub-array, and finally key3 in the resulting sub-table.

The toml::result<T, E> type is a container that holds either a success value of type T or a failure value of type E. It is primarily used as the return type for non-throwing functions like toml::try_parse.

Key behaviors:

• It cannot be default-constructed; it must be initialized with either a success<T> or a failure<E>.
• You can check its state using is_ok(), is_err(), or by using it in a boolean context via explicit operator bool().
• Accessing a value when the result is in the wrong state (e.g., calling unwrap() on a failure) throws a toml::bad_result_access exception.

The toml11 library provides two ways to enable conversion from your custom types to TOML values:

1. Member Function: If you have control over the class definition, add an into_toml member function directly to the class. This is the most direct approach.
2. into<T> Specialization: If you are working with a class from an external library or a type where you cannot modify the source code, specialize the toml::into<T> struct as described in the into.hpp documentation.

toml::source_location is a class that represents a specific area within a TOML file. It is primarily used to pinpoint problematic areas when handling errors or parsing issues.

Important Construction Rule: You cannot manually construct a source_location with arbitrary values. It can only be obtained via toml::parse or the _toml literal. If you attempt to access a location() from a toml::value that was created outside of these methods, is_ok() will return false.