From 76dc01cbf1e8f7a2381e1383dc1accf4ffc0684f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andrei=20Ioni=C8=9B=C4=83?= <hi@andrei.io>
Date: Thu, 31 Jul 2025 12:54:15 +0100
Subject: [PATCH] docs: add examples

---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d0b3c9e..9810193 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 Collection of utilities for working with enums.
 
-[Contributing](#contributing) | [Feedback](#feedback) | [License](#license) | [About Code for Romania](#about-code-for-romania)
+[Contributing](#contributing) | [Install](#install) | [Usage](#usage) | [Feedback](#feedback) | [License](#license) | [About Code for Romania](#about-code-for-romania)
 
 ## Contributing
 
@@ -16,6 +16,76 @@ Help us out by testing this project in the [staging environment][link-staging].
 
 If you would like to suggest new functionality, open an Issue and mark it as a __[Feature request]__. Please be specific about why you think this functionality will be of use. If you can, please include some visual description of what you would like the UI to look like, if you are suggesting new UI elements.
 
+## Install
+
+```console
+composer require commitglobal/enum-utils
+```
+
+## Usage
+
+### Arrayable
+
+> [!important]
+> For `Arrayable::options()`, your enum must implement a `getLabel()` method.
+
+| Method      | Description                                            |
+| ----------- | ------------------------------------------------------ |
+| `names()`   | Returns an array of enum case names.                   |
+| `values()`  | Returns an array of enum case values.                  |
+| `options()` | Returns an associative array mapping values to labels. |
+
+```php
+enum Status: string
+{
+    use CommitGlobal\Enums\Concerns\Arrayable;
+
+    case ACTIVE = 'active';
+    case INACTIVE = 'inactive';
+
+    public function getLabel(): string
+    {
+        return match($this) {
+            self::ACTIVE => 'Account is active',
+            self::INACTIVE => 'Account is inactive',
+        };
+    }
+}
+```
+
+```php
+Status::names();   // ['ACTIVE', 'INACTIVE']
+Status::values();  // ['active', 'inactive']
+Status::options(); // ['active' => 'Account is active', 'inactive' => 'Account is inactive']
+```
+
+### Comparable
+
+| Method         | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `is($enum)`    | Check if this enum matches the given enum instance or value.      |
+| `isNot($enum)` | Check if this enum does't match the given enum instance or value. |
+
+#### Example
+```php
+enum Status: string
+{
+    use CommitGlobal\Enums\Concerns\Comparable;
+
+    case ACTIVE = 'active';
+    case INACTIVE = 'inactive';
+}
+```
+
+```php
+$status = Status::ACTIVE;
+
+$status->is(Status::ACTIVE);   // true
+$status->is('active');         // true
+$status->is(Status::INACTIVE); // false
+$status->isNot('inactive');    // true
+```
+
 ## Feedback
 
 * Request a new feature on GitHub.