From eb24183d93f39b5bc9485ef3ca46a5d49e76b9b7 Mon Sep 17 00:00:00 2001
From: Petr Knap <8299754+petrknap@users.noreply.github.com>
Date: Sun, 27 Apr 2025 21:17:13 +0200
Subject: [PATCH] feat: created ASCII enum

---
 README.md     | 21 +++++++++++++++++-
 src/Ascii.php | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 src/Ascii.php

diff --git a/README.md b/README.md
index 5a64616..d95c5b5 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # Library for work with binary data and objects
 
 Simple library for work with binary data and objects in PHP.
-See the examples below for more information, or check out [`Encoder`](./src/Encoder.php), [`Decoder`](./src/Decoder.php), [`Serializer`](./src/Serializer.php) and [`Byter`](./src/Byter.php).
+See the examples below for more information, or check out [`Encoder`](./src/Encoder.php), [`Decoder`](./src/Decoder.php), [`Serializer`](./src/Serializer.php), [`Byter`](./src/Byter.php) and [`Ascii`](./src/Ascii.php).
+
+## Coder
 
 ```php
 namespace PetrKnap\Binary;
@@ -13,6 +15,8 @@ $decoded = Binary::decode($encoded)->base64()->zlib()->checksum()->data;
 printf('Data was coded into `%s` %s.', $encoded, $decoded === $data ? 'successfully' : 'unsuccessfully');
 ```
 
+## Serializer
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -26,6 +30,8 @@ $unserialized = Binary::unserialize($serialized);
 printf('Data was serialized into `%s` %s.', base64_encode($serialized), $unserialized === $data ? 'successfully' : 'unsuccessfully');
 ```
 
+## Self-serializer
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -54,6 +60,8 @@ printf(
 );
 ```
 
+## Byter
+
 ```php
 namespace PetrKnap\Binary;
 
@@ -70,6 +78,17 @@ printf(
 );
 ```
 
+## ASCII
+
+```php
+namespace PetrKnap\Binary;
+
+printf(Ascii::RecordSeparator->join(
+    Ascii::UnitSeparator->join('200', 'EUR', 'Maya Wilson'),
+    Ascii::UnitSeparator->join('1600', 'USD', 'Quinton Rice'),
+));
+```
+
 ---
 
 Run `composer require petrknap/binary` to install it.
diff --git a/src/Ascii.php b/src/Ascii.php
new file mode 100644
index 0000000..4b90df0
--- /dev/null
+++ b/src/Ascii.php
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @see https://datatracker.ietf.org/doc/html/rfc20
+ *
+ * @todo upgrade to PHP 8.2, move values to cases and move `values of cases` region under `groups of cases` region
+ */
+enum Ascii: string
+{
+    #region values of cases
+    public const FILE_SEPARATOR = "\x1C";
+    public const GROUP_SEPARATOR = "\x1D";
+    public const NULL = "\x00";
+    public const RECORD_SEPARATOR = "\x1E";
+    public const UNIT_SEPARATOR = "\x1F";
+    #endregion
+
+    /**
+     * Separates different files (databases)
+     */
+    case FileSeparator = self::FILE_SEPARATOR;
+    /**
+     * Separates different groups (tables) of the same file (database)
+     */
+    case GroupSeparator = self::GROUP_SEPARATOR;
+    case Null = self::NULL;
+    /**
+     * Separates different records (rows) of the same group (table)
+     */
+    case RecordSeparator = self::RECORD_SEPARATOR;
+    /**
+     * Separates different units (columns) of the same record (row)
+     */
+    case UnitSeparator = self::UNIT_SEPARATOR;
+
+    #region groups of cases
+    /**
+     * Used to separate and qualify information in a logical sense
+     */
+    public const INFORMATION_SEPARATORS = [
+        self::FileSeparator,
+        self::GroupSeparator,
+        self::RecordSeparator,
+        self::UnitSeparator,
+    ];
+    #endregion
+
+    /**
+     * @see implode()
+     */
+    public function join(string $element1, string ...$elementN): string
+    {
+        return implode($this->value, [$element1, ...$elementN]);
+    }
+}