From 3ccc514a463324ccf85ff8b34b1157eda7c949b7 Mon Sep 17 00:00:00 2001
From: Roberto Butti <roberto.butti@gmail.com>
Date: Fri, 11 Oct 2024 23:03:56 +0200
Subject: [PATCH] Add tests and documentation for getFormattedByte()

---
 README.md                                 | 20 ++++++++++++
 tests/Unit/Traits/FormattableBlokTest.php | 40 +++++++++++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 8f73fe7..ecb4e00 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,26 @@ Here are some key points:
 *   The second parameter `$format` controls the date-time format used for formatting.
 *   Custom formats can be applied to provide tailored outputs for different use cases.
 
+### The `getFormattedByte()` for getting and formatting a 'byte' field value
+
+The `getFormattedByte()` method retrieves and formats a byte value from a specified field in a data block. It converts the raw byte count into a more human-readable format (e.g., GB, MB, etc.), with an optional precision parameter to control the number of decimal places displayed.
+
+Parameters:
+- `$path` (string): The path to the field containing the byte value (e.g., "assets.0.total_bytes").
+- `$precision` (int): (Optional) Number of decimal places to include in the formatted result. Default is 2.
+
+Example usage:
+
+```php
+$data1->getFormattedByte("assets.0.total_bytes");  // Returns "5.98 GB"
+$data1->getFormattedByte("assets.1.total_bytes");  // Returns "2.18 GB"
+$data1->getFormattedByte("assets.1.total_bytes", 5);  // Returns "2.18288 GB"
+$data1->getFormattedByte("assets.1.total_bytes", 0);  // Returns "2 GB"
+```
+
+Key Features:
+- Automatic unit conversion: converts bytes into appropriate units (e.g., KB, MB, GB) based on the size.
+- customizable precision: you can specify the number of decimal places for the output, making it flexible for various use cases.
 
 ### The `getBlock()` method
 If you need to manage a complex array (nested array) or an array obtained from a complex JSON structure, you can access a portion of the array and obtain the `Block` object via the `getBlock()` method.
diff --git a/tests/Unit/Traits/FormattableBlokTest.php b/tests/Unit/Traits/FormattableBlokTest.php
index 3a8d2d4..97072e0 100644
--- a/tests/Unit/Traits/FormattableBlokTest.php
+++ b/tests/Unit/Traits/FormattableBlokTest.php
@@ -17,3 +17,43 @@ function (): void {
 
     },
 );
+
+test(
+    'Format byte field into KB or MB ot GB ',
+    function (): void {
+        $stringData = <<<DATA
+{
+    "assets": [
+        {
+            "id": 17571534,
+            "alt": "",
+            "asset_folder_id": null,
+            "content_length": 146327844,
+            "content_type": "image\/gif",
+            "deleted_at": "2024-10-07T11:03:20.415Z",
+            "filename": "demo-4.gif",
+            "is_private": false,
+            "total_bytes": 6423742856
+        },
+        {
+            "id": 17580896,
+            "alt": "",
+            "asset_folder_id": null,
+            "content_length": 146327844,
+            "content_type": "image\/gif",
+            "deleted_at": null,
+            "filename": "demo-5.gif",
+            "is_private": false,
+            "total_bytes": 2343850964
+        }
+    ]
+}
+DATA;
+        $data1 = Block::fromJsonString($stringData);
+        expect($data1->getBlock("assets"))->toHaveCount(2);
+        expect($data1->getFormattedByte("assets.0.total_bytes"))->toBe("5.98 GB");
+        expect($data1->getFormattedByte("assets.1.total_bytes"))->toBe("2.18 GB");
+        expect($data1->getFormattedByte("assets.1.total_bytes", 5))->toBe("2.18288 GB");
+        expect($data1->getFormattedByte("assets.1.total_bytes", 0))->toBe("2 GB");
+    },
+);