doc: add reference manual

docs/content.en/docs/changelog/_index.md

@@ -0,0 +1,293 @@
++++
+title = "changelog"
+type  = "docs"
+weight = 4
++++
+
+# Change Log
+
+# Changes from v3
+
+## Breaking Changes
+
+### Changed `template` Parameters of `toml::basic_value`
+
+In toml11 v3, `toml::basic_value` took separate template arguments for the comment container, table-type container, and array-type container.
+
+```cpp
+template<typename Comment,
+         template<typename ...> class Table = std::unordered_map,
+         template<typename ...> class Array = std::vector>
+class basic_value;
+```
+
+However, this approach does not accommodate changes to types such as `integer_type`.
+
+In toml11 v4, `toml::basic_value` now accepts a single `TypeConfig`, allowing for more types to be customized.
+
+```cpp
+template<typename TypeConfig>
+class basic_value;
+```
+
+By default, the types stored in `toml::value` remain unchanged.
+
+For more information on changing types, please refer to the
+[`type_config`]({{< ref "/docs/reference/types.md">}}) documentation.
+
+### Removed `std::initializer_list` Support for `toml::basic_value`
+
+In toml11 v3, there was an overload for `toml::value` that accepted `std::initializer_list`. This allowed for more intuitive initialization of `toml::value` with arrays and tables.
+
+```cpp
+// toml11 v3
+toml::value v{1,2,3,4,5};
+toml::value v{ {"a", 42}, {"b", "foo"} };
+```
+
+However, this caused the following issues:
+
+First, it was impossible to distinguish between a single-element array and a regular value, as it always became an array.
+
+```cpp
+// toml11 v3
+toml::value v{1}; // Becomes [1,] instead of 1
+```
+
+With the widespread use of uniform initialization, this became very inconvenient.
+
+Second, it was unclear whether the value represented a table with all string values or a nested array.
+
+```cpp
+// toml11 v3
+toml::value v{ {"a", "foo"}, {"b", "bar"} };
+// Could be either:
+// {a = "foo", b = "bar"}
+// [["a", "foo"], ["b", "bar"]]
+```
+
+These issues were difficult to resolve due to language specifications.
+
+To avoid confusion, toml11 v4 has removed `std::initializer_list` support.
+
+When initializing `toml::value` with an array, you must explicitly specify `toml::array`, and when initializing with a table, you must explicitly specify `toml::table`.
+
+```cpp
+// toml11 v4
+toml::value v(toml::array{1,2,3,4,5});
+toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
+
+toml::value v{toml::array{1}}; // [1,]
+toml::value v{1}               // 1
+
+toml::value v{toml::table{{"a", "foo"}, {"b", "bar"}}};
+toml::value v{toml::array{toml::array{"a", "foo"}, toml::array{"b", "bar"}}};
+```
+
+While this makes initializing `toml::value` with tables or arrays slightly less convenient, it ensures that the values will not become unpredictable by requiring explicit type information.
+
+### Renamed `toml::basic_value::is_uninitialized()` to `is_empty()`
+
+In toml11 v3, the function to check whether a `basic_value` was uninitialized was called `is_uninitialized`.
+
+However, in toml11 v4, the library supports `null` values as an extension, allowing for the intentional construction of empty values.
+Therefore, the function has been renamed to `is_empty` to reflect this change.
+
+### Added Format Information and Removed `toml::string`
+
+In toml11 v3, to retain information on whether a string was `basic` or `literal`, the library used a thin wrapper around `std::string` called `toml::string`.
+
+```cpp
+// toml11 v3
+namespace toml
+{
+enum class string_t : std::uint8_t
+{
+    basic   = 0,
+    literal = 1,
+};
+
+struct string
+{
+    string_t    kind;
+    std::string str;
+};
+} // namespace toml
+```
+
+In toml11 v4, to accommodate more format information such as the numeric base or whether arrays should be multiline, every type now has an associated `xxx_format` type, which is stored alongside the value.
+
+```cpp
+// toml11 v4
+enum class string_format : std::uint8_t
+{
+    basic             = 0,
+    literal           = 1,
+    multiline_basic   = 2,
+    multiline_literal = 3
+};
+
+struct string_format_info
+{
+    string_format fmt = string_format::basic;
+    bool start_with_newline    = false;
+};
+```
+
+This change allows for more detailed format information to be preserved, ensuring that format specifics for numeric types, arrays, and tables are maintained even after parsing.
+
+### Changed Arguments of `toml::format`
+
+In toml11 v3, `toml::format` accepted values such as the precision and width of numeric types.
+
+However, this approach did not allow for detailed formatting specifications, resulting in serialized files that did not match expectations.
+
+In toml11 v4, each `toml::value` now carries its own format information, enabling more detailed formatting options to be preserved within the `toml::value` itself.
+
+As a result, `toml::format` no longer accepts specific formatting values. Instead, it now only takes a `toml::spec`, which includes language feature flags used during formatting.
+
+### Changed Member Functions of `toml::source_location`
+
+In toml11 v3, the member types of `toml::source_location` were designed to handle only single lines.
+
+In toml11 v4, the member types of `toml::source_location` are designed to handle multiple lines.
+
+### Renamed `toml::format_underline` to `toml::format_location`
+
+In toml11 v3, the function used to format location information from `toml::source_location` was called `toml::format_underline`.
+
+To make the name clearer, it has been renamed to `toml::format_location`.
+
+## Changed Arguments of `toml::format_error`
+
+In toml11 v3, there was no class to represent error information, resulting in complex arguments for `toml::format_error`.
+
+```cpp
+template<typename C, template<typename ...> class T, template<typename ...> class A>
+std::string format_error(const std::string& err_msg,
+        const basic_value<C, T, A>& v, const std::string& comment,
+        std::vector<std::string> hints = {},
+        const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
+
+template<typename C, template<typename ...> class T, template<typename ...> class A>
+inline std::string format_error(const std::string& err_msg,
+        const toml::basic_value<C, T, A>& v1, const std::string& comment1,
+        const toml::basic_value<C, T, A>& v2, const std::string& comment2,
+        std::vector<std::string> hints = {},
+        const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
+
+template<typename C, template<typename ...> class T, template<typename ...> class A>
+inline std::string format_error(const std::string& err_msg,
+        const toml::basic_value<C, T, A>& v1, const std::string& comment1,
+        const toml::basic_value<C, T, A>& v2, const std::string& comment2,
+        const toml::basic_value<C, T, A>& v3, const std::string& comment3,
+        std::vector<std::string> hints = {},
+        const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
+```
+
+In toml11 v4, we have introduced `class error_info` and `make_error_info`, simplifying the arguments for `format_error`.
+
+```cpp
+std::string format_error(const error_info& err);
+std::string format_error(const std::string& errkind, const error_info& err);
+
+template<typename ... Ts>
+std::string format_error(std::string title,
+        source_location loc, std::string msg, Ts&& ... tail);
+
+template<typename TC, typename ... Ts>
+std::string format_error(std::string title,
+        const basic_value<TC>& v, std::string msg, Ts&& ... tail);
+```
+
+### Changed Control of `toml::color`
+
+In toml11 v3, to control whether to colorize the output, we used the manipulator `toml::colorize` in conjunction with `toml::color::enable/disable`.
+
+The manipulator allowed us to decide whether to apply color to each stream,
+but in v4, the frequency of using streams has decreased,
+and issues such as the fact that `std::ios_base::xalloc` used internally is not thread-safe in C++11 have arisen.
+Therefore, we have decided to use only `toml::color::enable/disable` and have removed `toml::colorize`.
+
+## Non-Breaking Changes
+
+### Added `parse_str`
+
+In toml11 v3, there was no function to directly parse a string itself.
+Therefore, when parsing a string, it was necessary to use `std::istringstream`.
+
+To address this inconvenience, we have added `toml::parse_str`, allowing for direct parsing of strings.
+
+### Added `try_parse`
+
+In toml11 v3, when a parser encountered an error, it threw `toml::syntax_error`.
+
+However, there are cases where you do not want to throw exceptions due to environments where exceptions cannot be thrown, or for reasons of performance.
+
+In toml11 v4, we have implemented `toml::try_parse` using `toml::result`, which communicates parsing failures without throwing exceptions.
+
+This doesn't mean exceptions are never thrown. Errors in the standard library being used, such as `std::bad_alloc` due to allocation failure from memory exhaustion, may still be thrown.
+
+### Support for Parsing Byte Sequences
+
+To allow for parsing TOML content obtained through means other than files, we have added `toml::parse` and `toml::try_parse` functions that accept `std::vector<unsigned char>`.
+
+### Added `toml::spec`
+
+In toml11 v3, all new features of the TOML language were incorporated, and features that were decided to be introduced in future versions of the TOML language were controlled by the macro `TOML11_USE_UNRELEASED_TOML_FEATURES`.
+
+This was because, at the time of developing toml11 v3, the TOML language had not yet reached version 1.0.0, being at versions 0.4.0 to 0.5.0.
+
+As not all users are familiar with the latest TOML language specification, displaying error messages based on an older language usage could confuse the entire community. Therefore, until reaching version 1.0.0, it was necessary to provide new language specifications as quickly as possible and encourage users to update.
+
+However, the current TOML language specification is at version 1.0.0. Therefore, there was a need to be mindful of the choice to continue using version 1.0.0 even after TOML v1.1.0 was released.
+
+To allow for more flexibility in selecting the TOML language specification, we introduced `toml::spec`, enabling the TOML language version to be changed at runtime.
+
+Additionally, in `toml::spec`, flags are set for each language feature, allowing for the testing of specific language features only.
+
+This mechanism is also used for TOML-specific language extensions in toml11 v4.
+
+### Added Format Information
+
+In toml11 v3, format information was not saved except for strings, and during serialization, only width and precision were considered.
+
+However, this resulted in hexadecimal integers being serialized as decimal integers and no reliable way to ensure inline tables.
+
+In toml11 v4, format information (`integer_format`, etc.) has been added to all TOML types, and it is now considered during parsing and serialization.
+
+This allows for more detailed format information to be set for values, such as hexadecimal integers or inline tables.
+
+### Changed to `preserve_comments` by Default
+
+In toml11 v3, comments were not parsed by default and were also not serialized.
+
+This was because comments were a later introduced feature and were being read through a special hack.
+
+In toml11 v4, comments are parsed, preserved, and serialized by default.
+
+Furthermore, the parser implementation has been significantly changed to ensure comments are parsed alongside other elements.
+
+### Changed to Preserve Comments by Default
+
+In toml11 v3, comments were neither parsed nor serialized by default. This was because comment support was a late addition, implemented through a special hack.
+
+In toml11 v4, comments are now parsed, preserved, and serialized by default. The parser implementation has also been significantly revised so that comments are parsed just like any other element.
+
+### Added `single_include/toml.hpp`
+
+toml11 is a versatile library with different header files for various features to enhance development efficiency. However, this required a certain amount of effort to install.
+
+Starting with toml11 v4, a `single_include/toml.hpp` file has been added, which combines all the header files in the correct order. This allows the library to be installed by simply copying a single file.
+
+### Option to Use Precompiled Library
+
+Due to the extensive use of templates in toml11, compile times have been long.
+
+In toml11 v4, the number of precompilable functions has been increased, allowing them to be compiled ahead of time into a library. This is expected to reduce compile times when using the library in large-scale development projects.
+
+### Reference Documentation
+
+Previously, all features were documented in the README, with no detailed function definitions or reference materials available in Japanese.
+
+In toml11 v4, reference documentation has been included, provided in both Japanese and English. However, since the library author is a native Japanese speaker, the Japanese content is considered primary. If there are discrepancies between the Japanese and English content, the Japanese version takes precedence.

docs/content.en/docs/features/_index.md

@@ -0,0 +1,100 @@
++++
+title = "features"
+type  = "docs"
+weight = 2
+bookCollapseSection = true
++++
+
+# Features
+
+This section explains the main features provided by toml11, with examples.
+
+## [Parsing Files and Strings](parsing_files)
+
+Describes the functions for parsing files and strings, and how to handle the errors they produce.
+
+Includes:
+
+- Parsing files
+- Parsing strings
+- Parsing byte arrays
+- Parsing files without throwing exceptions
+- Parsing strings without throwing exceptions
+- Parsing byte arrays without throwing exceptions
+
+## [Extracting Values from `toml::value`](value)
+
+Explains how to examine, extract, and convert the data types held by `toml::value`.
+
+Includes:
+
+- Checking the type of a value using member functions
+- Accessing values using member functions
+- Accessing comments
+- Handling inline tables and dotted keys
+- Handling date information
+- Using `toml::get<T>` for conversion
+- Using `toml::get_or` to specify a fallback value
+- Using `toml::find<T>` for searching and conversion
+- Using `toml::find_or` to specify a fallback value
+- Defining conversions with user-defined types
+- Applying functions with `toml::visit`
+- Constructing `toml::value`
+
+## [Creating Error Messages](error_message)
+
+Explains how to generate error messages with location information from a TOML file using `toml::value`.
+
+Includes:
+
+- Extracting location information from `toml::value`
+- Constructing error messages
+- Adding color to the output
+
+## [Serializing TOML Files](serialize)
+
+Describes how to format the values of `toml::value` and the available formatting options.
+
+Includes:
+
+- Specifying formats for each value of `toml::value`
+- Formatting `toml::value` into a string
+
+## [Configuring Types of `toml::value`](configure_types)
+
+Explains how to customize the types stored in `toml::value` (such as `integer_type` and `table_type`).
+
+Includes:
+
+- Defining `type_config`
+- Using `ordered_type_config`
+- Disabling comment preservation
+- Using different containers like `std::deque`
+- Using different numeric types like `boost::multiprecision`
+
+## [TOML Literals](literal)
+
+Explains the `_toml` literal for embedding TOML files directly in C++ code.
+
+Includes:
+
+- Using TOML literals
+
+## [TOML Language Version](toml_spec)
+
+Describes the versions of the TOML language supported by toml11 and how to control language features added in TOML-v1.1.0.
+
+Includes:
+
+- Using TOML language version 1.1.0
+- Using specific features of TOML language version 1.1.0
+
+## [TOML Language Extensions](extension)
+
+Explains the custom extensions to the TOML language provided by toml11.
+
+Includes:
+
+- Supporting `null`
+- Supporting hexadecimal format for floating-point numbers
+- Allowing units for numbers

docs/content.en/docs/features/configure_types.md

@@ -0,0 +1,188 @@
++++
+title = "configuring types"
+type  = "docs"
+weight = 50
++++
+
+# Customizing Types
+
+The `toml::value` class uses `std::int64_t` for `integer_type` and `std::unordered_map<key_type, value_type>` for `table_type`.
+
+However, in some cases, you may want to use `boost::multiprecision::int128_t` or `std::map`.
+
+To accommodate this, `toml::value` is implemented with template parameters that allow you to change the stored types.
+
+Just as `std::string` is actually an alias for `std::basic_string<char, std::char_traits<char>, std::allocator<char>>`, `toml::value` is an alias for `toml::basic_value<toml::type_config>`.
+
+Here, we will explain the types contained in `toml::type_config` and how to define a different `config` type.
+
+## `type_config`
+
+The `type_config` class contains the following member types and `static` member functions:
+
+```cpp
+namespace toml
+{
+struct type_config
+{
+    using comment_type  = preserve_comments;
+
+    using boolean_type  = bool;
+    using integer_type  = std::int64_t;
+    using floating_type = double;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::vector<T>;
+    template<typename K, typename T>
+    using table_type = std::unordered_map<K, T>;
+
+    static result<integer_type, error_info>
+    parse_int(const std::string& str, const source_location src, const std::uint8_t base);
+
+    static result<floating_type, error_info>
+    parse_float(const std::string& str, const source_location src, const bool is_hex);
+};
+}
+```
+
+`toml::basic_value<TypeConfig>` defines the stored `boolean_type` as `TypeConfig::boolean_type`, the stored `integer_type` as `TypeConfig::integer_type`, and so on.
+
+Additionally, `array_type` is defined as `TypeConfig::array_type<toml::basic_value<TypeConfig>>` and `table_type` is defined as `TypeConfig::table_type<key_type, toml::basic_value<TypeConfig>>`.
+
+By passing a class that defines these member types and functions to `toml::basic_value`, you can customize the types used by that `toml::basic_value`.
+
+The `parse_int` and `parse_float` functions provide parsing methods when custom numeric types are used. These functions receive strings with prefixes like `0x` and digit separators like `_` removed, such as `123456` or `DEADBEEF`. The `base` parameter will be one of `10`, `16`, `8`, or `2`. Implement these functions to parse your custom `integer_type` and `floating_type`.
+
+As a default implementation, `toml::read_int` and `toml::read_float` are provided.
+
+```cpp
+static result<integer_type, error_info>
+parse_int(const std::string& str, const source_location src, const std::uint8_t base)
+{
+    return toml::read_int<integer_type>(str, src, base);
+}
+
+static result<floating_type, error_info>
+parse_float(const std::string& str, const source_location src, const bool is_hex)
+{
+    return toml::read_float<floating_type>(str, src, is_hex);
+}
+```
+
+The `read_int` function uses `istream` and employs `std::hex` and `std::oct` for hexadecimal and octal parsing, respectively. For binary parsing, it is implemented using multiplication and addition. If your type supports these operations, you can use `read_int` as-is.
+
+The `read_float` function also uses `istream`. Hexadecimal floating-point numbers are only supported for `double` and `float` types. If `read_float` is called with any other type and `hexfloat` is used, it will always return a parse error. Therefore, if you need to use a floating-point type other than `double` or `float` with `hexfloat`, you will need to implement support for that. If `hexfloat` is not used, no additional implementation is necessary.
+
+## Preserving Order of Values in Tables
+
+In addition to the default `toml::type_config`, there is also `toml::ordered_type_config`. This changes the `table_type` to an [ordered_map]({{< ref "docs/reference/ordered_map" >}}).
+
+Using this, `toml::ordered_value` is defined, along with aliases for its array and table types as `toml::ordered_array` and `toml::ordered_table`, respectively.
+
+You can use `toml::ordered_value` by calling `toml::parse(...)` as `toml::parse<toml::ordered_type_config>(...)`.
+
+## Not Preserving Comments
+
+The `type_config` defines a container for storing comments via `comment_type`.
+
+If comments do not contain significant information and can be discarded during parsing, specify `toml::discard_comments` for `comment_type`.
+
+```cpp
+struct wo_comment_config
+{
+    using comment_type  = toml::discard_comments; // XXX
+
+    using boolean_type  = bool;
+    using integer_type  = std::int64_t;
+    using floating_type = double;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::vector<T>;
+    template<typename K, typename T>
+    using table_type = std::unordered_map<K, T>;
+
+    static result<integer_type, error_info>
+    parse_int(const std::string& str, const source_location src, const std::uint8_t base)
+    {
+        return toml::read_int<integer_type>(str, src, base);
+    }
+
+    static result<floating_type, error_info>
+    parse_float(const std::string& str, const source_location src, const bool is_hex)
+    {
+        return toml::read_float<floating_type>(str, src, is_hex);
+    }
+};
+```
+
+## Using Containers Other Than `std::vector` for Arrays
+
+To use a container other than `vector` (e.g., `std::deque`) for implementing TOML arrays, modify `array_type` as follows.
+
+Similarly, to use a container other than `unordered_map` (e.g., `std::map`) for table types, modify `table_type` as shown below.
+
+```cpp
+struct deque_map_config
+{
+    using comment_type  = toml::preserve_comments;
+
+    using boolean_type  = bool;
+    using integer_type  = std::int64_t;
+    using floating_type = double;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::deque<T>; // XXX
+    template<typename K, typename T>
+    using table_type = std::map<K, T>; // XXX
+
+    static result<integer_type, error_info>
+    parse_int(const std::string& str, const source_location src, const std::uint8_t base)
+    {
+        return toml::read_int<integer_type>(str, src, base);
+    }
+
+    static result<floating_type, error_info>
+    parse_float(const std::string& str, const source_location src, const bool is_hex)
+    {
+        return toml::read_float<floating_type>(str, src, is_hex);
+    }
+};
+```
+
+## Using `boost::multiprecision` for Numeric Types
+
+By using `boost::multiprecision::cpp_int` and `boost::multiprecision::cpp_bin_float_oct`, you can utilize a wider integer type and a more precise floating-point type.
+
+These types implement stream operators, so you can use the default implementations of `read_int` and `read_float` without modification.
+
+```cpp
+struct large_num_config
+{
+    using comment_type  = toml::preserve_comments;
+
+    using boolean_type  = bool;
+    using integer_type  = boost::multiprecision::cpp_int;
+    using floating_type = boost::multiprecision::cpp_bin_float_oct;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::vector<T>;
+    template<typename K, typename T>
+    using table_type = std::unordered_map<K, T>;
+
+    static toml::result<integer_type, toml::error_info>
+    parse_int(const std::string& str, const toml::source_location src, const std::uint8_t base)
+    {
+        return toml::read_int<integer_type>(str, src, base);
+    }
+    static toml::result<floating_type, toml::error_info>
+    parse_float(const std::string& str, const toml::source_location src, const bool is_hex)
+    {
+        return toml::read_float<floating_type>(str, src, is_hex);
+    }
+};
+```
+

docs/content.en/docs/features/error_message.md

@@ -0,0 +1,212 @@
++++
+title = "error message"
+type  = "docs"
+weight = 30
++++
+
+# Outputting Error Messages
+
+`toml11` provides error messages that include location information within the file when using functions like `toml::parse`, `toml::get<T>/find<T>`, and `as_integer()`, among others.
+
+For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:
+
+```
+[error] bad integer: `_` must be surrounded by digits
+ --> internal string at line 64 in file main.cpp
+   |
+ 1 | a = 123__456
+   |        ^-- invalid underscore
+Hint: valid  : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
+Hint: invalid: _42, 1__000, 0123
+```
+
+Or, if a type different from the one actually stored is requested:
+
+```
+[error] toml::value::as_string(): bad_cast to string
+ --> input.toml
+   |
+ 1 | a = 123_456
+   |     ^^^^^^^-- the actual type is integer
+```
+
+`toml11` provides methods to create such error messages from `toml::value`.
+
+By utilizing this feature, you can inform users not only about TOML syntax errors but also about application-specific errors. For example, if a negative number appears where only positive values are allowed, you can highlight the location within the TOML file to convey the error to the user.
+
+## Creating Error Messages from `toml::value` Location Information
+
+`toml::value` retains information about the location where it was parsed.
+
+This information is encapsulated in `toml::source_location` and can be retrieved using `toml::value::location()`.
+
+```cpp
+const toml::value& a = input.at("a");
+const toml::source_location src = a.location();
+```
+
+When a file is parsed with `toml::parse`, the TOML filename and line numbers are stored.
+
+If parsed with `toml::parse_str`, the TOML filename is not available, but instead, the filename and line number of the C++ source code that called `toml::parse_str` are stored as the TOML filename. The first example on this page was output from `toml::parse_str`. Note the filename part.
+
+For details, see the [reference]({{<ref "/docs/reference/source_location">}}).
+
+You can build error information by passing a `toml::source_location` or `toml::value` and the associated error message to `toml::make_error_info`. Passing this to `toml::format_error` formats the error message into a `std::string`.
+
+```cpp
+const toml::value& a = input.at("a");
+if(a.as_integer() < 0)
+{
+    const toml::error_info err = toml::make_error_info(
+            "positive integer is required", // Error title
+            a, "but got negative value"     // Message next to the value
+        );
+    std::cerr << toml::format_error(err) << std::endl;
+}
+```
+
+This will output:
+
+```
+[error] positive integer is required
+ --> input.toml
+   |
+ 1 | a = -123456
+   |     ^^^^^^^-- but got negative value
+```
+
+You can also add a supplementary message at the end. This part is not indented.
+
+```cpp
+const toml::value& a = input.at("a");
+if(a.as_integer() < 0)
+{
+    const toml::error_info err = toml::make_error_info(
+            "positive integer is required",      // Error title
+            a, "but got negative value",         // Message next to the value
+            "Hint: `a` means length of the data" // Supplementary message
+        );
+    std::cerr << toml::format_error(err) << std::endl;
+}
+```
+
+This will output:
+
+```
+[error] positive integer is required
+ --> input.toml
+   |
+ 1 | a = -123456
+   |     ^^^^^^^-- but got negative value
+Hint: `a` means length of the data
+```
+
+{{<hint info>}}
+The ability to output lines from the file using `toml::value` is because the parsed file is retained in memory as a string.
+
+The parsed string is shared by `toml::value` via a `std::shared_ptr`. Copying it does not duplicate the entire file string. The file information is freed from memory when all `toml::value` instances constructed from parsing the file are destructed.
+
+Therefore, when using this in an application, it is recommended to extract and store the required values during loading rather than directly storing `toml::value`.
+{{</hint>}}
+
+## Adding Colors to Strings
+
+You can add color to error messages using ANSI escape codes.
+
+If `TOML11_COLORIZE_ERROR_MESSAGE` is defined at compile time, the error messages output by toml11 will be colored by default.
+
+If not, you can enable color for subsequent error messages by calling `toml::color::enable()`. Conversely, if you do not want colored output, for example, because the output is not to a console, call `toml::color::disable()`. You can check whether coloring is enabled at any point by calling `toml::color::should_color()`.
+
+Additionally, while the error title, error message, and supplementary information are not colored by default, you can use manipulators from toml::color to add color to them.
+
+```cpp
+std::ostringstream oss;
+oss << toml::color::red << "but got negative value";
+
+const toml::error_info err = toml::make_error_info(
+        "positive integer is required",      // Error title
+        a, oss.str(),                        // Message next to the value
+        "Hint: `a` means length of the data" // Supplementary message
+    );
+```
+
+For more details, see the [reference]({{<ref "docs/reference/color">}}).
+
+## Changing the Prefix of Error Messages from `[error]`
+
+There may be different types of errors, and the default `[error]` prefix might not always be appropriate.
+
+With `toml::format_error`, you can provide a `std::string` before `toml::error_info` to replace the `[error]` prefix.
+
+For example:
+
+```cpp
+const toml::value& a = input.at("a");
+if(a.as_integer() < 0)
+{
+    const toml::error_info err = toml::make_error_info(
+            "positive integer is required", // Error title
+            a, "but got negative value"     // Message next to the value
+        );
+
+    std::ostringstream prefix;
+    prefix << toml::color::bold << toml::color::yellow << "[warn]";
+    std::cerr << toml::format_error(prefix.str(), err) << std::endl;
+    return 0;
+}
+else
+{
+    return a.as_integer();
+}
+```
+
+This will output a warning starting with `[warn]`.
+
+Additionally, you can create error messages without the `[error]` prefix by directly passing the components of `error_info` to `toml::format_error`.
+
+```cpp
+const toml::value& a = input.at("a");
+if(a.as_integer() < 0)
+{
+    std::cerr << toml::format_error(
+            "[warn] positive integer is required", // Error title
+            a, "but got negative value"            // Message next to the value
+        ) << std::endl;
+    return 0;
+}
+else
+{
+    return a.as_integer()
+}
+```
+
+## Creating Error Messages Referencing Multiple `toml::value`
+
+In application settings, the range of permissible values might change based on previously read values.
+
+In such cases, you may want to output the values causing the error simultaneously.
+
+`toml::format_error` and `toml::make_error_info` can take multiple pairs of `toml::value` and their corresponding error messages as `std::string`.
+
+```cpp
+std::cerr << toml::format_error(
+        "[error] invalid range",
+        a, "minimum value is defined here",
+        b, "maximum value is defined here",
+        c, "and it exceeds the range"
+    ) << std::endl;
+```
+
+You can also add supplementary information at the end.
+
+```cpp
+std::cerr << toml::format_error(
+        "[error] invalid range",
+        a, "minimum value is defined here",
+        b, "maximum value is defined here",
+        c, "and it exceeds the range",
+        "Hint: all the values must be in the range [a, b)"
+    ) << std::endl;
+```
+
+When passing `toml::value` or `toml::source_location`, an error message related to it must follow. If not, it will result in a very confusing compilation error.

docs/content.en/docs/features/extension.md

