Skip to content

Commit 65f8e47

Browse files
henriquemoodyhenriquemoody
committed
Add TrimFormatter for configurable string edge trimming
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)
1 parent 801a389 commit 65f8e47

File tree

6 files changed

+513
-8
lines changed

6 files changed

+513
-8
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ echo f::create()
5151
| [PatternFormatter](docs/PatternFormatter.md) | Pattern-based string filtering with placeholders |
5252
| [PlaceholderFormatter](docs/PlaceholderFormatter.md) | Template interpolation with placeholder replacement |
5353
| [TimeFormatter](docs/TimeFormatter.md) | Time promotion (mil, c, dec, y, mo, w, d, h, min, s, ms, us, ns) |
54+
| [TrimFormatter](docs/TrimFormatter.md) | Remove whitespace from string edges |
5455

5556
## Contributing
5657

‎docs/TrimFormatter.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
<!--
2+
SPDX-FileCopyrightText: (c) Respect Project Contributors
3+
SPDX-License-Identifier: ISC
4+
SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
5+
-->
6+
7+
# TrimFormatter
8+
9+
The `TrimFormatter` removes characters from the edges of strings with configurable masking and side selection, fully supporting UTF-8 Unicode characters.
10+
11+
## Usage
12+
13+
### Basic Usage
14+
15+
```php
16+
use Respect\StringFormatter\TrimFormatter;
17+
18+
$formatter = new TrimFormatter();
19+
20+
echo $formatter->format(' hello world ');
21+
// Outputs: "hello world"
22+
```
23+
24+
### Trim Specific Side
25+
26+
```php
27+
use Respect\StringFormatter\TrimFormatter;
28+
29+
$formatter = new TrimFormatter('left');
30+
31+
echo $formatter->format(' hello ');
32+
// Outputs: "hello "
33+
34+
$formatterRight = new TrimFormatter('right');
35+
36+
echo $formatterRight->format(' hello ');
37+
// Outputs: " hello"
38+
```
39+
40+
### Custom Mask
41+
42+
```php
43+
use Respect\StringFormatter\TrimFormatter;
44+
45+
$formatter = new TrimFormatter('both', '-._');
46+
47+
echo $formatter->format('---hello---');
48+
// Outputs: "hello"
49+
50+
echo $formatter->format('._hello_._');
51+
// Outputs: "hello"
52+
```
53+
54+
### Unicode Characters
55+
56+
```php
57+
use Respect\StringFormatter\TrimFormatter;
58+
59+
// CJK full-width spaces are trimmed by default
60+
$formatter = new TrimFormatter();
61+
62+
echo $formatter->format('　hello世界　');
63+
// Outputs: "hello世界"
64+
65+
// Trim emoji with custom mask
66+
$formatterEmoji = new TrimFormatter('both', '😊');
67+
68+
echo $formatterEmoji->format('😊hello😊');
69+
// Outputs: "hello"
70+
```
71+
72+
## API
73+
74+
### `TrimFormatter::__construct`
75+
76+
- `__construct(string $side = "both", string|null $mask = null)`
77+
78+
Creates a new trim formatter instance.
79+
80+
**Parameters:**
81+
82+
- `$side`: Which side(s) to trim: "left", "right", or "both" (default: "both")
83+
- `$mask`: The characters to trim from the string edges, or `null` for default Unicode whitespace (default: `null`)
84+
85+
**Throws:** `InvalidFormatterException` when `$side` is not "left", "right", or "both"
86+
87+
### `format`
88+
89+
- `format(string $input): string`
90+
91+
Removes characters from the specified side(s) of the input string.
92+
93+
**Parameters:**
94+
95+
- `$input`: The string to trim
96+
97+
**Returns:** The trimmed string
98+
99+
## Examples
100+
101+
| Side | Mask | Input | Output | Description |
102+
| --------- | -------------- | --------------- | ------------ | ----------------------------------- |
103+
| `"both"` | `null` | `" hello "` | `"hello"` | Trim default whitespace both sides |
104+
| `"left"` | `null` | `" hello "` | `"hello "` | Trim default whitespace left only |
105+
| `"right"` | `null` | `" hello "` | `" hello"` | Trim default whitespace right only |
106+
| `"both"` | `"-"` | `"---hello---"` | `"hello"` | Trim hyphens from both sides |
107+
| `"both"` | `"-._"` | `"-._hello_.-"` | `"hello"` | Trim multiple custom characters |
108+
| `"left"` | `":"` | `":::hello:::"` | `"hello:::"` | Trim colons from left only |
109+
| `"both"` | `null` | `"　hello"` | `"hello"` | CJK space trimmed by default |
110+
| `"both"` | `"😊"` | `"😊hello😊"` | `"hello"` | Trim emoji with custom mask |
111+
112+
## Notes
113+
114+
- Uses PHP's `mb_trim`, `mb_ltrim`, and `mb_rtrim` functions for multibyte-safe trimming
115+
- Fully UTF-8 aware - handles all Unicode scripts including CJK, emoji, and complex characters
116+
- Empty strings return empty strings
117+
- If the mask is empty or contains no characters present in the input, the string is returned unchanged
118+
- Trimming operations are character-oriented, not byte-oriented
119+
120+
### Default Mask
121+
122+
When no mask is provided (`null`), the formatter uses `mb_trim`'s default which includes all Unicode whitespace characters:
123+
124+
**ASCII whitespace:**
125+
- ` ` (U+0020): Ordinary space
126+
- `\t` (U+0009): Tab
127+
- `\n` (U+000A): New line (line feed)
128+
- `\r` (U+000D): Carriage return
129+
- `\0` (U+0000): NUL-byte
130+
- `\v` (U+000B): Vertical tab
131+
- `\f` (U+000C): Form feed
132+
133+
**Unicode whitespace:**
134+
- U+00A0: No-break space
135+
- U+1680: Ogham space mark
136+
- U+2000–U+200A: Various width spaces (en quad, em quad, en space, em space, etc.)
137+
- U+2028: Line separator
138+
- U+2029: Paragraph separator
139+
- U+202F: Narrow no-break space
140+
- U+205F: Medium mathematical space
141+
- U+3000: Ideographic space (CJK full-width space)
142+
- U+0085: Next line (NEL)
143+
- U+180E: Mongolian vowel separator
144+
145+
See [mb_trim documentation](https://www.php.net/manual/en/function.mb-trim.php) for the complete list.

‎src/Mixin/Builder.php‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,30 +18,33 @@ interface Builder
1818
{
1919
public function area(string $unit): FormatterBuilder;
2020

21+
public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
22+
2123
public function imperialArea(string $unit): FormatterBuilder;
2224

2325
public function imperialLength(string $unit): FormatterBuilder;
2426

2527
public function imperialMass(string $unit): FormatterBuilder;
2628

27-
public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
28-
2929
public function mask(string $range, string $replacement = '*'): FormatterBuilder;
3030

3131
public function metric(string $unit): FormatterBuilder;
3232

33+
public function metricMass(string $unit): FormatterBuilder;
34+
3335
public function number(
3436
int $decimals = 0,
3537
string $decimalSeparator = '.',
3638
string $thousandsSeparator = ',',
3739
): FormatterBuilder;
3840

39-
public function metricMass(string $unit): FormatterBuilder;
40-
4141
public function pattern(string $pattern): FormatterBuilder;
4242

4343
/** @param array<string, mixed> $parameters */
4444
public function placeholder(array $parameters): FormatterBuilder;
4545

4646
public function time(string $unit): FormatterBuilder;
47+
48+
/** @param 'both'|'left'|'right' $side */
49+
public function trim(string $side = 'both', string $mask = " \t\n\r\0\x0B"): FormatterBuilder;
4750
}

‎src/Mixin/Chain.php‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,30 +18,33 @@ interface Chain extends Formatter
1818
{
1919
public function area(string $unit): FormatterBuilder;
2020

21+
public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
22+
2123
public function imperialArea(string $unit): FormatterBuilder;
2224

2325
public function imperialLength(string $unit): FormatterBuilder;
2426

2527
public function imperialMass(string $unit): FormatterBuilder;
2628

27-
public function date(string $format = 'Y-m-d H:i:s'): FormatterBuilder;
28-
2929
public function mask(string $range, string $replacement = '*'): FormatterBuilder;
3030

3131
public function metric(string $unit): FormatterBuilder;
3232

33+
public function metricMass(string $unit): FormatterBuilder;
34+
3335
public function number(
3436
int $decimals = 0,
3537
string $decimalSeparator = '.',
3638
string $thousandsSeparator = ',',
3739
): FormatterBuilder;
3840

39-
public function metricMass(string $unit): FormatterBuilder;
40-
4141
public function pattern(string $pattern): FormatterBuilder;
4242

4343
/** @param array<string, mixed> $parameters */
4444
public function placeholder(array $parameters): FormatterBuilder;
4545

4646
public function time(string $unit): FormatterBuilder;
47+
48+
/** @param 'both'|'left'|'right' $side */
49+
public function trim(string $side = 'both', string $mask = " \t\n\r\0\x0B"): FormatterBuilder;
4750
}

‎src/TrimFormatter.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?php
2+
3+
/*
4+
* SPDX-FileCopyrightText: (c) Respect Project Contributors
5+
* SPDX-License-Identifier: ISC
6+
* SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
7+
*/
8+
9+
declare(strict_types=1);
10+
11+
namespace Respect\StringFormatter;
12+
13+
use function in_array;
14+
use function mb_ltrim;
15+
use function mb_rtrim;
16+
use function mb_trim;
17+
use function sprintf;
18+
19+
/**
20+
* Trims characters from strings using multibyte-safe functions.
21+
*
22+
* When no mask is provided, trims all Unicode whitespace characters including:
23+
* regular space, tab, newline, carriage return, vertical tab, form feed,
24+
* no-break space (U+00A0), em space (U+2003), ideographic space (U+3000), and others.
25+
*
26+
* @see https://www.php.net/manual/en/function.mb-trim.php
27+
*/
28+
final readonly class TrimFormatter implements Formatter
29+
{
30+
/**
31+
* @param 'both'|'left'|'right' $side Which side(s) to trim
32+
* @param string|null $mask Characters to trim, or null for default Unicode whitespace
33+
*/
34+
public function __construct(
35+
private string $side = 'both',
36+
private string|null $mask = null,
37+
) {
38+
if (!in_array($this->side, ['left', 'right', 'both'], true)) {
39+
throw new InvalidFormatterException(
40+
sprintf('Invalid side "%s". Must be "left", "right", or "both".', $this->side),
41+
);
42+
}
43+
}
44+
45+
public function format(string $input): string
46+
{
47+
return match ($this->side) {
48+
'left' => mb_ltrim($input, $this->mask),
49+
'right' => mb_rtrim($input, $this->mask),
50+
default => mb_trim($input, $this->mask),
51+
};
52+
}
53+
}

0 commit comments

Comments
 (0)