From a1d030c327a97891b689c9effbfea8bd8212dceb Mon Sep 17 00:00:00 2001
From: azjezz <azjezz@protonmail.com>
Date: Sat, 3 Oct 2020 18:56:55 +0100
Subject: [PATCH] [Str] add grarpheme support

---
 .github/workflows/security-analysis.yml     |  2 +-
 .github/workflows/static-analysis.yml       |  2 +-
 composer.json                               |  3 +-
 src/Psl/Internal/Loader.php                 | 14 ++++
 src/Psl/Str/Grapheme/contains.php           | 30 +++++++++
 src/Psl/Str/Grapheme/contains_ci.php        | 30 +++++++++
 src/Psl/Str/Grapheme/ends_with.php          | 33 ++++++++++
 src/Psl/Str/Grapheme/ends_with_ci.php       | 33 ++++++++++
 src/Psl/Str/Grapheme/length.php             | 17 +++++
 src/Psl/Str/Grapheme/search.php             | 34 ++++++++++
 src/Psl/Str/Grapheme/search_ci.php          | 34 ++++++++++
 src/Psl/Str/Grapheme/search_last.php        | 35 ++++++++++
 src/Psl/Str/Grapheme/search_last_ci.php     | 35 ++++++++++
 src/Psl/Str/Grapheme/slice.php              | 39 +++++++++++
 src/Psl/Str/Grapheme/starts_with.php        | 18 ++++++
 src/Psl/Str/Grapheme/starts_with_ci.php     | 18 ++++++
 src/Psl/Str/Grapheme/strip_prefix.php       | 23 +++++++
 src/Psl/Str/Grapheme/strip_suffix.php       | 23 +++++++
 tests/Psl/Str/Grapheme/ContainsCiTest.php   | 32 +++++++++
 tests/Psl/Str/Grapheme/ContainsTest.php     | 72 +++++++++++++++++++++
 tests/Psl/Str/Grapheme/EndsWithCiTest.php   | 35 ++++++++++
 tests/Psl/Str/Grapheme/EndsWithTest.php     | 34 ++++++++++
 tests/Psl/Str/Grapheme/LengthTest.php       | 33 ++++++++++
 tests/Psl/Str/Grapheme/SearchCiTest.php     | 33 ++++++++++
 tests/Psl/Str/Grapheme/SearchLastCiTest.php | 33 ++++++++++
 tests/Psl/Str/Grapheme/SearchLastTest.php   | 33 ++++++++++
 tests/Psl/Str/Grapheme/SearchTest.php       | 33 ++++++++++
 tests/Psl/Str/Grapheme/SliceTest.php        | 62 ++++++++++++++++++
 tests/Psl/Str/Grapheme/StartsWithCiTest.php | 41 ++++++++++++
 tests/Psl/Str/Grapheme/StartsWithTest.php   | 41 ++++++++++++
 tests/Psl/Str/Grapheme/StripPrefixTest.php  | 41 ++++++++++++
 tests/Psl/Str/Grapheme/StripSuffixTest.php  | 48 ++++++++++++++
 32 files changed, 991 insertions(+), 3 deletions(-)
 create mode 100644 src/Psl/Str/Grapheme/contains.php
 create mode 100644 src/Psl/Str/Grapheme/contains_ci.php
 create mode 100644 src/Psl/Str/Grapheme/ends_with.php
 create mode 100644 src/Psl/Str/Grapheme/ends_with_ci.php
 create mode 100644 src/Psl/Str/Grapheme/length.php
 create mode 100644 src/Psl/Str/Grapheme/search.php
 create mode 100644 src/Psl/Str/Grapheme/search_ci.php
 create mode 100644 src/Psl/Str/Grapheme/search_last.php
 create mode 100644 src/Psl/Str/Grapheme/search_last_ci.php
 create mode 100644 src/Psl/Str/Grapheme/slice.php
 create mode 100644 src/Psl/Str/Grapheme/starts_with.php
 create mode 100644 src/Psl/Str/Grapheme/starts_with_ci.php
 create mode 100644 src/Psl/Str/Grapheme/strip_prefix.php
 create mode 100644 src/Psl/Str/Grapheme/strip_suffix.php
 create mode 100644 tests/Psl/Str/Grapheme/ContainsCiTest.php
 create mode 100644 tests/Psl/Str/Grapheme/ContainsTest.php
 create mode 100644 tests/Psl/Str/Grapheme/EndsWithCiTest.php
 create mode 100644 tests/Psl/Str/Grapheme/EndsWithTest.php
 create mode 100644 tests/Psl/Str/Grapheme/LengthTest.php
 create mode 100644 tests/Psl/Str/Grapheme/SearchCiTest.php
 create mode 100644 tests/Psl/Str/Grapheme/SearchLastCiTest.php
 create mode 100644 tests/Psl/Str/Grapheme/SearchLastTest.php
 create mode 100644 tests/Psl/Str/Grapheme/SearchTest.php
 create mode 100644 tests/Psl/Str/Grapheme/SliceTest.php
 create mode 100644 tests/Psl/Str/Grapheme/StartsWithCiTest.php
 create mode 100644 tests/Psl/Str/Grapheme/StartsWithTest.php
 create mode 100644 tests/Psl/Str/Grapheme/StripPrefixTest.php
 create mode 100644 tests/Psl/Str/Grapheme/StripSuffixTest.php