@@ -0,0 +1,124 @@
++++
+title = "extension"
+type  = "docs"
+weight = 80
++++
+
+# TOML Language Extensions
+
+The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.
+
+Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.
+
+In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future.
+
+Additionally, these features are disabled by default. To use them, you must explicitly set the corresponding feature flags to `true`. This design choice ensures that non-standard features are only used intentionally.
+
+Some of these features may eventually be merged into the TOML language itself. If a feature is officially adopted, the corresponding experimental implementation in toml11 may be removed in a minor version update after the official feature is implemented.
+
+## `null`
+
+This feature allows the use of `null` as a value in TOML files.
+
+```
+a = null
+b = [ 1, 2, 3, null, 5]
+```
+
+To enable this, set the `ext_null_value` flag in `toml::spec` to `true`.
+
+When parsed, it will be treated as `toml::value_t::empty`, similar to a default-constructed value. However, the location information within the file will be set.
+
+`null` is parsed only in the context of values. Therefore, if `null` is used as a key, it will be interpreted as the string `"null"`, as it has been in the standard TOML.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec;
+    spec.ext_null_value = true;
+
+    const auto v = toml::parse_str("a = null", spec);
+
+    assert(v.at("a").is_empty());
+    assert(v.at("a").is(toml::value_t::empty));
+
+    return 0;
+}
+```
+
+## Hexadecimal Format for Floating-Point Numbers
+
+This feature allows the use of hexadecimal format for floating-point numbers in TOML files.
+
+```
+a = 0x1.91eb851eb851fp+1 # 3.14
+```
+
+To enable this, set the `ext_hex_float` flag in `toml::spec` to `true`.
+
+The format follows the `printf` specification for `%a/%A`.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec;
+    spec.ext_hex_float = true;
+
+    const auto v = toml::parse_str("a = 0x1.91eb851eb851fp+1", spec);
+
+    assert(v.at("a").is_floating());
+    assert(v.at("a").as_floating() == 3.14);
+
+    return 0;
+}
+```
+
+## Suffixes for Integers and Floating-Point Numbers
+
+This feature allows the use of suffixes for numbers in TOML files. It can be applied to integers and floating-point numbers in decimal notation.
+
+This is particularly useful for displaying units.
+
+```
+a = 86_400_sec
+b = 3.1416_rad
+c = 10_μm
+```
+
+However, these are purely suffixes and do not perform any unit conversion. If unit conversion is needed, users should implement it by referencing the suffix.
+
+To enable this, set the `ext_num_suffix` flag in `toml::spec` to `true`.
+
+The suffix must be separated from the number by an underscore (`_`).
+
+For clarity, the suffix cannot start with a digit.
+
+```
+distance = 100_m  # valid
+distance = 10_0m  # invalid
+distance = 10_0_m # valid
+```
+
+The suffix is stored as `std::string suffix` in the format information.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec;
+    spec.ext_hex_float = true;
+
+    const auto v = toml::parse_str("a = 86_400_sec", spec);
+
+    assert(v.at("a").is_integer());
+    assert(v.at("a").as_integer() == 86400);
+    assert(v.at("a").as_integer_fmt().suffix == "sec");
+
+    return 0;
+}
+```

docs/content.en/docs/features/literal.md

@@ -0,0 +1,92 @@
++++
+title = "toml literal"
+type  = "docs"
+weight = 60
++++
+
+# `_toml` Literal
+
+With the `""_toml` literal, you can format TOML files inline.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    using namespace toml::literals::toml_literals;
+
+    const auto v = "a = 42"_toml;
+
+    assert(v.at("a").as_integer() == 42);
+
+    return 0;
+}
+```
+
+When including line breaks, raw string literals come in handy.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    using namespace toml::literals::toml_literals;
+
+    const auto v = R"(
+        a = 42
+        b = "foo"
+    )"_toml;
+
+    assert(v.at("a").as_integer() == 42);
+    assert(v.at("b").as_string()  == "foo");
+
+    return 0;
+}
+```
+
+If a value is written on its own, that value is returned.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    using namespace toml::literals::toml_literals;
+
+    const auto a = "42"_toml;
+    const auto b = "12:34:56"_toml;
+
+    assert(a.as_integer() == 42);
+    assert(b.as_local_time().hour   == 12);
+    assert(b.as_local_time().minute == 34);
+    assert(b.as_local_time().second == 56);
+
+    return 0;
+}
+```
+
+TOML allows keys consisting solely of numbers. Therefore, `[1]` is a valid table name.
+
+When there's ambiguity between table definitions and arrays, table definitions take precedence.
+
+To interpret as an array, please use a trailing comma.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    using namespace toml::literals::toml_literals;
+
+    const auto t = "[1]"_toml;  // {1 = {}}
+    const auto a = "[1,]"_toml; // [1,]
+
+    assert(t.is_table());
+    assert(t.at("1").is_table());
+
+    assert(a.is_array());
+    assert(a.at(0).as_integer() == 1);
+
+    return 0;
+}
+```

docs/content.en/docs/features/parsing_files.md

@@ -0,0 +1,240 @@
++++
+title = "parsing files"
+type  = "docs"
+weight = 10
++++
+
+# Parsing Files and Strings
+
+In toml11, you can parse files, strings, and byte arrays using `toml::parse` or `toml::try_parse`.
+
+Upon success, these functions return a `toml::value`.
+Although the parsed file is always a table, the return type is not `toml::table`.
+This is because `toml::value` contains metadata about the file, whereas `toml::table` is merely an alias for `std::unordered_map<std::string, toml::value>`.
+To include metadata, a `toml::value` is returned instead of a `toml::table`.
+The `toml::value` corresponding to the root of the file will always hold a `table_type`.
+
+## Parsing Files
+
+To parse files, use either
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
+or
+[`toml::try_parse`]({{< ref "docs/reference/parser#try_parse" >}}).
+
+### `toml::parse`
+
+#### Specifying the Filename with `std::string`
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
+accepts a filename as a string, opens the file, and parses it.
+
+The following sample code parses a file named `input.toml`, extracts the `title` variable as a string, and prints it.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    const toml::value input = toml::parse("input.toml");
+    std::cout << input.at("title").as_string() << std::endl;
+    return 0;
+}
+```
+
+#### Specifying an Input Stream with `std::istream`
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept an `std::istream`.
+
+Without the filename information, error messages will display `"unknown file"`. To avoid this, you can pass the filename as a `std::string` in the second argument when using `std::istream`.
+
+You can use streams other than `std::ifstream`, such as `std::istringstream`. Note that the entire content is readable at the time of the call.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    std::string filename("input.toml");
+    std::ifstream ifs(filename);
+    const toml::value input = toml::parse(ifs, filename);
+    std::cout << input.at("title").as_string() << std::endl;
+    return 0;
+}
+```
+
+#### Specifying a File with `std::filesystem::path`
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can accept a `std::filesystem::path`.
+
+This requires C++17 or later, as it relies on the `<filesystem>` support.
+
+#### Specifying a File with `FILE*`
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept a `FILE*`.
+
+As with `std::istream`, you need to provide the filename as a string in the second argument.
+
+When passing a `FILE*`, if the file read fails, `errno` will be reported.
+
+#### Error Handling
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) throws a [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) if it encounters a syntax error.
+
+[`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) is derived from [`toml::exception`]({{< ref "docs/reference/exception" >}}), which in turn is derived from `std::exception`.
+
+Therefore, you can use the `what()` member function to retrieve the error message from a [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}).
+
+Additionally, [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) contains a [`std::vector<toml::error_info>`]({{< ref "docs/reference/error_info" >}}), which can be accessed using the `errors()` member function.
+
+`toml::parse` attempts to recover from minor errors and report multiple errors whenever possible. While it can often recover from simple errors like number format issues, errors within arrays or tables might not be recoverable and may lead to multiple similar error reports. If you find the error messages redundant, you can use only the `front()` of the `std::vector<toml::error_info>` to get a message about the most critical issue.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    try {
+        const toml::value input = toml::parse("input.toml");
+        std::cout << input.at("title").as_string() << std::endl;
+    } catch(const toml::syntax_error& err) {
+        // report all the errors
+        std::cerr << err.what() << std::endl;
+
+        // report the first error only
+        std::cerr << err.errors().front() << std::endl;
+    }
+}
+```
+
+### `toml::try_parse`
+
+While `toml::parse` throws an exception on failure, `toml::try_parse` does not throw exceptions when it fails.
+
+Instead, its return type is [`toml::result<toml::value, std::vector<toml::error_info>>`]({{<ref "docs/reference/result#result">}}).
+
+The [`result`]({{<ref "docs/reference/result#result">}}) type holds either a success value or a failure value, similar to Rust's `Result` or Haskell's `Either`.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    const auto parse_result = toml::try_parse("input.toml");
+    if(parse_result.is_ok())
+    {
+        std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
+    }
+    else
+    {
+        std::cerr << parse_result.unwrap_err().at(0) << std::endl;
+    }
+    return 0;
+}
+```
+
+To check which value the [`result`]({{<ref "docs/reference/result#result">}}) type holds, use the `is_ok()` and `is_err()` functions. The success or failure value can be retrieved using `unwrap()` and `unwrap_err()`, respectively. If `unwrap` fails, it throws a `bad_result_access` exception. Using the `as_ok()` and `as_err()` functions does not throw exceptions on failure, but results in undefined behavior.
+
+{{<hint warning>}}
+
+Although `try_parse` does not throw `syntax_error` or `file_io_error`, it returns the same `toml::error_info` as the failure type in the `result`. However, it is not entirely exception-free.
+
+If an internal standard library error occurs, such as `std::bad_alloc` when a `vector` fails to allocate memory, `toml::try_parse` does not catch this and will let it propagate. Thus, exceptions originating from the standard library may still be thrown.
+
+{{</hint>}}
+
+## Parsing Strings
+
+### `toml::parse_str`
+
+[`toml::parse_str`]({{<ref "docs/reference/parser#parse_str">}}) accepts the string to be parsed directly, instead of a filename.
+
+For the part of the error message that corresponds to the TOML file's name, if the `std::source_location` equivalent compiler extension is available, the name and line number of the C++ file that called `parse_str` will be used instead.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    const toml::value input = toml::parse_str("title = \"parse_str\"");
+    std::cout << input.at("title").as_string() << std::endl;
+    return 0;
+}
+```
+
+### `toml::try_parse_str`
+
+[`toml::try_parse_str`]({{<ref "docs/reference/parser#try_parse_str">}}) also takes the string to be parsed directly, similar to `parse_str`. Like `try_parse`, it uses [`toml::result`]({{<ref "docs/reference/result#result">}}) to report errors.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    const auto parse_result = toml::try_parse_str("title = \"parse_str\"");
+    if(parse_result.is_ok())
+    {
+        std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
+    }
+    else
+    {
+        std::cerr << parse_result.unwrap_err().at(0) << std::endl;
+    }
+    return 0;
+}
+```
+
+## Parsing Byte Arrays
+
+It is also possible to parse byte arrays instead of files.
+
+Since the byte arrays must be encoded in UTF-8, `unsigned char` is used.
+
+### `toml::parse(std::vector<unsigned char>)`
+
+The behavior is the same as [`toml::parse`]({{<ref "docs/reference/parser#parse">}}).
+
+When parsing byte arrays, a `filename` is required.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    std::vector<unsigned char> bytes{/* ... */};
+    const toml::value input = toml::parse(bytes, "internal bytes");
+    std::cout << input.at("title").as_string() << std::endl;
+    return 0;
+}
+```
+
+### `toml::try_parse(std::vector<unsigned char>)`
+
+The behavior is the same as [`toml::try_parse`]({{<ref "docs/reference/parser#try_parse">}}).
+
+When parsing byte arrays, a `filename` is required.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    std::vector<unsigned char> bytes{/* ... */};
+    const auto parse_result = toml::try_parse(bytes, "internal bytes");
+    if(parse_result.is_ok())
+    {
+        std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
+    }
+    else
+    {
+        std::cerr << parse_result.unwrap_err().at(0) << std::endl;
+    }
+    return 0;
+}
+```
+

docs/content.en/docs/features/serialize.md

