From c4fb41b812cd70014e4e86c7d5026694719fef00 Mon Sep 17 00:00:00 2001
From: ToruNiina <niina.toru.68u@gmail.com>
Date: Wed, 26 Jun 2024 00:24:25 +0900
Subject: [PATCH] doc: add try_at to docs/features

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

diff --git a/docs/content.en/docs/features/value.md b/docs/content.en/docs/features/value.md
index 8c99b77..a52a3c8 100644
--- a/docs/content.en/docs/features/value.md
+++ b/docs/content.en/docs/features/value.md
@@ -92,6 +92,32 @@ std::cout << v.at(1);
 
 If the stored type is not `array_type`, a `type_error` is thrown.
 
+### `try_at(std::size_t i)`
+
+Performs the same operation as `at(i)`, but instead of throwing an exception on failure, it always returns a [`toml::result<T&, error_info>`]({{<ref "docs/reference/result">}}). It does not throw an exception on failure.
+
+```cpp
+toml::value v(toml::array{1,2,3});
+
+auto res1 = v.try_at(1);
+assert(res1.is_ok());
+std::cout << res1.unwrap() << std::endl;
+
+auto res5 = v.try_at(5);
+assert(res1.is_err());
+std::cout << toml::format_error(res1.unwrap_err()) << std::endl;
+```
+
+Additionally, since this `toml::result` holds a reference, it is possible to update the value.
+
+```cpp
+toml::value v(toml::array{1,2,3});
+
+auto res1 = v.try_at(1);
+assert(res1.is_ok());
+res1.unwrap() = 42;
+```
+
 #### `at(std::string key)`, `operator[](std::string key)`
 
 These are equivalent to `as_table().at(key)` and `as_table()[key]`.
@@ -105,6 +131,32 @@ v["a"] = 42;
 
 If the stored type is not `table_type`, a `type_error` is thrown.
 
+### `try_at(std::string key)`
+
+Performs the same operation as `at(key)`, but instead of throwing an exception on failure, it always returns a [`toml::result<T&, error_info>`]({{<ref "docs/reference/result">}}). It does not throw an exception on failure.
+
+```cpp
+toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
+
+auto res_a = v.try_at("a");
+assert(res_a.is_ok());
+std::cout << res_a.unwrap() << std::endl;
+
+auto res_c = v.try_at("c");
+assert(res_c.is_err());
+std::cout << toml::format_error(res_c.unwrap_err()) << std::endl;
+```
+
+Additionally, since this `toml::result` holds a reference, it is possible to update the value.
+
+```cpp
+toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
+
+auto res_a = v.try_at("a");
+assert(res_a.is_ok());
+res_a.unwrap() = 6 * 9;
+```
+
 #### `size()`
 
 Returns the length.
diff --git a/docs/content.ja/docs/features/value.md b/docs/content.ja/docs/features/value.md
index afdcaf2..f302549 100644
--- a/docs/content.ja/docs/features/value.md
+++ b/docs/content.ja/docs/features/value.md
@@ -96,6 +96,32 @@ std::cout << v.at(1);
 
 格納している型が `array_type` ではなかった場合、 `type_error` を送出します。
 
+#### `try_at(std::size_t i)`
+
+`at(i)`と同様の操作をしますが、失敗時に例外を投げる代わりに、常に[`toml::result<T&, error_info>`]({{<ref "docs/reference/result">}})を返します。失敗時に例外は投げません。
+
+```cpp
+toml::value v(toml::array{1,2,3});
+
+auto res1 = v.try_at(1);
+assert(res1.is_ok());
+std::cout << res1.unwrap() << std::endl;
+
+auto res5 = v.try_at(5);
+assert(res1.is_err());
+std::cout << toml::format_error(res1.unwrap_err()) << std::endl;
+```
+
+また、この`toml::result`は成功値として参照を持つので、値を更新することも可能です。
+
+```cpp
+toml::value v(toml::array{1,2,3});
+
+auto res1 = v.try_at(1);
+assert(res1.is_ok());
+res1.unwrap() = 42;
+```
+
 #### `at(std::string key)`, `operator[](std::string key)`
 
 `as_table().at(key)`, `as_table()[key]` と同等です。
@@ -111,6 +137,32 @@ v["a"] = 42;
 
 格納している型が `table_type` ではなかった場合、 `type_error` を送出します。
 
+#### `try_at(std::string key)`
+
+`at(key)`と同様の操作をしますが、失敗時に例外を投げる代わりに、常に[`toml::result<T&, error_info>`]({{<ref "docs/reference/result">}})を返します。失敗時に例外は投げません。
+
+```cpp
+toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
+
+auto res_a = v.try_at("a");
+assert(res_a.is_ok());
+std::cout << res_a.unwrap() << std::endl;
+
+auto res_c = v.try_at("c");
+assert(res_c.is_err());
+std::cout << toml::format_error(res_c.unwrap_err()) << std::endl;
+```
+
+また、この`toml::result`は成功値として参照を持つので、値を更新することも可能です。
+
+```cpp
+toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
+
+auto res_a = v.try_at("a");
+assert(res_a.is_ok());
+res_a.unwrap() = 6 * 9;
+```
+
 #### `size()`
 
 長さを返します。