Add TrimFormatter for configurable string edge trimming

henriquemoody · henriquemoody · commit 4d383f4e414b · 2026-02-06T22:19:50.000+01:00
Allows precise control over trimming operations with support for left,
right, or both sides and custom character masks, using UTF-8-aware
regex operations for proper international text handling.

The formatter automatically escapes special regex characters in the
custom mask and handles complex multi-byte characters including CJK
spaces, emoji, and combining diacritics which are essential for
global applications.

Includes comprehensive tests covering all trim modes, custom masks,
Unicode characters (CJK, emoji), special characters, multi-byte
strings, and edge cases like empty strings and strings shorter than
the mask.

Assisted-by: OpenCode (GLM-4.7)
diff --git a/README.md b/README.md
@@ -51,6 +51,7 @@ echo f::create()
 | [PatternFormatter](docs/PatternFormatter.md)               | Pattern-based string filtering with placeholders                 |
 | [PlaceholderFormatter](docs/PlaceholderFormatter.md)       | Template interpolation with placeholder replacement              |
 | [TimeFormatter](docs/TimeFormatter.md)                     | Time promotion (mil, c, dec, y, mo, w, d, h, min, s, ms, us, ns) |
+| [TrimFormatter](docs/TrimFormatter.md)                     | Remove whitespace from string edges                              |
 
 ## Contributing
 
diff --git a/docs/TrimFormatter.md b/docs/TrimFormatter.md
@@ -0,0 +1,130 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+-->
+
+# TrimFormatter
+
+The `TrimFormatter` removes characters from the edges of strings with configurable masking and side selection, fully supporting UTF-8 Unicode characters.
+
+## Usage
+
+### Basic Usage
+
+```php
+use Respect\StringFormatter\TrimFormatter;
+
+$formatter = new TrimFormatter();
+
+echo $formatter->format('  hello world  ');
+// Outputs: "hello world"
+```
+
+### Trim Specific Side
+
+```php
+use Respect\StringFormatter\TrimFormatter;
+
+$formatter = new TrimFormatter(' ', 'left');
+
+echo $formatter->format('  hello  ');
+// Outputs: "hello  "
+
+$formatterRight = new TrimFormatter(' ', 'right');
+
+echo $formatterRight->format('  hello  ');
+// Outputs: "  hello"
+```
+
+### Custom Mask
+
+```php
+use Respect\StringFormatter\TrimFormatter;
+
+$formatter = new TrimFormatter('-._');
+
+echo $formatter->format('---hello---');
+// Outputs: "hello"
+
+echo $formatter->format('._hello_._');
+// Outputs: "hello"
+```
+
+### Unicode Characters
+
+```php
+use Respect\StringFormatter\TrimFormatter;
+
+// Trim CJK full-width spaces
+$formatter = new TrimFormatter('　');
+
+echo $formatter->format('　hello世界　');
+// Outputs: "hello世界"
+
+// Trim emoji
+$formatterEmoji = new TrimFormatter('😊');
+
+echo $formatterEmoji->format('😊hello😊');
+// Outputs: "hello"
+```
+
+## API
+
+### `TrimFormatter::__construct`
+
+- `__construct(string $mask = " \t\n\r\0\x0B", string $side = "both")`
+
+Creates a new trim formatter instance.
+
+**Parameters:**
+
+- `$mask`: The characters to trim from the string edges (default: whitespace characters)
+- `$side`: Which side(s) to trim: "left", "right", or "both" (default: "both")
+
+**Throws:** `InvalidFormatterException` when `$side` is not "left", "right", or "both"
+
+### `format`
+
+- `format(string $input): string`
+
+Removes characters from the specified side(s) of the input string.
+
+**Parameters:**
+
+- `$input`: The string to trim
+
+**Returns:** The trimmed string
+
+## Examples
+
+| Configuration      | Input           | Output       | Description                     |
+| ------------------ | --------------- | ------------ | ------------------------------- |
+| default            | `"  hello  "`   | `"hello"`    | Trim spaces from both sides     |
+| `"left"`           | `"  hello  "`   | `"hello  "`  | Trim spaces from left only      |
+| `"right"`          | `"  hello  "`   | `"  hello"`  | Trim spaces from right only     |
+| `"-"`              | `"---hello---"` | `"hello"`    | Trim hyphens from both sides    |
+| `"-._"`            | `"-._hello_.-"` | `"hello"`    | Trim multiple custom characters |
+| `":"` (`"left"`)   | `":::hello:::"` | `"hello:::"` | Trim colons from left only      |
+| `"　"` (CJK space) | `"　hello"`     | `"hello"`    | Trim CJK full-width space       |
+| `"😊"`             | `"😊hello😊"`   | `"hello"`    | Trim emoji                      |
+
+## Notes
+
+- Fully UTF-8 aware - handles all Unicode scripts including CJK, emoji, and complex characters
+- Special regex characters in the mask (e.g., `.`, `*`, `?`, `+`) are automatically escaped
+- Empty strings return empty strings
+- If the mask is empty or contains no characters present in the input, the string is returned unchanged
+- Trimming operations are character-oriented, not byte-oriented
+- Combining characters are handled correctly (trimming considers the full character sequence)
+
+### Default Mask
+
+The default mask includes standard whitespace characters:
+
+- ` `: ASCII SP character 0x20, an ordinary space.
+- `\t`: ASCII HT character 0x09, a tab.
+- `\n`: ASCII LF character 0x0A, a new line (line feed).
+- `\r`: ASCII CR character 0x0D, a carriage return.
+- `\0`: ASCII NUL character 0x00, the NUL-byte.
+- `\v`: ASCII VT character 0x0B, a vertical tab.
diff --git a/src/Mixin/Builder.php b/src/Mixin/Builder.php
@@ -18,30 +18,33 @@ interface Builder
 {
     public function area(string $unit): FormatterBuilder;
 
+    public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
+
     public function imperialArea(string $unit): FormatterBuilder;
 
     public function imperialLength(string $unit): FormatterBuilder;
 
     public function imperialMass(string $unit): FormatterBuilder;
 
-    public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
-
     public function mask(string $range, string $replacement = '*'): FormatterBuilder;
 
     public function metric(string $unit): FormatterBuilder;
 
+    public function metricMass(string $unit): FormatterBuilder;
+
     public function number(
         int $decimals = 0,
         string $decimalSeparator = '.',
         string $thousandsSeparator = ',',
     ): FormatterBuilder;
 
-    public function metricMass(string $unit): FormatterBuilder;
-
     public function pattern(string $pattern): FormatterBuilder;
 
     /** @param array<string, mixed> $parameters */
     public function placeholder(array $parameters): FormatterBuilder;
 
     public function time(string $unit): FormatterBuilder;
+
+    /** @param 'both'|'left'|'right' $side */
+    public function trim(string $side = 'both', string $mask = " \t\n\r\0\x0B"): FormatterBuilder;
 }
