add result tutorial

Author: SizzinSeal

docs/tutorials/result.md

@@ -0,0 +1,170 @@
+# Tutorial: Using the `Result` Class
+
+This tutorial will guide you through using the `Result` class template, a powerful error-handling mechanism inspired by `std::expected` that allows you to handle both success values and errors in a type-safe manner. Unlike `std::expected` however, the expected type is *always* valid.
+
+## Table of Contents
+1. [Key Concepts](#key-concepts)
+2. [Defining Error Types](#defining-error-types)
+3. [Using `Result` with Value Types](#using-result-with-value-types)
+4. [Using `Result<void>`](#using-resultvoid)
+5. [Monadic Operations](#monadic-operations)
+6. [Comparison Operators](#comparison-operators)
+7. [Important Notes](#important-notes)
+
+---
+
+## 1. Key Concepts<a name="key-concepts"></a>
+The `Result` class:
+- Always holds a **value** (success), but may sometimes contain an **error**
+- Can convert implicitly to the value type
+- Can have multiple possible error types, but only one error value
+- Uses a `sentinel_v<T>` for the value when an error occurs
+- Provides monadic operations for functional-style error handling, similar to those of std::expected
+
+## 2. Defining Error Types<a name="defining-error-types"></a>
+Define your error types by inheriting from `ResultError`:
+
+```cpp
+struct FileNotFound : protected zest::ResultError {};
+struct PermissionDenied : protected zest::ResultError {};
+struct InvalidFormat : protected zest::ResultError {};
+```
+
+## 3. Using `Result` with Value Types<a name="using-result-with-value-types"></a>
+### Basic Usage
+```cpp
+zest::Result<std::string, FileNotFound, PermissionDenied> read_file() {
+    if (!file_exists()) return FileNotFound{};
+    if (!has_permission()) return PermissionDenied{};
+    return "todo"; // (success) return the contents of the file
+}
+
+// Using the result
+auto result = read_file();
+if (result.has_error()) {
+    // Handle error
+    if (auto err = result.get_error<FileNotFound>()) {
+        std::println("File not found");
+    }
+} else {
+    std::println("value: {}", result); // result converted to std::string implicitly
+}
+```
+
+### Extracting Values
+```cpp
+// Result can implicitly convert to its value type
+int value = Result<int, ExampleError>(2);
+std::println("{}", value); // output: 2
+
+// Result::or_default can be used to change the default error value
+int value = Result<int, ExampleError>(ExampleError{}).or_default(-4);
+std::println("{}", value); // output: -4
+
+// Result::or_default only changes the value if there's an error
+int value = Result<int, ExampleError>(5).or_default(-4);
+std::println("{}", value); // output: 5
+```
+
+## 4. Using `Result<void>`<a name="using-resultvoid"></a>
+For operations without return values:
+
+```cpp
+zest::Result<void, PermissionDenied> delete_file() {
+    if (!has_permission()) return PermissionDenied{};
+    // Perform deletion
+    return {}; // Success
+}
+
+// Usage
+auto delete_result = delete_file();
+if (delete_result.has_error()) {
+    // Handle error...
+}
+```
+
+## 5. Monadic Operations<a name="monadic-operations"></a>
+
+Monadic operations can be used for functional-style error handling.
+
+### Chaining Operations with `and_then`
+
+Invokes the callable with the value if there is no error. The callable must return a `Result` which can contain any of the possible error types.
+
+```cpp
+read_file()
+    .and_then([](std::string contents) -> Result<Data, FileNotFound, PermissionDenied> {
+        return parse(contents); // parse returns Data
+    });
+```
+
+### Error Handling with `or_else`
+
+Invokes the callable with the error if there is an error. The callable must return a `Result` with the same value type.
+
+```cpp
+read_file()
+    .or_else([](auto error) -> zest::Result<int, FileNotFound, PermissionDenied> {
+        // print error
+        std::println("An error occurred: {}", error);
+        // Fallback operation
+        return read_backup_file();
+    });
+```
+
+### Inspecting Errors
+
+Invokes the callable with the error if there is an error. The callable must return `void`.
+
+```cpp
+result.inspect_error([](const auto& error) {
+    // Log error without changing result
+    std::cerr << "Operation failed: ";
+    if constexpr (std::is_same_v<decltype(error), FileNotFound>) {
+        std::cerr << "File not found";
+    }
+    // ...
+});
+```
+
+### Transforming Values with `transform`
+
+For non-void `Result` instances, `transform` can be used to transform a value if there is no error.
+
+```cpp
+auto modified = result.transform([](int res) {
+    res.value += 10; // Modify value in-place
+    return res;
+});
+```
+
+## 6. Comparison Operators<a name="comparison-operators"></a>
+Results can be compared if their value types are comparable:
+
+```cpp
+auto result1 = read_file();
+auto result2 = read_another_file();
+
+if (result1 == result2) {
+    // Compares the contained values
+}
+```
+
+## 7. Important Notes<a name="important-notes"></a>
+1. **Sentinel Values**: 
+   - The value type `T` must have a defined sentinel value (`sentinel_v<T>`)
+   - The sentinel value for built-in number types is the maximum value for the given type, or infinity if the type supports it.
+   - When an error occurs, the value is set to this sentinel
+
+2. **Error Type Requirements**:
+   - All error types must inherit from `ResultError`
+   - Error types in a single `Result` must be unique (can't do `Result<void, ExampleError, ExampleError>`)
+
+3. **Monadic Constraints**:
+   - `and_then` requires callables to return compatible `Result` types
+   - `or_else` requires callables to handle all possible error types
+   - Constraints are checked at compile time
+
+4. **Void Specialization**:
+   - Use `Result<void, Errs...>` for operations without return values
+   - `and_then` callables take no arguments for void results