Str\Grapheme\reverse() function

docs/component/str-grapheme.md

@@ -25,6 +25,7 @@
 - [ends_with](./../../src/Psl/Str/Grapheme/ends_with.php#L17)
 - [ends_with_ci](./../../src/Psl/Str/Grapheme/ends_with_ci.php#L17)
 - [length](./../../src/Psl/Str/Grapheme/length.php#L19)
+- [reverse](./../../src/Psl/Str/Grapheme/reverse.php#L19)
 - [search](./../../src/Psl/Str/Grapheme/search.php#L24)
 - [search_ci](./../../src/Psl/Str/Grapheme/search_ci.php#L24)
 - [search_last](./../../src/Psl/Str/Grapheme/search_last.php#L25)

src/Psl/Internal/Loader.php

@@ -456,6 +456,7 @@ final class Loader
         'Psl\Str\Grapheme\ends_with',
         'Psl\Str\Grapheme\ends_with_ci',
         'Psl\Str\Grapheme\length',
+        'Psl\Str\Grapheme\reverse',
         'Psl\Str\Grapheme\search',
         'Psl\Str\Grapheme\search_ci',
         'Psl\Str\Grapheme\search_last',

src/Psl/Str/Grapheme/reverse.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl\Exception\InvalidArgumentException;
+
+use function grapheme_strlen;
+use function grapheme_substr;
+
+/**
+ * Reverses the string.
+ *
+ * @pure
+ *
+ * @throws \Psl\Exception\InvalidArgumentException If $string length cannot be determined.
+ */
+function reverse(string $string): string
+{
+    $reversed = '';
+
+    $length = grapheme_strlen($string);
+
+    if ($length === false || $length === null) {
+        throw new InvalidArgumentException('Cannot get string length. Possibly invalid UTF-8 sequence');
+    }
+
+    while ($length-- > 0) {
+        $reversed .= grapheme_substr($string, $length, 1);
+    }
+
+    return $reversed;
+}

tests/unit/Str/Grapheme/ReverseTest.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl;
+
+class ReverseTest extends TestCase
+{
+    public function provideData(): array
+    {
+        return [
+            ['Hello World 👩🏽‍❤️‍👨🏼', '👩🏽‍❤️‍👨🏼 dlroW olleH'],
+            ['👩‍👩‍👦👩🏽‍❤️‍👨🏼👩🏽‍🏫', '👩🏽‍🏫👩🏽‍❤️‍👨🏼👩‍👩‍👦'],
+            ['某物 🖖🏿', '🖖🏿 物某' ],
+            ['👲🏻 что-то', 'от-отч 👲🏻'],
+            ['🙂👨🏼‍🎤😟', '😟👨🏼‍🎤🙂'],
+            ['مرحبا👲🏻👨🏼‍🎤', '👨🏼‍🎤👲🏻ابحرم'],
+        ];
+    }
+
+    /**
+     * @dataProvider provideData
+     */
+    public function testReverse(string $string, string $expected): void
+    {
+        static::assertSame(Psl\Str\Grapheme\reverse($string), $expected);
+    }
+
+    public function testFailReverse(): void
+    {
+        $string = Psl\Str\Byte\slice('🐶🐶🐶', 0, 5);
+
+        $this->expectException(Psl\Exception\InvalidArgumentException::class);
+        Psl\Str\Grapheme\reverse($string);
+    }
+}