Added Str::match() and Str::matchAll() methods

Resolves issue #37

src/Str.php

@@ -13,6 +13,7 @@ class Str implements \ArrayAccess, \JsonSerializable, \Serializable
         Traits\Encryptable,
         Traits\Hashable,
         Traits\Joinable,
+        Traits\Searchable,
         Traits\Segmentable,
         Traits\Transformable,
         Traits\Typeable;

src/Traits/Searchable.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace PHLAK\Twine\Traits;
+
+trait Searchable
+{
+    /**
+     * Return the first occurence of a matched pattern.
+     *
+     * @param string $pattern The patern to be matched
+     *
+     * @return self
+     */
+    public function match(string $pattern) : self
+    {
+        preg_match($pattern, $this->string, $matches);
+
+        return new static($matches[0]);
+    }
+
+    /**
+     * Return an array of occurences of a matched pattern.
+     *
+     * @param string $pattern The pattern to be matched
+     *
+     * @return array
+     */
+    public function matchAll(string $pattern) : array
+    {
+        preg_match_all($pattern, $this->string, $matches);
+
+        return array_map(function ($match) {
+            return new static($match);
+        }, $matches[0]);
+    }
+}

tests/Methods/MatchAllTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace PHLAK\Twine\Tests\Methods;
+
+use PHLAK\Twine;
+use PHPUnit\Framework\TestCase;
+
+class MatchAllTest extends TestCase
+{
+    public function test_it_can_find_all_matches_within()
+    {
+        $string = new Twine\Str(
+            'You can reach me on my cell at 123-456-7890 or at work 987-654-3210'
+        );
+
+        $matches = $string->matchAll('/(?:\d{3}-?)\d{3}-?\d{4}/');
+
+        $this->assertEquals(['123-456-7890', '987-654-3210'], $matches);
+        foreach ($matches as $match) {
+            $this->assertInstanceOf(Twine\Str::class, $match);
+        }
+    }
+
+    public function test_it_is_multibyte_compatible()
+    {
+        $string = new Twine\Str(
+            '123-456-7890または職場987-654-3210の私の携帯で連絡できます'
+        );
+
+        $matches = $string->matchAll('/(?:\d{3}-?)\d{3}-?\d{4}/');
+
+        $this->assertEquals(['123-456-7890', '987-654-3210'], $matches);
+        foreach ($matches as $match) {
+            $this->assertInstanceOf(Twine\Str::class, $match);
+        }
+    }
+}

tests/Methods/MatchTest.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace PHLAK\Twine\Tests\Methods;
+
+use PHLAK\Twine;
+use PHPUnit\Framework\TestCase;
+
+class MatchTest extends TestCase
+{
+    public function test_it_can_find_a_match_within()
+    {
+        $string = new Twine\Str(
+            'You can reach me on my cell at 123-456-7890 or at work 987-654-3210'
+        );
+
+        $match = $string->match('/(?:\d{3}-?)\d{3}-?\d{4}/');
+
+        $this->assertInstanceOf(Twine\Str::class, $match);
+        $this->assertEquals('123-456-7890', $match);
+    }
+
+    public function test_it_is_multibyte_compatible()
+    {
+        $string = new Twine\Str(
+            '123-456-7890または職場987-654-3210の私の携帯で連絡できます'
+        );
+
+        $match = $string->match('/(?:\d{3}-?)\d{3}-?\d{4}/');
+
+        $this->assertInstanceOf(Twine\Str::class, $match);
+        $this->assertEquals('123-456-7890', $match);
+    }
+}