feat: str regex functions (#528)

Author: brendt

src/Tempest/Support/src/StringHelper.php

@@ -347,13 +347,27 @@ public function replace(string|array $search, string|array $replace): self
         return new self(str_replace($search, $replace, $this->string));
     }
 
+    public function replaceRegex(string|array $regex, string|array|callable $replace): self
+    {
+        if (is_callable($replace)) {
+            return new self(preg_replace_callback($regex, $replace, $this->string));
+        }
+
+        return new self(preg_replace($regex, $replace, $this->string));
+    }
+
     public function match(string $regex): array
     {
         preg_match($regex, $this->string, $matches);
 
         return $matches;
     }
 
+    public function matches(string $regex): bool
+    {
+        return ($this->match($regex)[0] ?? null) !== null;
+    }
+
     public function ld(mixed ...$ld): void
     {
         ld($this->string, ...$ld);

src/Tempest/Support/tests/StringHelperTest.php

@@ -267,4 +267,20 @@ public function test_match(): void
 
         $this->assertSame('10-', $match);
     }
+
+    public function test_matches(): void
+    {
+        $this->assertTrue(str('10-abc')->matches('/(?<id>\d+-)/'));
+        $this->assertTrue(str('10-abc')->matches('/(\d+-)/'));
+        $this->assertTrue(str('10-abc')->matches('/\d+-/'));
+        $this->assertFalse(str('10abc')->matches('/\d+-/'));
+        $this->assertFalse(str('abc')->matches('/\d+-/'));
+    }
+
+    public function test_replace_regex(): void
+    {
+        $this->assertTrue(str('10-abc')->replaceRegex('/(?<id>\d+-)/', '')->equals('abc'));
+        $this->assertTrue(str('10-abc')->replaceRegex('/(?<id>\d+-)/', fn () => '')->equals('abc'));
+        $this->assertTrue(str('10-abc')->replaceRegex(['/\d/', '/\w/'], ['#', 'X'])->equals('##-XXX'));
+    }
 }