feat(str): use enum for encoding

Signed-off-by: azjezz <azjezz@protonmail.com>
azjezz · Nov 8, 2021 · 73f176b · 73f176b
1 parent 5b6d386
commit 73f176b
Show file tree

Hide file tree

Showing 57 changed files with 410 additions and 354 deletions.
diff --git a/config/.phpcs.xml b/config/.phpcs.xml
@@ -8,6 +8,7 @@
     <file>../tests</file>
 
     <exclude-pattern>*/src/Psl/File/(WriteMode|LockType).php</exclude-pattern>
+    <exclude-pattern>*/src/Psl/Str/Encoding.php</exclude-pattern>
 
     <arg name="basepath" value="."/>
     <arg name="colors"/>

diff --git a/docs/component/encoding-base64.md b/docs/component/encoding-base64.md
@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [decode](./../../src/Psl/Encoding/Base64/decode.php#L27)
+- [decode](./../../src/Psl/Encoding/Base64/decode.php#L26)
 - [encode](./../../src/Psl/Encoding/Base64/encode.php#L18)
 
 
diff --git a/docs/component/str.md b/docs/component/str.md
@@ -17,63 +17,67 @@
 
 #### `Functions`
 
-- [after](./../../src/Psl/Str/after.php#L15)
-- [after_ci](./../../src/Psl/Str/after_ci.php#L15)
-- [after_last](./../../src/Psl/Str/after_last.php#L15)
-- [after_last_ci](./../../src/Psl/Str/after_last_ci.php#L15)
-- [before](./../../src/Psl/Str/before.php#L15)
-- [before_ci](./../../src/Psl/Str/before_ci.php#L15)
-- [before_last](./../../src/Psl/Str/before_last.php#L15)
-- [before_last_ci](./../../src/Psl/Str/before_last_ci.php#L15)
-- [capitalize](./../../src/Psl/Str/capitalize.php#L33)
-- [capitalize_words](./../../src/Psl/Str/capitalize_words.php#L35)
-- [chr](./../../src/Psl/Str/chr.php#L27)
-- [chunk](./../../src/Psl/Str/chunk.php#L40)
+- [after](./../../src/Psl/Str/after.php#L14)
+- [after_ci](./../../src/Psl/Str/after_ci.php#L14)
+- [after_last](./../../src/Psl/Str/after_last.php#L14)
+- [after_last_ci](./../../src/Psl/Str/after_last_ci.php#L14)
+- [before](./../../src/Psl/Str/before.php#L14)
+- [before_ci](./../../src/Psl/Str/before_ci.php#L14)
+- [before_last](./../../src/Psl/Str/before_last.php#L14)
+- [before_last_ci](./../../src/Psl/Str/before_last_ci.php#L14)
+- [capitalize](./../../src/Psl/Str/capitalize.php#L29)
+- [capitalize_words](./../../src/Psl/Str/capitalize_words.php#L30)
+- [chr](./../../src/Psl/Str/chr.php#L22)
+- [chunk](./../../src/Psl/Str/chunk.php#L39)
 - [concat](./../../src/Psl/Str/concat.php#L20)
-- [contains](./../../src/Psl/Str/contains.php#L42)
-- [contains_ci](./../../src/Psl/Str/contains_ci.php#L42)
+- [contains](./../../src/Psl/Str/contains.php#L41)
+- [contains_ci](./../../src/Psl/Str/contains_ci.php#L41)
 - [convert_encoding](./../../src/Psl/Str/convert_encoding.php#L19)
 - [detect_encoding](./../../src/Psl/Str/detect_encoding.php#L21)
-- [ends_with](./../../src/Psl/Str/ends_with.php#L39)
-- [ends_with_ci](./../../src/Psl/Str/ends_with_ci.php#L39)
-- [fold](./../../src/Psl/Str/fold.php#L22)
+- [ends_with](./../../src/Psl/Str/ends_with.php#L35)
+- [ends_with_ci](./../../src/Psl/Str/ends_with_ci.php#L35)
+- [fold](./../../src/Psl/Str/fold.php#L19)
 - [format](./../../src/Psl/Str/format.php#L26)
 - [format_number](./../../src/Psl/Str/format_number.php#L19)
 - [from_code_points](./../../src/Psl/Str/from_code_points.php#L20)
 - [is_empty](./../../src/Psl/Str/is_empty.php#L29)
 - [is_utf8](./../../src/Psl/Str/is_utf8.php#L14)
 - [join](./../../src/Psl/Str/join.php#L27)
-- [length](./../../src/Psl/Str/length.php#L30)
+- [length](./../../src/Psl/Str/length.php#L25)
 - [levenshtein](./../../src/Psl/Str/levenshtein.php#L29)
-- [lowercase](./../../src/Psl/Str/lowercase.php#L35)
+- [lowercase](./../../src/Psl/Str/lowercase.php#L34)
 - [metaphone](./../../src/Psl/Str/metaphone.php#L23)
-- [ord](./../../src/Psl/Str/ord.php#L27)
-- [pad_left](./../../src/Psl/Str/pad_left.php#L38)
-- [pad_right](./../../src/Psl/Str/pad_right.php#L38)
+- [ord](./../../src/Psl/Str/ord.php#L26)
+- [pad_left](./../../src/Psl/Str/pad_left.php#L37)
+- [pad_right](./../../src/Psl/Str/pad_right.php#L37)
 - [repeat](./../../src/Psl/Str/repeat.php#L28)
-- [replace](./../../src/Psl/Str/replace.php#L19)
+- [replace](./../../src/Psl/Str/replace.php#L15)
 - [replace_ci](./../../src/Psl/Str/replace_ci.php#L20)
-- [replace_every](./../../src/Psl/Str/replace_every.php#L19)
-- [replace_every_ci](./../../src/Psl/Str/replace_every_ci.php#L19)
+- [replace_every](./../../src/Psl/Str/replace_every.php#L15)
+- [replace_every_ci](./../../src/Psl/Str/replace_every_ci.php#L15)
 - [reverse](./../../src/Psl/Str/reverse.php#L14)
-- [search](./../../src/Psl/Str/search.php#L25)
-- [search_ci](./../../src/Psl/Str/search_ci.php#L25)
-- [search_last](./../../src/Psl/Str/search_last.php#L25)
-- [search_last_ci](./../../src/Psl/Str/search_last_ci.php#L25)
-- [slice](./../../src/Psl/Str/slice.php#L25)
-- [splice](./../../src/Psl/Str/splice.php#L22)
+- [search](./../../src/Psl/Str/search.php#L23)
+- [search_ci](./../../src/Psl/Str/search_ci.php#L23)
+- [search_last](./../../src/Psl/Str/search_last.php#L24)
+- [search_last_ci](./../../src/Psl/Str/search_last_ci.php#L24)
+- [slice](./../../src/Psl/Str/slice.php#L23)
+- [splice](./../../src/Psl/Str/splice.php#L21)
 - [split](./../../src/Psl/Str/split.php#L24)
-- [starts_with](./../../src/Psl/Str/starts_with.php#L16)
-- [starts_with_ci](./../../src/Psl/Str/starts_with_ci.php#L16)
+- [starts_with](./../../src/Psl/Str/starts_with.php#L12)
+- [starts_with_ci](./../../src/Psl/Str/starts_with_ci.php#L12)
 - [strip_prefix](./../../src/Psl/Str/strip_prefix.php#L17)
-- [strip_suffix](./../../src/Psl/Str/strip_suffix.php#L17)
+- [strip_suffix](./../../src/Psl/Str/strip_suffix.php#L13)
 - [to_int](./../../src/Psl/Str/to_int.php#L12)
 - [trim](./../../src/Psl/Str/trim.php#L18)
 - [trim_left](./../../src/Psl/Str/trim_left.php#L18)
 - [trim_right](./../../src/Psl/Str/trim_right.php#L18)
-- [truncate](./../../src/Psl/Str/truncate.php#L29)
-- [uppercase](./../../src/Psl/Str/uppercase.php#L19)
-- [width](./../../src/Psl/Str/width.php#L19)
-- [wrap](./../../src/Psl/Str/wrap.php#L23)
+- [truncate](./../../src/Psl/Str/truncate.php#L28)
+- [uppercase](./../../src/Psl/Str/uppercase.php#L14)
+- [width](./../../src/Psl/Str/width.php#L18)
+- [wrap](./../../src/Psl/Str/wrap.php#L22)
+
+#### `Enums`
+
+- [Encoding](./../../src/Psl/Str/Encoding.php#L7)
 
 
diff --git a/src/Psl/Encoding/Hex/decode.php b/src/Psl/Encoding/Hex/decode.php
@@ -27,8 +27,7 @@ function decode(string $hexadecimal): string
         );
     }
 
-    /** @psalm-suppress MissingThrowsDocblock */
-    $hex_len = Str\length($hexadecimal, '8bit');
+    $hex_len = Str\length($hexadecimal, Str\Encoding::ASCII_8BIT);
     if (($hex_len & 1) !== 0) {
         throw new Exception\RangeException(
             'Expected an even number of hexadecimal characters.',

diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
@@ -648,6 +648,7 @@ final class Loader
     public const ENUMS = [
         'Psl\File\LockType',
         'Psl\File\WriteMode',
+        'Psl\Str\Encoding',
     ];
 
     public const TYPE_CONSTANTS = 1;

diff --git a/src/Psl/Internal/validate_offset.php b/src/Psl/Internal/validate_offset.php
@@ -20,7 +20,7 @@
  *
  * @return ($assert is true ? bool : int)
  */
-function validate_offset(int $offset, int $length, bool $assert = false)
+function validate_offset(int $offset, int $length, bool $assert = false): int|bool
 {
     $original_offset = $offset;
 

diff --git a/src/Psl/Str/Encoding.php b/src/Psl/Str/Encoding.php
@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Str;
+
+enum Encoding: string
+{
+    case BASE64 = 'BASE64';
+    case UUENCODE = 'UUENCODE';
+    case HTML_ENTITIES = 'HTML-ENTITIES';
+    case QUOTED_PRINTABLE = 'Quoted-Printable';
+    case ASCII_7BIT = '7bit';
+    case ASCII_8BIT = '8bit';
+    case UCS_4 = 'UCS-4';
+    case UCS_4BE = 'UCS-4BE';
+    case UCS_4LE = 'UCS-4LE';
+    case UCS_2 = 'UCS-2';
+    case UCS_2BE = 'UCS-2BE';
+    case UCS_2LE = 'UCS-2LE';
+    case UTF_32 = 'UTF-32';
+    case UTF_32BE = 'UTF-32BE';
+    case UTF_32LE = 'UTF-32LE';
+    case UTF_16 = 'UTF-16';
+    case UTF_16BE = 'UTF-16BE';
+    case UTF_16LE = 'UTF-16LE';
+    case UTF_8 = 'UTF-8';
+    case UTF_7 = 'UTF-7';
+    case UTF7_IMAP = 'UTF7-IMAP';
+    case ASCII = 'ASCII';
+    case EUC_JP = 'EUC-JP';
+    case SJIS = 'SJIS';
+    case EUCJP_WIN = 'eucJP-win';
+    case EUC_JP_2004 = 'EUC-JP-2004';
+    case SJIS_MOBILE_DOCOMO = 'SJIS-Mobile#DOCOMO';
+    case SJIS_MOBILE_KDDI = 'SJIS-Mobile#KDDI';
+    case SJIS_MOBILE_SOFTBANK = 'SJIS-Mobile#SOFTBANK';
+    case SJIS_MAC = 'SJIS-mac';
+    case SJIS_2004 = 'SJIS-2004';
+    case UTF_8_MOBILE_DOCOMO = 'UTF-8-Mobile#DOCOMO';
+    case UTF_8_MOBILE_KDDI_A = 'UTF-8-Mobile#KDDI-A';
+    case UTF_8_MOBILE_KDDI_B = 'UTF-8-Mobile#KDDI-B';
+    case UTF_8_MOBILE_SOFTBANK = 'UTF-8-Mobile#SOFTBANK';
+    case CP932 = 'CP932';
+    case CP51932 = 'CP51932';
+    case JIS = 'JIS';
+    case ISO_2022_JP = 'ISO-2022-JP';
+    case ISO_2022_JP_MS = 'ISO-2022-JP-MS';
+    case GB18030 = 'GB18030';
+    case WINDOWS_1252 = 'Windows-1252';
+    case WINDOWS_1254 = 'Windows-1254';
+    case ISO_8859_1 = 'ISO-8859-1';
+    case ISO_8859_2 = 'ISO-8859-2';
+    case ISO_8859_3 = 'ISO-8859-3';
+    case ISO_8859_4 = 'ISO-8859-4';
+    case ISO_8859_5 = 'ISO-8859-5';
+    case ISO_8859_6 = 'ISO-8859-6';
+    case ISO_8859_7 = 'ISO-8859-7';
+    case ISO_8859_8 = 'ISO-8859-8';
+    case ISO_8859_9 = 'ISO-8859-9';
+    case ISO_8859_10 = 'ISO-8859-10';
+    case ISO_8859_13 = 'ISO-8859-13';
+    case ISO_8859_14 = 'ISO-8859-14';
+    case ISO_8859_15 = 'ISO-8859-15';
+    case ISO_8859_16 = 'ISO-8859-16';
+    case EUC_CN = 'EUC-CN';
+    case CP936 = 'CP936';
+    case HZ = 'HZ';
+    case EUC_TW = 'EUC-TW';
+    case BIG_5 = 'BIG-5';
+    case CP950 = 'CP950';
+    case EUC_KR = 'EUC-KR';
+    case UHC = 'UHC';
+    case ISO_2022_KR = 'ISO-2022-KR';
+    case WINDOWS_1251 = 'Windows-1251';
+    case CP866 = 'CP866';
+    case KOI8_R = 'KOI8-R';
+    case KOI8_U = 'KOI8-U';
+    case ARMSCII_8 = 'ArmSCII-8';
+    case CP850 = 'CP850';
+    case ISO_2022_JP_2004 = 'ISO-2022-JP-2004';
+    case ISO_2022_JP_MOBILE_KDDI = 'ISO-2022-JP-MOBILE#KDDI';
+    case CP50220 = 'CP50220';
+    case CP50221 = 'CP50221';
+    case CP50222 = 'CP50222';
+}
diff --git a/src/Psl/Str/after.php b/src/Psl/Str/after.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function after(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $position = search($haystack, $needle, $offset, $encoding);
     if (null === $position) {

diff --git a/src/Psl/Str/after_ci.php b/src/Psl/Str/after_ci.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function after_ci(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $position = search_ci($haystack, $needle, $offset, $encoding);
     if (null === $position) {

diff --git a/src/Psl/Str/after_last.php b/src/Psl/Str/after_last.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function after_last(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $position = search_last($haystack, $needle, $offset, $encoding);
     if (null === $position) {

diff --git a/src/Psl/Str/after_last_ci.php b/src/Psl/Str/after_last_ci.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function after_last_ci(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $position = search_last_ci($haystack, $needle, $offset, $encoding);
     if (null === $position) {

diff --git a/src/Psl/Str/before.php b/src/Psl/Str/before.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function before(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $length = search($haystack, $needle, $offset, $encoding);
     if (null === $length) {

diff --git a/src/Psl/Str/before_ci.php b/src/Psl/Str/before_ci.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function before_ci(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $length = search_ci($haystack, $needle, $offset, $encoding);
     if (null === $length) {

diff --git a/src/Psl/Str/before_last.php b/src/Psl/Str/before_last.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function before_last(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $length = search_last($haystack, $needle, $offset, $encoding);
     if (null === $length) {

diff --git a/src/Psl/Str/before_last_ci.php b/src/Psl/Str/before_last_ci.php
@@ -8,15 +8,14 @@
 
 /**
  * @throws Psl\Exception\InvariantViolationException If the $offset is out-of-bounds.
- * @throws Psl\Exception\InvariantViolationException If an invalid $encoding is provided.
  *
  * @pure
  */
 function before_last_ci(
     string $haystack,
     string $needle,
     int $offset = 0,
-    ?string $encoding = null
+    Encoding $encoding = Encoding::UTF_8
 ): ?string {
     $length = search_last_ci($haystack, $needle, $offset, $encoding);
     if (null === $length) {

diff --git a/src/Psl/Str/capitalize.php b/src/Psl/Str/capitalize.php
@@ -4,8 +4,6 @@
 
 namespace Psl\Str;
 
-use Psl\Exception;
-
 /**
  * Returns the string with the first character capitalized.
  *
@@ -27,10 +25,8 @@
  *      => Str('1337)
  *
  * @pure
- *
- * @throws Exception\InvariantViolationException If an invalid $encoding is provided.
  */
-function capitalize(string $string, ?string $encoding = null): string
+function capitalize(string $string, Encoding $encoding = Encoding::UTF_8): string
 {
     if ('' === $string) {
         return '';