@@ -0,0 +1,198 @@
++++
+title = "serializing values"
+type  = "docs"
+weight = 40
++++
+
+# Outputting TOML Files
+
+Using `toml::format`, you can convert a `toml::value` to a string.
+
+```cpp
+#include <toml.hpp>
+#include <cassert>
+
+int main()
+{
+    const toml::value v(toml::table{
+        {"a", 42},
+        {"b", "foo"},
+    });
+    const std::string s = toml::format(v);
+
+    const toml::value u = toml::parse_str(s);
+
+    assert(u.at("a").as_integer() == 42);
+    assert(u.at("b").as_string()  == "foo");
+
+    return 0;
+}
+```
+
+If the `toml::value` contains a `table_type`, it is interpreted as the root table of the file.
+
+If a `toml::value` containing anything other than `table_type` is passed, only that value is formatted.
+
+Certain format specifications may require a key to be provided for formatting. For example, `toml::array_format::array_of_tables` formats as `[[array.of.tables]]`, which requires key access.
+
+If a format specification that requires a key is provided without a key, a `toml::serialization_error` is thrown.
+
+Additionally, if there are values that contradict the format specification, a `toml::serialization_error` is thrown. For instance, specifying `integer_format::hex` for a negative integer, or `string_format::literal` for a string containing newlines, will cause an error.
+
+The method for specifying formats is explained later.
+
+## Outputting with Keys
+
+You can pass a key to `toml::format` as a `std::string`.
+
+In this case, the key is considered to be under the root table, and the passed value corresponds to that key.
+
+For nested keys, you can pass a `std::vector<std::string>`.
+
+```cpp
+#include <toml.hpp>
+#include <cassert>
+
+int main()
+{
+    const toml::value v(toml::table{
+        {"a", 42},
+        {"b", "foo"},
+    });
+    const std::string s = toml::format("bar", v);
+
+    const toml::value u = toml::parse_str(s);
+
+    assert(u.at("bar").at("a").as_integer() == 42);
+    assert(u.at("bar").at("b").as_string()  == "foo");
+
+    return 0;
+}
+```
+
+## Specifying Formats
+
+Each type in `toml::value` has a corresponding format information type.
+
+For `toml::value::integer_type`, there is `toml::integer_format_info`.
+For `toml::value::table_type`, there is `toml::table_format_info`.
+
+These format information types are set when parsing and are retained even if the value is changed, as long as the type remains the same.
+
+You can access and directly edit these formats using member functions like `as_integer_fmt()` or `as_table_fmt()`.
+
+Below are some examples explaining how to use these formats.
+
+For more details on how to access formats, refer to the [`toml::value` reference]({{< ref "/docs/reference/value" >}}). For a complete list and detailed information on format information classes, see the [format reference]({{< ref "/docs/reference/format" >}}).
+
+### Specifying Integer Formats
+
+For integers, you can specify the radix, width, and the position of `_`.
+
+When using `hex`, `oct`, or `bin`, values are padded with zeros until the specified width is reached. For `dec`, the width specification adds spaces, which are not parsed.
+
+For more details, see the [integer format reference]({{< ref "/docs/reference/format#integer_format" >}}).
+
+### Single-Line and Multi-Line Arrays
+
+For arrays, you can specify `toml::array_format::oneline` or `toml::array_format::multiline`.
+
+```toml
+# oneline
+a = [1, 2, 3, 4, 5]
+# multiline
+a = [
+  1,
+  2,
+  3,
+  4, 
+  5
+]
+```
+
+When using `multiline`, you can specify the indentation. Each element is indented by the amount specified in `body_indent`, and the closing bracket `]` is indented by the amount specified in `closing_indent`.
+
+The type of character used for indentation is specified by `indent_type`, and you can choose between `toml::indent_char::space` or `toml::indent_char::tab`.
+
+{{<hint warning>}}
+Ensure that the same type of character is used for indentation throughout the document.
+
+If different types of characters are specified for indentation within the same file, the result is undefined. Some form of indentation will be applied, but the type of character and the depth of the indentation may be inconsistent.
+{{</hint>}}
+
+If all elements of an `array` have `table_type`, you can specify `toml::array_format::array_of_tables`.
+
+If you do not specify `array_of_tables` and use `multiline`, the tables will be formatted as inline tables.
+
+```toml
+# multiline
+a = [
+  {foo = 42},
+  {bar = "hoge"},
+]
+
+# array_of_tables
+[[a]]
+foo = 42
+
+[[a]]
+bar = "hoge"
+```
+
+By default, `toml::array_format::default_format` is used. This automatically selects an appropriate format.
+
+For example, with `default_format`, if all elements are `table_type`, it will choose `array_of_tables`. Short arrays are formatted as `oneline`, while long or nested arrays, or those with complex elements, are formatted as `multiline`.
+
+For more details, see the [array format reference]({{< ref "/docs/reference/format#array_format" >}}).
+
+### Inline Tables
+
+To format a table as an inline table, specify `toml::table_format::oneline`.
+For standard tables, use `toml::table_format::multiline`.
+
+```toml
+oneline = {a = 42, b = "foo"}
+
+[multiline]
+a = 42
+b = "foo"
+```
+
+In TOML v1.1.0, line breaks within inline tables are allowed. In this case, use `toml::table_format::multiline_oneline`. This is only applied if the corresponding feature flag is set to `true` as per the TOML version specification described later.
+
+```toml
+multiline_oneline = {
+    a = 42,
+    b = "foo"
+}
+```
+
+For more details, see the [table format reference]({{< ref "/docs/reference/format#table_format" >}}).
+
+## Specifying the TOML Language Version for Output
+
+Certain language features, such as line breaks within inline tables and `\x` escape sequences, are only available after TOML v1.1.0.
+
+The `toml::format` function accepts a `toml::spec` as its argument.
+
+This allows you to specify the version of TOML to use during serialization.
+
+When you use `toml::parse` with a `toml::spec` to leverage new features,
+the parsed values may contain format information that is only compatible with that specific version.
+Ensure that you pass the same `toml::spec` to `toml::format` to maintain compatibility.
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    const auto spec = toml::spec::v(1, 1, 0);
+
+    const toml::value v = toml::parse("input.toml", spec);
+
+    std::cout << toml::format(v, spec) << std::endl;
+
+    return 0;
+}
+```

docs/content.en/docs/features/toml_spec.md

@@ -0,0 +1,107 @@
++++
+title = "toml spec"
+type  = "docs"
+weight = 70
++++
+
+# TOML Language Version
+
+You can specify the version of the TOML language and individual feature flags to use with `toml::parse` or `toml::format` through [`toml::spec`](docs/reference/spec#tomlspec).
+
+## Specifying TOML Version
+
+You can construct a [`toml::spec`](docs/reference/spec#tomlspec) from [`toml::semantic_version`](docs/reference/spec#tomlsemantic_version).
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec(toml::semantic_version(1, 1, 0));
+    return 0;
+}
+```
+
+However, to make this shorter, the `toml::spec::v()` function is provided.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec = toml::spec::v(1, 1, 0);
+    return 0;
+}
+```
+
+If not specified explicitly, `toml::spec::default_version()` is used to construct with default values.
+
+The default value depends on the version of toml11 and follows the latest version of the TOML language released at that time.
+
+As of v4.0.0, TOML v1.1.0 has not been released yet, so the default TOML version is v1.0.0.
+
+{{<hint warning>}}
+
+Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.
+
+If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.
+
+As such, any features related to future versions should be considered unstable.
+
+{{</hint>}}
+
+### Parsing with Version Specification
+
+The overload of [`toml::parse`](docs/reference/parser) takes a `toml::spec` following the file name.
+
+This allows you to change the TOML version being used.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::value input = toml::parse("input.toml", toml::spec::v(1, 1, 0));
+    return 0;
+}
+```
+
+### Serializing with Version Specification
+
+The overload of [`toml::format`](docs/reference/serializer) takes a `toml::spec` following the `toml::value`.
+
+This allows you to change the TOML version being used.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::value v = toml::parse("input.toml", toml::spec::v(1, 1, 0));
+    std::cout << toml::format(v, toml::spec::v(1, 1, 0)) << std::endl;
+    return 0;
+}
+```
+
+If a format is passed that is not permitted by the provided `toml::spec`, it will be ignored, and another format will be used as a fallback.
+
+## Specifying Newly Added Features in TOML
+
+With version upgrades in TOML, multiple new features are introduced, and it's possible to enable only some of them.
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::spec spec = toml::spec::v(1, 0, 0);
+
+    // Allowing newlines in inline tables
+    spec.v1_1_0_allow_newlines_in_inline_tables = true;
+
+    toml::value input = toml::parse("input.toml", spec);
+    return 0;
+}
+```
+
+For a full list of all flags, refer to [`toml::spec`](docs/reference/spec#tomlspec).

docs/content.en/docs/features/value.md

@@ -0,0 +1,799 @@
++++
+title = "getting values"
+type  = "docs"
+weight = 20
++++
+
+# Retrieving Values
+
+This section explains how to access the values stored in `toml::value`.
+
+## Accessing Values Using Member Functions
+
+### `is_something` and `as_something`
+
+`toml::value` has member functions like `is_boolean()` and `is_integer()` which allow you to check the type of the stored value.
+
+Additionally, it has member functions like `as_boolean()` and `as_integer()` that allow you to access the value of that type.
+
+For a complete list, refer to the [`toml::value` reference]({{<ref "docs/reference/value#is_xxx">}}).
+
+```cpp
+toml::value v = /* ... */;
+if(v.is_string())
+{
+    std::cout << v.as_string() << std::endl;
+}
+```
+
+If the stored value is of a different type than specified, a [`toml::type_error`]({{<ref "docs/reference/value#tomltype_error">}}) is thrown.
+
+The `what()` method will contain a message like the following:
+
+```
+[error] toml::value::as_string(): bad_cast to string
+ --> input.toml
+   |
+ 1 | a = 123_456
+   |     ^^^^^^^-- the actual type is integer
+```
+
+### `toml::value_t`
+
+Type information can be identified using [`enum class toml::value_t`]({{<ref "docs/reference/value_t">}}).
+
+The [`type()`]({{<ref "docs/reference/value#type">}}) member function returns the type information of the currently stored value.
+
+```cpp
+toml::value v = /* ... */;
+switch(v.type())
+{
+    case toml:value_t::empty          : { /*...*/ break; }
+    case toml:value_t::boolean        : { /*...*/ break; }
+    case toml:value_t::integer        : { /*...*/ break; }
+    case toml:value_t::floating       : { /*...*/ break; }
+    case toml:value_t::string         : { /*...*/ break; }
+    case toml:value_t::offset_datetime: { /*...*/ break; }
+    case toml:value_t::local_datetime : { /*...*/ break; }
+    case toml:value_t::local_date     : { /*...*/ break; }
+    case toml:value_t::local_time     : { /*...*/ break; }
+    case toml:value_t::array          : { /*...*/ break; }
+    case toml:value_t::table          : { /*...*/ break; }
+    default: {break;}
+}
+```
+
+The [`is(toml::value_t)`]({{<ref "docs/reference/value#istomlvalue_t">}}) member function returns `true` if the stored value is of the given `value_t` type, otherwise it returns `false`.
+
+```cpp
+toml::value v = /* ... */;
+if(v.is(toml::value_t::integer))
+{
+    std::cout << v.as_integer() << std::endl;
+}
+```
+
+### `at`, `[]`, `contains`, `size`, `push_back`, `emplace_back`
+
+`toml::value` provides some member functions similar to those of standard library containers.
+
+These functions internally convert `toml::value` to the corresponding type and call the respective member functions.
+
+#### `at(std::size_t i)`, `operator[](std::size_t i)`
+
+These are equivalent to `as_array().at(i)` and `as_array()[i]`.
+
+`toml::value` uses `std::vector<toml::value>` as `array_type` by default, so `at` throws `std::out_of_range` on error, while `operator[]` results in undefined behavior.
+
+```cpp
+toml::value v(toml::array{1,2,3});
+std::cout << v.at(1);
+```
+
+If the stored type is not `array_type`, a `type_error` is thrown.
+
+#### `at(std::string key)`, `operator[](std::string key)`
+
+These are equivalent to `as_table().at(key)` and `as_table()[key]`.
+
+`toml::value` uses `std::unordered_map<std::string, toml::value>` as `table_type` by default, so if the corresponding value does not exist, `at` throws `std::out_of_range`, while `operator[]` constructs a new `toml::value` and returns a reference to it. Therefore, there is no `const` version of `operator[]`.
+
+```cpp
+toml::value v(toml::table{});
+v["a"] = 42;
+```
+
+If the stored type is not `table_type`, a `type_error` is thrown.
+
+#### `size()`
+
+Returns the length.
+
+For `array_type` or `table_type`, it returns the number of elements; for `string_type`, it returns the number of characters (in bytes).
+
+If the stored type is none of these, a `type_error` is thrown.
+
+#### `push_back()`, `emplace_back()`
+
+These are equivalent to `as_array().push_back()` and `as_array().emplace_back()`.
+
+If the stored type is not `array_type`, a `type_error` is thrown.
+
+## Accessing Comments
+
+In toml11, comments are parsed by default and saved line by line with the corresponding value.
+
+A comment corresponds to the value that comes immediately after the consecutive lines of comments, or to the value on the same line as the comment.
+
+If there is no value immediately before or after the comment, it is not associated with any value and is ignored.
+
+```toml
+# input.toml
+
+# This is a comment about a.
+a = 42
+b = 3.14 # This is a comment about b.
+
+# This comment is ignored because it has no corresponding value.
+
+# This is the 1st comment about c.
+# This is the 2nd comment about c.
+c = "foo" # This is the final comment about c.
+# This comment is NOT a comment about c.
+```
+
+Comments corresponding to a value can be accessed using the `comments()` member function of `toml::value`.
+
+`comments()` returns a container that has the same member functions as `std::vector<std::string>`.
+
+```cpp
+const auto v = toml::parse("input.toml");
+const auto& a = v.at("a");
+const auto& b = v.at("b");
+const auto& c = v.at("c");
+
+assert(a.comments().size() == 1);
+assert(a.comments().at(0) == "# This is a comment about a.");
+
+assert(b.comments().size() == 1);
+assert(b.comments().at(0) == "# This is a comment about b.");
+
+assert(c.comments().size() == 3);
+assert(c.comments().at(0) == "# This is the 1st comment about c.");
+assert(c.comments().at(1) == "# This is the 2nd comment about c.");
+assert(c.comments().at(2) == "# This is the final comment about c.");
+```
+
+Comments related to the root table of the entire file are written at the beginning of the file.
+
+```toml
+# This is a comment about the root table.
+# This is also a comment about the root table.
+
+# This comment is ignored.
+
+# This is a comment about a.
+a = 42
+```
+
+However, if a value immediately follows the initial comment, the comment is interpreted as pertaining to that value, and there are no comments for the root table.
+
+```toml
+# This is a comment about a.
+# This is also a comment about a.
+a = 42
+```
+
+## Handling Inline Tables and Dotted Keys
+
+An inline table is simply a table, and there is no difference in handling it compared to other tables in C++ code.
+
+```toml
+a = {b = 42, c = "foo"}
+```
+
+Dotted keys are also just tables, with no difference in handling compared to other tables in C++ code.
+
+```toml
+a.b = 42
+a.c = "foo"
+```
+
+These TOML files are identical to the following file.
+
+```toml
+[a]
+b = 42
+c = "foo"
+```
+
+Thus, they can all be processed with the exact same code.
+
+```cpp
+const auto input = toml::parse("input.toml");
+
+assert(input.at("a").at("b").as_integer() == 42);
+assert(input.at("a").at("c").as_string()  == "foo");
+```
+
+However, it is possible to distinguish them based on format information.
+
+```cpp
+const auto input = toml::parse("input.toml");
+switch(input.at("a").as_table_fmt().fmt)
+{
+    case toml::table_format::oneline: 
+    {
+        std::cout << "inline table" << std::endl;
+        break;
+    }
+    case toml::table_format::multiline:
+    {
+        std::cout << "normal table" << std::endl;
+        break;
+    }
+    case toml::table_format::dotted:
+    {
+        std::cout << "dotted keys" << std::endl;
+        break;
+    }
+}
+```
+
+This format information is also considered during serialization, which will be described later.
+
+## Handling Date and Time Information
+
+[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
+[`local_time`]({{<ref "docs/reference/datetime#local_time">}}),
+[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}), and
+[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}})
+are parsed into dedicated structures with corresponding member variables in toml11.
+
+When using these, you can directly extract the values or use `toml::get` and `toml::find` to convert them into types such as `std::chrono::system_clock::time_point` or `std::tm`.
+
+## Converting Using `toml::get<T>`
+
+`toml::get<T>` is a function that converts and retrieves the value stored in `toml::value`.
+Specify the desired target type as `T`.
+
+```cpp
+const toml::value v = /*...*/;
+std::cout << toml::get<int>(v) << std::endl;
+```
+
+The `toml::find<T>` function, described later, also has the same functionality for type conversion.
+
+If an unsupported type is specified for the stored value, a `toml::type_error` is thrown.
+
+### Simple Conversions
+
+#### boolean_type
+
+Conversion from `boolean_type` is possible only to `bool`.
+
+#### integer_type
+
+Any type for which `std::is_integral<T>` is `true`, except `bool`, can be converted from `integer_type`.
+
+```cpp
+toml::value v(42);
+const auto u32 = toml::get<std::uint32_t>(v);
+const auto i16 = toml::get<short>(v);
+```
+
+#### floating_type
+
+Any type for which `std::is_floating_point<T>` is `true` can be converted from `floating_type`.
+
+```cpp
+toml::value v(3.14);
+const auto f64 = toml::get<double>(v);
+const auto f32 = toml::get<float >(v);
+```
+
+#### string_type
+
+`string_type` can be converted to `std::string`.
+From C++17 onwards, it can also be converted to `std::string_view`.
+
+```cpp
+toml::value v("foo");
+const auto s = toml::get<std::string>(v);
+
+// C++17
+const auto sv = toml::get<std::string_view>(v);
+```
+
+#### datetime variants
+
+[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
+[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}), and
+[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}}) represent specific dates and times,
+so they can be converted to `std::chrono::system_clock::time_point`.
+
+However, since [`local_time`]({{<ref "docs/reference/datetime#local_time">}}) does not include date information, it supports conversion to `std::chrono::duration` as the elapsed time from `00:00.00`.
+
+Additionally, `local_date` and `local_datetime` conversions take the executing machine's timezone into account.
+
+```toml
+date = 2024-01-23
+time = 12:30:00
+l_dt = 2024-01-23T12:30:00
+o_dt = 2024-01-23T12:30:00+09:00
+```
+
+```cpp
+const auto input = toml::parse("input.toml");
+
+const auto date = toml::get<std::chrono::system_clock::time_point>(input.at("date"));
+const auto l_dt = toml::get<std::chrono::system_clock::time_point>(input.at("l_dt"));
+const auto o_dt = toml::get<std::chrono::system_clock::time_point>(input.at("o_dt"));
+
+const auto time = toml::get<std::chrono::minutes>(input.at("time")); // 12 * 60 + 30 min
+```
+
+### Conditions for Obtaining References
+
+`toml::get<T>` can return a reference if `T` is the exact type stored in `toml::value`.
+
+Conversely, if a conversion is necessary (e.g., extracting an integer stored as `std::int64_t` into `std::uint32_t`), it is not possible to return a reference to the converted type.
+
+When no conversion is needed, the returned reference can be used to modify the value.
+
+```cpp
+toml::value v(42);
+
+toml::get<toml::value::integer_type>(v) = 6 * 9;
+
+assert(v.as_integer() == 54);
+```
+
+### Converting Arrays to STL Containers
+
+If all elements in an array have the same type and can be converted to `T`, it is possible to convert them to `std::vector<T>`.
+
+```toml
+a = [1, 2, 3, 4, 5]
+```
+
+```cpp
+const auto a = toml::get<std::vector<int>>(input.at("a"));
+```
+
+Other STL containers can also be used.
+
+```cpp
+const auto a1 = toml::get<std::deque<int>>(input.at("a"));
+const auto a2 = toml::get<std::list <int>>(input.at("a"));
+const auto a3 = toml::get<std::array<int, 5>>(input.at("a"));
+```
+
+When converting to `std::array`, the number of elements must match. If they don't match, a `std::out_of_range` exception is thrown.
+
+Non-STL containers that have a default constructor and a `push_back` method can also be converted using `toml::get`.
+
+```cpp
+const auto a = toml::get<boost::container::small_vector<int, 8>>(input.at("a"));
+```
+
+### Converting Arrays to `std::pair` or `std::tuple`
+
+If an array contains elements of different types, it can be converted to `std::pair` or `std::tuple`.
+
+```toml
+a = [true, 3.14]
+b = [42, 2.718, "foo"]
+```
+
+```cpp
+const auto a = toml::get<std::pair<bool, double>>(input.at("a"));
+const auto b = toml::get<std::tuple<int, double, std::string>>(input.at("b"));
+```
+
+As with `std::array`, the length of the array must match the number of elements in the `std::pair` or `std::tuple`. If they don't match, a `std::out_of_range` exception is thrown.
+
+Additionally, each element must be convertible to the corresponding element in the `std::pair` or `std::tuple`. If conversion is not possible, a `toml::type_error` exception is thrown.
+
+### Converting Nested Arrays
+
+Nested arrays can be converted to nested containers.
+
+```toml
+a = [ [1, 2, 3], [4, 5, 6] ]
+```
+
+```cpp
+const auto a = toml::get<std::vector<std::vector<int>>>(input.at("a"));
+```
+
+If the types are different, `std::pair` or `std::tuple` can be useful.
+
+```toml
+a = [ [1, 2, 3], ["foo", "bar"] ]
+```
+
+```cpp
+const auto a = toml::get<
+    std::pair<std::vector<int>, std::vector<std::string>>
+    >(input.at("a"));
+```
+
+### Converting Tables to `std::map`
+
+If all values in a table have the same type, they can be converted to `std::map` or `std::unordered_map`.
+
+```toml
+t = {a = 1, b = 2}
+```
+
+```cpp
+const auto t = toml::get<std::map<std::string, int>>(input.at("t"));
+```
+
+Non-STL containers that have a default constructor and an `emplace(key, mapped)` method can also be converted using `toml::get`.
+
+```cpp
+const auto t = toml::get<boost::container::flat_map<std::string, int>>(input.at("t"));
+```
+
+If the conversion of any element fails, a `toml::type_error` exception is thrown.
+
+## Using `toml::get_or` to Specify a Value on Failure
+
+`toml::get` throws a `toml::type_error` exception if the conversion fails.
+
+By using `toml::get_or`, you can specify a default value to return instead of an exception in case of a conversion failure.
+
+Unlike `toml::get<T>`, `get_or` infers the target type from the arguments, so there is no need to specify `<T>`.
+
+```cpp
+const auto a = toml::get_or(input.at("a"), 42);
+```
+
+The types that can be converted are the same as for `toml::get`.
+
+If you specify `toml::value::xxx_type`, you can also retrieve a reference, but in that case, the argument must also be a reference.
+
+```cpp
+toml::value::integer_type a_default = 42;
+auto a& = toml::get_or(input.at("a"), a_default);
+```
+
+## Using `toml::find<T>` to Search and Convert Simultaneously
+
+`toml::find<T>` is a function that searches for a value in a `toml::value` holding a table and simultaneously performs the same type conversion as `toml::get`.
+
+```cpp
+const auto a = toml::find<int>(input, "a");
+// Equivalent to: const auto a = toml::get<int>(input.at("a"));
+```
+
+`toml::find<T>` can also be used with arrays.
+
+```cpp
+const auto a  = input.at("a");
+const auto a2 = toml::find<int>(a, 2);
+// Equivalent to: const auto a2 = toml::get<int>(input.at("a").at(2));
+```
+
+If an error occurs during type conversion, `toml::find<T>` throws the same `toml::type_error` as `toml::get`.
+If the key is not found or the index does not exist, it throws `std::out_of_range`.
+
+If no type is specified, `toml::find` returns a `toml::value` without type conversion.
+
+```cpp
+const auto a = toml::find(input, "a");
+// Equivalent to: const auto a = input.at("a");
+```
+
+`toml::find<T>` can access values recursively.
+
+```toml
+a = {b = {c = 42}}
+```
+
+```cpp
+const auto a_b_c = toml::find<int>(input, "a", "b", "c");
+// Equivalent to: const auto a = toml::get<int>(input.at("a").at("b").at("c"));
+```
+
+You can mix keys and indexes.
+
+
+```toml
+a = [ {b = 1}, {b = 2}, {b = 3} ]
+```
+
+```cpp
+const auto a_2_b = toml::find<int>(input, "a", 2, "b");
+// Equivalent to: const auto a = toml::get<int>(input.at("a").at(2).at("c"));
+```
+
+{{<hint info>}}
+
+TOML supports a feature called quoted keys, which allows using normally disallowed characters in keys by enclosing them in `""` or `''`. Within quoted keys, `.` does **not** introduce tables.
+
+```toml
+"127.0.0.1" = "value"
+site."google.com" = true
+```
+
+You can read this TOML file as follows:
+
+```cpp
+const auto input = toml::parse("input.toml");
+
+assert(input.at("127.0.0.1").as_string() == "value");
+assert(input.at("site").at("google.com").as_boolean());
+```
+
+To handle such cases seamlessly, toml11 does not automatically split keys containing `.`. Explicitly specifying the table hierarchy helps in structuring the input file correctly.
+
+Reference: [toml.io/Key](https://toml.io/en/v1.0.0#key)
+
+{{</hint>}}
+
+## Using `toml::find_or` to Search and Specify a Value on Failure
+
+`toml::find_or` works similarly to `toml::find<T>`, but allows specifying a default value to return if the search or conversion fails.
+
+This is useful when you want to provide a fallback value instead of handling exceptions.
+
+```cpp
+const auto a = toml::find_or(input, "a", 42);
+```
+
+## Defining Conversions for User-Defined Types
+
+With `toml::get` and `toml::find`, you can use user-defined types by employing one of the following methods.
+
+### Defining `toml::from`
+
+In toml11, there is a `toml::from` type that supports conversions from user-defined types by specializing it as follows:
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+namespace toml
+{
+template<>
+struct from<extlib::foo>
+{
+    static extlib::foo from_toml(const toml::value& v)
+    {
+        return extlib::foo{
+            toml::find<int>(v, "a"),
+            toml::find<std::string>(v, "b")
+        };
+    }
+};
+} // toml
+```
+
+If you also want to support `toml::value` with a modified type configuration, do as follows:
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+namespace toml
+{
+template<>
+struct from<extlib::foo>
+{
+    template<typename <TC>
+    static extlib::foo from_toml(const toml::basic_value<TC>& v)
+    {
+        return extlib::foo{
+            toml::find<int>(v, "a"),
+            toml::find<std::string>(v, "b")
+        };
+    }
+};
+} // toml
+```
+
+This definition can be automatically generated using `TOML11_DEFINE_CONVERSION_NON_INTRUSIVE`.
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(extlib::foo, a, b)
+```
+
+Alternatively, you can use a reflection library. Refer to the sample in `example` using `boost-ext/reflect`.
+
+### Defining a `from_toml` Member Function
+
+You can also define a conversion by defining a `from_toml` member function.
+
+When using this method, a default constructor is required.
+
+```cpp
+struct bar
+{
+    int a;
+    std::string b;
+
+    void from_toml(const toml::value& v)
+    {
+        this->a = toml::find<int>(v, "a");
+        this->b = toml::find<std::string>(v, "b");
+        return ;
+    }
+};
+```
+
+If both are defined, `toml::from` takes precedence.
+
+### Constructor Accepting `toml::value`
+
+If there is a constructor that accepts `toml::value`, conversion via `toml::get` can be performed.
+
+```cpp
+struct baz
+{
+    explicit baz(const toml::value& v)
+        : a(toml::find<int>(v, "a")), b(toml::find<std::string>(v, "b"))
+    {}
+    int a;
+    std::string b;
+};
+```
+
+If both are defined, `toml::from` and `from_toml` take precedence.
+
+## Applying Functions with `toml::visit`
+
+If you have a function object that can be applied to all types stored in `toml::value`, you can directly call that function without type conversion using `toml::visit`.
+
+```cpp
+struct type_name_of
+{
+    std::string operator()(const toml::value::boolean_type        &) const {return "boolean";}
+    std::string operator()(const toml::value::integer_type        &) const {return "integer";}
+    std::string operator()(const toml::value::floating_type       &) const {return "floating";}
+    std::string operator()(const toml::value::string_type         &) const {return "string";}
+    std::string operator()(const toml::value::local_time_type     &) const {return "local_time";}
+    std::string operator()(const toml::value::local_date_type     &) const {return "local_date";}
+    std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
+    std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
+    std::string operator()(const toml::value::array_type          &) const {return "array";}
+    std::string operator()(const toml::value::table_type          &) const {return "table";}
+};
+
+toml::value v(3.14);
+std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
+```
+
+## Constructing `toml::value`
+
+`toml::value` can be constructed not only internally by the parser but also in user code.
+
+You can construct it by passing a type that is either the same as or convertible to the types stored in `toml::value`.
+
+```cpp
+toml::value v1(true);
+toml::value v2(42);
+toml::value v3(3.14);
+```
+
+For arrays, you can use `toml::array`:
+
+```cpp
+toml::value v(toml::array{1, 2, 3});
+```
+
+Alternatively, you can pass containers such as `std::vector` directly:
+
+```cpp
+const std::vector<toml::value> a{1,2,3};
+toml::value v(a);
+```
+
+For tables, you can use `toml::table`:
+
+```cpp
+toml::value v(toml::table{{"foo", 1}, {"bar", 2}, {"baz", 3}});
+```
+
+Or pass containers such as `std::map` directly:
+
+```cpp
+const std::map<std::string, toml::value> t{
+        {"foo", 1}, {"bar", 2}, {"baz", 3}
+    }
+toml::value v(t);
+```
+
+You can pass `format_info` and comments to the constructor.
+
+The type of comments is `std::vector<std::string>`.
+Each element corresponds to a line.
+
+```cpp
+toml::integer_format_info fmt;
+fmt.fmt = toml::integer_format::hex;
+fmt.spacer = 4;
+
+toml::value v1(0xDEADBEEF, fmt);
+toml::value v2(0xC0FFEE, fmt, {"hex value!"});
+```
+
+## Converting to `toml::value`
+
+When constructing `toml::value` from user-defined types, you can customize the behavior by defining `toml::into` or `into_toml`.
+
+`toml::into` is particularly useful when converting types from other libraries.
+
+### Defining `toml::into`
+
+By specializing `toml::into`, you can enable conversions to `toml::value`.
+
+This is useful for types from external libraries that do not provide a conversion to `toml::value`.
+
+Since `toml::value` passes `type_config` during conversion, you need to accept the `template` argument of `basic_value`.
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+template<>
+struct into<extlib::foo>
+{
+    template<typename TC>
+    static toml::basic_value<TC> into_toml(const extlib::foo& f)
+    {
+        return toml::basic_value<TC>(typename toml::basic_value<TC>::table_type{{"a", f.a}, {"b", f.b}});
+    }
+};
+```
+
+### Defining `into_toml` Member Function
+
+Similar to `from_toml`, you can define the conversion through a member function.
+
+If `toml::into` is defined, it takes precedence.
+
+```cpp
+struct bar
+{
+    int a;
+    std::string b;
+
+    template<typename TC>
+    toml::basic_value<TC> into_toml() const
+    {
+        return toml::basic_value<TC>(typename toml::basic_value<TC>::table_type{
+                {"a", this->a}, {"b", this->b}
+            });
+    }
+};
+```

docs/content.en/docs/installation/_index.md

@@ -0,0 +1,102 @@
++++
+title = "installation"
+type  = "docs"
+weight = 1
++++
+
+# Installation
+
+## Using `single_include`
+
+The `ingle_include/toml.hpp`s is a single-file, header-only library that consolidates all the functionalities of toml11 into one file.
+
+The simplest way to use it is to copy this file to a location included in your `INCLUDE_PATH` and then add `#include <toml.hpp>` to your source code.
+
+The MIT license notice is included in both the comments and the `toml::license_notice()` function.
+If you are redistributing the software without releasing the source code, you must either copy the toml11 license file and include it with your distribution, or ensure that the `toml::license_notice()` function can be called.
+
+## Cloning toml11 and using cmake
+
+If you place toml11 within your repository, for example by using git submodule, and you are using cmake, you can make use of it by adding `add_subdirectory(toml11)` to your `CMakeLists.txt`.
+
+```cmake
+add_subdirectory(toml11)
+add_executable(main main.cpp)
+target_link_libraries(main PUBLIC toml11::toml11)
+```
+
+toml11 will only run tests and install when it is the root project.
+
+## Installing using cmake
+
+After cloning toml11, you can install it using cmake.
+
+```console
+$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
+$ cmake --install ./build/ --prefix=/opt/toml11
+```
+
+If you want to run the test programs before installation, make sure to set `-DTOML11_BUILD_TESTS=ON` first.
+
+Once the installation is complete, you can use it as follows:
+
+```cmake
+find_package(toml11)
+add_executable(main main.cpp)
+target_link_libraries(main PRIVATE toml11::toml11)
+```
+
+## Compiling with cmake to Create a Static Library
+
+By defining `-DTOML11_PRECOMPILE=ON` when running cmake, you can precompile some of the functions in toml11, thereby reducing the overall compile time.
+
+```console
+$ cmake -B ./build/ -DTOML11_PRECOMPILE=ON
+```
+
+However, since toml11 supports multiple C++ versions and may switch types based on the value of `__cplusplus`,
+there is a possibility of link failures if the version used during build differs from the version used during usage.
+If you encounter issues, set the required version using `CMAKE_CXX_STANDARD` during compilation.
+If this is difficult, use it as a header-only library as usual.
+
+The `find_package(toml11)` command defines `TOML11_INCLUDE_DIR`.
+Even if you install it as a precompiled library, you can still use it as a header-only library by adding `TOML11_INCLUDE_DIR` to `target_include_directories` and avoiding the use of `target_link_libraries`.
+
+```cmake
+find_package(toml11)
+add_executable(main main.cpp)
+# Include only, do not link
+target_include_directories(main PRIVATE ${TOML11_INCLUDE_DIR})
+```
+
+## Compiling Examples
+
+You can compile the `examples/` directory by setting `-DTOML11_BUILD_EXAMPLES=ON`.
+
+```console
+$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
+$ cmake --build ./build/
+```
+
+The executable binaries for the examples will be generated in the `examples/` directory.
+
+## Running Tests
+
+To build the tests, set `-DTOML11_BUILD_TESTS=ON`.
+
+```console
+$ git submodule update --init --recursive
+$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
+$ cmake --build ./build/
+$ ctest --test-dir ./build/
+```
+
+To run the `toml-lang/toml-tests`, set `-DTOML11_BUILD_TOML_TESTS=ON`. This will build `toml11_decoder` and `toml11_encoder` in the `tests/` directory.
+
+```console
+$ git submodule update --init --recursive
+$ cmake -B ./build/ -DTOML11_BUILD_TOML_TESTS=ON
+$ cmake --build ./build/
+$ ctest --test-dir ./build/
+```
+

docs/content.en/docs/reference/_index.md

@@ -0,0 +1,122 @@
++++
+title = "reference"
+type  = "docs"
+weight = 3
+bookCollapseSection = true
++++
+
+# Reference
+
+Here, we explain the effects of the classes and functions provided by toml11.
+
+## Directory Structure
+
+`toml.hpp` and `toml_fwd.hpp` reside in `${TOML11_INCLUDE_DIR}`.
+Other files are located in `${TOML11_INCLUDE_DIR}/toml11`.
+
+If you want to `#include` each feature's file individually, use `#include <toml11/color.hpp>`.
+If you want to include all at once, use `#include <toml.hpp>`.
+
+## [color.hpp](color)
+
+Defines functions related to colorizing error messages.
+
+## [comments.hpp](comments)
+
+Defines types `preserve_comment` and `discard_comment` for preserving comments.
+
+## [conversion.hpp](conversion)
+
+Defines macros to automatically convert `toml::value` and user-defined classes.
+
+## [datetime.hpp](datetime)
+
+Defines classes for datetime information.
+
+## [error_info.hpp](error_info)
+
+Defines a class for error information.
+
+## [exception.hpp](exception)
+
+Defines the base class for exceptions used in toml11, `toml::exception`.
+
+## [find.hpp](find)
+
+Defines the `toml::find` function to search for and convert values.
+
+## [format.hpp](format)
+
+Defines classes for formatting information of values.
+
+## [from.hpp](from)
+
+Forward declaration of the `from<T>` type for converting user-defined types.
+
+## [get.hpp](get)
+
+Defines the `toml::get<T>` function to retrieve and convert values from `toml::value`.
+
+## [into.hpp](into)
+
+Forward declaration of the `into<T>` type for converting user-defined types.
+
+## [literal.hpp](literal)
+
+Defines the `operator"" _toml` literal.
+
+## [ordered_map.hpp](ordered_map)
+
+Defines `toml::ordered_map`.
+
+## [parser.hpp](parser)
+
+Defines functions to parse files or strings.
+
+## [result.hpp](result)
+
+Defines the `result<T, E>` type for representing success or failure values used as return types in other functions.
+
+## [serializer.hpp](serializer)
+
+Defines the `toml::format` function and `toml::serializer` used for serialization.
+
+## [source_location.hpp](source_location)
+
+Defines the `source_location` type used for error information, pointing to a location within a file.
+
+## [spec.hpp](spec)
+
+Defines the `toml::semantic_version` and `toml::spec` types to control TOML language version information and feature flags.
+
+## [toml.hpp](toml)
+
+`toml.hpp` includes all other headers, making all toml11 features available.
+
+## [toml_fwd.hpp](toml_fwd)
+
+`toml_fwd.hpp` contains forward declarations of structs defined in toml11 and macro definitions.
+
+## [types.hpp](types)
+
+Defines the `toml::type_config` type for controlling the types held by `toml::value`.
+
+## [value.hpp](value)
+
+Defines the `toml::value` type.
+
+## [value_t.hpp](value_t)
+
+Defines the `toml::value_t` enumeration.
+
+## [version.hpp](version)
+
+Defines the version information for toml11.
+
+## [visit.hpp](visit)
+
+Defines the `toml::visit` function to apply functions to the values held by `toml::value`.
+
+## Notes
+
+Functions not explicitly mentioned here (mostly those defined under `namespace toml::detail` or `namespace toml::cxx`) are available by inspecting the source code but are not guaranteed to maintain their interface across future versions (including patch version updates).

docs/content.en/docs/reference/color.md

@@ -0,0 +1,138 @@
++++
+title = "color.hpp"
+type  = "docs"
++++
+
+# color.hpp
+
+In `color.hpp`, functions related to colorizing error messages are defined.
+
+Colors are specified using ANSI escape code.
+In terminals or other output destinations that do not support ANSI escape code, the output may become difficult to read.
+
+## Macros
+
+```cpp
+TOML11_COLORIZE_ERROR_MESSAGE
+```
+
+If this macro is defined during compilation (`-DTOML11_COLORIZE_ERROR_MESASGE`), error messages are colored by default.
+
+If not defined, colors are not applied by default. You need to specify them using `toml::color::enable()`.
+
+## Functions
+
+### `enable()`
+
+```cpp
+namespace toml {
+namespace color {
+void enable();
+} // color
+} // toml
+```
+
+Enables colorization using ANSI escape code.
+
+#### Example
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::color::enable(); // All subsequent errors will be colored.
+    const auto input = toml::parse("input.toml");
+    return 0;
+}
+```
+
+### `disable()`
+
+```cpp
+namespace toml {
+namespace color {
+void disable();
+} // color
+} // toml
+```
+
+Disables colorization using ANSI escape code.
+
+#### Example
+
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::color::disable(); // All subsequent errors will not be colored.
+    const auto input = toml::parse("input.toml");
+    return 0;
+}
+```
+
+### `should_color()`
+
+```cpp
+namespace toml {
+namespace color {
+bool should_color();
+} // color
+} // toml
+```
+
+Returns `true` if colorization is enabled, `false` otherwise.
+
+#### Example
+
+```cpp
+#include <toml.hpp>
+#include <iomanip>
+#include <iostream>
+
+int main()
+{
+    std::cout << "colorized? : " << std::boolalpha << toml::color::should_color() << std::endl;
+    return 0;
+}
+```
+
+## Manipulators
+
+```cpp
+namespace toml {
+namespace color {
+std::ostream& reset  (std::ostream&);
+std::ostream& bold   (std::ostream&);
+std::ostream& grey   (std::ostream&);
+std::ostream& gray   (std::ostream&);
+std::ostream& red    (std::ostream&);
+std::ostream& green  (std::ostream&);
+std::ostream& yellow (std::ostream&);
+std::ostream& blue   (std::ostream&);
+std::ostream& magenta(std::ostream&);
+std::ostream& cyan   (std::ostream&);
+std::ostream& white  (std::ostream&);
+} // color
+} // toml
+```
+
+Colorizes the foreground with ANSI escape code.
+
+#### Example
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+int main()
+{
+    std::cout << toml::color::red << "red!" << toml::color::reset << std::endl;
+    return 0;
+}
+```
+
+# Related
+
+- [error_info.hpp]({{<ref "error_info.md">}})

docs/content.en/docs/reference/comments.md

@@ -0,0 +1,776 @@
++++
+title = "comments.hpp"
+type  = "docs"
++++
+
+# comments.hpp
+
+In `comments.hpp`, comment containers are provided.
+
+# `toml::preserve_comments`
+
+`preserve_comments` is a container that preserves comments.
+
+It has all the member functions of `std::vector<std::string>`.
+
+Comments are preserved as `std::string`.
+If the comment does not start with `#`, it will be prefixed with `#` during output.
+However, this prefixing is not done when adding comments to the container.
+
+Spaces are not automatically added, so if you want a space immediately after `#`,
+either start the comment with a space or pass the comment with `#`.
+
+```cpp
+namespace toml
+{
+class preserve_comments;
+
+bool operator==(const preserve_comments&, const preserve_comments&);
+bool operator!=(const preserve_comments&, const preserve_comments&);
+bool operator< (const preserve_comments&, const preserve_comments&);
+bool operator<=(const preserve_comments&, const preserve_comments&);
+bool operator> (const preserve_comments&, const preserve_comments&);
+bool operator>=(const preserve_comments&, const preserve_comments&);
+
+void swap(preserve_comments&,        preserve_comments&);
+void swap(preserve_comments&,        std::vector<std::string>&);
+void swap(std::vector<std::string>&, preserve_comments&);
+
+std::ostream& operator<<(std::ostream&, const preserve_comments&);
+} //toml
+```
+
+## Member types
+
+```cpp
+using container_type         = std::vector<std::string>;
+using size_type              = container_type::size_type;
+using difference_type        = container_type::difference_type;
+using value_type             = container_type::value_type;
+using reference              = container_type::reference;
+using const_reference        = container_type::const_reference;
+using pointer                = container_type::pointer;
+using const_pointer          = container_type::const_pointer;
+using iterator               = container_type::iterator;
+using const_iterator         = container_type::const_iterator;
+using reverse_iterator       = container_type::reverse_iterator;
+using const_reverse_iterator = container_type::const_reverse_iterator;
+```
+
+## Member Functions
+
+### Default Constructor
+
+```cpp
+preserve_comments() = default;
+```
+
+Constructs an empty `preserve_comments`.
+
+### Copy and Move Constructors
+
+```cpp
+preserve_comments(preserve_comments const&) = default;
+preserve_comments(preserve_comments &&)     = default;
+```
+
+Constructs a `preserve_comments` by copying or moving.
+
+### Constructor (`std::vector<std::string>`)
+
+```cpp
+explicit preserve_comments(const std::vector<std::string>& c);
+explicit preserve_comments(std::vector<std::string>&& c);
+```
+
+Constructs a `preserve_comments` holding the contents of `std::vector<std::string>`.
+
+### Constructor (`discard_comments`)
+
+```cpp
+explicit preserve_comments(const discard_comments&);
+```
+
+Constructs an empty `preserve_comments`.
+
+### Constructor (`Iterator`)
+
+```cpp
+template<typename InputIterator>
+preserve_comments(InputIterator first, InputIterator last);
+```
+
+Constructs a `preserve_comments` from the range represented by `InputIterator` pointing to `std::string`.
+
+### Constructor (`std::initializer_list`)
+
+```cpp
+preserve_comments(std::initializer_list<std::string> x);
+```
+
+Constructs a `preserve_comments` from the range represented by `std::initializer_list<std::string>`.
+
+### Constructor (Size Specified)
+
+```cpp
+explicit preserve_comments(size_type n);
+preserve_comments(size_type n, const std::string& x);
+```
+
+Constructs a `preserve_comments` with `n` comments.
+
+If a `std::string` is passed, it replicates that comment `n` times.
+
+### Destructor
+
+```cpp
+~preserve_comments() = default;
+```
+
+Destroys the `preserve_comments`.
+
+### `operator=(preserve_comments)`
+
+```cpp
+preserve_comments& operator=(preserve_comments const&) = default;
+preserve_comments& operator=(preserve_comments &&)     = default;
+```
+
+Assigns a `preserve_comments` by copying or moving.
+
+### `operator=(std::vector<std::string>)`
+
+```cpp
+preserve_comments& operator=(const std::vector<std::string>& c);
+preserve_comments& operator=(std::vector<std::string>&& c);
+```
+
+Assigns a `std::vector<std::string>` by copying or moving.
+
+### `assign`
+
+```cpp
+template<typename InputIterator>
+void assign(InputIterator first, InputIterator last);
+void assign(std::initializer_list<std::string> ini);
+void assign(size_type n, const std::string& val);
+```
+
+The same as `std::vector<std::string>::assign`.
+
+### `insert`
+
+```cpp
+iterator insert(const_iterator p, const std::string& x);
+iterator insert(const_iterator p, std::string&&      x);
+iterator insert(const_iterator p, size_type n, const std::string& x);
+template<typename InputIterator>
+iterator insert(const_iterator p, InputIterator first, InputIterator last);
+iterator insert(const_iterator p, std::initializer_list<std::string> ini);
+```
+
+The same as `std::vector<std::string>::insert`.
+
+### `emplace`
+
+```cpp
+template<typename ... Ts>
+iterator emplace(const_iterator p, Ts&& ... args);
+```
+
+The same as `std::vector<std::string>::emplace`.
+
+### `erase`
+
+```cpp
+iterator erase(const_iterator pos);
+iterator erase(const_iterator first, const_iterator last);
+```
+
+The same as `std::vector<std::string>::erase`.
+
+### `swap`
+
+```cpp
+void swap(preserve_comments& other);
+```
+
+Swaps the comments.
+
+### `push_back`
+
+```cpp
+void push_back(const std::string& v);
+void push_back(std::string&&      v);
+```
+
+The same as `std::vector<std::string>::push_back`.
+
+### `pop_back`
+
+```cpp
+void pop_back();
+```
+
+The same as `std::vector<std::string>::pop_back`.
+
+### `emplace_back`
+
+```cpp
+template<typename ... Ts>
+void emplace_back(Ts&& ... args);
+```
+
+The same as `std::vector<std::string>::emplace_back`.
+
+### `clear`
+
+```cpp
+void clear();
+```
+
+The same as `std::vector<std::string>::clear`.
+
+### `size`
+
+```cpp
+size_type size() const noexcept;
+```
+
+The same as `std::vector<std::string>::size`.
+
+### `max_size`
+
+```cpp
+size_type max_size() const noexcept;
+```
+
+The same as `std::vector<std::string>::max_size`.
+
+### `capacity`
+
+```cpp
+size_type capacity() const noexcept;
+```
+
+The same as `std::vector<std::string>::capacity`.
+
+### `empty`
+
+```cpp
+bool empty() const noexcept;
+```
+
+The same as `std::vector<std::string>::empty`.
+
+### `reserve`
+
+```cpp
+void reserve(size_type n);
+```
+
+The same as `std::vector<std::string>::reserve`.
+
+### `resize`
+
+```cpp
+void resize(size_type n);
+void resize(size_type n, const std::string& c);
+```
+
+The same as `std::vector<std::string>::resize`.
+
+### `shrink_to_fit`
+
+```cpp
+void shrink_to_fit();
+```
+
+The same as `std::vector<std::string>::shrink_to_fit`.
+
+### `operator[]`
+
+```cpp
+reference       operator[](const size_type n)       noexcept;
+const_reference operator[](const size_type n) const noexcept;
+```
+
+The same as `std::vector<std::string>::operator[]`.
+
+### `at`
+
+```cpp
+reference       at(const size_type n)      ;
+const_reference at(const size_type n) const;
+```
+
+The same as `std::vector<std::string>::at`.
+
+### `front`
+
+```cpp
+reference       front()       noexcept;
+const_reference front() const noexcept;
+```
+
+The same as `std::vector<std::string>::front`.
+
+### `back`
+
+```cpp
+reference       back()        noexcept;
+const_reference back()  const noexcept;
+```
+
+The same as `std::vector<std::string>::back`.
+
+### `data`
+
+```cpp
+pointer         data()        noexcept;
+const_pointer   data()  const noexcept;
+```
+
+The same as `std::vector<std::string>::data`.
+
+### `begin/end`
+
+```cpp
+iterator       begin()        noexcept;
+iterator       end()          noexcept;
+const_iterator begin()  const noexcept;
+const_iterator end()    const noexcept;
+const_iterator cbegin() const noexcept;
+const_iterator cend()   const noexcept;
+```
+
+The same as `std::vector<std::string>::begin/end`.
+
+### `rbegin/rend`
+
+```cpp
+reverse_iterator       rbegin()        noexcept;
+reverse_iterator       rend()          noexcept;
+const_reverse_iterator rbegin()  const noexcept;
+const_reverse_iterator rend()    const noexcept;
+const_reverse_iterator crbegin() const noexcept;
+const_reverse_iterator crend()   const noexcept;
+```
+
+The same as `std::vector<std::string>::rbegin/rend`
+
+## non-member functions
+
+### Comparison operator
+
+```cpp
+bool operator==(const preserve_comments&, const preserve_comments&);
+bool operator!=(const preserve_comments&, const preserve_comments&);
+bool operator< (const preserve_comments&, const preserve_comments&);
+bool operator<=(const preserve_comments&, const preserve_comments&);
+bool operator> (const preserve_comments&, const preserve_comments&);
+bool operator>=(const preserve_comments&, const preserve_comments&);
+```
+
+It compares two `preserve_comments` in the same way as `std::vector<std::string>`.
+
+### `swap`
+
+```cpp
+void swap(preserve_comments&,        preserve_comments&);
+void swap(preserve_comments&,        std::vector<std::string>&);
+void swap(std::vector<std::string>&, preserve_comments&);
+```
+
+### Stream operator
+
+```cpp
+std::ostream& operator<<(std::ostream&, const preserve_comments&);
+```
+
+Outputs as TOML comments.
+
+If the first character is not `#`, it adds `#`.
+
+# `toml::discard_comments`
+
+`discard_comments` serves as a container for discarding comments.
+
+It encompasses all the member functions of `std::vector<std::string>`, but invoking functions that modify the content has no effect, leaving it perpetually empty.
+
+```cpp
+namespace toml
+{
+class discard_comments;
+
+bool operator==(const discard_comments&, const discard_comments&);
+bool operator!=(const discard_comments&, const discard_comments&);
+bool operator< (const discard_comments&, const discard_comments&);
+bool operator<=(const discard_comments&, const discard_comments&);
+bool operator> (const discard_comments&, const discard_comments&);
+bool operator>=(const discard_comments&, const discard_comments&);
+
+void swap(discard_comments&, discard_comments&);
+
+std::ostream& operator<<(std::ostream&, const discard_comments&);
+} //toml
+```
+
+## Member types
+
+```cpp
+// container_type is not defined
+using size_type              = std::size_t;
+using difference_type        = std::ptrdiff_t;
+using value_type             = std::string;
+using reference              = std::string&;
+using const_reference        = std::string const&;
+using pointer                = std::string*;
+using const_pointer          = std::string const*;
+using iterator               = /* internal type: empty-iterator */
+using const_iterator         = /* internal type: empty-iterator */
+using reverse_iterator       = /* internal type: empty-iterator */
+using const_reverse_iterator = /* internal type: empty-iterator */
+```
+
+### Default Constructor
+
+```cpp
+discard_comments() = default;
+```
+
+Constructs an empty `discard_comments`.
+
+### Copy / Move Constructor
+
+```cpp
+discard_comments(discard_comments const&) = default;
+discard_comments(discard_comments &&)     = default;
+```
+
+Constructs a `discard_comments` by copying or moving.
+
+### Constructor(`std::vector<std::string>`)
+
+```cpp
+explicit discard_comments(const std::vector<std::string>& c);
+explicit discard_comments(std::vector<std::string>&& c);
+```
+
+Constructs an empty `discard_comments`. Arguments are ignored.
+
+### Constructor(`preserve_comments`)
+
+```cpp
+explicit discard_comments(const preserve_comments&);
+```
+
+Constructs an empty `discard_comments`. Arguments are ignored.
+
+### Constructor(`Iterator`)
+
+```cpp
+template<typename InputIterator>
+discard_comments(InputIterator first, InputIterator last);
+```
+
+Constructs an empty `discard_comments`. Arguments are ignored.
+
+### Constructor(`std::initializer_list`)
+
+```cpp
+discard_comments(std::initializer_list<std::string> x);
+```
+
+Constructs an empty `discard_comments`. Arguments are ignored.
+
+### Constructor(サイズ指定)
+
+```cpp
+explicit discard_comments(size_type n);
+discard_comments(size_type n, const std::string& x);
+```
+
+Constructs an empty `discard_comments`. Arguments are ignored.
+
+### Destructor
+
+```cpp
+~discard_comments() = default;
+```
+
+Destroys `discard_comments`.
+
+### `operator=(discard_comments)`
+
+```cpp
+discard_comments& operator=(discard_comments const&) = default;
+discard_comments& operator=(discard_comments &&)     = default;
+```
+
+Assigns `discard_comments` by copying or moving.
+
+### `operator=(std::vector<std::string>)`
+
+```cpp
+discard_comments& operator=(const std::vector<std::string>& c);
+discard_comments& operator=(std::vector<std::string>&& c);
+```
+
+Does nothing.
+
+### `assign`
+
+```cpp
+template<typename InputIterator>
+void assign(InputIterator first, InputIterator last);
+void assign(std::initializer_list<std::string> ini);
+void assign(size_type n, const std::string& val);
+```
+
+Does nothing.
+
+### `insert`
+
+```cpp
+iterator insert(const_iterator p, const std::string& x);
+iterator insert(const_iterator p, std::string&&      x);
+iterator insert(const_iterator p, size_type n, const std::string& x);
+template<typename InputIterator>
+iterator insert(const_iterator p, InputIterator first, InputIterator last);
+iterator insert(const_iterator p, std::initializer_list<std::string> ini);
+```
+
+Does nothing.
+
+### `emplace`
+
+```cpp
+template<typename ... Ts>
+iterator emplace(const_iterator p, Ts&& ... args);
+```
+
+Does nothing.
+
+### `erase`
+
+```cpp
+iterator erase(const_iterator pos);
+iterator erase(const_iterator first, const_iterator last);
+```
+
+Does nothing.
+
+### `swap`
+
+```cpp
+void swap(discard_comments& other);
+```
+
+Swaps two `discard_comments`. Effectively it does nothing.
+
+### `push_back`
+
+```cpp
+void push_back(const std::string& v);
+void push_back(std::string&&      v);
+```
+
+Does nothing.
+
+### `pop_back`
+
+```cpp
+void pop_back();
+```
+
+Does nothing.
+
+### `emplace_back`
+
+```cpp
+template<typename ... Ts>
+void emplace_back(Ts&& ... args);
+```
+
+Does nothing.
+
+### `clear`
+
+```cpp
+void clear();
+```
+
+Does nothing.
+
+### `size`
+
+```cpp
+size_type size() const noexcept;
+```
+
+Returns `0`.
+
+### `max_size`
+
+```cpp
+size_type max_size() const noexcept;
+```
+
+Returns `0`.
+
+### `capacity`
+
+```cpp
+size_type capacity() const noexcept;
+```
+
+Returns `0`.
+
+### `empty`
+
+```cpp
+bool empty() const noexcept;
+```
+
+Returns `true`.
+
+### `reserve`
+
+```cpp
+void reserve(size_type n);
+```
+
+Does nothing.
+
+### `resize`
+
+```cpp
+void resize(size_type n);
+void resize(size_type n, const std::string& c);
+```
+
+Does nothing.
+
+### `shrink_to_fit`
+
+```cpp
+void shrink_to_fit();
+```
+
+Does nothing.
+
+### `operator[]`
+
+```cpp
+reference       operator[](const size_type n)       noexcept;
+const_reference operator[](const size_type n) const noexcept;
+```
+
+Causes undefined behavior.
+
+### `at`
+
+```cpp
+reference       at(const size_type n)      ;
+const_reference at(const size_type n) const;
+```
+
+Throws `std::out_of_range`.
+
+### `front`
+
+```cpp
+reference       front()       noexcept;
+const_reference front() const noexcept;
+```
+
+Causes undefined behavior.
+
+### `back`
+
+```cpp
+reference       back()        noexcept;
+const_reference back()  const noexcept;
+```
+
+Causes undefined behavior.
+
+### `data`
+
+```cpp
+pointer         data()        noexcept;
+const_pointer   data()  const noexcept;
+```
+
+Returns `nullptr`.
+
+### `begin/end`
+
+```cpp
+iterator       begin()        noexcept;
+iterator       end()          noexcept;
+const_iterator begin()  const noexcept;
+const_iterator end()    const noexcept;
+const_iterator cbegin() const noexcept;
+const_iterator cend()   const noexcept;
+```
+
+Returns an internally defined `empty-iterator`.
+
+The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.
+
+Accessing the target of the `empty-iterator` always calls `std::terminate`.
+
+
+### `rbegin/rend`
+
+```cpp
+reverse_iterator       rbegin()        noexcept;
+reverse_iterator       rend()          noexcept;
+const_reverse_iterator rbegin()  const noexcept;
+const_reverse_iterator rend()    const noexcept;
+const_reverse_iterator crbegin() const noexcept;
+const_reverse_iterator crend()   const noexcept;
+```
+
+Returns an internally defined `empty-iterator`.
+
+The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.
+
+Accessing the target of the `empty-iterator` always calls `std::terminate`.
+
+## non-member functions
+
+### Comparison operator
+
+```cpp
+bool operator==(const discard_comments&, const discard_comments&);
+bool operator!=(const discard_comments&, const discard_comments&);
+bool operator< (const discard_comments&, const discard_comments&);
+bool operator<=(const discard_comments&, const discard_comments&);
+bool operator> (const discard_comments&, const discard_comments&);
+bool operator>=(const discard_comments&, const discard_comments&);
+```
+
+All the instances of `discard_comments` are the same value. `operator==` returns `true`, `operator=!` returns `false`.
+
+### `swap`
+
+```cpp
+void swap(discard_comments&, discard_comments&);
+```
+
+Swaps `discard_comments`. Effectively it does nothing.
+
+### Stream operator
+
+```cpp
+std::ostream& operator<<(std::ostream&, const discard_comments&);
+```
+
+Outputs nothing.
+
+# Related
+
+- [value.hpp]({{<ref "value.md">}})

