[10.x] introduce Str::substrPos (#48421)

* implement Str::substrPos helper method (fluent and static)

* apply ci fixes for Str::substrPos()

* additional tests for Str::substrPos()

* formatting

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: amacado

src/Illuminate/Support/Str.php

@@ -861,6 +861,20 @@ public static function password($length = 32, $letters = true, $numbers = true,
                 ->implode('');
     }
 
+    /**
+     * Find the multi-byte safe position of the first occurrence of a given substring in a string.
+     *
+     * @param  string  $haystack
+     * @param  string  $needle
+     * @param  int  $offset
+     * @param  string|null  $encoding
+     * @return int|false
+     */
+    public static function position($haystack, $needle, $offset = 0, $encoding = null)
+    {
+        return mb_strpos($haystack, (string) $needle, $offset, $encoding);
+    }
+
     /**
      * Generate a more truly "random" alpha-numeric string.
      *

src/Illuminate/Support/Stringable.php

@@ -575,6 +575,19 @@ public function pluralStudly($count = 2)
         return new static(Str::pluralStudly($this->value, $count));
     }
 
+    /**
+     * Find the multi-byte safe position of the first occurrence of the given substring.
+     *
+     * @param  string  $needle
+     * @param  int  $offset
+     * @param  string|null  $encoding
+     * @return int|false
+     */
+    public function position($needle, $offset = 0, $encoding = null)
+    {
+        return Str::position($this->value, $needle, $offset, $encoding);
+    }
+
     /**
      * Prepend the given values to the string.
      *

tests/Support/SupportStrTest.php

@@ -823,6 +823,23 @@ public function testSubstrCount()
         $this->assertSame(1, Str::substrCount('laravelPHPFramework', 'a', -10, -3));
     }
 
+    public function testPosition()
+    {
+        $this->assertSame(7, Str::position('Hello, World!', 'W'));
+        $this->assertSame(10, Str::position('This is a test string.', 'test'));
+        $this->assertSame(23, Str::position('This is a test string, test again.', 'test', 15));
+        $this->assertSame(0, Str::position('Hello, World!', 'Hello'));
+        $this->assertSame(7, Str::position('Hello, World!', 'World!'));
+        $this->assertSame(10, Str::position('This is a tEsT string.', 'tEsT', 0, 'UTF-8'));
+        $this->assertSame(7, Str::position('Hello, World!', 'W', -6));
+        $this->assertSame(18, Str::position('Äpfel, Birnen und Kirschen', 'Kirschen', -10, 'UTF-8'));
+        $this->assertSame(9, Str::position('@%€/=!"][$', '$', 0, 'UTF-8'));
+        $this->assertFalse(Str::position('Hello, World!', 'w', 0, 'UTF-8'));
+        $this->assertFalse(Str::position('Hello, World!', 'X', 0, 'UTF-8'));
+        $this->assertFalse(Str::position('', 'test'));
+        $this->assertFalse(Str::position('Hello, World!', 'X'));
+    }
+
     public function testSubstrReplace()
     {
         $this->assertSame('12:00', Str::substrReplace('1200', ':', 2, 0));

tests/Support/SupportStringableTest.php

@@ -1018,6 +1018,23 @@ public function testSubstrCount()
         $this->assertSame(1, $this->stringable('laravelPHPFramework')->substrCount('a', -10, -3));
     }
 
+    public function testSubstrPos()
+    {
+        $this->assertSame(7, $this->stringable('Hello, World!')->position('W'));
+        $this->assertSame(10, $this->stringable('This is a test string.')->position('test'));
+        $this->assertSame(23, $this->stringable('This is a test string, test again.')->position('test', 15));
+        $this->assertSame(0, $this->stringable('Hello, World!')->position('Hello'));
+        $this->assertSame(7, $this->stringable('Hello, World!')->position('World!'));
+        $this->assertSame(10, $this->stringable('This is a tEsT string.')->position('tEsT', 0, 'UTF-8'));
+        $this->assertSame(7, $this->stringable('Hello, World!')->position('W', -6));
+        $this->assertSame(18, $this->stringable('Äpfel, Birnen und Kirschen')->position('Kirschen', -10, 'UTF-8'));
+        $this->assertSame(9, $this->stringable('@%€/=!"][$')->position('$', 0, 'UTF-8'));
+        $this->assertFalse($this->stringable('Hello, World!')->position('w', 0, 'UTF-8'));
+        $this->assertFalse($this->stringable('Hello, World!')->position('X', 0, 'UTF-8'));
+        $this->assertFalse($this->stringable('')->position('test'));
+        $this->assertFalse($this->stringable('Hello, World!')->position('X'));
+    }
+
     public function testSubstrReplace()
     {
         $this->assertSame('12:00', (string) $this->stringable('1200')->substrReplace(':', 2, 0));