Propose restructuring the docs to include a short explanation backed by the example of std::ranges::find()

.gitignore

@@ -21,4 +21,7 @@ yarn-error.log*
 
 # Custom
 .vscode/
-*.drawio.*
+*.drawio.*
+
+# JetBrains' IDEs
+.idea

content/docs/std/algo/ranges/_codes/find/example-Failing-to-find-a-value-safely-when-dealing-with-an-iterator-pair-subrange.mdx

@@ -0,0 +1,25 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const numbers = std::vector<int>{
+        1, 2, 3, 4, 5, 0, 6
+    };
+
+    auto const zeroInFirstThree = std::ranges::find(
+        numbers.begin(), numbers.begin() + 3, 0
+    );
+
+    if (zeroInFirstThree != numbers.begin() + 3)
+    {
+        std::cout << "there is a 0 in the first three elements";
+    }
+    else
+    {
+        std::cout << "there are no 0s in the first three elements";
+    }
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Failing-to-find-a-value-safely.mdx

@@ -0,0 +1,23 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const onlyEvens = std::vector<int>{
+        2, 4, 6, 8, 10
+    };
+
+    auto const positionOf1 = std::ranges::find(onlyEvens, 1);
+
+    if (positionOf1 != onlyEvens.end())
+    {
+        std::cout << "odd element found: " << *positionOf1;
+    }
+    else
+    {
+        std::cout << "no odd elements found";
+    }
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Failing-to-find-a-value-unsafely.mdx

@@ -0,0 +1,17 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const onlyEvens = std::vector<int>{
+        2, 4, 6, 8, 10
+    };
+
+    auto const positionOf1 = std::ranges::find(onlyEvens, 1);
+
+    // error-next-line
+    std::cout << "odd element found: " << *positionOf1; // dereferencing end, undefined behavior
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Failing-to-find-a-value-when-dealing-with-an-iterator-pair-subrange-unsafely.mdx

@@ -0,0 +1,26 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const numbers = std::vector<int>{
+        1, 2, 3, 4, 5, 0, 6
+    };
+
+    auto const zeroInFirstThree = std::ranges::find(
+        numbers.begin(), numbers.begin() + 3, 0
+    );
+
+    // error-next-line
+    if (zeroInFirstThree != numbers.end())
+    {
+        std::cout << "there is a 0 in the first three elements";
+    }
+    else
+    {
+        std::cout << "there are no 0s in the first three elements";
+    }
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Finding-and-changing-the-found-value.mdx

@@ -0,0 +1,20 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+int main()
+{
+    const auto println = [](std::vector<int> const& vec)
+    {
+        for (const int element : vec) std::cout << element << ' ';
+        std::cout << '\n';
+    };
+
+    std::vector<int> values{2, 4, 5, 8, 10};
+    println(values);
+    auto iteratorTo5 = std::ranges::find(values, 5);
+    *iteratorTo5 = 6;
+    println(values);
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Finding-and-printing-the-found-value.mdx

@@ -0,0 +1,12 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const values      = std::vector<int>{2, 4, 6, 1, 8, 10};
+    auto const iteratorTo1 = std::ranges::find(values, 1);
+    std::cout << *iteratorTo1;
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Finding-and-removing-the-found-value.mdx

@@ -0,0 +1,34 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <string>
+#include <vector>
+
+auto main() -> int
+{
+    auto const println = [](const std::vector<int>& vec)
+    {
+        for (auto const element : vec)
+        {
+            std::cout << element << ' ';
+        }
+        std::cout << '\n';
+    };
+
+    auto values = std::vector<int>{2, 4, 6, 1, 8, 10};
+    auto text   = std::string("hello, there!");
+
+    println(values);
+    std::cout << text << '\n';
+
+    auto const iteratorTo1 = std::ranges::find(values, 1);
+    values.erase(iteratorTo1);
+
+    auto const iteratorToComma = std::ranges::find(text, ',');
+    text.erase(iteratorToComma);
+
+    std::cout << '\n';
+    println(values);
+    std::cout << text << '\n';
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Finding-the-last-suitable-value-thanks-to-reverse-iterators.mdx

@@ -0,0 +1,36 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <ranges>
+#include <vector>
+
+auto main() -> int
+{
+    auto const println = [](std::vector<int> const& vec)
+    {
+        for (auto const element : vec)
+        {
+            std::cout << element << ' ';
+        }
+        std::cout << '\n';
+    };
+
+    auto numbers = std::vector<int>{
+        1, 2, 3, 2, 1
+    };
+
+    auto const first1 = std::ranges::find(numbers, 1);
+    auto const last1  = std::ranges::find(numbers.rbegin(), numbers.rend(), 1);
+
+    println(numbers);
+    *first1 = 9;
+    *last1  = 7;
+    println(numbers);
+
+    // can also use reverse_view from <ranges>
+    auto numbersReversed = numbers | std::views::reverse;
+    auto const last2 = std::ranges::find(numbersReversed, 2);
+    *last2 = 0;
+    println(numbers);
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Using-a-projection-to-find-a-value-with-a-given-characteristic1.mdx

@@ -0,0 +1,21 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <string>
+#include <vector>
+
+auto main() -> int
+{
+    auto const words = std::vector<std::string>{
+        "some", "of", "these", "words", "are",
+        "of", "the", "same", "lengths"
+    };
+
+    auto const bySize = [](const std::string& s) {
+        return s.size();
+    };
+
+    auto const ofSize5 = std::ranges::find(words, 5, bySize);
+    std::cout << *ofSize5;
+}
+```

content/docs/std/algo/ranges/_codes/find/example-Using-a-projection-to-find-a-value-with-a-given-characteristic2.mdx

@@ -0,0 +1,19 @@
+```cpp showLineNumbers
+#include <algorithm>
+#include <iostream>
+#include <vector>
+
+auto main() -> int
+{
+    auto const numbers = std::vector<int>{
+        5, 6, 7, 8
+    };
+
+    auto const byModulus5 = [](const int n) {
+        return n % 5;
+    };
+
+    auto const withRemainder2 = std::ranges::find(numbers, 2, byModulus5);
+    std::cout << *withRemainder2;
+}
+```

content/docs/std/algo/ranges/_codes/find/since-cpp20-simplified.mdx

@@ -7,18 +7,22 @@ constexpr I
 constexpr ranges::borrowed_iterator_t<R>
     find( R&& r, const T& value, Proj proj = {} );
 ```
+<details>
+<summary>Additional information regarding parameter constraints</summary>
 
 The type of arguments are generic and have the following constraints:
 - `I` - `std::input_iterator`
 - `S` - `std::sentinel_for<I>`
 - `T` - **(none)**
 - `Proj` - **(none)**
-- **(2)** - `R` - `std::ranges::input_range`
+- $(2)$ - `R` - `std::ranges::input_range`
 
 The `Proj` template argument has a default type of `std::identity` for all overloads.
 
 Additionally, each overload has the following constraints:
-- **(1)** - `indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>>`
-- **(2)** - `indirect_binary_predicate<ranges::equal_to, projected<ranges::iterator_t<R>, Proj>, const T*>`
+- $(1)$ - `indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>>`
+- $(2)$ - `indirect_binary_predicate<ranges::equal_to, projected<ranges::iterator_t<R>, Proj>, const T*>`
 
 (The `std::` namespace was ommitted here for readability)
+
+</details>