docs/content.en/docs/reference/conversion.md

@@ -0,0 +1,33 @@
++++
+title = "conversion.hpp"
+type  = "docs"
++++
+
+# conversion.hpp
+
+Provides macros to automatically define conversion functions for supporting user-defined types with `toml::get` and `toml::find`.
+
+```cpp
+TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(NAME, ...)
+```
+
+## Example
+
+```cpp
+namespace foo
+{
+struct Foo
+{
+    std::string s;
+    double      d;
+    int         i;
+};
+} // foo
+
+TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(foo::Foo, s, d, i)
+```
+
+# Related
+
+- [from.hpp]({{<ref "from.md">}})
+- [into.hpp]({{<ref "into.md">}})

docs/content.en/docs/reference/datetime.md

@@ -0,0 +1,779 @@
++++
+title = "datetime.hpp"
+type  = "docs"
++++
+
+# datetime.hpp
+
+Defines a class that stores date and time information used in TOML's `datetime`.
+
+# `enum class month_t`
+
+Enum class to specify months.
+
+Due to its relationship with `std::tm`, `local_date` treats January as `0`.
+To avoid confusion, `month_t` allows specification of months by their names.
+
+```cpp
+namespace toml
+{
+enum class month_t : std::uint8_t
+{
+    Jan =  0,
+    Feb =  1,
+    Mar =  2,
+    Apr =  3,
+    May =  4,
+    Jun =  5,
+    Jul =  6,
+    Aug =  7,
+    Sep =  8,
+    Oct =  9,
+    Nov = 10,
+    Dec = 11
+};
+}
+```
+
+# `local_date`
+
+`local_date` holds a date.
+
+`year` represents the year in AD. For `month`, January is represented as `0` to align with `std::tm`. `day` holds the day of the month.
+
+```cpp
+namespace toml
+{
+struct local_date
+{
+    std::int16_t year;
+    std::uint8_t month;
+    std::uint8_t day;
+
+    local_date() = default;
+    ~local_date() = default;
+    local_date(local_date const&) = default;
+    local_date(local_date&&)      = default;
+    local_date& operator=(local_date const&) = default;
+    local_date& operator=(local_date&&)      = default;
+
+    local_date(int y, month_t m, int d);
+    explicit local_date(const std::tm& t);
+    explicit local_date(const std::chrono::system_clock::time_point& tp);
+    explicit local_date(const std::time_t t);
+
+    operator std::chrono::system_clock::time_point() const;
+    operator std::time_t() const;
+};
+
+bool operator==(const local_date&, const local_date&);
+bool operator!=(const local_date&, const local_date&);
+bool operator< (const local_date&, const local_date&);
+bool operator<=(const local_date&, const local_date&);
+bool operator> (const local_date&, const local_date&);
+bool operator>=(const local_date&, const local_date&);
+
+std::ostream& operator<<(std::ostream& os, const local_date& date);
+std::string to_string(const local_date& date);
+}
+```
+
+## Member Variables
+
+### `year`
+
+```cpp
+std::int16_t year;
+```
+
+Represents the year in AD. There's no offset. `2024` is simply `2024`.
+
+### `month`
+
+```cpp
+std::uint8_t month;
+```
+
+Represents the month. To align with `std::tm`, January is `0`, February is `1`, and so on.
+
+To avoid confusion, use `month_t` during construction.
+
+### `day`
+
+```cpp
+std::uint8_t day;
+```
+
+Represents the day of the month. The first day is `1`.
+
+## Member Functions
+
+### Constructor
+
+```cpp
+local_date() = default;
+```
+
+Uses the default implementation.
+
+### Destructor
+
+```cpp
+~local_date() = default;
+```
+
+Uses the default implementation.
+
+### Copy and Move Constructors
+
+```cpp
+local_date(local_date const&) = default;
+local_date(local_date&&)      = default;
+```
+
+Uses the default implementations.
+
+### Copy and Move Assignment Operators
+
+```cpp
+local_date& operator=(local_date const&) = default;
+local_date& operator=(local_date&&)      = default;
+```
+
+Uses the default implementations.
+
+### Constructor (`int year, month_t month, int day`)
+
+```cpp
+local_date(int y, month_t m, int d);
+```
+
+Constructs a `local_date` from the specified values.
+
+Does not perform boundary checks.
+
+### Constructor (`std::tm`)
+
+```cpp
+local_date(const std::tm&);
+```
+
+Constructs a `local_date` from the specified `std::tm` value.
+
+### Constructor (`std::chrono::system_clock::time_point`)
+
+```cpp
+local_date(const std::chrono::system_clock::time_point&);
+```
+
+Constructs a `local_date` from the specified `std::chrono::system_clock::time_point` value.
+
+Time zone is determined by the environment.
+
+### Constructor (`std::time_t`)
+
+```cpp
+local_date(const std::time_t);
+```
+
+Constructs a `local_date` from the specified `std::time_t` value.
+
+Time zone is determined by the environment.
+
+### `operator std::chrono::system_clock::time_point`
+
+```cpp
+operator std::chrono::system_clock::time_point() const;
+```
+
+Converts to `std::chrono::system_clock::time_point`.
+
+Time zone is determined by the environment.
+
+Time is set to 0 hours and 0 minutes.
+
+### `operator std::time_t`
+
+```cpp
+operator std::time_t() const;
+```
+
+Converts to `std::time_t`.
+
+Time zone is determined by the execution environment.
+
+Time is set to 0 hours and 0 minutes.
+
+## Non-member Functions
+
+### Comparison Operators
+
+```cpp
+bool operator==(const local_date&, const local_date&);
+bool operator!=(const local_date&, const local_date&);
+bool operator< (const local_date&, const local_date&);
+bool operator<=(const local_date&, const local_date&);
+bool operator> (const local_date&, const local_date&);
+bool operator>=(const local_date&, const local_date&);
+```
+
+Compares two dates.
+
+### Stream Operators
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const local_date& date);
+```
+
+Outputs in the default TOML format.
+
+### `to_string`
+
+```cpp
+std::string to_string(const local_date& date);
+```
+
+Converts to a string in the default TOML format.
+
+# `local_time`
+
+```cpp
+namespace toml
+{
+struct local_time
+{
+    std::uint8_t  hour;        // [0, 23]
+    std::uint8_t  minute;      // [0, 59]
+    std::uint8_t  second;      // [0, 60]
+    std::uint16_t millisecond; // [0, 999]
+    std::uint16_t microsecond; // [0, 999]
+    std::uint16_t nanosecond;  // [0, 999]
+
+    local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
+
+    explicit local_time(const std::tm& t);
+
+    template<typename Rep, typename Period>
+    explicit local_time(const std::chrono::duration<Rep, Period>& t);
+
+    operator std::chrono::nanoseconds() const;
+
+    local_time() = default;
+    ~local_time() = default;
+    local_time(local_time const&) = default;
+    local_time(local_time&&)      = default;
+    local_time& operator=(local_time const&) = default;
+    local_time& operator=(local_time&&)      = default;
+};
+
+bool operator==(const local_time& lhs, const local_time& rhs);
+bool operator!=(const local_time& lhs, const local_time& rhs);
+bool operator< (const local_time& lhs, const local_time& rhs);
+bool operator<=(const local_time& lhs, const local_time& rhs);
+bool operator> (const local_time& lhs, const local_time& rhs);
+bool operator>=(const local_time& lhs, const local_time& rhs);
+
+std::ostream& operator<<(std::ostream& os, const local_time& time);
+std::string to_string(const local_time& time);
+}
+```
+
+## Member Values
+
+### `hour`
+
+```cpp
+std::uint8_t  hour;
+```
+
+Represents the hour. Values range from `0` to `23`.
+
+### `minute`
+
+```cpp
+std::uint8_t  minute;      // [0, 59]
+```
+
+Represents the minute. Values range from `0` to `59`.
+
+### `second`
+
+```cpp
+std::uint8_t  second;      // [0, 60]
+```
+
+Represents the second. Values range from `0` to `60`.
+
+### `millisecond`
+
+```cpp
+std::uint16_t millisecond; // [0, 999]
+```
+
+Represents the millisecond. Values range from `0` to `999`.
+
+### `microsecond`
+
+```cpp
+std::uint16_t microsecond; // [0, 999]
+```
+
+Represents the microsecond. Values range from `0` to `999`.
+
+### `nanosecond`
+
+```cpp
+std::uint16_t nanosecond;  // [0, 999]
+```
+
+Represents the nanosecond. Values range from `0` to `999`.
+
+## Member Functions
+
+### default constructor
+
+```cpp
+local_time() = default;
+```
+
+Initializes all values to `0`.
+
+### constructor (h, m, s, ms = 0, us = 0, ns = 0)
+
+```cpp
+local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
+```
+
+Constructs using the specified time components.
+
+No boundary checks are performed.
+
+### constructor(`std::tm`)
+
+```cpp
+explicit local_time(const std::tm& t);
+```
+
+Constructs using `tm_hour`, `tm_min`, and `tm_sec` from `std::tm`.
+
+Subseconds are initialized to `0`.
+
+### constructor(`std::chrono::duration`)
+
+```cpp
+template<typename Rep, typename Period>
+explicit local_time(const std::chrono::duration<Rep, Period>& t);
+```
+
+Constructs as the time of day from `0` hours of the day specified by `duration`.
+
+### `operator std::chrono::nanoseconds`
+
+```cpp
+operator std::chrono::nanoseconds() const;
+```
+
+Converts to `std::chrono::nanoseconds`.
+
+## Non-member Functions
+
+### Comparison Operators
+
+```cpp
+bool operator==(const local_time& lhs, const local_time& rhs);
+bool operator!=(const local_time& lhs, const local_time& rhs);
+bool operator< (const local_time& lhs, const local_time& rhs);
+bool operator<=(const local_time& lhs, const local_time& rhs);
+bool operator> (const local_time& lhs, const local_time& rhs);
+bool operator>=(const local_time& lhs, const local_time& rhs);
+```
+
+Compares based on time values.
+
+### Stream Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const local_time& time);
+```
+
+Outputs in the default TOML format.
+
+### `to_string`
+
+```cpp
+std::string to_string(const local_time& time);
+```
+
+Converts to a string in the default TOML format.
+
+# `time_offset`
+
+```cpp
+namespace toml
+{
+struct time_offset
+{
+    std::int8_t hour{0};   // [-12, 12]
+    std::int8_t minute{0}; // [-59, 59]
+
+    time_offset(int h, int m);
+
+    operator std::chrono::minutes() const;
+
+    time_offset() = default;
+    ~time_offset() = default;
+    time_offset(time_offset const&) = default;
+    time_offset(time_offset&&)      = default;
+    time_offset& operator=(time_offset const&) = default;
+    time_offset& operator=(time_offset&&)      = default;
+};
+
+bool operator==(const time_offset&, const time_offset&);
+bool operator!=(const time_offset&, const time_offset&);
+bool operator< (const time_offset&, const time_offset&);
+bool operator<=(const time_offset&, const time_offset&);
+bool operator> (const time_offset&, const time_offset&);
+bool operator>=(const time_offset&, const time_offset&);
+
+std::ostream& operator<<(std::ostream& os, const time_offset& offset);
+std::string to_string(const time_offset& offset);
+}
+```
+
+## Member Variables
+
+### `hour`
+
+```cpp
+std::int8_t hour{0};   // [-12, 12]
+```
+
+Represents the hour offset, ranging from -12 to +12.
+
+### `minute`
+
+```cpp
+std::int8_t minute{0}; // [-59, 59]
+```
+
+Represents the minute offset, ranging from -59 to +59.
+
+## Member Functions
+
+### Constructor
+
+```cpp
+time_offset(int h, int m);
+```
+
+Constructs with given hours and minutes.
+
+No boundary checking is performed.
+
+### `operator std::chrono::minutes`
+
+```cpp
+operator std::chrono::minutes() const;
+```
+
+Converts to `std::chrono::minutes`.
+
+## Non-member Functions
+
+### Comparison Operators
+
+```cpp
+bool operator==(const time_offset&, const time_offset&);
+bool operator!=(const time_offset&, const time_offset&);
+bool operator< (const time_offset&, const time_offset&);
+bool operator<=(const time_offset&, const time_offset&);
+bool operator> (const time_offset&, const time_offset&);
+bool operator>=(const time_offset&, const time_offset&);
+```
+
+Compares based on time length.
+
+### Stream Output Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const time_offset&);
+```
+
+Outputs in the default TOML format.
+
+### `to_string`
+
+```cpp
+std::string to_string(const time_offset&);
+```
+
+Converts to a string in the default TOML format.
+
+
+# `local_datetime`
+
+```cpp
+namespace toml
+{
+struct local_datetime
+{
+    local_date date;
+    local_time time;
+
+    local_datetime(local_date d, local_time t);
+
+    explicit local_datetime(const std::tm& t);
+    explicit local_datetime(const std::chrono::system_clock::time_point& tp);
+    explicit local_datetime(const std::time_t t);
+
+    operator std::chrono::system_clock::time_point() const;
+    operator std::time_t() const;
+
+    local_datetime() = default;
+    ~local_datetime() = default;
+    local_datetime(local_datetime const&) = default;
+    local_datetime(local_datetime&&)      = default;
+    local_datetime& operator=(local_datetime const&) = default;
+    local_datetime& operator=(local_datetime&&)      = default;
+};
+
+bool operator==(const local_datetime&, const local_datetime&);
+bool operator!=(const local_datetime&, const local_datetime&);
+bool operator< (const local_datetime&, const local_datetime&);
+bool operator<=(const local_datetime&, const local_datetime&);
+bool operator> (const local_datetime&, const local_datetime&);
+bool operator>=(const local_datetime&, const local_datetime&);
+
+std::ostream& operator<<(std::ostream& os, const local_datetime& dt);
+std::string to_string(const local_datetime& dt);
+}
+```
+
+## Member Variables
+
+### `local_date date`
+
+```cpp
+local_date date;
+```
+
+Stores the date component data.
+
+### `local_time time`
+
+```cpp
+local_time time;
+```
+
+Stores the time component data.
+
+## Member Functions
+
+### Default Constructor
+
+Constructs both `date` and `time` with default values.
+
+### Constructor (`local_date, local_time`)
+
+Constructs with the specified `date` and `time`.
+
+### Constructor (`std::tm`)
+
+Constructs from `std::tm`.
+
+The timezone is selected based on the execution environment.
+
+### Constructor (`std::chrono::system_clock::time_point`)
+
+Constructs from `std::chrono::system_clock::time_point`.
+
+The timezone is selected based on the execution environment.
+
+### Constructor (`std::time_t`)
+
+Constructs from `std::time_t`.
+
+The timezone is selected based on the execution environment.
+
+### `operator std::chrono::system_clock::time_point`
+
+Converts to `std::chrono::system_clock::time_point`.
+
+### `operator std::time_t`
+
+Converts to `std::time_t`.
+
+## Non-member Functions
+
+### Comparison Operators
+
+```cpp
+bool operator==(const local_datetime&, const local_datetime&);
+bool operator!=(const local_datetime&, const local_datetime&);
+bool operator< (const local_datetime&, const local_datetime&);
+bool operator<=(const local_datetime&, const local_datetime&);
+bool operator> (const local_datetime&, const local_datetime&);
+bool operator>=(const local_datetime&, const local_datetime&);
+```
+
+Compares based on chronological order.
+
+### Stream Output Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const local_datetime&);
+```
+
+Outputs in the default TOML format.
+
+### `to_string`
+
+```cpp
+std::string to_string(const local_datetime&);
+```
+
+Converts to a string in the default TOML format.
+
+# `offset_datetime`
+
+```cpp
+namespace toml
+{
+struct offset_datetime
+{
+    local_date  date;
+    local_time  time;
+    time_offset offset;
+
+    offset_datetime(local_date d, local_time t, time_offset o);
+    offset_datetime(const local_datetime& dt, time_offset o);
+    explicit offset_datetime(const local_datetime& ld);
+    explicit offset_datetime(const std::chrono::system_clock::time_point& tp);
+    explicit offset_datetime(const std::time_t& t);
+    explicit offset_datetime(const std::tm& t);
+
+    operator std::chrono::system_clock::time_point() const;
+    operator std::time_t() const;
+
+    offset_datetime() = default;
+    ~offset_datetime() = default;
+    offset_datetime(offset_datetime const&) = default;
+    offset_datetime(offset_datetime&&)      = default;
+    offset_datetime& operator=(offset_datetime const&) = default;
+    offset_datetime& operator=(offset_datetime&&)      = default;
+};
+
+bool operator==(const offset_datetime&, const offset_datetime&);
+bool operator!=(const offset_datetime&, const offset_datetime&);
+bool operator< (const offset_datetime&, const offset_datetime&);
+bool operator<=(const offset_datetime&, const offset_datetime&);
+bool operator> (const offset_datetime&, const offset_datetime&);
+bool operator>=(const offset_datetime&, const offset_datetime&);
+
+std::ostream& operator<<(std::ostream& os, const offset_datetime& dt);
+std::string to_string(const offset_datetime& dt);
+}
+```
+
+## Member Variables
+
+### `date`
+
+```cpp
+local_date date;
+```
+
+Stores the date component.
+
+### `time`
+
+```cpp
+local_time time;
+```
+
+Stores the time component.
+
+### `offset`
+
+```cpp
+time_offset offset;
+```
+
+Stores the offset component.
+
+## Member Functions
+
+### Default Constructor
+
+Constructs `date`, `time`, and `offset` with default values.
+
+### Constructor (`local_date, local_time, time_offset`)
+
+Constructs with the specified `date`, `time`, and `offset`.
+
+### Constructor (`local_datetime, time_offset`)
+
+Constructs from `local_datetime` and `offset`.
+
+### Constructor (`std::tm`)
+
+Constructs from `std::tm`.
+
+The timezone is UTC (00:00).
+
+### Constructor (`std::chrono::system_clock::time_point`)
+
+Constructs from `std::chrono::system_clock::time_point`.
+
+The timezone is UTC (00:00).
+
+### Constructor (`std::time_t`)
+
+Constructs from `std::time_t`.
+
+The timezone is UTC (00:00).
+
+### `operator std::chrono::system_clock::time_point`
+
+Converts to `std::chrono::system_clock::time_point`.
+
+The timezone is UTC (00:00).
+
+### `operator std::time_t`
+
+Converts to `std::time_t`.
+
+The timezone is UTC (00:00).
+
+## Non-member Functions
+
+### Comparison Operators
+
+```cpp
+bool operator==(const offset_datetime&, const offset_datetime&);
+bool operator!=(const offset_datetime&, const offset_datetime&);
+bool operator< (const offset_datetime&, const offset_datetime&);
+bool operator<=(const offset_datetime&, const offset_datetime&);
+bool operator> (const offset_datetime&, const offset_datetime&);
+bool operator>=(const offset_datetime&, const offset_datetime&);
+```
+
+Compares based on chronological order.
+
+If dates are the same, compares based on timezone order.
+
+### Stream Output Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const offset_datetime&);
+```
+
+Outputs in the default TOML format.
+
+### `to_string`
+
+```cpp
+std::string to_string(const offset_datetime&);
+```
+
+Converts to a string in the default TOML format.

docs/content.en/docs/reference/error_info.md

@@ -0,0 +1,145 @@
++++
+title = "error_info.hpp"
+type  = "docs"
++++
+
+# error_info.hpp
+
+In `error_info.hpp`, definitions for `error_info` and functions to format it are provided.
+
+# `toml::error_info`
+
+```cpp
+namespace toml
+{
+struct error_info
+{
+    error_info(std::string t, source_location l, std::string m, std::string s = "");
+    error_info(std::string t, std::vector<std::pair<source_location, std::string>> l, std::string s = "");
+
+    std::string const& title() const noexcept;
+    std::string &      title()       noexcept;
+
+    std::vector<std::pair<source_location, std::string>> const& locations() const noexcept;
+    void add_locations(source_location loc, std::string msg) noexcept;
+
+    std::string const& suffix() const noexcept;
+    std::string &      suffix()       noexcept;
+};
+
+template<typename ... Ts>
+error_info make_error_info(
+    std::string title, source_location loc, std::string msg, Ts&& ... tail);
+
+std::string format_error(const std::string& errkind, const error_info& err);
+std::string format_error(const error_info& err);
+
+template<typename ... Ts>
+std::string format_error(std::string title,
+                         source_location loc, std::string msg, Ts&& ... tail);
+
+std::ostream& operator<<(std::ostream& os, const error_info& e);
+}
+```
+
+## Member Functions
+
+### Constructor (`title, loc, msg, suffix`)
+
+Constructs `error_info` with specified `title`, location information `loc`, message `msg`, and optional `suffix`.
+
+`suffix` defaults to empty.
+
+### Constructor (`title, [{loc, msg}, ...], suffix`)
+
+Constructs `error_info` with specified `title`, an array of location-message pairs `[{loc, msg}, ...]`, and optional `suffix`.
+
+`suffix` defaults to empty.
+
+### `std::string title()`
+
+Returns the title of the error message.
+
+### `std::vector<std::pair<source_location, std::string>> locations()`
+
+Returns the list of locations where errors occurred along with their respective messages.
+
+Multiple locations can be specified.
+
+### `std::string suffix()`
+
+Returns the suffix message to display at the end, providing hints or additional information.
+
+## Non-Member Functions
+
+### `make_error_info`
+
+```cpp
+template<typename ... Ts>
+error_info make_error_info(
+    std::string title, source_location loc, std::string msg, Ts&& ... tail);
+```
+
+Creates a new `error_info`.
+
+Must be followed by a `msg` related to `source_location` or `basic_value`.
+
+Overloads are added in [`value.hpp`](docs/reference/value#tomlmake_error_info) when passing `toml::basic_value` instead of `source_location`.
+
+Possible to pass `suffix` at the end.
+
+### `format_error`
+
+Formats `error_info` as follows:
+
+```
+{title}
+ --> {locations().at(0).first.file_name()}
+   |
+ 1 | {locations().at(0).first.line()}
+   |         ^-- {locations().at(0).second}
+   |
+ 2 | {locations().at(1).first.line()}
+   |         ^-- {locations().at(1).second}
+{suffix}
+```
+
+If file names differ between two `source_location`, the file name is displayed again.
+
+```cpp
+std::string format_error(const std::string& errkind, const error_info& err);
+std::string format_error(const error_info& err);
+```
+
+Formats `error_info`.
+
+If `errkind` is not provided, a red-bold `[error]` prefix is added before `title`.
+
+If `errkind` is provided (including an empty string), it replaces `[error]`.
+
+```cpp
+namespace toml
+{
+template<typename ... Ts>
+std::string format_error(std::string title,
+                         source_location loc, std::string msg, Ts&& ... tail);
+} // toml
+```
+
+Returns a formatted string using `format_error` for `error_info` created with `make_error_info`.
+
+Overloads are added in [`value.hpp`](docs/reference/value#tomlformat_error) when passing `toml::basic_value` instead of `source_location`.
+
+### Stream Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const error_info& e);
+```
+
+Calls `format_error(e)` and outputs it.
+
+# Related
+
+- [color.hpp](color.md)
+- [parser.hpp](parser.md)
+- [source_location.hpp](source_location.md)

