add replaceArray() replaceFirst() replaceLast() start() startsWith() endsWith() finish() methods

Author: Awilum

README.md

@@ -58,6 +58,13 @@ use Flextype\Component\Strings;
 | <a href="#strings_padBoth">`Strings::padBoth()`</a> | Pad both sides of a string with another. |
 | <a href="#strings_padLeft">`Strings::padLeft()`</a> | Pad the left side of a string with another. |
 | <a href="#strings_padRight">`Strings::padRight()`</a> | Pad the right side of a string with another. |
+| <a href="#strings_replaceArray">`Strings::replaceArray()`</a> | Replace a given value in the string sequentially with an array. |
+| <a href="#strings_replaceFirst">`Strings::replaceFirst()`</a> | Replace the first occurrence of a given value in the string. |
+| <a href="#strings_replaceLast">`Strings::replaceLast()`</a> | Replace the last occurrence of a given value in the string. |
+| <a href="#strings_start">`Strings::start()`</a> | Begin a string with a single instance of a given value. |
+| <a href="#strings_startsWith">`Strings::startsWith()`</a> | Determine if a given string starts with a given substring. |
+| <a href="#strings_endsWith">`Strings::endsWith()`</a> | Determine if a given string ends with a given substring. |
+| <a href="#strings_finish">`Strings::finish()`</a> | Cap a string with a single instance of a given value. |
 
 <hr>
 
@@ -389,6 +396,62 @@ Pad the left side of a string with another.
 $string = Strings::padLeft('SG-1 returns from an off-world mission', 50, '-');
 ```
 
+#### <a name="strings_replaceArray"></a> Method: `Strings::replaceArray()`
+
+Replace a given value in the string sequentially with an array.
+
+```php
+$string = Strings::replaceArray('SG-1 returns from an off-world mission', 'SG-1', ['SG-2']);
+```
+
+#### <a name="strings_replaceFirst"></a> Method: `Strings::replaceFirst()`
+
+Replace the first occurrence of a given value in the string.
+
+```php
+$string = Strings::replaceFirst('SG-1 returns from an off-world mission', 'SG-1', 'SG-2');
+```
+
+#### <a name="strings_replaceLast"></a> Method: `Strings::replaceLast()`
+
+Replace the last occurrence of a given value in the string.
+
+```php
+$string = Strings::replaceLast('SG-1 returns from an off-world mission', 'off-world', 'P9Y-3C3');
+```
+
+#### <a name="strings_start"></a> Method: `Strings::start()`
+
+Begin a string with a single instance of a given value.
+
+```php
+$string = Strings::start('movies/sg-1/season-5/episode-21/', '/');
+```
+
+#### <a name="strings_startsWith"></a> Method: `Strings::startsWith()`
+
+Determine if a given string starts with a given substring.
+
+```php
+$result = Strings::startsWith('/movies/sg-1/season-5/episode-21/', '/');
+```
+
+#### <a name="strings_endsWith"></a> Method: `Strings::endsWith()`
+
+Determine if a given string ends with a given substring.
+
+```php
+$result = Strings::endsWith('/movies/sg-1/season-5/episode-21/', '/');
+```
+
+#### <a name="strings_finish"></a> Method: `Strings::finish()`
+
+Cap a string with a single instance of a given value.
+
+```php
+$result = Strings::finish('/movies/sg-1/season-5/episode-21', '/');
+```
+
 ### License
 [The MIT License (MIT)](https://github.com/flextype-components/strings/blob/master/LICENSE.txt)
 Copyright (c) 2020 [Sergey Romanenko](https://github.com/Awilum)

src/Strings.php

@@ -6,6 +6,7 @@
 
 use function abs;
 use function array_reverse;
+use function array_shift;
 use function ctype_lower;
 use function explode;
 use function implode;
@@ -21,11 +22,18 @@
 use function mb_strwidth;
 use function mb_substr;
 use function preg_match;
+use function preg_quote;
 use function preg_replace;
 use function random_int;
 use function rtrim;
 use function str_pad;
 use function str_replace;
+use function strlen;
+use function strncmp;
+use function strpos;
+use function strrpos;
+use function substr;
+use function substr_replace;
 use function trim;
 use function ucwords;
 
@@ -528,4 +536,124 @@ public static function stripSpaces(string $string): string
     {
         return preg_replace('/\s+/', '', $string);
     }
+
+    /**
+     * Replace a given value in the string sequentially with an array.
+     *
+     * @param  string $string  String
+     * @param  string $search  Search
+     * @param  array  $replace Replace
+     */
+    public static function replaceArray(string $string, string $search, array $replace): string
+    {
+        $segments = explode($search, $string);
+
+        $result = array_shift($segments);
+
+        foreach ($segments as $segment) {
+            $result .= (array_shift($replace) ?? $search) . $segment;
+        }
+
+        return $result;
+    }
+
+  /**
+   * Replace the first occurrence of a given value in the string.
+   *
+   * @param  string $string  String
+   * @param  string $search  Search
+   * @param  string $replace Replace
+   */
+    public static function replaceFirst(string $string, string $search, string $replace): string
+    {
+        if ($search === '') {
+            return $string;
+        }
+
+        $position = strpos($string, $search);
+
+        if ($position !== false) {
+            return substr_replace($string, $replace, $position, strlen($search));
+        }
+
+        return $search;
+    }
+
+  /**
+   * Replace the last occurrence of a given value in the string.
+   *
+   * @param  string $string  String
+   * @param  string $search  Search
+   * @param  string $replace Replace
+   */
+    public static function replaceLast(string $string, string $search, string $replace): string
+    {
+        $position = strrpos($string, $search);
+
+        if ($position !== false) {
+            return substr_replace($string, $replace, $position, strlen($search));
+        }
+
+        return $subject;
+    }
+
+  /**
+   * Begin a string with a single instance of a given value.
+   *
+   * @param  string $string String
+   * @param  string $prefix Prefix
+   */
+    public static function start(string $string, string $prefix): string
+    {
+        $quoted = preg_quote($prefix, '/');
+
+        return $prefix . preg_replace('/^(?:' . $quoted . ')+/u', '', $string);
+    }
+
+      /**
+       * Determine if a given string starts with a given substring.
+       *
+       * @param  string          $haystack Haystack
+       * @param  string|string[] $needles  needles
+       */
+    public static function startsWith(string $haystack, $needles): bool
+    {
+        foreach ((array) $needles as $needle) {
+            if ((string) $needle !== '' && strncmp($haystack, $needle, strlen($needle)) === 0) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Determine if a given string ends with a given substring.
+     *
+     * @param  string          $haystack Haystack
+     * @param  string|string[] $needles  needles
+     */
+    public static function endsWith(string $haystack, $needles): bool
+    {
+        foreach ((array) $needles as $needle) {
+            if ($needle !== '' && substr($haystack, -strlen($needle)) === (string) $needle) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Cap a string with a single instance of a given value.
+     *
+     * @param  string $string String
+     * @param  string $cap    Cap
+     */
+    public static function finish(string $string, string $cap): string
+    {
+        $quoted = preg_quote($cap, '/');
+
+        return preg_replace('/(?:' . $quoted . ')+$/u', '', $string) . $cap;
+    }
 }