feat(str): add swap() method

Author: oniice

docs/methods.md

@@ -752,6 +752,21 @@ echo $str->surround('!!!');
 // !!!Foo Bar!!!
 ```
 
+### swap `Utility`
+Swap multiple keywords in the string using a key/value map
+
+```php
+$str = new Utility('foo bar')
+
+echo $str->swap(['foo' => 'bar', 'bar' => 'foo']);
+// bar foo
+
+$str = new Utility('a-b-c')
+
+echo $str->swap(['a' => '1', 'b' => '2', 'c' => '3']);
+// 1-2-3
+```
+
 ### toAlphanumeric `Utility`
 Convert the string to only contain alphanumeric values
 

src/Utility.php

@@ -835,6 +835,20 @@ public function surround(string|Stringable|Utility $with): Utility
         return static::make(implode('', [$utility, $this->string, $utility]), $this->encoding);
     }
 
+    /**
+     * Swap multiple keywords in the string using a key/value map
+     *
+     * @param array<string, string> $map
+     */
+    public function swap(array $map): Utility
+    {
+        if ($map === []) {
+            return static::make($this->string, $this->encoding);
+        }
+
+        return static::make(strtr($this->string, $map), $this->encoding);
+    }
+
     /**
      * Sanitize a string to only contain letters
      */

tests/SwapTest.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use Iterator;
+
+final class SwapTest extends BaseStringSuite
+{
+    public static function __validData(): Iterator
+    {
+        yield ['bar foo', 'foo bar', ['foo' => 'bar', 'bar' => 'foo']];
+        yield ['Hello World', 'Hello World', []];
+        yield ['Hello World', 'Hi World', ['Hi' => 'Hello']];
+        yield ['abc', 'xyz', ['x' => 'a', 'y' => 'b', 'z' => 'c']];
+        yield ['', '', ['foo' => 'bar']];
+        yield ['Hello World', 'Hello World', ['xyz' => 'abc']];
+        yield ['foobär', 'foobaz', ['baz' => 'bär']];
+        yield ['1-2-3', 'a-b-c', ['a' => '1', 'b' => '2', 'c' => '3']];
+        yield ['HELLO world', 'hello WORLD', ['hello' => 'HELLO', 'WORLD' => 'world']];
+        yield ['foo foo', 'bar bar', ['bar' => 'foo']];
+    }
+
+    #[DataProvider('__validData')]
+    public function testSwapMethod(string $expected, string $string, array $map): void
+    {
+        $this->assertSame($expected, $this->utility($string)->swap($map)->value());
+    }
+}