docs/content.en/docs/reference/exception.md

@@ -0,0 +1,40 @@
++++
+title = "exception.hpp"
+type  = "docs"
++++
+
+# exception.hpp
+
+# `toml::exception`
+
+Base class for exception types defined in toml11.
+
+```cpp
+namespace toml
+{
+struct exception : public std::exception
+{
+  public:
+    virtual ~exception() noexcept override = default;
+    virtual const char* what() const noexcept override {return "";}
+};
+} // toml
+```
+
+## Member Functions
+
+### Destructor
+
+```cpp
+virtual ~exception() noexcept override = default;
+```
+
+Override when derived.
+
+### `what`
+
+```cpp
+virtual const char* what() const noexcept override {return "";}
+```
+
+Returns the error message. Override when derived.

docs/content.en/docs/reference/find.md

@@ -0,0 +1,244 @@
++++
+title = "find.hpp"
+type  = "docs"
++++
+
+# find.hpp
+
+This function searches for a value in a `toml::value` and performs type conversion if necessary.
+
+{{< hint info >}}
+
+`toml::value` can change the type it stores, and `toml::find` accommodates these types.
+Technically, all functions use `toml::basic_value<TC>`.
+However, for simplicity, we refer to it as `toml::value` in explanations unless a distinction is necessary.
+In the documentation, if the template parameter `TC` changes the type, assume that types like `toml::value::integer_type` will also change accordingly.
+
+{{< /hint >}}
+
+# `toml::find`
+
+## Overview
+
+`toml::find` uses template arguments for the type you want to retrieve and function arguments for the key of the value you want to find.
+
+```cpp
+template<typename T, typename TC, typename ... Keys>
+T find(const basic_value<TC>& v, Keys ... keys);
+```
+
+The supported types for `T` and the behavior of the conversion are the same as for `toml::get`.
+
+If `T` is not specified, a `toml::value` will be returned.
+
+Keys can be of type `toml::value::key_type` or `std::size_t`.
+When multiple keys are provided, the function will search recursively through sub-tables or arrays.
+If a `toml::value::key_type` is given, `toml::value` is interpreted as a `toml::table`; if a `std::size_t` is given, `toml::value` is interpreted as a `toml::array`.
+
+### Note on Recursive Search
+
+TOML allows for bare keys as well as quoted keys (enclosed in `"` or `'`). Using a quoted key like `"foo.bar" = "baz"` means no sub-table is constructed, and the key is `"foo.bar"`. To handle such patterns, toml11 does not split keys containing `.` and searches using the full string.
+
+Consider the following TOML file:
+
+```toml
+[foo]
+[foo.bar]
+baz = "hoge"
+
+["foo.bar"]
+baz = "fuga"
+```
+
+The corresponding usage of `toml::find` is shown below:
+
+```cpp
+const auto input = toml::parse("input.toml");
+const auto baz1 = toml::find<std::string>(input, "foo", "bar", "baz"); // hoge
+const auto baz2 = toml::find<std::string>(input, "foo.bar",    "baz"); // fuga
+```
+
+cf. [toml.io/en/v1.0.0#keys](https://toml.io/en/v1.0.0#keys)
+
+## `toml::find(value, key)`
+
+Searches for `key` in `value` as if `value` were a `toml::table`, then converts using `toml::get`.
+
+```cpp
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(const value&) */ find(
+    const basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
+
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(value&) */ find(
+    basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
+
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(value&&) */ find(
+    basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
+```
+
+If `T` is not specified, the function returns a `toml::value` without conversion.
+
+```cpp
+template<typename TC>
+basic_value<TC> const& find(
+    basic_value<TC> const& v, const typename basic_value<TC>::key_type& ky);
+
+template<typename TC>
+basic_value<TC>& find(
+    basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
+
+template<typename TC>
+basic_value<TC> find(
+    basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
+```
+
+### Exceptions
+
+If the `toml::value` does not contain a `table`, a `toml::type_error` is thrown.
+
+If the contained `table` does not have the specified element, a `std::out_of_range` is thrown.
+
+If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.
+
+## `toml::find(value, index)`
+
+Accesses the `index`-th element of `value` as if `value` were a `toml::array`, then converts using `toml::get`.
+
+```cpp
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(const value&) */ find(
+    const basic_value<TC>& v, const std::size_t index);
+
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(value&) */ find(
+    basic_value<TC>& v, const std::size_t index);
+
+template<typename T, typename TC>
+/* Equivalent to toml::get<T>(value&&) */ find(
+    basic_value<TC>&& v, const std::size_t index);
+```
+
+If `T` is not specified, the function returns a `toml::value` without conversion.
+
+```cpp
+template<typename TC>
+basic_value<TC> const& find(basic_value<TC> const& v, const std::size_t ky);
+
+template<typename TC>
+basic_value<TC>& find(basic_value<TC>& v, const std::size_t ky);
+
+template<typename TC>
+basic_value<TC> find(basic_value<TC>&& v, const std::size_t ky);
+```
+
+### Exceptions
+
+If the `toml::value` does not contain an `array`, a `toml::type_error` is thrown.
+
+If the contained `array` does not have the specified number of elements, a `std::out_of_range` is thrown.
+
+If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.
+
+## `toml::find(value, keys...)`
+
+```cpp
+template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
+/* Equivalent to toml::get<T>(const value&) */ find(
+    const basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
+
+template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
+/* Equivalent to toml::get<T>(value&) */ find(
+    basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
+
+template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
+/* Equivalent to toml::get<T>(value&&) */ find(
+    basic_value<TC>&& v, const K1& k1, const K2& k2, const Ks& ... ks);
+```
+
+This function calls `toml::find` recursively.
+
+The failure conditions and the exceptions thrown are the same as those for `toml::find`.
+
+# `toml::find_or(value, key, fallback)`
+
+```cpp
+template<typename T, typename TC, typename Key>
+T find_or(const basic_value<TC>& v, const Key& key, T&& opt);
+```
+
+The `find_or` function takes a default value to avoid throwing an exception when the search fails.
+
+The default value must be of the same type as the return type `T`. Therefore, unlike `toml::find<T>`, `find_or` infers the type `T`.
+
+You can specify `T` explicitly with `find_or<T>`, but this always returns a new value. To obtain a reference, do not specify `T`.
+
+## When `T` is `basic_value`
+
+```cpp
+template<typename TC, typename K>
+basic_value<TC>& find_or(basic_value<TC>& v, const K& key, basic_value<TC>& opt) noexcept
+
+template<typename TC, typename K>
+basic_value<TC> const& find_or(const basic_value<TC>& v, const K& key, const basic_value<TC>& opt) noexcept
+```
+
+Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.
+
+If the value is not found, the default value is returned.
+
+## When `T` is `toml::value::{some_type}`
+
+```cpp
+template<typename T, typename TC, typename K>
+T& find_or(basic_value<TC>& v, const K& key, T& opt) noexcept
+
+template<typename T, typename TC, typename K>
+T const& find_or(const basic_value<TC>& v, const K& key, const T& opt) noexcept
+```
+
+Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.
+
+If the value is not found or if a different type is stored, the default value is returned.
+
+## When `T` is `const char*`
+
+```cpp
+template<typename T, typename TC, typename K>
+T find_or(const basic_value<TC>& v, const K& key, T opt)
+```
+
+Searches for the corresponding value and returns it as a `std::string`.
+
+Since the fallback is constructed from `const char*` to `std::string`, a reference cannot be returned in case of failure.
+
+## When `T` is any other type
+
+```cpp
+template<typename T, typename TC, typename K>
+T find_or(const basic_value<TC>& v, const K& key, T opt);
+```
+
+Searches for the corresponding value and converts it to `T` before returning it.
+
+Because conversion is performed, a reference cannot be returned.
+
+## When multiple keys are provided
+
+```cpp
+template<typename Value, typename K1, typename K2, typename K3, typename ... Ks>
+auto find_or(Value&& v, const K1& k1, const K2& k2, K3&& k3, Ks&& ... keys) noexcept
+ -> decltype(find_or(v, k2, std::forward<K3>(k3), std::forward<Ks>(keys)...))
+```
+
+Interprets the last element in the key sequence as the default value and applies `find_or` recursively.
+
+If the inferred type of `T` is `toml::value` or `toml::value::some_type`, a reference can be returned.
+
+If `T` is explicitly specified, conversion is always performed.
+
+# Related
+
+- [get.hpp]({{<ref "get.md">}})
+- [value.hpp]({{<ref "value.md">}})

docs/content.en/docs/reference/format.md

@@ -0,0 +1,446 @@
++++
+title = "format.hpp"
+type  = "docs"
++++
+
+# format.hpp
+
+Defines structures and enumerations related to formatting information for `toml::value`.
+
+# `indent_char`
+
+An enumeration representing the indentation character choice.
+
+```cpp
+enum class indent_char : std::uint8_t
+{
+    space, // use space
+    tab,   // use tab
+    none   // no indent
+};
+std::ostream& operator<<(std::ostream& os, const indent_char& c);
+std::string to_string(const indent_char);
+```
+
+Choosing `none` means no indentation is used, regardless of the value in super tables.
+
+If both `space` and `tab` are specified within the serializable value, the behavior is unspecified; typically, the unspecified indentation character appears.
+
+# `boolean_format_info`
+
+Formatting information for `boolean`.
+
+```cpp
+struct boolean_format_info {};
+
+bool operator==(const boolean_format_info&, const boolean_format_info&) noexcept;
+bool operator!=(const boolean_format_info&, const boolean_format_info&) noexcept;
+```
+
+There is only one way to format `boolean`, so no configurable values are provided.
+
+# `integer_format`
+
+```cpp
+enum class integer_format : std::uint8_t
+{
+    dec = 0,
+    bin = 1,
+    oct = 2,
+    hex = 3,
+};
+std::ostream& operator<<(std::ostream& os, const integer_format f);
+std::string to_string(const integer_format);
+```
+
+Specifies the radix of an `integer`.
+
+# `integer_format_info`
+
+```cpp
+struct integer_format_info
+{
+    integer_format fmt = integer_format::dec;
+    std::size_t width  = 0;  // minimal width (may exceed)
+    std::size_t spacer = 0;  // position of `_` (if 0, no spacer)
+    std::string suffix = ""; // _suffix (library extension)
+};
+
+bool operator==(const integer_format_info&, const integer_format_info&) noexcept;
+bool operator!=(const integer_format_info&, const integer_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `integer_format fmt`
+
+Specifies the radix.
+
+### `std::size_t width`
+
+Specifies the minimum width. The formatted value may exceed this width.
+
+For values smaller than this width, if `integer_format::dec`, no effect. Otherwise, leading zeros are added.
+
+### `std::size_t spacer`
+
+Specifies the width at which underscores `_` are inserted.
+
+- If `3`, formatted as `1_234_567`.
+- If `4`, formatted as `0xdead_beef`.
+- If `0`, no underscores are inserted.
+
+Irregular widths are not allowed.
+
+### `std::string suffix`
+
+Stores the suffix when `spec::ext_num_suffix` of toml11 extension is `true`.
+
+cf. [spec.hpp](spec.md)
+
+# `floating_format`
+
+```cpp
+enum class floating_format : std::uint8_t
+{
+    defaultfloat = 0,
+    fixed        = 1, // does not include exponential part
+    scientific   = 2, // always include exponential part
+    hex          = 3  // hexfloat extension
+};
+std::ostream& operator<<(std::ostream& os, const floating_format f);
+std::string to_string(const floating_format);
+```
+
+Specifies the formatting style for `floating` numbers.
+Corresponds to `std::defaultfloat`, `std::fixed`, `std::scientific`, `std::hexfloat`.
+
+`hexfloat` is available only if `toml::spec::ext_hex_float` is `true`.
+
+cf. [spec.hpp](spec.md)
+
+# `floating_format_info`
+
+```cpp
+struct floating_format_info
+{
+    floating_format fmt = floating_format::defaultfloat;
+    std::size_t prec  = 0;        // precision (if 0, use the default)
+    std::string suffix = "";      // 1.0e+2_suffix (library extension)
+};
+
+bool operator==(const floating_format_info&, const floating_format_info&) noexcept;
+bool operator!=(const floating_format_info&, const floating_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `floating_format fmt`
+
+Specifies the formatting style.
+
+### `std::size_t prec`
+
+Specifies the precision after the decimal point.
+
+### `std::string suffix`
+
+Stores the suffix when `spec::ext_num_suffix` of toml11 extension is `true`.
+
+cf. [spec.hpp](spec.md)
+
+# `string_format`
+
+```cpp
+enum class string_format : std::uint8_t
+{
+    basic             = 0,
+    literal           = 1,
+    multiline_basic   = 2,
+    multiline_literal = 3
+};
+std::ostream& operator<<(std::ostream& os, const string_format f);
+std::string to_string(const string_format);
+```
+
+Specifies the formatting style for strings.
+
+# `string_format_info`
+
+```cpp
+struct string_format_info
+{
+    string_format fmt = string_format::basic;
+    bool start_with_newline    = false;
+};
+
+bool operator==(const string_format_info&, const string_format_info&) noexcept;
+bool operator!=(const string_format_info&, const string_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `string_format fmt`
+
+Specifies the formatting information for strings.
+
+### `bool start_with_newline`
+
+For `multiline_basic` or `multiline_literal`, specifies whether to include a newline after the initial `"""` or `'''`.
+
+# `datetime_delimiter_kind`
+
+```cpp
+enum class datetime_delimiter_kind : std::uint8_t
+{
+    upper_T = 0,
+    lower_t = 1,
+    space   = 2,
+};
+std::ostream& operator<<(std::ostream& os, const datetime_delimiter_kind d);
+std::string to_string(const datetime_delimiter_kind);
+```
+
+Specifies the delimiter used between date and time in `datetime`.
+
+Possible options include `T`, `t`, and a space ` `.
+
+# `offset_datetime_format_info`
+
+```cpp
+struct offset_datetime_format_info
+{
+    datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
+    bool has_seconds = true;
+    std::size_t subsecond_precision = 6; // [us]
+};
+
+bool operator==(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
+bool operator!=(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `datetime_delimiter_kind delimiter`
+
+Specifies the delimiter to use.
+
+### `bool has_seconds`
+
+Specifies whether to omit seconds.
+
+### `std::size_t subsecond_precision`
+
+Specifies how many digits to output for subseconds.
+
+# `local_datetime_format_info`
+
+```cpp
+struct local_datetime_format_info
+{
+    datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
+    bool has_seconds = true;
+    std::size_t subsecond_precision = 6; // [us]
+};
+
+bool operator==(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
+bool operator!=(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `datetime_delimiter_kind delimiter`
+
+Specifies the delimiter to use.
+
+### `bool has_seconds`
+
+Specifies whether to omit seconds.
+
+### `std::size_t subsecond_precision`
+
+Specifies how many digits to output for subseconds.
+
+# `local_date_format_info`
+
+```cpp
+struct local_date_format_info
+{
+    // nothing, for now
+};
+
+bool operator==(const local_date_format_info&, const local_date_format_info&) noexcept;
+bool operator!=(const local_date_format_info&, const local_date_format_info&) noexcept;
+```
+
+No formatting parameters are specified for `local_date`.
+
+# `local_time_format_info`
+
+```cpp
+struct local_time_format_info
+{
+    bool has_seconds = true;
+    std::size_t subsecond_precision = 6; // [us]
+};
+
+bool operator==(const local_time_format_info&, const local_time_format_info&) noexcept;
+bool operator!=(const local_time_format_info&, const local_time_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `bool has_seconds`
+
+Specifies whether to omit seconds.
+
+### `std::size_t subsecond_precision`
+
+Specifies how many digits to output for subseconds.
+
+# `array_format`
+
+```cpp
+enum class array_format : std::uint8_t
+{
+    default_format  = 0,
+    oneline         = 1,
+    multiline       = 2,
+    array_of_tables = 3 // [[format.in.this.way]]
+};
+
+std::ostream& operator<<(std::ostream& os, const array_format f);
+std::string to_string(const array_format);
+```
+
+- `default_format`
+  - Automatically selects the appropriate format. Longer arrays may span multiple lines.
+- `oneline`
+  - Formats all elements in a single line.
+- `multiline`
+  - Outputs each element on its own line.
+- `array_of_tables`
+  - Formats in the `[[array.of.tables]]` style. Cannot contain elements other than `table`.
+
+# `array_format_info`
+
+```cpp
+struct array_format_info
+{
+    array_format fmt            = array_format::default_format;
+    indent_char  indent_type    = indent_char::space;
+    std::int32_t body_indent    = 4; // indent in case of multiline
+    std::int32_t closing_indent = 0; // indent of `]`
+};
+
+bool operator==(const array_format_info&, const array_format_info&) noexcept;
+bool operator!=(const array_format_info&, const array_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `array_format fmt`
+
+Specifies the format style.
+
+### `indent_char indent_type`
+
+Selects the type of character used for indentation.
+
+### `std::int32_t body_indent`
+
+Specifies the number of characters to indent before each element in `array_format::multiline`.
+
+### `std::int32_t closing_indent`
+
+Specifies the number of characters to indent before the closing bracket `]` in `array_format::multiline`.
+
+# `table_format`
+
+```cpp
+enum class table_format : std::uint8_t
+{
+    multiline         = 0, // [foo] \n bar = "baz"
+    oneline           = 1, // foo = {bar = "baz"}
+    dotted            = 2, // foo.bar = "baz"
+    multiline_oneline = 3, // foo = { \n bar = "baz" \n }
+    implicit          = 4  // [x] defined by [x.y.z]. skip in serializer.
+};
+
+std::ostream& operator<<(std::ostream& os, const table_format f);
+std::string to_string(const table_format);
+```
+
+- `multiline`
+  - Formats as a multiline normal table.
+- `oneline`
+  - Formats as an inline table.
+- `dotted`
+  - Formats in the form of `a.b.c = "d"`.
+- `multiline_oneline`
+  - Formats as a multiline inline table with line breaks. Available from TOML v1.1.0 onwards.
+  - cf. [spec.hpp](spec.md)
+- `implicit`
+  - Skips implicit definitions like `[x.y.z.w]`, leaving `[x]`, `[x.y]`, `[x.y.z]` as implicit.
+
+{{< hint warning >}}
+
+According to TOML syntax, `dotted` table can have sub-tables:
+
+```toml
+[fruit]
+apple.color = "red"
+apple.taste.sweet = true
+
+# [fruit.apple]        # INVALID
+# [fruit.apple.taste]  # INVALID
+[fruit.apple.texture]  # you can add sub-tables
+smooth = true
+```
+
+toml11 currently does not support this format.
+Sub-tables under a `dotted` table would all be `dotted`, and tables are forced into inline table format.
+
+{{< /hint >}}
+
+# `table_format_info`
+
+```cpp
+struct table_format_info
+{
+    table_format fmt = table_format::multiline;
+    indent_char  indent_type    = indent_char::space;
+    std::int32_t body_indent    = 0; // indent of values
+    std::int32_t name_indent    = 0; // indent of [table]
+    std::int32_t closing_indent = 0; // in case of {inline-table}
+};
+
+bool operator==(const table_format_info&, const table_format_info&) noexcept;
+bool operator!=(const table_format_info&, const table_format_info&) noexcept;
+```
+
+## Member Variables
+
+### `table_format fmt`
+
+Specifies the formatting method.
+
+### `indent_char indent_type`
+
+Specifies the character used for indentation.
+
+### `std::int32_t body_indent`
+
+Specifies the width of indentation before keys.
+
+The indentation width of the super table is not added.
+
+### `std::int32_t name_indent`
+
+Specifies the indentation of keys in `[table]` format.
+
+The indentation width of the super table is not added.
+
+### `std::int32_t closing_indent`
+
+Specifies the indentation width before the closing brace `}` in the case of `multiline_oneline`.

docs/content.en/docs/reference/from.md

@@ -0,0 +1,56 @@
++++
+title = "from.hpp"
+type  = "docs"
++++
+
+# from.hpp
+
+Defines a `struct` used for conversion from `toml::value` in `toml::get` and `toml::find`.
+
+You can achieve the same functionality by adding a `from_toml` member function, but for classes where you cannot add member functions, use `from<T>`.
+
+This file does not provide specific implementations. Please specialize this `struct` when using.
+
+```cpp
+namespace toml
+{
+
+template<typename T>
+struct from;
+
+} // toml
+```
+
+## Example
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+#include <toml11/from.hpp>
+
+namespace toml
+{
+template<>
+struct from<extlib::foo>
+{
+    template<typename TC>
+    static extlib::foo from_toml(const toml::basic_value<TC>& v)
+    {
+        return extlib::foo{toml::find<int>(v, "a"), toml::find<std::string>(v, "b")};
+    }
+};
+} // toml
+```
+
+# Related
+
+- [conversion.hpp]({{<ref "conversion.md">}})
+- [into.hpp]({{<ref "into.md">}})
+

docs/content.en/docs/reference/get.md

@@ -0,0 +1,427 @@
++++
+title = "get.hpp"
+type  = "docs"
++++
+
+# get.hpp
+
+These are functions for extracting values from `toml::value` and performing type conversions if necessary.
+
+{{< hint info >}}
+
+`toml::value` can change the type it stores, and `toml::get` accommodates these types.
+Technically, all functions use `toml::basic_value<TC>`.
+However, for simplicity, we refer to it as `toml::value` in explanations unless a distinction is necessary.
+In the documentation, if the template parameter `TC` changes the type, assume that types like `toml::value::integer_type` will also change accordingly.
+
+{{< /hint >}}
+
+# `toml::get<T>`
+
+## Overview
+
+Generally, `toml::get` behaves as follows:
+You specify `T` as in `toml::get<int>(v)`.
+
+```cpp
+template<typename T, typename TC>
+T get(const basic_value<TC>& v);
+```
+
+However, depending on the type of `T`, `toml::get` can exhibit different behaviors.
+
+The types of `T` can be categorized into:
+
+1. Types that do not require conversion
+2. Types that require conversion
+
+Detailed conditions and the specific types supported are discussed later.
+
+### Types that Do Not Require Conversion
+
+No conversion is needed if the provided `toml::value` is already storing the desired type. For instance, since `toml::value::integer_type` is an alias for `std::int64_t`, `toml::get<std::int64_t>(v)` requires no conversion. In this case, `toml::get` retrieves the `integer` value from `toml::value` and returns a reference to it.
+
+If the provided `toml::value` is a mutable reference (`&`), the returned value is also a mutable reference (`&`). If it is an immutable reference (`const&`), the returned value will also be an immutable reference (`const&`). Returning a mutable reference allows you to overwrite the value stored in `toml::value` through that reference.
+
+### Types that Require Conversion
+
+Types other than the ones mentioned above require conversion. For example, since `toml::value::integer_type` is an alias for `std::int64_t`, `toml::get<std::size_t>(toml::value&)` requires conversion. In this case, `toml::get` retrieves the `integer` value from `toml::value` and casts it to return the appropriate type.
+
+toml11 supports not only simple casts but also complex type conversions like converting from `toml::array` to `std::tuple<int, double, std::string>`, `std::array<double, 4>`, or from `toml::table` to `std::map<std::string, int>`. For specifics, refer to the subsequent sections.
+
+### When Conversion Fails
+
+Sometimes, the expected type conversion cannot be performed. For example, applying `toml::get<int>(v)` to a `toml::value` that holds a `table`.
+
+In such cases, an attempt to convert to the type most similar to the desired type (in this case, `int` using `as_integer`) fails, and a `toml::type_error` is thrown.
+
+When parsing from a file, an error message similar to the following is output:
+
+```
+terminate called after throwing an instance of 'toml::type_error'
+  what():  toml::value::as_integer(): bad_cast to integer
+ --> input.toml
+   |
+ 6 | [fruit]
+   | ^^^^^^^-- the actual type is table
+```
+
+## When `T` is identical to `toml::value`
+
+```cpp
+template<typename T, typename TC>
+T& get(basic_value<TC>& v);
+
+template<typename T, typename TC>
+T const& get(const basic_value<TC>& v);
+
+template<typename T, typename TC>
+T get(basic_value<TC>&& v);
+```
+
+Condition:
+- `std::is_same<T, basic_value<TC>>` is satisfied.
+
+Since this involves retrieving `toml::value` from `toml::value`, no conversion is performed, and the value is returned as is. This exists solely to generalize the implementation of other functions.
+
+This does not fail.
+
+## When `T` is one of `toml::value::{some_type}`
+
+```cpp
+template<typename T, typename TC>
+T& get(basic_value<TC>& v);
+
+template<typename T, typename TC>
+T const& get(const basic_value<TC>& v);
+
+template<typename T, typename TC>
+T get(basic_value<TC>&& v);
+```
+
+Condition:
+- `T` must be the same as one of the types that `toml::value` can store (e.g., `toml::value::boolean_type`).
+
+If `toml::value` is storing a type that matches the specified type in `toml::get<T>`, such as `toml::value::integer_type`, no type conversion is needed, and a reference can be returned.
+
+If a different type is stored, a `toml::type_error` is thrown.
+
+## When `T` is `basic_value<OtherTC>` with a different `TypeConfig`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `T` is not `toml::basic_value<TC>`.
+- `T` is `toml::basic_value<OtherTC>`.
+
+When a `basic_value` that can store different types is specified, conversion is performed.
+
+Since type conversion occurs, the returned value is a new value and not a reference.
+
+This does not fail (except in cases like memory exhaustion).
+
+## When `T` is an integer type
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `std::is_integral<T>` is satisfied
+- `T` is not `bool`
+- `T` is not `toml::value::integer_type`
+
+The function assumes that `toml::value` holds an `integer_type`, retrieves its value, converts it to `T`, and returns it.
+
+If a type other than `toml::value::integer_type` is stored, a `toml::type_error` is thrown.
+
+## When `T` is a floating-point type
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `std::is_floating_point<T>` is satisfied
+- `T` is not `toml::value::floating_type`
+
+The function assumes that `toml::value` holds a `floating_type`, retrieves its value, converts it to `T`, and returns it.
+
+If a type other than `toml::value::floating_type` is stored, a `toml::type_error` is thrown.
+
+## When `T` is `std::string_view`
+
+This is only available in C++17 and later.
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `std::is_same<std::string_view, T>` is satisfied
+
+The function assumes that `toml::value` holds a `string_type`, retrieves its value, constructs a `std::string_view` from it, and returns it.
+
+If a type other than `toml::value::string_type` is stored, a `toml::type_error` is thrown.
+
+## When `T` is `std::chrono::duration`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `T` is `std::chrono::duration<Rep, Period>`
+
+The function assumes that `toml::value` holds a `local_time`, retrieves its value, converts it to `std::chrono::duration`, and returns it.
+
+If a type other than `toml::value::local_time` is stored, a `toml::type_error` is thrown.
+
+## When `T` is `std::chrono::system_clock::time_point`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `std::is_same<T, std::chrono::system_clock::time_point>` is satisfied
+
+If the `toml::value` holds a `local_date`, `local_datetime`, or `offset_datetime`, this function retrieves the value and converts it to `std::chrono::system_clock::time_point`, returning the result.
+
+If the value is of a type other than `local_date`, `local_datetime`, or `offset_datetime`, a `toml::type_error` is thrown.
+
+## When `T` is array-like
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Conditions:
+- `T` has an `iterator`
+- `T` has a `value_type`
+- `T` supports `push_back(x)`
+- `T` is not `toml::value::array_type`
+- `T` is not `std::string`
+- `T` is not `std::string_view`
+- `T` is not map-like
+- `T` does not have `from_toml()` member function
+- `toml::from<T>` is not defined
+- A constructor from `toml::basic_value<TC>` is not defined
+
+This includes types like `std::vector<int>` and `std::deque<std::string>`.
+
+If the `toml::value` holds an `array`, this function retrieves the value and converts it to the specified container type, returning the result.
+
+If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
+
+## When `T` is `std::array`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+条件：
+- `T` is `std::array<U, N>`
+
+If the `toml::value` holds an `array`, this function retrieves the value and converts it to the specified container type, returning the result.
+
+If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
+
+If the `array` held by `toml::value` does not contain enough elements, a `std::out_of_range` is thrown.
+
+## When `T` is `std::forward_list`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `T` is `std::forward_list<U>`
+
+If the `toml::value` holds an `array`, this function retrieves the value and converts it to a `std::forward_list`, returning the result.
+
+If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
+
+## When `T` is `std::pair`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `T` is `std::pair<T1, T2>`
+
+If the `toml::value` holds an `array`, this function retrieves the value and converts it to `std::pair<T1, T2>`, returning the result.
+
+The `first` and `second` elements are recursively converted.
+
+If the value is of a type other than `basic_value::array_type`, a `toml::type_error` is thrown.
+
+If the `array` held by `toml::value` does not contain exactly 2 elements, a `std::out_of_range` is thrown.
+
+## When `T` is `std::tuple`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- `T` is `std::tuple<T1, T2, ... TN>`
+
+If the `toml::value` holds an `array`, this function retrieves the value and converts it to `std::tuple<T1, T2, ...TN>`, returning the result.
+
+Each element is recursively converted.
+
+If the value is of a type other than `basic_value::array_type`, a `toml::type_error` is thrown.
+
+If the `array` held by `toml::value` does not contain exactly `std::tuple_size<T>::value` elements, a `std::out_of_range` is thrown.
+
+## When `T` is map-like
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Conditions:
+- `T` has an `iterator`
+- `T` has a `key_type`
+- `T` has a `value_type`
+- `T` has a `mapped_type`
+- `T` is not `toml::value::table_type`
+- `T` does not have a `from_toml()` member function
+- `toml::from<T>` is not defined
+- A constructor from `toml::basic_value<TC>` is not defined
+
+This includes types like `std::map<std::string, int>` and `std::unordered_map<std::string, float>`.
+
+If the `toml::value` holds a `table`, this function retrieves the value and converts it to `T`, returning the result.
+
+Elements are recursively converted.
+
+If the value is of a type other than `basic_value::table_type`, a `toml::type_error` is thrown.
+
+## When `T` is a user-defined type with a specialization of `toml::from<T>`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Condition:
+- A specialization of `toml::from<T>` is defined
+
+If a specialization of `toml::from` for `T` is defined, it is used for type conversion.
+
+Ensure this does not conflict with individually supported types (`std::array`, `std::pair`, `std::tuple` etc).
+
+## When `T` is a user-defined type with a `from_toml` member function
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Conditions:
+- `toml::from<T>` is not defined
+- `T` has `from_toml()` member function
+
+If `T` has a `from_toml(toml::basic_value<TC>)` member function, it is used for type conversion.
+
+If `toml::from<T>` is defined, it takes precedence.
+
+## When `T` is a user-defined type with a constructor that takes `toml::basic_value<TC>`
+
+```cpp
+template<typename T, typename TC>
+T get(basic_value<TC>& v);
+```
+
+Conditions:
+- `toml::from<T>` is not defined
+- `T` does not have `from_toml()` member function
+- `T` has a constructor that takes `toml::basic_value<TC>`
+
+If `T` has a constructor that takes `toml::basic_value<TC>`, it is used for type conversion.
+
+If `toml::from<T>` or `T::from_toml` is defined, they take precedence.
+
+# `toml::get_or<T>`
+
+`get_or` takes a default value for use when the conversion fails, avoiding exceptions.
+
+The default value must be of the same type as the target type `T`.
+Therefore, unlike `toml::get<T>`, `T` can be inferred in `get_or`.
+
+## When `T` is `basic_value<TC>`
+
+```cpp
+template<typename TC>
+basic_value<TC> const& get_or(const basic_value<TC>& v, const basic_value<TC>& opt)
+
+template<typename TC>
+basic_value<TC> & get_or(basic_value<TC>& v, basic_value<TC>& opt)
+
+template<typename TC>
+basic_value<TC> get_or(basic_value<TC>&& v, basic_value<TC>&& opt)
+```
+
+Since the conversion target is the same `toml::value`, this never fails.
+
+It exists solely to generalize the implementation of other functions.
+
+## When `T` is `basic_value<TC>::{some_type}`
+
+```cpp
+template<typename T, typename TC>
+T const& get_or(const basic_value<TC>& v, const T& opt) noexcept
+
+template<typename T, typename TC>
+T & get_or(basic_value<TC>& v, T& opt) noexcept
+
+template<typename T, typename TC>     
+T get_or(basic_value<TC>&& v, T&& opt) noexcept
+```
+
+Performs the same conversion as `toml::get<T>`. If it fails, the second argument is returned.
+
+## When `T` is `const char*`
+
+```cpp
+template<typename TC>
+typename basic_value<TC>::string_type
+get_or(const basic_value<TC>& v,
+       const typename basic_value<TC>::string_type::value_type* opt);
+```
+
+When `const char*` is passed, the conversion target is interpreted as `std::string`.
+
+## When `T` is something else
+
+```cpp
+template<typename TC>
+typename std::remove_cv<typename std::remove_reference<T>::type>::type
+get_or(const basic_value<TC>& v, T&& opt);
+```
+
+Performs the same conversion as `toml::get<T>`. If it fails, the second argument is returned.
+
+# Related
+
+- [find.hpp]({{<ref "find.md">}})
+- [from.hpp]({{<ref "from.md">}})
+- [value.hpp]({{<ref "value.md">}})
+

docs/content.en/docs/reference/into.md

@@ -0,0 +1,58 @@
++++
+title = "into.hpp"
+type  = "docs"
++++
+
+# into.hpp
+
+Defines a `struct` used for conversion from user-defined types into `toml::value` constructors.
+
+You can achieve the same functionality by adding an `into_toml` member function, but for classes where you cannot add member functions, use `into<T>`.
+
+This file does not provide specific implementations. Please specialize this `struct` when using.
+
+```cpp
+namespace toml
+{
+
+template<typename T>
+struct into;
+
+} // toml
+```
+
+## Example
+
+```cpp
+namespace extlib
+{
+struct foo
+{
+    int a;
+    std::string b;
+};
+} // extlib
+
+#include <toml11/into.hpp>
+
+namespace toml
+{
+template<>
+struct into<extlib::foo>
+{
+    template<typename TC>
+    static toml::basic_value<TC> into_toml(const extlib::foo& f)
+    {
+        using value_type = toml::basic_value<TC>;
+        using table_type = typename value_type::table_type;
+        return value_type(table_type{{"a", f.a}, {"b", f.b}});
+    }
+};
+} // toml
+```
+
+# Related
+
+- [conversion.hpp]({{<ref "conversion.md">}})
+- [from.hpp]({{<ref "from.md">}})
+

docs/content.en/docs/reference/literal.md

@@ -0,0 +1,82 @@
++++
+title = "literal.hpp"
+type  = "docs"
++++
+
+# literal.hpp
+
+In `literal.hpp`, the `_toml` literal is defined.
+
+The `_toml` literal parses string literals into `toml::value`.
+
+```cpp
+namespace toml
+{
+inline namespace literals
+{
+inline namespace toml_literals
+{
+toml::value operator"" _toml(const char* str, std::size_t len);
+toml::value operator"" _toml(const char8_t* str, std::size_t len); // Available in C++20 and later
+} // toml_literals
+} // literals
+} // toml
+```
+
+## Free Functions
+
+### `operator"" _toml(const char*)`
+
+```cpp
+toml::value operator"" _toml(const char* str, std::size_t len);
+```
+
+Converts a string literal into a `toml::value` by parsing it.
+
+For typical TOML files, this performs equivalent parsing to `toml::parse`.
+
+```cpp
+const auto v1 = "a = 'foo'"_toml; // v1: {a = 'foo'}
+```
+
+When dealing with multiline content, raw string literal is convenient.
+
+```cpp
+const auto v1 = R"(
+    a = 42
+    b = "foo"
+)"_toml;
+```
+
+If the value is a standalone entity, it represents that value.
+
+```cpp
+const auto v2 = "'foo'"_toml;     // v2: 'foo'
+```
+
+TOML allows keys consisting solely of numbers. When distinguishing between table definitions and arrays is ambiguous (e.g., `[1]`), table definitions take precedence.
+
+To interpret as an array, use a trailing comma.
+
+```cpp
+const auto v3 = "[1]"_toml;  // v3: {1 = {}}
+const auto v4 = "[1,]"_toml; // v4: [1,]
+```
+
+### `operator"" _toml(const char8_t*)`
+
+Defined when `char8_t` is available. Otherwise identical in functionality, differing only in argument type.
+
+# Example
+
+```cpp
+#include <toml.hpp>
+int main()
+{
+    using namespace toml::literals::toml_literals;
+    const auto v = "a = \"foo\""_toml;
+    assert(v.at("a").as_string() == "foo");
+    return 0;
+}
+```
+

docs/content.en/docs/reference/ordered_map.md

@@ -0,0 +1,344 @@
++++
+title = "ordered_map.hpp"
+type  = "docs"
++++
+
+# ordered_map.hpp
+
+Defines `toml::ordered_map`, which is used to maintain the order of values in a file.
+
+# `class ordered_map`
+
+```cpp
+namespace toml
+{
+template<typename Key, typename Val, typename Cmp = std::equal_to<Key>,
+         typename Allocator = std::allocator<std::pair<Key, Val>>>
+class ordered_map;
+}
+```
+
+The `ordered_map` is a `map` type that preserves the insertion order of values, allowing iteration in that order.
+
+As a linear container, searches require `O(n)` time relative to the number of elements.
+Use this when search operations are infrequent and maintaining the order of values is important.
+
+## Non-Member Types
+
+```cpp
+namespace toml
+{
+struct ordered_type_config;
+
+using ordered_value = basic_value<ordered_type_config>;
+using ordered_table = typename ordered_value::table_type;
+using ordered_array = typename ordered_value::array_type;
+}
+```
+
+Use these in place of `toml::type_config` and `toml::value`.
+
+{{< hint info >}}
+
+Since `toml::parse` defaults to using `type_config`, specify
+
+```cpp
+const auto input = toml::parse<toml::ordered_type_config>("input.toml");
+```
+
+when parsing.
+
+{{< /hint >}}
+
+## Member Types
+
+```cpp
+using key_type       = Key;
+using mapped_type    = Val;
+using value_type     = std::pair<Key, Val>;
+using key_compare    = Cmp;
+using allocator_type = Allocator;
+
+using container_type  = std::vector<value_type, Allocator>;
+using reference       = typename container_type::reference;
+using pointer         = typename container_type::pointer;
+using const_reference = typename container_type::const_reference;
+using const_pointer   = typename container_type::const_pointer;
+using iterator        = typename container_type::iterator;
+using const_iterator  = typename container_type::const_iterator;
+using size_type       = typename container_type::size_type;
+using difference_type = typename container_type::difference_type;
+```
+
+## Member Functions
+
+### Constructors
+
+```cpp
+ordered_map() = default;
+```
+
+Constructs an empty `ordered_map`.
+
+### Constructors (Comparator, Allocator)
+
+```cpp
+explicit ordered_map(const Cmp& cmp, const Allocator& alloc = Allocator());
+explicit ordered_map(const Allocator& alloc);
+```
+
+Constructs an `ordered_map` with a specified comparator for key comparison and an allocator for memory management.
+
+### Copy and Move Constructors
+
+```cpp
+ordered_map(const ordered_map&) = default;
+ordered_map(ordered_map&&)      = default;
+
+ordered_map(const ordered_map& other, const Allocator& alloc);
+ordered_map(ordered_map&& other, const Allocator& alloc);
+```
+
+Constructs an `ordered_map` by copying or moving the contents from another `ordered_map`.
+An allocator can also be specified for memory management.
+
+### Constructors (Iterator)
+
+```cpp
+template<typename InputIterator>
+ordered_map(InputIterator first, InputIterator last, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
+template<typename InputIterator>
+ordered_map(InputIterator first, InputIterator last, const Allocator& alloc = Allocator());
+```
+
+Constructs an `ordered_map` with a range represented by iterators.
+The order of the elements follows the order of the iterators.
+
+### Constructors (std::initializer_list)
+
+```cpp
+ordered_map(std::initializer_list<value_type> v, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
+ordered_map(std::initializer_list<value_type> v, const Allocator& alloc);
+```
+
+Initializes the `ordered_map` using an initializer list.
+
+### Copy and Move Assignment Operators
+
+```cpp
+ordered_map& operator=(const ordered_map&) = default;
+ordered_map& operator=(ordered_map&&)      = default;
+```
+
+Assigns the contents of another `ordered_map` to this one, using copy or move semantics.
+
+### Assignment Operator (std::initializer_list)
+
+```cpp
+ordered_map& operator=(std::initializer_list<value_type> v);
+```
+
+Assigns the contents of an initializer list to the `ordered_map`.
+
+### Destructor
+
+```cpp
+~ordered_map() = default;
+```
+
+Destroys the `ordered_map`.
+
+### `begin()`, `end()`
+
+```cpp
+iterator       begin()        noexcept;
+iterator       end()          noexcept;
+const_iterator begin()  const noexcept;
+const_iterator end()    const noexcept;
+const_iterator cbegin() const noexcept;
+const_iterator cend()   const noexcept;
+```
+
+Returns iterators to the beginning and end of the container, allowing iteration over its contents in order.
+
+
+### `empty()`
+
+```cpp
+bool empty() const noexcept;
+```
+
+Returns `true` if the `ordered_map` is empty, `false` otherwise.
+
+### `size()`
+
+```cpp
+std::size_t size() const noexcept;
+```
+
+Returns the number of elements in the `ordered_map`.
+
+### `max_size()`
+
+```cpp
+std::size_t max_size() const noexcept;
+```
+
+Returns the maximum number of elements the `ordered_map` can hold.
+
+### `clear()`
+
+```cpp
+void clear();
+```
+
+Clears all elements from the `ordered_map`.
+
+### `push_back(kv)`
+
+```cpp
+void push_back(const value_type&);
+void push_back(value_type&&);
+```
+
+Appends a key-value pair to the end of the `ordered_map`.
+
+### `emplace_back(k, v)`
+
+```cpp
+void emplace_back(key_type, mapped_type);
+```
+
+Appends a key-value pair to the end of the `ordered_map` by constructing it in place.
+
+### `pop_back()`
+
+```cpp
+void pop_back();
+```
+
+Removes the last element from the `ordered_map`.
+
+### `insert(kv)`
+
+```cpp
+void insert(value_type);
+```
+
+Inserts a key-value pair at the end of the `ordered_map`.
+
+### `emplace(k, v)`
+
+```cpp
+void emplace(key_type, mapped_type);
+```
+
+Inserts a key-value pair at the end of the `ordered_map` by constructing it in place.
+
+### `count(k)`
+
+```cpp
+std::size_t count(const key_type&) const noexcept;
+```
+
+Returns the number of elements with the specified key.
+Since duplicate keys are not allowed, this will return either `1` if the key exists or `0` if it does not.
+
+### `contains(k)`
+
+```cpp
+bool contains(const key_type&) const noexcept;
+```
+
+Returns `true` if the `ordered_map` contains an element with the specified key, `false` otherwise.
+
+### `find(k)`
+
+```cpp
+iterator       find(const key_type& key)       noexcept;
+const_iterator find(const key_type& key) const noexcept;
+```
+
+Finds an element with the specified key and returns an iterator to it. If the key is not found, returns `end()`.
+
+### `at(k)`
+
+```cpp
+mapped_type&       at(const key_type& k);
+mapped_type const& at(const key_type& k) const;
+```
+
+Finds an element with the specified key and returns a reference to its value. Throws `std::out_of_range` if the key is not found.
+
+### `operator[](k)`
+
+```cpp
+mapped_type&       operator[](const key_type& k);
+mapped_type const& operator[](const key_type& k) const;
+```
+
+Finds an element with the specified key and returns a reference to its value.
+If the key is not found, a new value is constructed and returned.
+If the `ordered_map` is `const`, throws `std::out_of_range` instead.
+
+### `key_comp()`
+
+```cpp
+key_compare key_comp() const;
+```
+
+Returns the comparator used for key comparison.
+
+## Notes
+
+### Key Modification
+
+{{< hint warning >}}
+
+Since `ordered_map` uses `std::pair<Key, Val>` for `value_type`, it is possible to modify the key through an iterator. However, this practice is not recommended.
+
+If you modify a key this way and it conflicts with an existing key, one of the conflicting keys will become unsearchable.
+
+When using `operator[]`, `push_back`, or `insert`, collisions with existing keys are detected.
+
+{{< /hint >}}
+
+### Order Preservation Details
+
+{{< hint warning >}}
+
+`ordered_map` maintains the order of keys, but this order preservation applies only to keys defined within the same table. Order across different tables is not maintained.
+
+For example, the order in the following file will be preserved:
+
+```cpp
+apple.type = "fruit"
+apple.skin = "thin"
+apple.color = "red"
+orange.type = "fruit"
+orange.skin = "thick"
+orange.color = "orange"
+```
+
+In contrast, the order in the following file will not be preserved:
+
+```cpp
+apple.type = "fruit"
+orange.type = "fruit"
+
+apple.skin = "thin"
+orange.skin = "thick"
+
+apple.color = "red"
+orange.color = "orange"
+```
+
+`ordered_map` preserves the order of the `apple` and `orange` definitions at the root table level, and the order of `type`, `skin`, `color` within each `apple` and `orange` table.
+
+{{< /hint >}}
+
+## Related
+
+- [parser.hpp]({{<ref "parser.md">}})
+- [types.hpp]({{<ref "types.md">}})
+- [value.hpp]({{<ref "value.md">}})

docs/content.en/docs/reference/parser.md

@@ -0,0 +1,375 @@
++++
+title = "parser.hpp"
+type  = "docs"
++++
+
+# parser.hpp
+
+Defines functions for parsing files or strings and the exceptions they use.
+
+While `parse` throws an exception on failure, `try_parse` returns error information.
+
+# `parse`
+
+Parses the content of a given file and returns a `toml::basic_value`.
+
+In case of failure, `toml::syntax_error` is thrown.
+
+The type information of `basic_value` is provided by a `template`, and the TOML language version is specified by `toml::spec`.
+
+### `parse(std::istream&, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse(std::istream& is,
+      std::string fname = "unknown file",
+      spec s = spec::default_version());
+}
+```
+
+Parses the content of the given `std::istream&`.
+
+The filename information is taken as the third argument. If the filename is not provided, it defaults to `"unknown file"`.
+
+### `parse(std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse(std::string fname,
+      spec s = spec::default_version());
+}
+```
+
+Parses the content of the given filename.
+
+If reading the file fails, `toml::file_io_error` is thrown.
+
+If parsing fails, `toml::syntax_error` is thrown.
+
+### `parse(const char (&)[N] filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config, std::size_t N>
+basic_value<TC>
+parse(const char (&fname)[N],
+      spec s = spec::default_version());
+}
+```
+
+Parses the content of the given filename from a string literal.
+
+If reading the file fails, `toml::file_io_error` is thrown.
+
+If parsing fails, `toml::syntax_error` is thrown.
+
+### `parse(std::filesystem::path, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse(const std::filesystem::path& fpath,
+      spec s = spec::default_version());
+}
+```
+
+This is defined only if `<filesystem>` is available.
+
+Parses the content of the file at the given file path.
+
+If reading the file fails, `toml::file_io_error` is thrown.
+
+If parsing fails, `toml::syntax_error` is thrown.
+
+### `parse(FILE*, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+parse(FILE* fp,
+      std::string filename,
+      spec s = spec::default_version());
+}
+```
+
+Parses the content of the file pointed to by `FILE*`.
+
+If reading the file fails, `file_io_error` containing `errno` is thrown.
+
+If parsing fails, `syntax_error` is thrown.
+
+### `parse(std::vector<unsigned char>, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse(std::vector<unsigned char> content,
+      std::string filename,
+      spec s = spec::default_version());
+}
+```
+
+Parses the byte sequence as a TOML file.
+
+If parsing fails, `toml::syntax_error` is thrown.
+
+# `parse_str`
+
+### `parse_str(std::string, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse_str(std::string content,
+          spec s = spec::default_version(),
+          cxx::source_location loc = cxx::source_location::current());
+}
+```
+
+Parses a string as a TOML file.
+
+In case of failure, `toml::syntax_error` is thrown.
+
+The type information of `basic_value` is provided by a `template`, and the TOML language version is specified by `toml::spec`.
+
+You generally don't need to manually set the third argument, `cxx::source_location`.
+If `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` is available,
+the location information where `parse_str` was called will be stored.
+
+# `try_parse`
+
+Parses the contents of the given file and returns a `toml::basic_value` if successful, or a `std::vector<toml::error_info>` if it fails.
+
+The type information of `basic_value` is specified by `template`, and the version of the TOML language is specified by `toml::spec`.
+
+{{< hint warning >}}
+
+Unlike `parse`, `try_parse` does not throw exceptions defined in toml11 such as `syntax_error`.
+However, please note that exceptions thrown by the standard library will still propagate.
+
+For instance, errors occurring internally within `std::ifstream` or memory exhaustion in `std::vector` will throw exceptions.
+
+{{< /hint >}}
+
+### `try_parse(std::istream&, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(std::istream& is,
+          std::string fname = "unknown file",
+          spec s = spec::default_version());
+}
+```
+
+Takes a `std::istream&` and parses its content.
+
+The file name information is taken as the second argument. If a file name is not provided, it defaults to `"unknown file"`.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+### `try_parse(std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(std::string fname,
+          spec s = spec::default_version());
+}
+```
+
+Takes a file name and parses its content.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+### `try_parse(const char (&)[N] filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config, std::size_t N>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(const char (&fname)[N],
+          spec s = spec::default_version());
+}
+```
+
+Takes a string literal as a file name and parses its content.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+### `try_parse(std::filesystem::path, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(const std::filesystem::path& fpath,
+          spec s = spec::default_version());
+}
+```
+
+Takes a file path and parses its content.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+### `try_parse(FILE*, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(FILE* fp,
+          std::string filename,
+          spec s = spec::default_version());
+}
+```
+
+Takes a `FILE*` and parses its content.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+### `try_parse(std::vector<unsigned char>, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(std::vector<unsigned char> content,
+          std::string filename,
+          spec s = spec::default_version());
+}
+```
+
+Takes a byte array and parses its content as a TOML file.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
+# `try_parse_str`
+
+### `try_parse_str(std::string, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse_str(std::string content,
+              spec s = spec::default_version(),
+              cxx::source_location loc = cxx::source_location::current());
+}
+```
+
+Parses a string as a TOML file, returning a `toml::basic_value` if successful, or a `std::vector<toml::error_info>` if it fails.
+
+Unlike `parse_str`, it does not throw `syntax_error`, but instead returns error information as the failure type of the `result`.
+
+If `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` is available, it will record the location information.
+
+Typically, you do not need to manually set the third argument `cxx::source_location`. If any of `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` are available, the information of the location where `parse_str` was called will be saved as the location information.
+
+{{< hint warning >}}
+
+Unlike `parse`, `try_parse` does not throw exceptions defined in toml11 such as `syntax_error`. However, please note that exceptions thrown by the standard library will still propagate.
+
+For instance, errors occurring internally within `std::ifstream` or memory exhaustion in `std::vector` will throw exceptions.
+
+{{< /hint >}}
+
+# `syntax_error`
+
+```cpp
+namespace toml
+{
+struct syntax_error final : public ::toml::exception
+{
+  public:
+    syntax_error(std::string what_arg, std::vector<error_info> err);
+    ~syntax_error() noexcept override = default;
+
+    const char* what() const noexcept override;
+    std::vector<error_info> const& errors() const noexcept
+};
+}
+```
+
+An exception thrown when a syntax error is detected in TOML.
+
+It is thrown by `parse` but not by `try_parse`.
+
+# `file_io_error`
+
+```cpp
+namespace toml
+{
+struct file_io_error final : public ::toml::exception
+{
+  public:
+    file_io_error(const std::string& msg, const std::string& fname);
+    file_io_error(int errnum, const std::string& msg, const std::string& fname);
+    ~file_io_error() noexcept override = default;
+
+    const char* what() const noexcept override;
+
+    bool has_errno() const noexcept;
+    int  get_errno() const noexcept;
+};
+}
+```
+
+An exception thrown when reading the contents of a file fails.
+
+When using `FILE*` to read a file, `errno` is set.
+
+### `has_errno`
+
+If `std::ifstream` fails, `errno` is not set.
+
+In this case, `has_errno` returns `false`.
+
+### `get_errno`
+
+Particularly when passing a `FILE*`, retrieves the value of `errno`.
+
+If `has_errno` is `false`, it returns `0`.
+
+# Related
+
+- [error_info.hpp]({{<ref "error_info.md">}})
+- [result.hpp]({{<ref "result.md">}})
+- [spec.hpp]({{<ref "spec.md">}})
+- [value.hpp]({{<ref "value.md">}})

docs/content.en/docs/reference/result.md

@@ -0,0 +1,518 @@
++++
+title = "result.hpp"
+type  = "docs"
++++
+
+# result.hpp
+
+`result.hpp` defines the `result` type, which can hold either a success value or a failure value.
+
+This is used as the return type for `toml::try_parse`, which does not throw exceptions.
+
+# success
+
+A type that holds a success value.
+
+```cpp
+namespace toml
+{
+template<typename T>
+struct success
+{
+    using value_type = T;
+
+    explicit success(value_type v);
+
+    ~success() = default;
+    success(const success&) = default;
+    success(success&&)      = default;
+    success& operator=(const success&) = default;
+    success& operator=(success&&)      = default;
+
+    template<typename U>
+    explicit success(U&& v);
+    template<typename U>
+    explicit success(success<U> v);
+
+    value_type&       get()       noexcept;
+    value_type const& get() const noexcept;
+};
+
+template<typename T>
+success<typename std::decay<T>::type> ok(T&& v);
+template<std::size_t N>
+success<std::string> ok(const char (&literal)[N])
+}
+```
+
+## Member Types
+
+```cpp
+using value_type = T;
+```
+
+The type of the success value.
+
+## Member Functions
+
+### Constructor
+
+```cpp
+explicit success(value_type v);
+```
+
+Constructs with a `value_type` argument.
+
+```cpp
+template<typename U>
+explicit success(U&& v);
+```
+
+Constructs with another type that can be converted to `value_type`.
+
+```cpp
+template<typename U>
+explicit success(success<U> v);
+```
+
+Constructs with another `success` type that can be converted to `value_type`.
+
+### `get()`
+
+```cpp
+value_type&       get()       noexcept;
+value_type const& get() const noexcept;
+```
+
+Accesses the stored value.
+
+## Non-Member Functions
+
+### `ok(T)`
+
+```cpp
+template<typename T>
+success<typename std::decay<T>::type> ok(T&& v);
+template<std::size_t N>
+success<std::string> ok(const char (&literal)[N]);
+```
+
+Constructs and returns a `success` type from a success value.
+
+Converts a string literal into `std::string`.
+
+# `success<reference_wrapper<T>>`
+
+Specialization of `success` for when the success value is a reference.
+
+```cpp
+namespace toml
+{
+template<typename T>
+struct success<std::reference_wrapper<T>>
+{
+    using value_type = T;
+
+    explicit success(std::reference_wrapper<value_type> v) noexcept;
+
+    value_type&       get()       noexcept;
+    value_type const& get() const noexcept;
+};
+}
+```
+
+## Member Types
+
+```cpp
+using value_type = T;
+```
+
+The type of the success value. It is `T` from `std::reference_wrapper<T>`, not the reference itself.
+
+### `get()`
+
+```cpp
+value_type&       get()       noexcept;
+value_type const& get() const noexcept;
+```
+
+Accesses the stored value.
+
+# failure
+
+A type that holds a failure value.
+
+```cpp
+namespace toml
+{
+template<typename T>
+struct failure
+{
+    using value_type = T;
+
+    explicit failure(value_type v);
+
+    ~failure() = default;
+    failure(const failure&) = default;
+    failure(failure&&)      = default;
+    failure& operator=(const failure&) = default;
+    failure& operator=(failure&&)      = default;
+
+    template<typename U>
+    explicit failure(U&& v);
+    template<typename U>
+    explicit failure(failure<U> v);
+
+    value_type&       get()       noexcept;
+    value_type const& get() const noexcept;
+};
+
+template<typename T>
+failure<typename std::decay<T>::type> err(T&& v);
+template<std::size_t N>
+failure<std::string> err(const char (&literal)[N]);
+}
+```
+
+## Member Types
+
+```cpp
+using value_type = T;
+```
+
+The type of the failure value.
+
+## Member Functions
+
+### Constructor
+
+```cpp
+explicit failure(value_type v);
+```
+
+Constructs with a `value_type` argument.
+
+```cpp
+template<typename U>
+explicit failure(U&& v);
+```
+
+Constructs with another type that can be converted to `value_type`.
+
+```cpp
+template<typename U>
+explicit failure(failure<U> v);
+```
+
+Constructs with another `failure` type that can be converted to `value_type`.
+
+### `get()`
+
+```cpp
+value_type&       get()       noexcept;
+value_type const& get() const noexcept;
+```
+
+Accesses the stored value.
+
+## Non-Member Functions
+
+### `err(T)`
+
+```cpp
+template<typename T>
+failure<typename std::decay<T>::type> err(T&& v);
+template<std::size_t N>
+failure<std::string> err(const char (&literal)[N]);
+```
+
+Constructs and returns a `failure` type from a failure value.
+
+Converts a string literal into `std::string`.
+
+# `failure<reference_wrapper<T>>`
+
+Specialization of `failure` for when the failure value is a reference.
+
+```cpp
+namespace toml
+{
+template<typename T>
+struct failure<std::reference_wrapper<T>>
+{
+    using value_type = T;
+
+    explicit failure(std::reference_wrapper<value_type> v) noexcept;
+
+    value_type&       get()       noexcept {return value.get();}
+    value_type const& get() const noexcept {return value.get();}
+};
+}
+```
+
+## Member Types
+
+```cpp
+using value_type = T;
+```
+
+The type of the failure value. It is `T` from `std::reference_wrapper<T>`, not the reference itself.
+
+### `get()`
+
+```cpp
+value_type&       get()       noexcept;
+value_type const& get() const noexcept;
+```
+
+Accesses the stored value.
+
+# result
+
+A type that holds either a success value or a failure value.
+
+```cpp
+namespace toml
+{
+template<typename T, typename E>
+struct result
+{
+    using success_type = success<T>;
+    using failure_type = failure<E>;
+    using value_type = typename success_type::value_type;
+    using error_type = typename failure_type::value_type;
+
+    result(success_type s);
+    result(failure_type f);
+
+    template<typename U>
+    result(success<U> s);
+    template<typename U>
+    result(failure<U> f);
+
+    result& operator=(success_type s);
+    result& operator=(failure_type f);
+
+    template<typename U>
+    result& operator=(success<U> s);
+    template<typename U>
+    result& operator=(failure<U> f);
+
+    ~result() noexcept;
+
+    result(const result& other);
+    result(result&& other);
+    result& operator=(const result& other);
+    result& operator=(result&& other);
+
+    template<typename U, typename F>
+    result(result<U, F> other);
+    template<typename U, typename F>
+    result& operator=(result<U, F> other);
+
+    bool is_ok()  const noexcept;
+    bool is_err() const noexcept;
+
+    explicit operator bool() const noexcept;
+
+    value_type&       unwrap(cxx::source_location loc = cxx::source_location::current());
+    value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
+
+    value_type&       unwrap_or(value_type& opt)             noexcept;
+    value_type const& unwrap_or(value_type const& opt) const noexcept;
+
+    error_type&       unwrap_err(cxx::source_location loc = cxx::source_location::current());
+    error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
+
+    value_type&       as_ok()       noexcept;
+    value_type const& as_ok() const noexcept;
+
+    error_type&       as_err()       noexcept;
+    error_type const& as_err() const noexcept;
+};
+}
+```
+
+## Member Types
+
+### `success_type`
+
+`success<T>`.
+
+### `failure_type`
+
+`failure<E>`.
+
+### `value_type`
+
+The type `T` of the success value, alias for `success_type::value_type`.
+
+If `T` is `std::reference_wrapper<U>`, then it is `U`.
+
+### `error_type`
+
+The type `E` of the failure value, alias for `failure_type::value_type`.
+
+If `E` is `std::reference_wrapper<F>`, then it is `F`.
+
+## Member Functions
+
+### Constructor
+
+```cpp
+result() = delete;
+```
+
+Cannot construct `result` type by default. Needs to be given either a success or failure type.
+
+```cpp
+result(success_type s);
+result(failure_type f);
+```
+
+Constructs with a `success_type` or `failure_type`.
+
+```cpp
+template<typename U>
+result(success<U> s);
+template<typename U>
+result(failure<U> f);
+```
+
+Constructs with a `success<U>` or `failure<U>` that is convertible to `value_type` or `error_type`.
+
+```cpp
+template<typename U, typename F>
+result(result<U, F> other);
+template<typename U, typename F>
+result& operator=(result<U, F> other);
+```
+
+Constructs from or assigns to another `result` with convertible `success` or `failure` types.
+
+### Copy and Move Constructors
+
+```cpp
+result(const result& other);
+result(result&& other);
+```
+
+Can be copy or move constructed.
+
+### `operator=`
+
+```cpp
+result& operator=(const result& other);
+result& operator=(result&& other);
+```
+
+Can be copy or move assigned.
+
+```cpp
+template<typename U>
+result& operator=(success<U> s);
+template<typename U>
+result& operator=(failure<U> f);
+```
+
+Can be assigned from convertible `success` or `failure` types.
+
+### `is_ok()`
+
+```cpp
+bool is_ok()  const noexcept;
+```
+
+Returns `true` if it holds a success value, `false` otherwise.
+
+### `is_err()`
+
+```cpp
+bool is_err() const noexcept;
+```
+
+Returns `true` if it holds a failure value, `false` otherwise.
+
+### `operator bool()`
+
+```cpp
+explicit operator bool() const noexcept;
+```
+
+Returns `true` if it holds a success value, `false` otherwise.
+
+### `unwrap()`
+
+```cpp
+value_type&       unwrap(cxx::source_location loc = cxx::source_location::current());
+value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
+```
+
+Returns the stored success value.
+
+Throws `toml::bad_result_access` if it holds a failure value.
+
+If `std::source_location` or equivalent compiler extension is available, the file name and line number where `unwrap()` occurred are included in the `what()` string.
+
+### `unwrap_or()`
+
+```cpp
+value_type&       unwrap_or(value_type& opt)             noexcept;
+value_type const& unwrap_or(value_type const& opt) const noexcept;
+```
+
+Returns the stored success value if present, otherwise returns the provided default value.
+
+### `unwrap_err()`
+
+```cpp
+error_type&       unwrap_err(cxx::source_location loc = cxx::source_location::current());
+error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
+```
+
+Returns the stored failure value.
+
+Throws `toml::bad_result_access` if it holds a success value.
+
+If `std::source_location` or equivalent compiler extension is available, the file name and line number where `unwrap_err()` occurred are included in the `what()` string.
+
+### `as_ok()`
+
+```cpp
+value_type&       as_ok()       noexcept;
+value_type const& as_ok() const noexcept;
+```
+
+Returns the success value without checking.
+
+Behavior is undefined if it holds a failure value.
+
+### `as_err()`
+
+```cpp
+error_type&       as_err()       noexcept;
+error_type const& as_err() const noexcept;
+```
+
+Returns the failure value without checking.
+
+Behavior is undefined if it holds a success value.
+
+# bad_result_access
+
+An exception thrown when `unwrap` or `unwrap_err` fails in a `result`.
+
+```cpp
+namespace toml
+{
+struct bad_result_access : public ::toml::exception
+{
+  public:
+    explicit bad_result_access(const std::string& what_arg);
+    virtual ~bad_result_access() noexcept override = default;
+    virtual const char* what() const noexcept override;
+  protected:
+    std::string what_;
+};
+}
+```

docs/content.en/docs/reference/serializer.md

@@ -0,0 +1,65 @@
++++
+title = "serializer.hpp"
+type  = "docs"
++++
+
+# serializer.hpp
+
+## `format`
+
+Serializes the data.
+
+```cpp
+namespace toml
+{
+template<typename TC>
+std::string format(const basic_value<TC>& v,
+                   const spec s = spec::default_version());
+template<typename TC>
+std::string format(const typename basic_value<TC>::key_type& k,
+                   const basic_value<TC>& v,
+                   const spec s = spec::default_version());
+template<typename TC>
+std::string format(const std::vector<typename basic_value<TC>::key_type>& ks,
+                   const basic_value<TC>& v,
+                   const spec s = spec::default_version());
+}
+```
+
+If there's a conflict between the format information and the `spec`, for example, when using `v1.0.0` with `table_format::multiline_oneline`, the `spec` takes precedence.
+
+### `format(v, spec)`
+
+Formats a `toml::value` according to its format information and the provided `spec`.
+
+If it's a `table_type`, it's formatted as if it were the root table. Otherwise, only the value is formatted.
+
+### `format(k, v, spec)`
+
+Formats a `toml::value` along with the given key.
+
+`v` is interpreted as being defined under that key.
+
+### `format([k,...], v, spec)`
+
+`v` is interpreted as being defined under those keys.
+If multiple keys are provided, it's interpreted as a recursively defined table.
+
+## `serialization_error`
+
+Reports errors that occurred during serialization.
+
+```cpp
+namespace toml
+{
+struct serialization_error final : public ::toml::exception
+{
+  public:
+    explicit serialization_error(std::string what_arg, source_location loc);
+    ~serialization_error() noexcept override = default;
+
+    const char* what() const noexcept override;
+    source_location const& location() const noexcept;
+};
+}
+```

docs/content.en/docs/reference/source_location.md

@@ -0,0 +1,235 @@
++++
+title = "source_location.hpp"
+type  = "docs"
++++
+
+# source_location.hpp
+
+`source_location.hpp` defines a class representing a specific area within a TOML file.
+
+This class is used to represent problematic areas in error messages.
+
+# `toml::source_location`
+
+`source_location` is a class representing a specific area within a TOML file.
+
+```cpp
+namespace toml
+{
+struct source_location
+{
+  public:
+
+    explicit source_location(/* implementation-defined */);
+    ~source_location() = default;
+    source_location(source_location const&) = default;
+    source_location(source_location &&)     = default;
+    source_location& operator=(source_location const&) = default;
+    source_location& operator=(source_location &&)     = default;
+
+    bool        is_ok()  const noexcept;
+    std::size_t length() const noexcept;
+
+    std::size_t first_line_number()   const noexcept;
+    std::size_t first_column_number() const noexcept;
+    std::size_t last_line_number()    const noexcept;
+    std::size_t last_column_number()  const noexcept;
+
+    std::string const& file_name()    const noexcept;
+
+    std::size_t num_lines()           const noexcept;
+
+    std::string const& first_line() const;
+    std::string const& last_line()  const;
+
+    std::vector<std::string> const& lines() const noexcept;
+};
+
+template<typename ... Ts>
+std::string format_location(const source_location& loc, const std::string& msg, const Ts& ... locs_and_msgs);
+} //toml
+```
+
+## Member Functions
+
+### Constructor
+
+```cpp
+explicit source_location(/* implementation-defined */);
+```
+
+`toml::source_location` can only be constructed via `toml::parse` or the `_toml` literal.
+
+### `is_ok()`
+
+```cpp
+bool is_ok() const noexcept;
+```
+
+Returns `true` if the `source_location` holds a valid value, `false` otherwise.
+
+The result of `location()` from `toml::value` constructed outside of `toml::parse` or `_toml` literals returns `false` for `is_ok` as it points to nothing.
+
+### `length()`
+
+```cpp
+std::size_t length() const noexcept;
+```
+
+Returns the length of the area pointed to by the `source_location`.
+
+Returns `0` if it does not hold a valid value.
+
+### `first_line_number()`
+
+```cpp
+std::size_t first_line_number() const noexcept;
+```
+
+Returns the line number of the first line of the area pointed to by the `source_location`.
+
+Returns `1` if it does not hold a valid value.
+
+### `first_column_number()`
+
+```cpp
+std::size_t first_column_number() const noexcept;
+```
+
+Returns the column number of the first column of the area pointed to by the `source_location`.
+
+Returns `1` if it does not hold a valid value.
+
+### `last_line_number()`
+
+```cpp
+std::size_t last_line_number() const noexcept;
+```
+
+Returns the line number of the last line of the area pointed to by the `source_location`.
+
+Returns `1` if it does not hold a valid value.
+
+### `last_column_number()`
+
+```cpp
+std::size_t last_column_number() const noexcept;
+```
+
+Returns the column number of the last column of the area pointed to by the `source_location`.
+
+Returns `1` if it does not hold a valid value.
+
+### `file_name()`
+
+```cpp
+std::string const& file_name() const noexcept;
+```
+
+Returns the file name containing the area pointed to by the `source_location`.
+
+Returns `"unknown file"` if it does not hold a valid value.
+
+### `num_lines()`
+
+```cpp
+std::size_t num_lines() const noexcept;
+```
+
+Returns the number of lines in the area pointed to by the `source_location`.
+
+Returns `0` if it does not hold a valid value.
+
+### `first_line()`
+
+```cpp
+std::string const& first_line() const;
+```
+
+Returns the first line of the area pointed to by the `source_location`.
+
+Throws `std::out_of_range` if it does not hold a valid value.
+
+### `last_line()`
+
+```cpp
+std::string const& last_line() const;
+```
+
+Returns the last line of the area pointed to by the `source_location`.
+
+Throws `std::out_of_range` if it does not hold a valid value.
+
+### `lines()`
+
+```cpp
+std::vector<std::string> const& lines() const noexcept;
+```
+
+Returns all lines in the area pointed to by the `source_location`.
+
+Returns a reference to an empty `std::vector` if it does not hold a valid value.
+
+## Non-Member Functions
+ 
+### `format_location`
+
+```cpp
+template<typename ... Ts>
+std::string format_location(const source_location& loc, const std::string& msg,
+                            const Ts& ... locs_and_msgs);
+```
+
+Formats the specified `source_location` and its associated message as follows:
+
+```
+ -> {filename.toml}
+   |
+ 1 | a = 42
+   |     ^-- {message}
+```
+
+If colorization is enabled, ANSI escape sequences will be added for coloring.
+
+When multiple `locs_and_msgs` are provided, they must be in the order of `const source_location&` followed by `const std::string&`, and the next pair in the same order, and so on.
+
+#### Example: Multiple `source_location` and `std::string`
+
+When multiple `source_location` and `std::string` pairs are provided, they are formatted as follows:
+
+
+```cpp
+source_location& loc0;
+source_location& loc1;
+source_location& loc2;
+
+std::string msg0;
+std::string msg1;
+std::string msg2;
+
+format_location(loc0, msg0,
+                loc1, msg1,
+                loc2, msg2);
+```
+
+```
+ -> {filename0.toml}
+   |
+ 1 | a = 42
+   |     ^-- {message0}
+   |
+ -> {filename1.toml}
+   |
+ 2 | b = 3.14
+   |     ^-- {message1}
+   |
+ -> {filename2.toml}
+   |
+ 3 | c = "foo"
+   |     ^-- {message2}
+```
+
+# Related
+
+- [error_info.hpp]({{<ref "error_info.md">}})
+- [value.hpp]({{<ref "value.md">}})

docs/content.en/docs/reference/spec.md

@@ -0,0 +1,309 @@
++++
+title = "spec.hpp"
+type  = "docs"
++++
+
+# spec.hpp
+
+`spec.hpp` defines classes for specifying the version of TOML.
+
+# `toml::semantic_version`
+
+`semantic_version` is a class that stores version information.
+
+```cpp
+namespace toml
+{
+struct semantic_version
+{
+    constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
+
+    std::uint32_t major;
+    std::uint32_t minor;
+    std::uint32_t patch;
+};
+
+constexpr semantic_version
+make_semver(std::uint32_t major, std::uint32_t minor, std::uint32_t patch) noexcept;
+
+constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
+
+std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
+} //toml
+```
+
+## Member Functions
+
+### Constructor
+
+```cpp
+constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
+```
+
+Constructs a `semantic_version` instance with the specified `major`, `minor`, and `patch` version numbers.
+
+## Non-Member Functions
+
+### Comparison Operators
+
+```cpp
+constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
+constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
+```
+
+Compares two `semantic_version` instances according to semantic versioning rules.
+
+### Stream Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
+```
+
+Outputs the version in the format `{major}.{minor}.{patch}`.
+
+### `to_string`
+
+```cpp
+std::string to_string(const semantic_version& ver);
+```
+
+Converts the version to a string in the format `{major}.{minor}.{patch}`.
+
+# `toml::spec`
+
+`spec` is a class that stores TOML version information.
+
+```cpp
+struct spec
+{
+    constexpr static spec default_version() noexcept;
+
+    constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
+
+    constexpr explicit spec(const semantic_version& semver) noexcept;
+
+    semantic_version version; // toml version
+
+    // diff from v1.0.0 -> v1.1.0
+    bool v1_1_0_allow_control_characters_in_comments;
+    bool v1_1_0_allow_newlines_in_inline_tables;
+    bool v1_1_0_allow_trailing_comma_in_inline_tables;
+    bool v1_1_0_allow_non_english_in_bare_keys;
+    bool v1_1_0_add_escape_sequence_e;
+    bool v1_1_0_add_escape_sequence_x;
+    bool v1_1_0_make_seconds_optional;
+
+    // library extensions
+    bool ext_hex_float;  // allow hex float
+    bool ext_num_suffix; // allow number suffix
+    bool ext_null_value; // allow null value
+};
+```
+
+## Member Functions
+
+### Constructor
+
+```cpp
+constexpr explicit spec(const semantic_version& semver) noexcept;
+```
+
+Constructs a `spec` with the specified TOML version.
+
+Supports TOML v1.0.0 and TOML v1.1.0.
+
+### `default_version()`
+
+```cpp
+constexpr static spec default_version() noexcept;
+```
+
+Constructs a `spec` with the default version.
+
+Used as the default value for `toml::parse` and `toml::format`.
+
+In toml11 v4.0.0, the value is v1.0.0.
+
+### `v(major, minor, patch)`
+
+```cpp
+constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
+```
+
+Constructs a `spec` with the specified version.
+
+## Member Variables
+
+Each flag is automatically set to `true` when the specified version includes the corresponding feature.
+
+You can modify these flags to change the behavior of `toml::parse` and `toml::format`.
+
+{{<hint warning>}}
+
+Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.
+
+If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.
+
+As such, any features related to future versions should be considered unstable.
+
+{{</hint>}}
+
+### Example
+
+```cpp
+auto spec = toml::spec::v(1, 0, 0);
+// Allow newlines in inline tables in addition to v1.0.0 features.
+// Other v1.1.0 features are not enabled.
+spec.v1_1_0_allow_newlines_in_inline_tables = true;
+
+auto input = toml::parse("input_file.toml", spec);
+```
+
+### `v1_1_0_allow_control_characters_in_comments`
+
+```cpp
+bool v1_1_0_allow_control_characters_in_comments;
+```
+
+Allows most control characters in comments.
+
+Added in TOML v1.1.0.
+
+### `v1_1_0_allow_newlines_in_inline_tables`
+
+```cpp
+bool v1_1_0_allow_newlines_in_inline_tables;
+```
+
+Allows newlines in inline tables.
+
+Added in TOML v1.1.0.
+
+### `v1_1_0_allow_trailing_comma_in_inline_tables`
+
+```cpp
+bool v1_1_0_allow_trailing_comma_in_inline_tables;
+```
+
+Allows trailing commas in inline tables.
+
+Added in TOML v1.1.0.
+
+### `v1_1_0_add_escape_sequence_e`
+
+```cpp
+bool v1_1_0_add_escape_sequence_e;
+```
+
+Allows `\e` to represent the ESC character.
+
+Added in TOML v1.1.0.
+
+### `v1_1_0_add_escape_sequence_x`
+
+```cpp
+bool v1_1_0_add_escape_sequence_x;
+```
+
+Allows `\xHH` to represent a single byte character.
+
+Added in TOML v1.1.0.
+
+### `v1_1_0_make_seconds_optional`
+
+```cpp
+bool v1_1_0_make_seconds_optional;
+```
+
+Makes the seconds component in time optional.
+
+Unspecified seconds default to `0`.
+
+Added in TOML v1.1.0.
+
+### `ext_hex_float`
+
+```cpp
+bool ext_hex_float;
+```
+
+This is a language extension specific to toml11.
+
+It is initialized to `false` regardless of the specified version.
+You must explicitly set it to `true` if you want to use it.
+
+Allows hexadecimal representation of floating-point numbers.
+
+The hexadecimal representation conforms to the `printf` format specifier `%a/%A`.
+
+```
+hexf = 0xC0FFEEp-10
+```
+
+`toml::format` will format using hexadecimal notation only if the passed `toml::spec` has `ext_hex_float` set to `true`.
+If the format specifier indicates `hex` but the `toml::spec` passed to `toml::format` has `ext_hex_float` set to `false`, the hexadecimal specification is ignored, and the number is output in decimal notation with maximum precision.
+
+### `ext_num_suffix`
+
+```cpp
+bool ext_num_suffix;
+```
+
+This is a language extension specific to toml11.
+
+It is initialized to `false` regardless of the specified version.
+You must explicitly set it to `true` if you want to use it.
+
+Allows the addition of suffixes to decimal integers and floating-point numbers. This does not apply to hexadecimal, octal, or binary notations.
+
+There must be an `_` separator between the number and the suffix.
+
+The suffix cannot start with a digit to avoid confusion with the numeric part.
+
+```
+distance = 10_m   # valid
+distance = 10_2m  # invalid
+distance = 10_2_m # valid
+```
+
+The suffix is stored in the format information as `std::string suffix`.
+The `_` separating the number from the suffix is not included in the `suffix`.
+
+```cpp
+toml::value distance = toml::find(input, "distance");
+assert(distance.as_integer_fmt().suffix == std::string("m"));
+```
+
+`toml::format` will format the value with the suffix only if the passed `toml::spec` has `ext_num_suffix` set to `true`.
+
+The `suffix` follows the grammar defined as:
+
+```abnf
+non-digit-graph = ALPHA / non-ascii
+graph           = ALPHA / DIGIT / non-ascii
+suffix          = _ non-digit-graph *( graph / ( _ graph ) )
+```
+
+### `ext_null_value`
+
+```cpp
+bool ext_null_value;
+```
+
+This is a language extension specific to toml11.
+
+Allows the use of `null` as a value.
+
+A `toml::value` specified as `null` will have no value, and `is_empty()` will return `true`.
+
+`toml::format` will format it as `null` only if the passed `toml::spec` has `ext_null_value` set to `true`.
+Otherwise, `toml::format` will terminate with an error.

docs/content.en/docs/reference/toml.md

@@ -0,0 +1,13 @@
++++
+title = "toml.hpp"
+type  = "docs"
++++
+
+# toml.hpp
+
+`toml.hpp` includes all other headers.
+
+This allows access to all features of toml11.
+
+This header file and `toml_fwd.hpp` are located under `${TOML11_INCLUDE_DIR}/`,
+while other header files are located under `${toml11_include_dir}/toml11/`.

docs/content.en/docs/reference/toml_fwd.md

@@ -0,0 +1,18 @@
++++
+title = "toml_fwd.hpp"
+type  = "docs"
++++
+
+# toml_fwd.hpp
+
+`toml_fwd.hpp` contains forward declarations of structures defined in toml11 and macro definitions.
+
+When only forward declarations of toml11 structures are needed and implementation is not required, including `toml_fwd.hpp` instead of `toml.hpp` can reduce compilation time.
+
+{{<hint warning>}}
+
+Since this file only contains forward declarations, you cannot use `toml::table`, defined as `toml::basic_value<toml::type_config>::table_type`, and similarly defined `toml::array`. This is because they require the implementation of `basic_value`.
+
+{{</hint>}}
+
+This header file and `toml.hpp` are located under `${TOML11_INCLUDE_DIR}/`, while other header files are located under `${TOML11_INCLUDE_DIR}/toml11/`.

docs/content.en/docs/reference/types.md

@@ -0,0 +1,156 @@
++++
+title = "types.hpp"
+type  = "docs"
++++
+
+# types.hpp
+
+This document defines classes that specifies type information.
+
+# `type_config`
+
+`type_config` is a type that encapsulates parameters given to `toml::basic_value`.
+
+When using different types within `toml::basic_value<T>`, you need to define and pass this type separately.
+All elements listed are required.
+
+If you use numerical types that cannot use standard stream operators, define and replace the equivalents for `read_int` and `read_float`.
+
+```cpp
+namespace toml
+{
+struct type_config
+{
+    using comment_type  = preserve_comments;
+
+    using boolean_type  = bool;
+    using integer_type  = std::int64_t;
+    using floating_type = double;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::vector<T>;
+    template<typename K, typename T>
+    using table_type = std::unordered_map<K, T>;
+
+    static result<integer_type, error_info>
+    parse_int(const std::string& str, const source_location src, const std::uint8_t base);
+
+    static result<floating_type, error_info>
+    parse_float(const std::string& str, const source_location src, const bool is_hex);
+};
+
+using value = basic_value<type_config>;
+using table = typename value::table_type;
+using array = typename value::array_type;
+
+} // toml
+```
+
+## `static` Member Functions
+
+### `parse_int(str, src, base)`
+
+```cpp
+static result<integer_type, error_info>
+parse_int(const std::string& str, const source_location src, const std::uint8_t base);
+```
+
+If you use a type as `integer_type` that cannot utilize standard stream operators, implement this function.
+Otherwise, use `read_int` described later.
+
+The `str` parameter receives a string with prefixes, leading zeros, and underscores removed.
+
+The `src` parameter receives a `source_location` pointing to where the string was defined.
+
+The `base` parameter receives one of `10`, `2`, `8`, or `16`.
+
+### `parse_float(str, src, is_hex)`
+
+```cpp
+static result<floating_type, error_info>
+parse_float(const std::string& str, const source_location src, const bool is_hex);
+```
+
+If you use a type as `floating_type` that cannot utilize standard stream operators, implement this function.
+Otherwise, use `read_float` described later.
+
+The `str` parameter receives a string with prefixes, leading zeros, and underscores removed.
+
+The `src` parameter receives a `source_location` pointing to where the string was defined.
+
+The `is_hex` parameter indicates whether the format is `hexfloat`. If you don't use the `hexfloat` extension, you don't need to implement this.
+
+For details on the `hexfloat` extension, refer to [spec.hpp]({{<ref "spec.md">}}).
+
+## Non-member Functions
+
+### `read_int`
+
+```cpp
+template<typename T>
+result<T, error_info>
+read_int(const std::string& str, const source_location src, const std::uint8_t base);
+```
+
+This is the default function used. It parses using `std::istringstream`.
+
+If `operator>>` and manipulators like `std::hex`, and `std::numeric_limits<T>` are defined (such as for `boost::multiprecision`), you can use this without modifications.
+
+### `read_float`
+
+```cpp
+template<typename T>
+result<T, error_info>
+read_float(const std::string& str, const source_location src, const bool is_hex);
+```
+
+This is the default function used. It parses decimals using `std::istringstream` and hexfloats using `sscanf()`.
+
+It supports `double` and `float`.
+
+For other types, if `operator>>` is defined and `hex` is not used, you can use this function.
+
+# `ordered_type_config`
+
+`ordered_type_config` is a variation of `toml::type_config` where the table type is replaced with `toml::ordered_map`.
+Additionally, it defines the `toml::ordered_value` alias.
+
+Other than these changes, it is identical to `type_config`.
+
+```cpp
+namespace toml
+{
+struct ordered_type_config
+{
+    using comment_type  = preserve_comments;
+
+    using boolean_type  = bool;
+    using integer_type  = std::int64_t;
+    using floating_type = double;
+    using string_type   = std::string;
+
+    template<typename T>
+    using array_type = std::vector<T>;
+    template<typename K, typename T>
+    using table_type = ordered_map<K, T>;
+
+    static result<integer_type, error_info>
+    parse_int(const std::string& str, const source_location src, const std::uint8_t base)
+    {
+        return read_int<integer_type>(str, src, base);
+    }
+    static result<floating_type, error_info>
+    parse_float(const std::string& str, const source_location src, const bool is_hex)
+    {
+        return read_float<floating_type>(str, src, is_hex);
+    }
+};
+
+using ordered_value = basic_value<ordered_type_config>;
+using ordered_table = typename ordered_value::table_type;
+using ordered_array = typename ordered_value::array_type;
+
+} // toml
+```
+

docs/content.en/docs/reference/value.md

@@ -0,0 +1,896 @@
++++
+title = "value.hpp"
+type  = "docs"
++++
+
+# value.hpp
+
+`value.hpp` defines `basic_value`.
+
+# `toml::basic_value`
+
+`basic_value` is a class that stores TOML values.
+
+```cpp
+namespace toml
+{
+template <class TypeConfig>
+class basic_value;
+
+// Defined in types.hpp
+// using value = basic_value<type_config>;
+// using table = typename basic_value<type_config>::table_type;
+// using array = typename basic_value<type_config>::array_type;
+
+template<typename TC>
+bool operator==(const basic_value<TC>&, const basic_value<TC>&);
+template<typename TC>
+bool operator!=(const basic_value<TC>&, const basic_value<TC>&);
+template<typename TC>
+bool operator< (const basic_value<TC>&, const basic_value<TC>&);
+template<typename TC>
+bool operator<=(const basic_value<TC>&, const basic_value<TC>&);
+template<typename TC>
+bool operator> (const basic_value<TC>&, const basic_value<TC>&);
+template<typename TC>
+bool operator>=(const basic_value<TC>&, const basic_value<TC>&);
+} //toml
+```
+
+## Member Types
+
+The following member types are defined.
+
+You can modify the member types using `TypeConfig`.
+
+See also: [types.hpp]({{<ref "types.md">}})
+
+| Name                   | Definition |
+|:-----------------------|:-------------------------------------|
+| `char_type`            | `typename TypeConfig::char_type`     |
+| `key_type`             | `typename TypeConfig::string_type`   |
+| `value_type`           | `basic_value<TypeConfig>`            |
+| `boolean_type`         | `typename TypeConfig::boolean_type`  |
+| `integer_type`         | `typename TypeConfig::integer_type`  |
+| `floating_type`        | `typename TypeConfig::floating_type` |
+| `string_type`          | `typename TypeConfig::string_type`   |
+| `local_time_type`      | `toml::local_time`                   |
+| `local_date_type`      | `toml::local_date`                   |
+| `local_datetime_type`  | `toml::local_datetime`               |
+| `offset_datetime_type` | `toml::offset_datetime`              |
+| `array_type`           | `typename TypeConfig::template array_type<value_type>`|
+| `table_type`           | `typename TypeConfig::template table_type<key_type, value_type>`|
+| `comment_type`         | `typename TypeConfig::comment_type`  |
+
+## Member Functions
+
+### Default Constructor
+
+```cpp
+basic_value() noexcept
+```
+
+Constructs an empty `toml::value`.
+
+The constructed `toml::value` will be empty.
+
+### Copy and Move Constructors
+
+```cpp
+basic_value(const basic_value& v)
+basic_value(basic_value&& v)
+```
+
+Copies or moves all information including values, format information, comments, and file regions.
+
+### Copy and Move Constructors with Comments
+
+```cpp
+basic_value(basic_value v, std::vector<std::string> com)
+```
+
+Copies or moves the object while overwriting comments.
+
+### Conversion Constructors
+
+```cpp
+template<typename TI>
+basic_value(basic_value<TI> other)
+template<typename TI>
+basic_value(basic_value<TI> other, std::vector<std::string> com)
+```
+
+Copies or moves from a `basic_value` with a different `type_config`.
+
+### Constructor (boolean)
+
+```cpp
+basic_value(boolean_type x)
+basic_value(boolean_type x, boolean_format_info fmt)
+basic_value(boolean_type x, std::vector<std::string> com)
+basic_value(boolean_type x, boolean_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `bool`, its format information, and comments.
+
+### Constructor (integer)
+
+```cpp
+template<typename T, /* std::is_integral<T> is true */>
+basic_value(T x)
+template<typename T, /* std::is_integral<T> is true */>
+basic_value(T x, integer_format_info fmt)
+template<typename T, /* std::is_integral<T> is true */>
+basic_value(T x, std::vector<std::string> com)
+template<typename T, /* std::is_integral<T> is true */>
+basic_value(T x, integer_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with an `integer`, its format information, and comments.
+
+### Constructor (floating)
+
+```cpp
+template<typename T, /* std::is_floating_point<T> is true */>
+basic_value(T x)
+template<typename T, /* std::is_floating_point<T> is true */>
+basic_value(T x, floating_format_info fmt)
+template<typename T, /* std::is_floating_point<T> is true */>
+basic_value(T x, std::vector<std::string> com)
+template<typename T, /* std::is_floating_point<T> is true */>
+basic_value(T x, floating_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `floating` point number, its format information, and comments.
+
+### Constructor (string)
+
+```cpp
+basic_value(string_type x)
+basic_value(string_type x, string_format_info fmt)
+basic_value(string_type x, std::vector<std::string> com)
+basic_value(string_type x, string_format_info fmt, std::vector<std::string> com)
+
+basic_value(const string_type::value_type* x)
+basic_value(const string_type::value_type* x, string_format_info fmt)
+basic_value(const string_type::value_type* x, std::vector<std::string> com)
+basic_value(const string_type::value_type* x, string_format_info fmt, std::vector<std::string> com)
+
+// C++17以降
+basic_value(string_view_type x)
+basic_value(string_view_type x, string_format_info fmt)
+basic_value(string_view_type x, std::vector<std::string> com)
+basic_value(string_view_type x, string_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `string`, its format information, and comments.
+
+`string_view_type` shares the same `value_type` and `traits_type` as `string_type`.
+
+### Constructor (local_date)
+
+```cpp
+basic_value(local_date_type x)
+basic_value(local_date_type x, local_date_format_info fmt)
+basic_value(local_date_type x, std::vector<std::string> com)
+basic_value(local_date_type x, local_date_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `local_date_type`, its format information, and comments.
+
+### Constructor (local_time)
+
+```cpp
+basic_value(local_time_type x)
+basic_value(local_time_type x, local_time_format_info fmt)
+basic_value(local_time_type x, std::vector<std::string> com)
+basic_value(local_time_type x, local_time_format_info fmt, std::vector<std::string> com)
+
+template<typename Rep, typename Period>
+basic_value(const std::chrono::duration<Rep, Period>& x)
+template<typename Rep, typename Period>
+basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt)
+template<typename Rep, typename Period>
+basic_value(const std::chrono::duration<Rep, Period>& x, std::vector<std::string> com)
+template<typename Rep, typename Period>
+basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `local_time_type`, its format information, and comments.
+
+For `std::chrono::duration`, constructs as a time span from `00:00:00`.
+
+### Constructor (local_datetime)
+
+```cpp
+basic_value(local_datetime_type x)
+basic_value(local_datetime_type x, local_date_format_info fmt)
+basic_value(local_datetime_type x, std::vector<std::string> com)
+basic_value(local_datetime_type x, local_date_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `local_datetime_type`, its format information, and comments.
+
+### Constructor (offset_datetime)
+
+```cpp
+basic_value(offset_datetime_type x)
+basic_value(offset_datetime_type x, offset_date_format_info fmt)
+basic_value(offset_datetime_type x, std::vector<std::string> com)
+basic_value(offset_datetime_type x, offset_date_format_info fmt, std::vector<std::string> com)
+
+basic_value(std::chrono::system_clock::time_point x)
+basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt)
+basic_value(std::chrono::system_clock::time_point x, std::vector<std::string> com)
+basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with an `offset_datetime_type`, its format information, and comments.
+
+For `std::chrono::system_clock::time_point`, constructs for the pointed time.
+
+### Constructor (array)
+
+```cpp
+basic_value(array_type x)
+basic_value(array_type x, integer_format_info fmt)
+basic_value(array_type x, std::vector<std::string> com)
+basic_value(array_type x, integer_format_info fmt, std::vector<std::string> com)
+
+template<typename T, /* T is array-like */>
+basic_value(T x)
+template<typename T, /* T is array-like */>
+basic_value(T x, array_format_info fmt)
+template<typename T, /* T is array-like */>
+basic_value(T x, std::vector<std::string> com)
+template<typename T, /* T is array-like */>
+basic_value(T x, array_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with an `array`, its format information, and comments.
+
+`array-like` types must meet the following criteria:
+
+- Has `T::iterator`.
+- Has `T::value_type`.
+- Does **not** have `T::key_type`.
+- Does **not** have `T::mapped_type`.
+- Is **not** `std::string`.
+- Is **not** `std::string_view` (since C++17).
+
+### Constructor (table)
+
+```cpp
+basic_value(table_type x)
+basic_value(table_type x, integer_format_info fmt)
+basic_value(table_type x, std::vector<std::string> com)
+basic_value(table_type x, integer_format_info fmt, std::vector<std::string> com)
+
+template<typename T, /* T is table-like */>
+basic_value(T x)
+template<typename T, /* T is table-like */>
+basic_value(T x, table_format_info fmt)
+template<typename T, /* T is table-like */>
+basic_value(T x, std::vector<std::string> com)
+template<typename T, /* T is table-like */>
+basic_value(T x, table_format_info fmt, std::vector<std::string> com)
+```
+
+Constructs an object with a `table`, its format information, and comments.
+
+`table-like` types must meet the following criteria:
+
+- Has `T::iterator`.
+- Has `T::value_type`.
+- Has `T::key_type`.
+- Has `T::mapped_type`.
+
+### Constructor (user-defined)
+
+```cpp
+template<typename T /* toml::into<T> is defined */>
+basic_value(const T& ud);
+
+template<typename T /* toml::into<T> is defined */>
+basic_value(const T& ud, std::vector<std::string> com);
+
+template<typename T /* toml::into<T> is not defined, but T{}.into_toml() exists */>
+basic_value(const T& ud);
+
+template<typename T /* toml::into<T> is not defined, but T{}.into_toml() exists */>
+basic_value(const T& ud, std::vector<std::string> com);
+```
+
+If `toml::into<T>` is defined, constructs from the result of `toml::into<T>(ud)`.
+
+If `toml::into<T>` is not defined but `T` has a `into_toml()` member function, constructs from the result of `ud.into_toml()`.
+
+-----
+
+### `operator=(basic_value)`
+
+```cpp
+basic_value& operator=(const basic_value& v)
+basic_value& operator=(basic_value&& v)
+template<typename TI>
+basic_value& operator=(basic_value<TI> other)
+```
+
+Assigns the right-hand side `basic_value` to the current object.
+
+### `operator=(T)`
+
+```cpp
+template<typename T>
+basic_value& operator=(T x)
+```
+
+Assigns a value corresponding to `T`.
+
+The contents pointed to by `source_location` are discarded.
+
+If the object already holds a value of the same type, the original format information is retained.
+
+-----
+
+### `is<T>()`
+
+```cpp
+bool is<T>() const noexcept
+```
+
+#### Requirements
+
+`T` must be an exact TOML type, meaning it corresponds to one of the `toml::value::xxx_type`.
+
+#### Return Value
+
+Returns `true` if the stored type matches `T`, otherwise returns `false`.
+
+-----
+
+### `is(toml::value_t)`
+
+```cpp
+bool is(toml::value_t t) const noexcept
+```
+
+#### Return Value
+
+Returns `true` if the tag of the stored type matches `t`, otherwise returns `false`.
+
+-----
+
+### `is_xxx()`
+
+```cpp
+bool is_boolean()         const noexcept;
+bool is_integer()         const noexcept;
+bool is_floating()        const noexcept;
+bool is_string()          const noexcept;
+bool is_offset_datetime() const noexcept;
+bool is_local_datetime()  const noexcept;
+bool is_local_date()      const noexcept;
+bool is_local_time()      const noexcept;
+bool is_array()           const noexcept;
+bool is_table()           const noexcept;
+```
+
+#### Return Value
+
+Returns `true` if the stored type matches the corresponding type, otherwise returns `false`.
+
+------
+
+### `is_empty()`
+
+```cpp
+bool is_empty()   const noexcept;
+```
+
+#### Return Value
+
+Returns `true` if the object is default constructed and no value is assigned, otherwise returns `false`.
+
+### `is_array_of_tables()`
+
+```cpp
+bool is_array_of_tables() const noexcept;
+```
+
+#### Return Value
+
+Returns `true` if the stored type is an array that is not empty and all elements are tables, otherwise returns `false`.
+
+-----
+
+### `type()`
+
+```cpp
+toml::value_t type() const noexcept
+```
+
+#### Return Value
+
+Returns the tag corresponding to the stored type.
+
+-----
+
+### `as_xxx()`
+
+```cpp
+boolean_type         const& as_boolean        () const;
+integer_type         const& as_integer        () const;
+floating_type        const& as_floating       () const;
+string_type          const& as_string         () const;
+offset_datetime_type const& as_offset_datetime() const;
+local_datetime_type  const& as_local_datetime () const;
+local_date_type      const& as_local_date     () const;
+local_time_type      const& as_local_time     () const;
+array_type           const& as_array          () const;
+table_type           const& as_table          () const;
+
+boolean_type        & as_boolean        ();
+integer_type        & as_integer        ();
+floating_type       & as_floating       ();
+string_type         & as_string         ();
+offset_datetime_type& as_offset_datetime();
+local_datetime_type & as_local_datetime ();
+local_date_type     & as_local_date     ();
+local_time_type     & as_local_time     ();
+array_type          & as_array          ();
+table_type          & as_table          ();
+```
+
+#### Return Value
+
+Returns a reference to the value of the specified type.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value's type does not match the specified type.
+
+-----
+
+### `as_xxx(std::nothrow)`
+
+Invoke with a `std::nothrow` object.
+
+```cpp
+boolean_type         const& as_boolean        (const std::nothrow_t&) const noexcept;
+integer_type         const& as_integer        (const std::nothrow_t&) const noexcept;
+floating_type        const& as_floating       (const std::nothrow_t&) const noexcept;
+string_type          const& as_string         (const std::nothrow_t&) const noexcept;
+offset_datetime_type const& as_offset_datetime(const std::nothrow_t&) const noexcept;
+local_datetime_type  const& as_local_datetime (const std::nothrow_t&) const noexcept;
+local_date_type      const& as_local_date     (const std::nothrow_t&) const noexcept;
+local_time_type      const& as_local_time     (const std::nothrow_t&) const noexcept;
+array_type           const& as_array          (const std::nothrow_t&) const noexcept;
+table_type           const& as_table          (const std::nothrow_t&) const noexcept;
+
+boolean_type        & as_boolean        (const std::nothrow_t&) noexcept;
+integer_type        & as_integer        (const std::nothrow_t&) noexcept;
+floating_type       & as_floating       (const std::nothrow_t&) noexcept;
+string_type         & as_string         (const std::nothrow_t&) noexcept;
+offset_datetime_type& as_offset_datetime(const std::nothrow_t&) noexcept;
+local_datetime_type & as_local_datetime (const std::nothrow_t&) noexcept;
+local_date_type     & as_local_date     (const std::nothrow_t&) noexcept;
+local_time_type     & as_local_time     (const std::nothrow_t&) noexcept;
+array_type          & as_array          (const std::nothrow_t&) noexcept;
+table_type          & as_table          (const std::nothrow_t&) noexcept;
+```
+
+#### Return Value
+
+Returns a reference to the value of the specified type.
+
+#### Note
+
+If the type of the stored value does not match the specified type, the behavior is undefined.
+
+-----
+
+### `as_xxx_fmt()`
+
+Accesses format information.
+
+```cpp
+boolean_format_info        & as_boolean_fmt        ();
+integer_format_info        & as_integer_fmt        ();
+floating_format_info       & as_floating_fmt       ();
+string_format_info         & as_string_fmt         ();
+offset_datetime_format_info& as_offset_datetime_fmt();
+local_datetime_format_info & as_local_datetime_fmt ();
+local_date_format_info     & as_local_date_fmt     ();
+local_time_format_info     & as_local_time_fmt     ();
+array_format_info          & as_array_fmt          ();
+table_format_info          & as_table_fmt          ();
+
+boolean_format_info         const& as_boolean_fmt        () const;
+integer_format_info         const& as_integer_fmt        () const;
+floating_format_info        const& as_floating_fmt       () const;
+string_format_info          const& as_string_fmt         () const;
+offset_datetime_format_info const& as_offset_datetime_fmt() const;
+local_datetime_format_info  const& as_local_datetime_fmt () const;
+local_date_format_info      const& as_local_date_fmt     () const;
+local_time_format_info      const& as_local_time_fmt     () const;
+array_format_info           const& as_array_fmt          () const;
+table_format_info           const& as_table_fmt          () const;
+```
+
+#### Return Value
+
+Returns a reference to the structure holding the format information for the specified type.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value's type does not match the specified type.
+
+-----
+
+### `as_xxx_fmt(std::nothrow)`
+
+Invoke with a `std::nothrow` object.
+
+```cpp
+boolean_format_info        & as_boolean_fmt        (const std::nothrow_t&) noexcept;
+integer_format_info        & as_integer_fmt        (const std::nothrow_t&) noexcept;
+floating_format_info       & as_floating_fmt       (const std::nothrow_t&) noexcept;
+string_format_info         & as_string_fmt         (const std::nothrow_t&) noexcept;
+offset_datetime_format_info& as_offset_datetime_fmt(const std::nothrow_t&) noexcept;
+local_datetime_format_info & as_local_datetime_fmt (const std::nothrow_t&) noexcept;
+local_date_format_info     & as_local_date_fmt     (const std::nothrow_t&) noexcept;
+local_time_format_info     & as_local_time_fmt     (const std::nothrow_t&) noexcept;
+array_format_info          & as_array_fmt          (const std::nothrow_t&) noexcept;
+table_format_info          & as_table_fmt          (const std::nothrow_t&) noexcept;
+
+boolean_format_info         const& as_boolean_fmt        (const std::nothrow_t&) const noexcept;
+integer_format_info         const& as_integer_fmt        (const std::nothrow_t&) const noexcept;
+floating_format_info        const& as_floating_fmt       (const std::nothrow_t&) const noexcept;
+string_format_info          const& as_string_fmt         (const std::nothrow_t&) const noexcept;
+offset_datetime_format_info const& as_offset_datetime_fmt(const std::nothrow_t&) const noexcept;
+local_datetime_format_info  const& as_local_datetime_fmt (const std::nothrow_t&) const noexcept;
+local_date_format_info      const& as_local_date_fmt     (const std::nothrow_t&) const noexcept;
+local_time_format_info      const& as_local_time_fmt     (const std::nothrow_t&) const noexcept;
+array_format_info           const& as_array_fmt          (const std::nothrow_t&) const noexcept;
+table_format_info           const& as_table_fmt          (const std::nothrow_t&) const noexcept;
+```
+
+#### Return Value
+
+Returns a reference to the structure holding the format information for the specified type.
+
+#### Note
+
+If the type of the stored value does not match the specified type, the behavior is undefined.
+
+-----
+
+### `at(key)`
+
+```cpp
+value_type&       at(const key_type& key);
+value_type const& at(const key_type& key) const;
+```
+
+#### Return Value
+
+Casts the current `value` to a `table` and returns the element specified by `key`.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not a `table`.
+
+Throws `std::out_of_range` if the `table` does not contain the specified element.
+
+-----
+
+#### `operator[](key)`
+
+```cpp
+value_type& operator[](const key_type& k);
+```
+
+##### Return Value
+
+Casts the current `value` to a `table` and returns a reference to the element specified by `key`.
+
+If the element specified by `key` does not exist, it is default-constructed.
+
+##### Exception
+
+Throws `toml::type_error` if the stored value is not a `table`.
+
+-----
+
+### `count(key)`
+
+```cpp
+std::size_t count(const key_type& key) const;
+```
+
+#### Return Value
+
+Casts the current `value` to a `table` and returns `1` if the element corresponding to `key` is present, otherwise returns `0`.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not a `table`.
+
+-----
+
+### `contains(key)`
+
+```cpp
+bool contains(const key_type& key) const;
+```
+
+#### Return Value
+
+Casts the current `value` to a `table` and returns `true` if the element corresponding to `key` is present, otherwise returns `false`.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not a `table`.
+
+-----
+
+### `at(idx)`
+
+```cpp
+value_type&       at(const std::size_t idx);
+value_type const& at(const std::size_t idx) const;
+```
+
+#### Return Value
+
+Casts the current `value` to an `array` and returns the element specified by `idx`.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not an `array`.
+
+Throws `std::out_of_range` if the specified element does not exist in the `array`.
+
+
+-----
+
+### `operator[](idx)`
+
+```cpp
+value_type&       operator[](const std::size_t idx)       noexcept;
+value_type const& operator[](const std::size_t idx) const noexcept;
+```
+
+#### Return Value
+
+Casts the current `value` to an `array` and returns a reference to the element specified by `idx`.
+
+#### Note
+
+Performs no checks. Behavior is undefined if the stored value is not an `array` or if the specified element does not exist.
+
+-----
+
+### `push_back(value)`
+
+```cpp
+void push_back(const value_type& x);
+void push_back(value_type&& x);
+```
+
+Casts the current `value` to an `array` and performs `push_back` on the `array`.
+
+#### Return Value
+
+None.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not an `array`.
+
+-----
+
+### `emplace_back(args...)`
+
+```cpp
+template<typename ... Ts>
+value_type& emplace_back(Ts&& ... args)
+```
+
+Casts the current `value` to an `array` and performs `emplace_back` on the `array`.
+
+#### Return Value
+
+A reference to the constructed value.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not an `array`.
+
+-----
+
+### `size()`
+
+```cpp
+std::size_t size() const;
+```
+
+#### Return Value
+
+Casts the current `value` to an `array`, `string`, or `table` and returns the number of elements. For a `string`, it returns the number of characters.
+
+#### Exception
+
+Throws `toml::type_error` if the stored value is not an `array`, `string`, or `table`.
+
+-----
+
+### `location()`
+
+```cpp
+source_location location() const;
+```
+
+#### Return Value
+
+Returns a `source_location` object representing the position within the TOML document where the `value` is defined.
+
+If the `value` was not constructed by parsing a TOML document, returns a `source_location` that points to nowhere.
+
+-----
+
+### `comments()`
+
+```cpp
+comment_type const& comments() const noexcept;
+comment_type&       comments()       noexcept;
+```
+
+#### Return Value
+
+Returns a reference to the comment container.
+
+## Non-Member Functions
+
+### `operator==`
+
+```cpp
+template<typename TC>
+bool operator==(const basic_value<TC>&, const basic_value<TC>&);
+```
+
+Two `basic_value<T>` instances are considered equal if they satisfy the following conditions:
+
+- The contained type is the same.
+- The contained values are identical.
+- The comments are identical at the byte level.
+
+### `operator!=`
+
+```cpp
+template<typename TC>
+bool operator!=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
+{
+    return !(lhs == rhs);
+}
+```
+
+### `operator<`
+
+Defined only if `array_type` and `table_type` have `operator<`.
+
+```cpp
+template<typename TC>
+bool operator<(const basic_value<TC>&, const basic_value<TC>&);
+```
+
+Comparison order:
+
+1. TOML type
+2. If TOML types are the same, their values
+3. If both the TOML types and values are the same, the comments
+
+TOML types have the following order (from smallest to largest):
+
+1. `toml::value_t::empty`
+2. `toml::value_t::boolean`
+3. `toml::value_t::integer`
+4. `toml::value_t::floating`
+5. `toml::value_t::string`
+6. `toml::value_t::offset_datetime`
+7. `toml::value_t::local_datetime`
+8. `toml::value_t::local_date`
+9. `toml::value_t::local_time`
+10. `toml::value_t::array`
+11. `toml::value_t::table`
+
+### `operator<=`
+
+Defined only if `array_type` and `table_type` have `operator<`.
+
+```cpp
+template<typename TC>
+bool operator<=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
+{
+    return (lhs < rhs) || (lhs == rhs);
+}
+```
+
+### `operator>`
+
+Defined only if `array_type` and `table_type` have `operator<`.
+
+```cpp
+template<typename TC>
+bool operator>(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
+{
+    return !(lhs <= rhs);
+}
+```
+
+### `operator>=`
+
+Defined only if `array_type` and `table_type` have `operator<`.
+
+```cpp
+template<typename TC>
+bool operator>=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
+{
+    return !(lhs < rhs);
+}
+```
+
+# `toml::type_error`
+
+Exception thrown in case of a type error.
+
+Contains the location information of the value that caused the type error.
+
+```cpp
+struct type_error final : public ::toml::exception
+{
+  public:
+    type_error(std::string what_arg, source_location loc);
+    ~type_error() noexcept override = default;
+
+    const char* what() const noexcept override;
+
+    source_location const& location() const noexcept;
+};
+```
+
+# `toml::make_error_info`
+
+```cpp
+template<typename TC, typename ... Ts>
+error_info make_error_info(
+    std::string title, const basic_value<TC>& v, std::string msg, Ts&& ... tail);
+```
+
+Calls `location()` on a `basic_value`, passes the resulting `source_location` to
+[`make_error_info`]({{<ref "docs/reference/error_info#make_error_info">}})
+to create an `error_info`.
+
+Refer to [`error_info`]({{<ref "docs/reference/error_info">}}) for more details.
+
+# `toml::format_error`
+
+```cpp
+template<typename TC, typename ... Ts>
+std::string format_error(std::string title,
+                         const basic_value<TC>& v, std::string msg, Ts&& ... tail);
+```
+
+Calls `location()` on a `basic_value`, passes the resulting `source_location` to
+[`format_error`]({{<ref "docs/reference/error_info#format_error">}})
+to create an `error_info`, then converts it to a string and returns it.
+
+Refer to [`error_info`]({{<ref "docs/reference/error_info">}}) for more details.
+
+# Related
+
+- [comments.hpp]({{<ref "comments.md">}})
+- [source_location.hpp]({{<ref "source_location.md">}})
+- [types.hpp]({{<ref "types.md">}})
+- [visit.hpp]({{<ref "visit.md">}})

docs/content.en/docs/reference/value_t.md

@@ -0,0 +1,51 @@
++++
+title = "value_t.hpp"
+type  = "docs"
++++
+
+# value_t.hpp
+
+# `value_t`
+
+`value_t` is used to handle the type information of `toml::value`.
+
+```cpp
+namespace toml
+{
+enum class value_t : std::uint8_t
+{
+    empty           =  0,
+    boolean         =  1,
+    integer         =  2,
+    floating        =  3,
+    string          =  4,
+    offset_datetime =  5,
+    local_datetime  =  6,
+    local_date      =  7,
+    local_time      =  8,
+    array           =  9,
+    table           = 10
+};
+
+std::ostream& operator<<(std::ostream& os, value_t t);
+std::string to_string(value_t t);
+} // toml
+```
+
+## Non-member Functions
+
+### Stream Operator
+
+```cpp
+std::ostream& operator<<(std::ostream& os, value_t t);
+```
+
+Outputs the string representation of the `value_t` to the stream.
+
+### `to_string`
+
+```cpp
+std::string to_string(value_t t);
+```
+
+Returns the string representation of the `value_t`.

docs/content.en/docs/reference/version.md

@@ -0,0 +1,37 @@
++++
+title = "version.hpp"
+type  = "docs"
++++
+
+# version.hpp
+
+In `version.hpp`, macros related to the version information of toml11 are defined.
+
+## Macros
+
+### `TOML11_VERSION_MAJOR`
+
+The major version of toml11.
+
+### `TOML11_VERSION_MINOR`
+
+The minor version of toml11.
+
+### `TOML11_VERSION_PATCH`
+
+The patch version of toml11.
+
+## Function
+
+### `license_notice`
+
+```cpp
+namespace toml
+{
+const char* license_notice() noexcept;
+}
+```
+
+Returns the license notice.
+
+Provided for convenience when redistributing without source code.

docs/content.en/docs/reference/visit.md

@@ -0,0 +1,69 @@
++++
+title = "visit.hpp"
+type  = "docs"
++++
+
+# visit.hpp
+
+In `visit.hpp`, `toml::visit` is defined.
+
+# `toml::visit`
+
+## Functions
+
+```cpp
+namespace toml
+{
+template<typename Visitor, typename TC>
+/* Return value when Visitor is called with a value of basic_value<TC> */
+visit(Visitor&& visitor, const basic_value<TC>& v);
+
+template<typename Visitor, typename TC>
+/* Return value when Visitor is called with a value of basic_value<TC> */
+visit(Visitor&& visitor, basic_value<TC>& v);
+
+template<typename Visitor, typename TC>
+/* Return value when Visitor is called with a value of basic_value<TC> */
+visit(Visitor&& visitor, basic_value<TC>&& v);
+}
+```
+
+`toml::visit` calls the overload of `Visitor` corresponding to the type held by `basic_value<TC>`, and returns the result.
+
+#### Requirements
+
+`Visitor` must be a function or function object callable with any type held by `basic_value<TC>`.
+
+Additionally, the return value must be consistent across all overloads.
+
+#### Example
+
+```cpp
+#include <toml.hpp>
+#include <iostream>
+
+struct type_name_of
+{
+    std::string operator()(const toml::value::boolean_type        &) const {return "boolean";}
+    std::string operator()(const toml::value::integer_type        &) const {return "integer";}
+    std::string operator()(const toml::value::floating_type       &) const {return "floating";}
+    std::string operator()(const toml::value::string_type         &) const {return "string";}
+    std::string operator()(const toml::value::local_time_type     &) const {return "local_time";}
+    std::string operator()(const toml::value::local_date_type     &) const {return "local_date";}
+    std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
+    std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
+    std::string operator()(const toml::value::array_type          &) const {return "array";}
+    std::string operator()(const toml::value::table_type          &) const {return "table";}
+};
+
+int main()
+{
+    toml::value v(3.14);
+    std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
+    return 0;
+}
+```
+
+# Related
+
+- [value.hpp]({{<ref "value.md">}})