diff --git a/.github/workflows/security-analysis.yml b/.github/workflows/security-analysis.yml
index f83d1c872..3e4a23df3 100644
--- a/.github/workflows/security-analysis.yml
+++ b/.github/workflows/security-analysis.yml
@@ -4,7 +4,7 @@ on: ["pull_request", "push"]
 
 jobs:
   security-analysis:
-    name: "security anaylsis"
+    name: "security analysis"
     runs-on: "ubuntu-latest"
     steps:
       - name: "checkout"
diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
index 857c9c2de..f3ac2ad03 100644
--- a/.github/workflows/static-analysis.yml
+++ b/.github/workflows/static-analysis.yml
@@ -4,7 +4,7 @@ on: ["pull_request", "push"]
 
 jobs:
   static-analysis:
-    name: "static anaylsis"
+    name: "static analysis"
     runs-on: "ubuntu-latest"
     steps:
       - name: "checkout"
diff --git a/composer.json b/composer.json
index 52237244f..be00ae12c 100644
--- a/composer.json
+++ b/composer.json
@@ -14,7 +14,8 @@
         "ext-bcmath": "*",
         "ext-mbstring": "*",
         "ext-json": "*",
-        "ext-sodium": "*"
+        "ext-sodium": "*",
+        "ext-intl": "*"
     },
     "require-dev": {
         "vimeo/psalm": "dev-master",
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
index 99247d888..eb12b57cb 100644
--- a/src/Psl/Internal/Loader.php
+++ b/src/Psl/Internal/Loader.php
@@ -325,6 +325,20 @@ final class Loader
         'Psl\Password\hash',
         'Psl\Password\needs_rehash',
         'Psl\Password\verify',
+        'Psl\Str\Grapheme\contains',
+        'Psl\Str\Grapheme\contains_ci',
+        'Psl\Str\Grapheme\ends_with',
+        'Psl\Str\Grapheme\ends_with_ci',
+        'Psl\Str\Grapheme\length',
+        'Psl\Str\Grapheme\search',
+        'Psl\Str\Grapheme\search_ci',
+        'Psl\Str\Grapheme\search_last',
+        'Psl\Str\Grapheme\search_last_ci',
+        'Psl\Str\Grapheme\slice',
+        'Psl\Str\Grapheme\starts_with',
+        'Psl\Str\Grapheme\starts_with_ci',
+        'Psl\Str\Grapheme\strip_prefix',
+        'Psl\Str\Grapheme\strip_suffix',
     ];
 
     public const INTERFACES = [
diff --git a/src/Psl/Str/Grapheme/contains.php b/src/Psl/Str/Grapheme/contains.php
new file mode 100644
index 000000000..daf207d14
--- /dev/null
+++ b/src/Psl/Str/Grapheme/contains.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the 'haystack' string contains the 'needle' string.
+ *
+ * An optional offset determines where in the haystack the search begins. If the
+ * offset is negative, the search will begin that many characters from the end
+ * of the string. If the offset is out-of-bounds, a ViolationException will be
+ * thrown.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
+ */
+function contains(string $haystack, string $needle, int $offset = 0): bool
+{
+    if ('' === $needle) {
+        Psl\Internal\validate_offset($offset, length($haystack));
+
+        return true;
+    }
+
+    return null !== search($haystack, $needle, $offset);
+}
diff --git a/src/Psl/Str/Grapheme/contains_ci.php b/src/Psl/Str/Grapheme/contains_ci.php
new file mode 100644
index 000000000..244cd6b54
--- /dev/null
+++ b/src/Psl/Str/Grapheme/contains_ci.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the 'haystack' string contains the 'needle' string.
+ *
+ * An optional offset determines where in the haystack the search begins. If the
+ * offset is negative, the search will begin that many characters from the end
+ * of the string. If the offset is out-of-bounds, a ViolationException will be
+ * thrown.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
+ */
+function contains_ci(string $haystack, string $needle, int $offset = 0): bool
+{
+    if ('' === $needle) {
+        Psl\Internal\validate_offset($offset, length($haystack));
+
+        return true;
+    }
+
+    return null !== search_ci($haystack, $needle, $offset);
+}
diff --git a/src/Psl/Str/Grapheme/ends_with.php b/src/Psl/Str/Grapheme/ends_with.php
new file mode 100644
index 000000000..e45033203
--- /dev/null
+++ b/src/Psl/Str/Grapheme/ends_with.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the string ends with the given suffix.
+ *
+ * @psalm-pure
+ */
+function ends_with(string $string, string $suffix): bool
+{
+    if ($suffix === $string) {
+        return true;
+    }
+
+    $suffix_length = length($suffix);
+    $total_length  = length($string);
+    if ($suffix_length > $total_length) {
+        return false;
+    }
+
+    /** @psalm-suppress MissingThrowsDocblock */
+    $position = search_last($string, $suffix);
+    if (null === $position) {
+        return false;
+    }
+
+    return $position + $suffix_length === $total_length;
+}
diff --git a/src/Psl/Str/Grapheme/ends_with_ci.php b/src/Psl/Str/Grapheme/ends_with_ci.php
new file mode 100644
index 000000000..9779e2ed2
--- /dev/null
+++ b/src/Psl/Str/Grapheme/ends_with_ci.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the string ends with the given suffix (case-insensitive).
+ *
+ * @psalm-pure
+ */
+function ends_with_ci(string $string, string $suffix): bool
+{
+    if ($suffix === $string) {
+        return true;
+    }
+
+    $suffix_length = length($suffix);
+    $total_length  = length($string);
+    if ($suffix_length > $total_length) {
+        return false;
+    }
+
+    /** @psalm-suppress MissingThrowsDocblock */
+    $position = search_last_ci($string, $suffix);
+    if (null === $position) {
+        return false;
+    }
+
+    return $position + $suffix_length === $total_length;
+}
diff --git a/src/Psl/Str/Grapheme/length.php b/src/Psl/Str/Grapheme/length.php
new file mode 100644
index 000000000..ee823dddc
--- /dev/null
+++ b/src/Psl/Str/Grapheme/length.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use function grapheme_strlen;
+
+/**
+ * Returns the length of the given string in grapheme units
+ *
+ * @psalm-pure
+ */
+function length(string $string): int
+{
+    return (int) grapheme_strlen($string);
+}
diff --git a/src/Psl/Str/Grapheme/search.php b/src/Psl/Str/Grapheme/search.php
new file mode 100644
index 000000000..bc5763597
--- /dev/null
+++ b/src/Psl/Str/Grapheme/search.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+use function grapheme_strpos;
+
+/**
+ * Returns the first position of the 'needle' string in the 'haystack' string
+ * grapheme units, or null if it isn't found.
+ *
+ * An optional offset determines where in the haystack the search begins. If the
+ * offset is negative, the search will begin that many characters from the end
+ * of the string.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
+ */
+function search(string $haystack, string $needle, int $offset = 0): ?int
+{
+    if ('' === $needle) {
+        return null;
+    }
+
+    $offset = Psl\Internal\validate_offset($offset, length($haystack));
+
+    return false === ($pos = grapheme_strpos($haystack, $needle, $offset)) ?
+        null :
+        $pos;
+}
diff --git a/src/Psl/Str/Grapheme/search_ci.php b/src/Psl/Str/Grapheme/search_ci.php
new file mode 100644
index 000000000..035ea9e1a
--- /dev/null
+++ b/src/Psl/Str/Grapheme/search_ci.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+use function grapheme_stripos;
+
+/**
+ * Returns the first position of the 'needle' string in the 'haystack' string,
+ * in grapheme units, or null if it isn't found (case-insensitive).
+ *
+ * An optional offset determines where in the haystack the search begins. If the
+ * offset is negative, the search will begin that many characters from the end
+ * of the string.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If $offset is out-of-bounds.
+ */
+function search_ci(string $haystack, string $needle, int $offset = 0): ?int
+{
+    if ('' === $needle) {
+        return null;
+    }
+
+    $offset = Psl\Internal\validate_offset($offset, length($haystack));
+
+    return false === ($pos = grapheme_stripos($haystack, $needle, $offset)) ?
+        null :
+        $pos;
+}
diff --git a/src/Psl/Str/Grapheme/search_last.php b/src/Psl/Str/Grapheme/search_last.php
new file mode 100644
index 000000000..4adf679bb
--- /dev/null
+++ b/src/Psl/Str/Grapheme/search_last.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+use function grapheme_strrpos;
+
+/**
+ * Returns the last position of the 'needle' string in the 'haystack' string,
+ * or null if it isn't found.
+ *
+ * An optional offset determines where in the haystack (from the beginning) the
+ * search begins. If the offset is negative, the search will begin that many
+ * characters from the end of the string and go backwards.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
+ */
+function search_last(string $haystack, string $needle, int $offset = 0): ?int
+{
+    if ('' === $needle) {
+        return null;
+    }
+
+    $haystack_length = length($haystack);
+    Psl\invariant($offset >= -$haystack_length && $offset <= $haystack_length, 'Offset is out-of-bounds.');
+
+    return false === ($pos = grapheme_strrpos($haystack, $needle, $offset)) ?
+        null :
+        $pos;
+}
diff --git a/src/Psl/Str/Grapheme/search_last_ci.php b/src/Psl/Str/Grapheme/search_last_ci.php
new file mode 100644
index 000000000..d1295e474
--- /dev/null
+++ b/src/Psl/Str/Grapheme/search_last_ci.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+use function grapheme_strripos;
+
+/**
+ * Returns the last position of the 'needle' string in the 'haystack' string,
+ * or null if it isn't found (case-insensitive).
+ *
+ * An optional offset determines where in the haystack (from the beginning) the
+ * search begins. If the offset is negative, the search will begin that many
+ * characters from the end of the string and go backwards.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If the offset is out-of-bounds.
+ */
+function search_last_ci(string $haystack, string $needle, int $offset = 0): ?int
+{
+    if ('' === $needle) {
+        return null;
+    }
+
+    $haystack_length = length($haystack);
+    Psl\invariant($offset >= -$haystack_length && $offset <= $haystack_length, 'Offset is out-of-bounds.');
+
+    return false === ($pos = grapheme_strripos($haystack, $needle, $offset)) ?
+        null :
+        $pos;
+}
diff --git a/src/Psl/Str/Grapheme/slice.php b/src/Psl/Str/Grapheme/slice.php
new file mode 100644
index 000000000..380594582
--- /dev/null
+++ b/src/Psl/Str/Grapheme/slice.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+use Psl\Internal;
+
+use function mb_substr;
+
+/**
+ * Returns a substring of length `$length` of the given string starting at the
+ * `$offset`.
+ *
+ * If no length is given, the slice will contain the rest of the
+ * string. If the length is zero, the empty string will be returned. If the
+ * offset is out-of-bounds, an InvariantViolationException will be thrown.
+ *
+ * @psalm-pure
+ *
+ * @throws Psl\Exception\InvariantViolationException If a negative $length is given, or $offset is out-of-bounds.
+ */
+function slice(string $string, int $offset, ?int $length = null): string
+{
+    Psl\invariant(null === $length || $length >= 0, 'Expected a non-negative length.');
+    $string_length = length($string);
+    $offset        = Psl\Internal\validate_offset($offset, $string_length);
+
+    if (0 === $offset && (null === $length || $string_length <= $length)) {
+        return $string;
+    }
+
+    if (null === $length) {
+        return (string) grapheme_substr($string, $offset);
+    }
+
+    return (string) grapheme_substr($string, $offset, $length);
+}
diff --git a/src/Psl/Str/Grapheme/starts_with.php b/src/Psl/Str/Grapheme/starts_with.php
new file mode 100644
index 000000000..f1cfd09ad
--- /dev/null
+++ b/src/Psl/Str/Grapheme/starts_with.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the string starts with the given prefix.
+ *
+ * @psalm-pure
+ */
+function starts_with(string $string, string $prefix): bool
+{
+    /** @psalm-suppress MissingThrowsDocblock */
+    return 0 === search($string, $prefix);
+}
diff --git a/src/Psl/Str/Grapheme/starts_with_ci.php b/src/Psl/Str/Grapheme/starts_with_ci.php
new file mode 100644
index 000000000..fc7c82af0
--- /dev/null
+++ b/src/Psl/Str/Grapheme/starts_with_ci.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns whether the string starts with the given prefix (case-insensitive).
+ *
+ * @psalm-pure
+ */
+function starts_with_ci(string $string, string $prefix): bool
+{
+    /** @psalm-suppress MissingThrowsDocblock */
+    return 0 === search_ci($string, $prefix);
+}
diff --git a/src/Psl/Str/Grapheme/strip_prefix.php b/src/Psl/Str/Grapheme/strip_prefix.php
new file mode 100644
index 000000000..a4bcd9505
--- /dev/null
+++ b/src/Psl/Str/Grapheme/strip_prefix.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns the string with the given prefix removed, or the string itself if
+ * it doesn't start with the prefix.
+ *
+ * @psalm-pure
+ */
+function strip_prefix(string $string, string $prefix): string
+{
+    if ('' === $prefix || !starts_with($string, $prefix)) {
+        return $string;
+    }
+
+    /** @psalm-suppress MissingThrowsDocblock */
+    return slice($string, length($prefix));
+}
diff --git a/src/Psl/Str/Grapheme/strip_suffix.php b/src/Psl/Str/Grapheme/strip_suffix.php
new file mode 100644
index 000000000..d489a3be9
--- /dev/null
+++ b/src/Psl/Str/Grapheme/strip_suffix.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str\Grapheme;
+
+use Psl;
+
+/**
+ * Returns the string with the given suffix removed, or the string itself if
+ * it doesn't end with the suffix.
+ *
+ * @psalm-pure
+ */
+function strip_suffix(string $string, string $suffix): string
+{
+    if ('' === $suffix || !ends_with($string, $suffix)) {
+        return $string;
+    }
+
+    /** @psalm-suppress MissingThrowsDocblock */
+    return slice($string, 0, length($string) - length($suffix));
+}
diff --git a/tests/Psl/Str/Grapheme/ContainsCiTest.php b/tests/Psl/Str/Grapheme/ContainsCiTest.php
new file mode 100644
index 000000000..4e3055338
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/ContainsCiTest.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class ContainsCiTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testContainsCi(bool $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\contains_ci($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [true, 'Hello, World', 'Hello', 0],
+            [true, 'Hello, World', 'world', 0],
+            [true, 'Hello, World', '', 8],
+            [false, 'hello, world', 'hey', 5],
+            [true, 'Azjezz', 'az', 0],
+            [false, 'azjezz', 'Az', 2],
+            [true, 'مرحبا بكم', 'بكم', 5],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/ContainsTest.php b/tests/Psl/Str/Grapheme/ContainsTest.php
new file mode 100644
index 000000000..2a9790857
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/ContainsTest.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class ContainsTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testContains(bool $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\contains($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [
+                true,
+                'Hello, World',
+                'Hello',
+                0
+            ],
+
+            [
+                false,
+                'Hello, World',
+                'world',
+                0
+            ],
+
+            [
+                true,
+                'Hello, World',
+                '',
+                8
+            ],
+
+            [
+                false,
+                'hello, world',
+                'hey',
+                5
+            ],
+
+            [
+                true,
+                'azjezz',
+                'az',
+                0
+            ],
+            [
+                false,
+                'azjezz',
+                'Az',
+                2
+            ],
+
+            [
+                true,
+                'مرحبا بكم',
+                'بكم',
+                5
+            ]
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/EndsWithCiTest.php b/tests/Psl/Str/Grapheme/EndsWithCiTest.php
new file mode 100644
index 000000000..78824a75a
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/EndsWithCiTest.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class EndsWithCiTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEndsWithCi(bool $expected, string $haystack, string $suffix): void
+    {
+        self::assertSame($expected, Grapheme\ends_with_ci($haystack, $suffix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [true, 'Hello', 'Hello'],
+            [true, 'Hello, World', 'world', ],
+            [true, 'Hello, WorlḐ', 'worlḑ', ],
+            [false, 'T U N I S I A', 'e', ],
+            [true, 'تونس', 'س'],
+            [false, 'Hello, World', '', ],
+            [false, 'hello, world', 'hey', ],
+            [false, 'hello, world', 'hello cruel world'],
+            [true, 'azjezz', 'z', ],
+            [true, 'مرحبا بكم', 'بكم', ],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/EndsWithTest.php b/tests/Psl/Str/Grapheme/EndsWithTest.php
new file mode 100644
index 000000000..d75a59aa2
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/EndsWithTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class EndsWithTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEndsWith(bool $expected, string $haystack, string $suffix): void
+    {
+        self::assertSame($expected, Grapheme\ends_with($haystack, $suffix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [true, 'Hello', 'Hello'],
+            [false, 'Hello, World', 'world', ],
+            [false, 'T U N I S I A', 'e', ],
+            [true, 'تونس', 'س'],
+            [false, 'Hello, World', '', ],
+            [false, 'Hello, World', 'Hello, cruel world!', ],
+            [false, 'hello, world', 'hey', ],
+            [true, 'azjezz', 'z', ],
+            [true, 'مرحبا بكم', 'بكم', ],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/LengthTest.php b/tests/Psl/Str/Grapheme/LengthTest.php
new file mode 100644
index 000000000..d9490793e
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/LengthTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class LengthTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testLength(int $expected, string $str): void
+    {
+        self::assertSame($expected, Grapheme\length($str));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [6, 'azjezz'],
+            [4, 'تونس'],
+            [3, 'سيف'],
+            [7, 'こんにちは世界'],
+            [3, '🥇🥈🥉'],
+            [2, '你好'],
+            [4, 'สวัสดี'],
+            [3, 'ؤخى']
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/SearchCiTest.php b/tests/Psl/Str/Grapheme/SearchCiTest.php
new file mode 100644
index 000000000..7b20445e5
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/SearchCiTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class SearchCiTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testSearchCi(?int $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\search_ci($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [7, 'Hello, you!', 'You', ],
+            [7, 'Hello, You!', 'You', ],
+            [0, 'Ho! Ho! Ho!', 'ho', ],
+            [0, 'Ho! Ho! Ho!', 'Ho', ],
+            [7, 'Hello, You!', 'You', 5],
+            [null, 'Hello, World!', 'You', 5],
+            [6, 'مرحبا سيف', 'سيف', 4],
+            [null, 'foo', 'bar', 2],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/SearchLastCiTest.php b/tests/Psl/Str/Grapheme/SearchLastCiTest.php
new file mode 100644
index 000000000..98767da89
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/SearchLastCiTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class SearchLastCiTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testSearchLastCi(?int $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\search_last_ci($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [7, 'Hello, you!', 'You', ],
+            [7, 'Hello, You!', 'You', ],
+            [8, 'Ho! Ho! Ho!', 'ho', ],
+            [8, 'Ho! Ho! Ho!', 'Ho', ],
+            [7, 'Hello, You!', 'You', 5],
+            [null, 'Hello, World!', 'You', 5],
+            [6, 'مرحبا سيف', 'سيف', 4],
+            [null, 'foo', 'bar', 2],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/SearchLastTest.php b/tests/Psl/Str/Grapheme/SearchLastTest.php
new file mode 100644
index 000000000..850eea947
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/SearchLastTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class SearchLastTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testSearchLast(?int $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\search_last($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [null, 'Hello, you!', 'You', ],
+            [7, 'Hello, You!', 'You', ],
+            [null, 'Ho! Ho! Ho!', 'ho', ],
+            [8, 'Ho! Ho! Ho!', 'Ho', ],
+            [7, 'Hello, You!', 'You', 5],
+            [null, 'Hello, World!', 'You', 5],
+            [6, 'مرحبا سيف', 'سيف', 4],
+            [null, 'foo', 'bar', 2],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/SearchTest.php b/tests/Psl/Str/Grapheme/SearchTest.php
new file mode 100644
index 000000000..be32b105b
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/SearchTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class SearchTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testSearch(?int $expected, string $haystack, string $needle, int $offset = 0): void
+    {
+        self::assertSame($expected, Grapheme\search($haystack, $needle, $offset));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [null, 'Hello, you!', 'You', ],
+            [7, 'Hello, You!', 'You', ],
+            [null, 'Ho! Ho! Ho!', 'ho', ],
+            [0, 'Ho! Ho! Ho!', 'Ho', ],
+            [7, 'Hello, You!', 'You', 5],
+            [null, 'Hello, World!', 'You', 5],
+            [6, 'مرحبا سيف', 'سيف', 4],
+            [null, 'foo', 'bar', 2],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/SliceTest.php b/tests/Psl/Str/Grapheme/SliceTest.php
new file mode 100644
index 000000000..9c208a881
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/SliceTest.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Exception;
+use Psl\Str\Grapheme;
+
+final class SliceTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testSlice(string $expected, string $string, int $offset, ?int $length = null): void
+    {
+        self::assertSame($expected, Grapheme\slice($string, $offset, $length));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            ['', '', 0, 0, ],
+            ['Hello', 'Hello, World!', 0, 5],
+            ['Hello, World!', 'Hello, World!', 0],
+            ['World', 'Hello, World!', 7, 5],
+            ['سيف', 'مرحبا سيف', 6, 3],
+            ['اهلا', 'اهلا بكم', 0, 4],
+            ['destiny', 'People linked by destiny will always find each other.', 17, 7],
+            ['lö ', 'héllö wôrld', 3, 3, ],
+            ['lö wôrld', 'héllö wôrld', 3, null, ],
+            ['', 'héllö wôrld', 3, 0],
+            ['', 'fôo', 3, null, ],
+            ['', 'fôo', 3, 12, ],
+            ['wôrld', 'héllö wôrld', -5, null, ],
+            ['wôrld', 'héllö wôrld', -5, 100, ],
+            ['wôr', 'héllö wôrld', -5, 3, ],
+        ];
+    }
+
+    public function testSliceThrowsForNegativeLength(): void
+    {
+        $this->expectException(Exception\InvariantViolationException::class);
+
+        Grapheme\slice('Hello', 0, -1);
+    }
+
+    public function testSliceThrowsForOutOfBoundOffset(): void
+    {
+        $this->expectException(Exception\InvariantViolationException::class);
+
+        Grapheme\slice('Hello', 10);
+    }
+
+    public function testSliceThrowsForNegativeOutOfBoundOffset(): void
+    {
+        $this->expectException(Exception\InvariantViolationException::class);
+
+        Grapheme\slice('hello', -6);
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/StartsWithCiTest.php b/tests/Psl/Str/Grapheme/StartsWithCiTest.php
new file mode 100644
index 000000000..3703a6be1
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/StartsWithCiTest.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class StartsWithCiTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testStartsWithCi(bool $expected, string $haystack, string $prefix): void
+    {
+        self::assertSame($expected, Grapheme\starts_with_ci($haystack, $prefix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [true, 'Hello, World', 'Hello', ],
+            [false, 'Hello, World', 'world', ],
+            [false, 'Hello, World', '', ],
+            [false, 'hello, world', 'hey', ],
+            [true, 'azjezz', 'az', ],
+            [true, 'azjezz', 'Az', ],
+            [false, 'مرحبا بكم', 'بكم', ],
+            [true, 'مرحبا بكم', 'مرحبا', ],
+            [true, 'مرحبا سيف', 'مرحبا', 3],
+            [false, 'مرحبا سيف', 'سيف', 3],
+            [true, 'اهلا بكم', 'اهلا', 2],
+            [true, 'héllö wôrld', 'héllö', ],
+            [false, 'héllö wôrld', 'hello', ],
+            [true, 'fôo', 'fôo', ],
+            [true, 'fôo', 'f', ],
+            [true, 'fôo', 'fô', ],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/StartsWithTest.php b/tests/Psl/Str/Grapheme/StartsWithTest.php
new file mode 100644
index 000000000..bbedbd921
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/StartsWithTest.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class StartsWithTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testStartsWith(bool $expected, string $haystack, string $prefix): void
+    {
+        self::assertSame($expected, Grapheme\starts_with($haystack, $prefix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [true, 'Hello, World', 'Hello', ],
+            [false, 'Hello, World', 'world', ],
+            [false, 'Hello, World', '', ],
+            [false, 'hello, world', 'hey', ],
+            [true, 'azjezz', 'az', ],
+            [false, 'azjezz', 'Az', ],
+            [false, 'مرحبا بكم', 'بكم', ],
+            [true, 'مرحبا بكم', 'مرحبا', ],
+            [true, 'مرحبا سيف', 'مرحبا', 3],
+            [false, 'مرحبا سيف', 'سيف', 3],
+            [true, 'اهلا بكم', 'اهلا', 2],
+            [true, 'héllö wôrld', 'héllö', ],
+            [false, 'héllö wôrld', 'hello', ],
+            [true, 'fôo', 'fôo', ],
+            [true, 'fôo', 'f', ],
+            [true, 'fôo', 'fô', ],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/StripPrefixTest.php b/tests/Psl/Str/Grapheme/StripPrefixTest.php
new file mode 100644
index 000000000..30a0e0e42
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/StripPrefixTest.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+class StripPrefixTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testStripPrefix(string $expected, string $haystack, string $prefix): void
+    {
+        self::assertSame($expected, Grapheme\strip_prefix($haystack, $prefix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            ['World', 'Hello, World', 'Hello, '],
+            ['Hello, World', 'Hello, World', 'world'],
+            ['Hello, World', 'Hello, World', ''],
+            ['hello, world', 'hello, world', 'hey'],
+            ['jezz', 'azjezz', 'az'],
+            ['azjezz', 'azjezz', 'Az'],
+            ['مرحبا بكم', 'مرحبا بكم', 'بكم'],
+            ['بكم', 'مرحبا بكم', 'مرحبا '],
+            ['سيف', 'مرحبا سيف', 'مرحبا ', 3],
+            ['مرحبا سيف', 'مرحبا سيف', 'سيف', 3],
+            [' بكم', 'اهلا بكم', 'اهلا', 2],
+            ['wôrld', 'héllö wôrld', 'héllö '],
+            ['héllö wôrld', 'héllö wôrld', 'hello'],
+            ['', 'fôo', 'fôo'],
+            ['ôo', 'fôo', 'f'],
+            ['o', 'fôo', 'fô'],
+        ];
+    }
+}
diff --git a/tests/Psl/Str/Grapheme/StripSuffixTest.php b/tests/Psl/Str/Grapheme/StripSuffixTest.php
new file mode 100644
index 000000000..d84df88da
--- /dev/null
+++ b/tests/Psl/Str/Grapheme/StripSuffixTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Str\Grapheme;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str\Grapheme;
+
+final class StripSuffixTest extends TestCase
+{
+
+    /**
+     * @dataProvider provideData
+     */
+    public function testStripSuffix(string $expected, string $haystack, string $suffix): void
+    {
+        self::assertSame($expected, Grapheme\strip_suffix($haystack, $suffix));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            ['', 'Hello', 'Hello'],
+            ['Hello, World', 'Hello, World', 'world', ],
+            ['T U N I S I A', 'T U N I S I A', 'e', ],
+            ['تون', 'تونس', 'س'],
+            ['Hello, World', 'Hello, World', '', ],
+            ['Hello, World', 'Hello, World', 'Hello, cruel world!', ],
+            ['hello, world', 'hello, world', 'hey', ],
+            ['azjez', 'azjezz', 'z', ],
+            ['مرحبا ', 'مرحبا بكم', 'بكم', ],
+            ['Hello', 'Hello, World', ', World', ],
+            ['Hello, World', 'Hello, World', 'world', ],
+            ['Hello, World', 'Hello, World', '', ],
+            ['hello, world', 'hello, world', 'universe', ],
+            ['azje', 'azjezz', 'zz', ],
+            ['azjezz', 'azjezz', 'ZZ', ],
+            ['مرحبا', 'مرحبا سيف', ' سيف', 3],
+            ['اهلا', 'اهلا بكم', ' بكم', 3],
+            ['héllö', 'héllö wôrld', ' wôrld', ],
+            ['héllö wôrld', 'héllö wôrld', ' world', ],
+            ['fô', 'fôo', 'o', ],
+            ['fôo', 'fôo', 'ô', ],
+            ['f', 'fôo', 'ôo', ],
+        ];
+    }
+}