doc: add description about ordered_type_config

ToruNiina · Aug 9, 2024 · 9b914db · 9b914db
1 parent fcb1d3d
commit 9b914db
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -493,10 +493,22 @@ For details on possible formatting specifications, please refer to the [document
 
 ### Configuring Types
 
-Many types held by `toml::value`, such as `integer_type` and `array_type`, can be modified by changing the `type_config` type.
+Many types in `toml::value`, such as `integer_type`, `array_type`, `table_type`, etc, can be modified by changing the `type_config` type.
 
-Refer to the [`examples` directory](https://github.com/ToruNiina/toml11/tree/main/examples) for complex use cases such as using multi-precision integers, changing containers, and normalizing Unicode.
+One commonly used example is an `ordered_map` that keeps the added order.
+toml11 provides a`type_config` that changes `table_type` to `ordered_map` as `toml::ordered_type_config`.
 
+```cpp
+const toml::ordered_value input = toml::parse<toml::ordered_type_config>("input.toml");
+```
+
+Here, `toml::ordered_value` is an alias of `toml::basic_value<toml::ordered_type_config>`.
+
+Note that, since `toml::value` uses `std::unordered_map`, once you convert it to `toml::value`, then the order of the values will be randomized.
+
+For more details about how to implement `type_config` variant, please refer to the [documentation](https://toruniina.github.io/toml11/docs/features/configure_types/).
+
+Also, refer to the [`examples` directory](https://github.com/ToruNiina/toml11/tree/main/examples) for complex use cases such as using multi-precision integers, changing containers, and normalizing Unicode.
 Use these examples as references for implementing such configurations.
 
 ## Examples

diff --git a/README_ja.md b/README_ja.md
@@ -495,10 +495,20 @@ std::cout << toml::format(output) << std::endl;
 
 `toml::value`が持つ型の多く、`integer_type`や`array_type`などは`type_config`型を変更することで変更可能です。
 
+よくある例として、値を追加した順序を保つ`map`型である`ordered_map`を使うというものがあります。
+toml11は`toml::ordered_map`を使用する`type_config`型として、`toml::ordered_type_config`を提供しています。
+
+```cpp
+const toml::ordered_value input = toml::parse<toml::ordered_type_config>("input.toml");
+```
+
+ここで、`toml::ordered_value`は`toml::basic_value<toml::ordered_type_config>`のエイリアスです。
+
+ただし、`toml::value`は`std::unordered_map`を使用しているため、一度`toml::ordered_value`から`toml::value`に変換してしまうと、順序は失われてしまうことに注意してください。
+
 [`examples`ディレクトリ](https://github.com/ToruNiina/toml11/tree/main/examples)には、
 多倍長整数を使用する場合やコンテナを変更する場合、ユニコードを正規化する場合などの複雑な使用例を用意しています。
-
-そのような状況での実装例として参照してください。
+`type_config`を実装する際の例として参照してください。
 
 ## Examples
 

diff --git a/docs/content.en/docs/features/configure_types.md b/docs/content.en/docs/features/configure_types.md
@@ -82,6 +82,17 @@ Using this, `toml::ordered_value` is defined, along with aliases for its array a
 
 You can use `toml::ordered_value` by calling `toml::parse(...)` as `toml::parse<toml::ordered_type_config>(...)`.
 
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::ordered_value input = toml::parse<toml::ordered_type_config>("example.toml");
+    std::cout << toml::format(input) << std::endl;
+    return 0;
+}
+```
+
 ## Not Preserving Comments
 
 The `type_config` defines a container for storing comments via `comment_type`.

diff --git a/docs/content.ja/docs/features/configure_types.md b/docs/content.ja/docs/features/configure_types.md
@@ -101,6 +101,17 @@ parse_float(const std::string& str, const source_location src, const bool is_hex
 `toml::parse(...)` を `toml::parse<toml::ordered_type_config>(...)` として呼び出すことで、
 `toml::ordered_value` を使用することができます。
 
+```cpp
+#include <toml.hpp>
+
+int main()
+{
+    toml::ordered_value input = toml::parse<toml::ordered_type_config>("example.toml");
+    std::cout << toml::format(input) << std::endl;
+    return 0;
+}
+```
+
 ## コメントを保存しない
 
 `type_config` は `comment_type` でコメントを保存するコンテナを定義しています。