Updated

Author: sorinsarca

src/Exception/InvalidStringException.php

@@ -24,12 +24,12 @@ class InvalidStringException extends UnicodeException
     /**
      * @var string
      */
-    protected $string;
+    protected string $string;
 
     /**
      * @var int
      */
-    protected $offset;
+    protected int $offset;
 
     /**
      * @param string $string

src/UnicodeString.php

@@ -27,7 +27,7 @@
     InvalidCodePointException
 };
 
-final class UnicodeString implements Countable, ArrayAccess, JsonSerializable
+class UnicodeString implements Countable, ArrayAccess, JsonSerializable
 {
     const KEEP_CASE = 0;
 
@@ -832,7 +832,7 @@ public function __invoke(int $offset): int
     /**
      * @inheritDoc
      */
-    public function offsetExists($offset)
+    public function offsetExists($offset): bool
     {
         // Allow negative index
         if ($offset < 0) {
@@ -845,7 +845,7 @@ public function offsetExists($offset)
     /**
      * @inheritDoc
      */
-    public function offsetGet($offset)
+    public function offsetGet($offset): string
     {
         if ($offset < 0) {
             if ($offset + $this->length < 0) {
@@ -905,7 +905,7 @@ public function offsetUnset($offset)
     /**
      * @inheritDoc
      */
-    public function count()
+    public function count(): int
     {
         return $this->length;
     }
@@ -925,7 +925,7 @@ public function __toString(): string
     /**
      * @inheritDoc
      */
-    public function jsonSerialize()
+    public function jsonSerialize(): string
     {
         return $this->__toString();
     }
@@ -1156,6 +1156,122 @@ public static function getCodePointsFromString(string $str, int $mode = self::KE
         return $codes;
     }
 
+    /**
+     * @param string $str
+     * @return iterable
+     *
+     * The key represents the current char index
+     * Value is a two element array
+     *  - first element is an integer representing the code point
+     *  - second element is an array of integers (length 1 to 4) representing bytes
+     */
+    public static function walkString(string $str): iterable
+    {
+        $i = 0;
+        $length = strlen($str);
+
+        while ($i < $length) {
+            $index = $i;
+
+            $ord0 = ord($str[$i++]);
+
+            if ($ord0 < 0x80) {
+                yield $index => [
+                    $ord0,
+                    [$ord0]
+                ];
+                continue;
+            }
+
+            if ($i === $length || $ord0 < 0xC2 || $ord0 > 0xF4) {
+                throw new InvalidStringException($str, $i - 1);
+            }
+
+            $ord1 = ord($str[$i++]);
+
+            if ($ord0 < 0xE0) {
+                if ($ord1 < 0x80 || $ord1 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 1);
+                }
+
+                yield $index => [
+                    ($ord0 - 0xC0) * 64 + $ord1 - 0x80,
+                    [$ord0, $ord1]
+                ];
+
+                continue;
+            }
+
+            if ($i === $length) {
+                throw new InvalidStringException($str, $i - 1);
+            }
+
+            $ord2 = ord($str[$i++]);
+
+            if ($ord0 < 0xF0) {
+                if ($ord0 === 0xE0) {
+                    if ($ord1 < 0xA0 || $ord1 >= 0xC0) {
+                        throw new InvalidStringException($str, $i - 2);
+                    }
+                } elseif ($ord0 === 0xED) {
+                    if ($ord1 < 0x80 || $ord1 >= 0xA0) {
+                        throw new InvalidStringException($str, $i - 2);
+                    }
+                } elseif ($ord1 < 0x80 || $ord1 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 2);
+                }
+
+                if ($ord2 < 0x80 || $ord2 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 1);
+                }
+
+                yield $index => [
+                    ($ord0 - 0xE0) * 0x1000 + ($ord1 - 0x80) * 64 + $ord2 - 0x80,
+                    [$ord0, $ord1, $ord2]
+                ];
+
+                continue;
+            }
+
+            if ($i === $length) {
+                throw new InvalidStringException($str, $i - 1);
+            }
+
+            $ord3 = ord($str[$i++]);
+
+            if ($ord0 < 0xF5) {
+                if ($ord0 === 0xF0) {
+                    if ($ord1 < 0x90 || $ord1 >= 0xC0) {
+                        throw new InvalidStringException($str, $i - 3);
+                    }
+                } elseif ($ord0 === 0xF4) {
+                    if ($ord1 < 0x80 || $ord1 >= 0x90) {
+                        throw new InvalidStringException($str, $i - 3);
+                    }
+                } elseif ($ord1 < 0x80 || $ord1 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 3);
+                }
+
+                if ($ord2 < 0x80 || $ord2 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 2);
+                }
+
+                if ($ord3 < 0x80 || $ord3 >= 0xC0) {
+                    throw new InvalidStringException($str, $i - 1);
+                }
+
+                yield $index => [
+                    ($ord0 - 0xF0) * 0x40000 + ($ord1 - 0x80) * 0x1000 + ($ord2 - 0x80) * 64 + $ord3 - 0x80,
+                    [$ord0, $ord1, $ord2, $ord3]
+                ];
+
+                continue;
+            }
+
+            throw new InvalidStringException($str, $i - 1);
+        }
+    }
+
     /**
      * Converts each code point to a char
      * @param array $codes
@@ -1179,6 +1295,16 @@ public static function getCharsFromCodePoints(array $codes, int $mode = self::KE
         return $codes;
     }
 
+    /**
+     * @param string $str
+     * @param int $mode
+     * @return string[]
+     */
+    public static function getCharsFromString(string $str, int $mode = self::KEEP_CASE): array
+    {
+        return self::getCharsFromCodePoints(self::getCodePointsFromString($str), $mode);
+    }
+
     /**
      * Converts all code points to chars and returns the string
      * Invalid code points are ignored
@@ -1463,6 +1589,7 @@ private static function getMapByMode(int $mode): array
                 return [];
         }
 
+        /** @noinspection PhpIncludeInspection */
         return self::$maps[$mode] = include(__DIR__ . "/../res/{$file}.php");
     }
 }