From 93428f295aa1ea6725b18c3c4862809561af7c67 Mon Sep 17 00:00:00 2001
From: ToruNiina <niina.toru.68u@gmail.com>
Date: Sun, 5 Jan 2025 14:50:17 +0900
Subject: [PATCH] doc: add find<optional> to docs

---
 docs/content.en/docs/features/value.md | 26 ++++++++++++++++++++++++++
 docs/content.ja/docs/features/value.md | 26 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/docs/content.en/docs/features/value.md b/docs/content.en/docs/features/value.md
index e7f289d..e391324 100644
--- a/docs/content.en/docs/features/value.md
+++ b/docs/content.en/docs/features/value.md
@@ -544,6 +544,32 @@ This is useful when you want to provide a fallback value instead of handling exc
 const auto a = toml::find_or(input, "a", 42);
 ```
 
+## `toml::find<std::optional<T>>`
+
+If `std::optional` is available, you can specify `std::optional` as a template argument of `toml::find`.
+
+Recursive access is also supported.
+
+```cpp
+const auto input = toml::parse_str(R"(
+integer = 1
+
+[table]
+key = 2
+
+[[array-of-tables]]
+key = 3
+)");
+
+const auto a = toml::find<std::optional<int>>(input, "integer");
+const auto b = toml::find<std::optional<int>>(input, "table", "key");
+const auto c = toml::find<std::optional<int>>(input, "array-of-tables", 0, "key");
+```
+
+If a key does not exist, no exception is thrown, and `std::nullopt` is returned.
+
+However, if a type conversion fails, or if you attempt to access a key on a value that is not a table, or an index on a value that is not an array, a `toml::type_error` is thrown.
+
 ## 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.
diff --git a/docs/content.ja/docs/features/value.md b/docs/content.ja/docs/features/value.md
index 43c6ac4..9de4490 100644
--- a/docs/content.ja/docs/features/value.md
+++ b/docs/content.ja/docs/features/value.md
@@ -569,6 +569,32 @@ const auto a = toml::find_or(input, "a", 42);
 
 型変換の失敗だけでなく、キーが見つからなかった場合もデフォルト値を返します。
 
+## `toml::find<std::optional<T>>`
+
+C++17以降の場合、`std::optional`を`toml::find`に指定することができます。
+
+`find`と同様に、再帰的なアクセスも可能です。
+
+```cpp
+const auto input = toml::parse_str(R"(
+integer = 1
+
+[table]
+key = 2
+
+[[array-of-tables]]
+key = 3
+)");
+
+const auto a = toml::find<std::optional<int>>(input, "integer");
+const auto b = toml::find<std::optional<int>>(input, "table", "key");
+const auto c = toml::find<std::optional<int>>(input, "array-of-tables", 0, "key");
+```
+
+キーが存在しなかった場合、例外は投げられず、`std::nullopt`が返却されます。
+
+ただし、型変換が失敗した場合や、テーブルではない値にキーでアクセスしようとした場合、配列でない値にインデックスでアクセス仕様とした場合は、`toml::type_error`が送出されます。
+
 ## ユーザー定義型との変換を定義する
 
 `toml::get` や `toml::find` では、以下のどれかの方法を使うことで