From 59d152ff7800d5c3f85dd0120a05a063a86d827c Mon Sep 17 00:00:00 2001
From: Yonel Ceruto <yonel.ceruto@scnd.com>
Date: Thu, 18 Apr 2024 19:17:35 -0400
Subject: [PATCH] update main usage example

---
 README.md        | 33 ++++++++++++++++-----------------
 docs/examples.md | 22 +++++++++++++++-------
 2 files changed, 31 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 2ff6e5e..70a3704 100644
--- a/README.md
+++ b/README.md
@@ -23,39 +23,38 @@ It’s a game-changer!
 composer require yceruto/option-type
 ```
 
-## Usage
+## Usage (Handling the presence or absence of a value)
 
-Class `Option` represents an optional value: every `Option` is either Some and 
-contains a value, or None, and does not.
+Options are commonly paired with pattern matching to query the presence of a value
+and take action, always accounting for the `None` case.
 
 ```php
-use App\Model\User;
 use Std\Type\Option;
-
 use function Std\Type\Option\none;
 use function Std\Type\Option\some;
 
 /**
- * @return Option<User>
+ * @return Option<int>
  */
-function findUser(int $id): Option
+function divide(int $dividend, int $divisor): Option
 {
-    $user = // get user from database by $id ... it can return null
-    
-    if (null === $user) {
+    if (0 === $divisor) {
         return none();
     }
 
-    return some($user);
+    return some(intdiv($dividend, $divisor));
 }
 
-// basic usage
-$user = findUser(1)->expect('user exists.');
-// do something safely with $user instance...
+// The return value of the function is an Option
+$result = divide(10, 2);
 
-// advanced usage (map the user to a DTO)
-$dto = findUser(1)->mapOr(UserDto::from(...), UserDto::new());
-// do something safely with $dto instance...
+// Pattern match to retrieve the value
+echo $result->match(
+    // The division was valid
+    some: fn ($v) => "Result: $v",
+    // The division was invalid
+    none: fn () => 'Division by zero!',
+);
 ```
 
 > [!TIP]
diff --git a/docs/examples.md b/docs/examples.md
index 55a852f..c7b04ee 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -4,24 +4,32 @@ This section provides examples of how to use the `Option` type in your PHP code.
 
 ## Example 1: Handling the presence or absence of a value
 
-The following example demonstrates how to use the `Option` type to handle the presence or absence of a value safely.
-
 ```php
+use App\Model\User;
 use Std\Type\Option;
+
 use function Std\Type\Option\none;
 use function Std\Type\Option\some;
 
 /**
- * @return Option<int>
+ * @return Option<User>
  */
-function divide(int $dividend, int $divisor): Option
+function findUser(int $id): Option
 {
-    if (0 === $divisor) {
+    $user = // get user from database by $id ... it can return null
+    
+    if (null === $user) {
         return none();
     }
 
-    return some(intdiv($dividend, $divisor));
+    return some($user);
 }
 
-$result = divide(10, 2)->expect('10 divided by 2.');
+// basic usage
+$user = findUser(1)->expect('user exists.');
+// do something safely with $user instance...
+
+// advanced usage (map the user to a DTO)
+$dto = findUser(1)->mapOr(UserDto::from(...), UserDto::new());
+// do something safely with $dto instance...
 ```