diff --git a/src/Mixin/Chain.php b/src/Mixin/Chain.php
@@ -18,30 +18,33 @@ interface Chain extends Formatter
 {
     public function area(string $unit): FormatterBuilder;
 
+    public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
+
     public function imperialArea(string $unit): FormatterBuilder;
 
     public function imperialLength(string $unit): FormatterBuilder;
 
     public function imperialMass(string $unit): FormatterBuilder;
 
-    public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
-
     public function mask(string $range, string $replacement = '*'): FormatterBuilder;
 
     public function metric(string $unit): FormatterBuilder;
 
+    public function metricMass(string $unit): FormatterBuilder;
+
     public function number(
         int $decimals = 0,
         string $decimalSeparator = '.',
         string $thousandsSeparator = ',',
     ): FormatterBuilder;
 
-    public function metricMass(string $unit): FormatterBuilder;
-
     public function pattern(string $pattern): FormatterBuilder;
 
     /** @param array<string, mixed> $parameters */
     public function placeholder(array $parameters): FormatterBuilder;
 
     public function time(string $unit): FormatterBuilder;
+
+    /** @param 'both'|'left'|'right' $side */
+    public function trim(string $side = 'both', string $mask = " \t\n\r\0\x0B"): FormatterBuilder;
 }
diff --git a/src/TrimFormatter.php b/src/TrimFormatter.php
@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter;
+
+use function in_array;
+use function preg_quote;
+use function preg_replace;
+use function sprintf;
+
+final readonly class TrimFormatter implements Formatter
+{
+    /** @param 'both'|'left'|'right' $side */
+    public function __construct(
+        private string $side = 'both',
+        private string $mask = " \t\n\r\0\x0B",
+    ) {
+        if (!in_array($this->side, ['left', 'right', 'both'], true)) {
+            throw new InvalidFormatterException(
+                sprintf('Invalid side "%s". Must be "left", "right", or "both".', $this->side),
+            );
+        }
+    }
+
+    public function format(string $input): string
+    {
+        $pattern = preg_quote($this->mask, '/');
+
+        // phpcs:disable Squiz.Strings.DoubleQuoteUsage.ContainsVar
+        return match ($this->side) {
+            'left' => preg_replace("/^[{$pattern}]+/u", '', $input) ?? $input,
+            'right' => preg_replace("/[{$pattern}]+$/u", '', $input) ?? $input,
+            default => preg_replace("/^[{$pattern}]+|[{$pattern}]+$/u", '', $input) ?? $input,
+        };
+    }
+}
diff --git a/tests/Unit/TrimFormatterTest.php b/tests/Unit/TrimFormatterTest.php
