Implement formatters for common units

README.md

@@ -37,13 +37,19 @@ echo f::create()
 
 ## Formatters
 
-| Formatter                                            | Description                                         |
-| ---------------------------------------------------- | --------------------------------------------------- |
-| [DateFormatter](docs/DateFormatter.md)               | Date and time formatting with flexible parsing      |
-| [MaskFormatter](docs/MaskFormatter.md)               | Range-based string masking with Unicode support     |
-| [NumberFormatter](docs/NumberFormatter.md)           | Number formatting with thousands and decimal separators |
-| [PatternFormatter](docs/PatternFormatter.md)         | Pattern-based string filtering with placeholders    |
-| [PlaceholderFormatter](docs/PlaceholderFormatter.md) | Template interpolation with placeholder replacement |
+| Formatter                                                  | Description                                                      |
+| ---------------------------------------------------------- | ---------------------------------------------------------------- |
+| [DateFormatter](docs/DateFormatter.md)                     | Date and time formatting with flexible parsing                   |
+| [ImperialAreaFormatter](docs/ImperialAreaFormatter.md)     | Imperial area promotion (in², ft², yd², ac, mi²)                 |
+| [ImperialLengthFormatter](docs/ImperialLengthFormatter.md) | Imperial length promotion (in, ft, yd, mi)                       |
+| [ImperialMassFormatter](docs/ImperialMassFormatter.md)     | Imperial mass promotion (oz, lb, st, ton)                        |
+| [MaskFormatter](docs/MaskFormatter.md)                     | Range-based string masking with Unicode support                  |
+| [MassFormatter](docs/MassFormatter.md)                     | Metric mass promotion (mg, g, kg, t)                             |
+| [MetricFormatter](docs/MetricFormatter.md)                 | Metric length promotion (mm, cm, m, km)                          |
+| [NumberFormatter](docs/NumberFormatter.md)                 | Number formatting with thousands and decimal separators          |
+| [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) |
 
 ## Contributing
 

docs/ImperialAreaFormatter.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# ImperialAreaFormatter
+
+The `ImperialAreaFormatter` promotes imperial area values between `in²`, `ft²`, `yd²`, `ac`, and `mi²`.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1ft²`, `2ac`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\ImperialAreaFormatter;
+
+$formatter = new ImperialAreaFormatter('ft²');
+
+echo $formatter->format('43560');
+// Outputs: 1ac
+```
+
+## API
+
+### `ImperialAreaFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted units: `in²`, `ft²`, `yd²`, `ac`, `mi²`.

docs/ImperialLengthFormatter.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# ImperialLengthFormatter
+
+The `ImperialLengthFormatter` promotes imperial length values between `in`, `ft`, `yd`, and `mi`.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1ft`, `2yd`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\ImperialLengthFormatter;
+
+$formatter = new ImperialLengthFormatter('in');
+
+echo $formatter->format('12');
+// Outputs: 1ft
+```
+
+## API
+
+### `ImperialLengthFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted units: `in`, `ft`, `yd`, `mi`.

docs/ImperialMassFormatter.md

@@ -0,0 +1,38 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# ImperialMassFormatter
+
+The `ImperialMassFormatter` promotes imperial mass values between `oz`, `lb`, `st`, and `ton`.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1lb`, `8oz`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\ImperialMassFormatter;
+
+$formatter = new ImperialMassFormatter('oz');
+
+echo $formatter->format('16');
+// Outputs: 1lb
+```
+
+## API
+
+### `ImperialMassFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted units: `oz`, `lb`, `st`, `ton`.
+
+## Notes
+
+- `ton` represents the imperial long ton (`2240lb`).

docs/MassFormatter.md

@@ -0,0 +1,43 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# MassFormatter
+
+The `MassFormatter` promotes metric *mass* values between `mg`, `g`, `kg`, and `t`.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1kg`, `500mg`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\MassFormatter;
+
+$formatter = new MassFormatter('g');
+
+echo $formatter->format('1000');
+// Outputs: 1kg
+
+echo $formatter->format('0.001');
+// Outputs: 1mg
+```
+
+## API
+
+### `MassFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted units: `mg`, `g`, `kg`, `t`.
+
+### `format`
+
+- `format(string $input): string`
+
+If the input is numeric, it is promoted to the closest appropriate metric scale and returned with the corresponding symbol.

docs/MetricFormatter.md

@@ -0,0 +1,60 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# MetricFormatter
+
+The `MetricFormatter` promotes metric *length* values between `mm`, `cm`, `m`, and `km`.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1km`, `10cm`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\MetricFormatter;
+
+$formatter = new MetricFormatter('m');
+
+echo $formatter->format('1000');
+// Outputs: 1km
+
+echo $formatter->format('0.1');
+// Outputs: 10cm
+```
+
+## API
+
+### `MetricFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted units: `mm`, `cm`, `m`, `km`.
+
+### `format`
+
+- `format(string $input): string`
+
+If the input is numeric, it is promoted to the closest appropriate metric scale and returned with the corresponding symbol.
+
+## Behavior
+
+### Promotion rule
+
+The formatter chooses a unit where the promoted value is in the range $[1, 1000)$ when possible. If not possible, it uses the smallest (`mm`) or largest (`km`) unit as needed.
+
+### No rounding
+
+Values are not rounded. Trailing fractional zeros are trimmed:
+
+```php
+$formatter = new MetricFormatter('m');
+
+echo $formatter->format('1.23000');
+// Outputs: 1.23m
+```

docs/TimeFormatter.md

@@ -0,0 +1,46 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# TimeFormatter
+
+The `TimeFormatter` promotes time values between multiple units.
+
+- Non-numeric input is returned unchanged.
+- Promotion is based on magnitude.
+- Output uses symbols only (no spaces), e.g. `1h`, `500ms`.
+
+## Usage
+
+```php
+use Respect\StringFormatter\TimeFormatter;
+
+$formatter = new TimeFormatter('s');
+
+echo $formatter->format('60');
+// Outputs: 1min
+
+echo $formatter->format('0.001');
+// Outputs: 1ms
+```
+
+## API
+
+### `TimeFormatter::__construct`
+
+- `__construct(string $unit)`
+
+The `$unit` is the input unit (the unit you are providing values in).
+
+Accepted symbols:
+
+- `ns`, `us`, `ms`, `s`, `min`, `h`, `d`, `w`, `mo`, `y`, `dec`, `c`, `mil`
+
+## Notes
+
+- `y` uses a fixed year of 365 days.
+- `mo` uses 1/12 of a fixed year (approx. 30.41 days).
+- `w` uses 7 days.
+- `dec`, `c`, and `mil` are based on that fixed year.

src/ImperialAreaFormatter.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter;
+
+use Respect\StringFormatter\Internal\UnitPromoter;
+
+final readonly class ImperialAreaFormatter implements Formatter
+{
+    use UnitPromoter;
+
+    private const array UNIT_RATIOS = [
+        'mi²' => [4_014_489_600, 1],
+        'ac' => [6_272_640, 1],
+        'yd²' => [1_296, 1],
+        'ft²' => [144, 1],
+        'in²' => [1, 1],
+    ];
+
+    public function __construct(private string $unit)
+    {
+        if (!isset(self::UNIT_RATIOS[$unit])) {
+            throw new InvalidFormatterException('Unsupported imperial area unit');
+        }
+    }
+}

src/ImperialLengthFormatter.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter;
+
+use Respect\StringFormatter\Internal\UnitPromoter;
+
+final readonly class ImperialLengthFormatter implements Formatter
+{
+    use UnitPromoter;
+
+    private const array UNIT_RATIOS = [
+        'mi' => [63_360, 1],
+        'yd' => [36, 1],
+        'ft' => [12, 1],
+        'in' => [1, 1],
+    ];
+
+    public function __construct(private string $unit)
+    {
+        if (!isset(self::UNIT_RATIOS[$unit])) {
+            throw new InvalidFormatterException('Unsupported imperial length unit');
+        }
+    }
+}

src/ImperialMassFormatter.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter;
+
+use Respect\StringFormatter\Internal\UnitPromoter;
+
+final readonly class ImperialMassFormatter implements Formatter
+{
+    use UnitPromoter;
+
+    private const array UNIT_RATIOS = [
+        'ton' => [35_840, 1],
+        'st' => [224, 1],
+        'lb' => [16, 1],
+        'oz' => [1, 1],
+    ];
+
+    public function __construct(private string $unit)
+    {
+        if (!isset(self::UNIT_RATIOS[$unit])) {
+            throw new InvalidFormatterException('Unsupported imperial mass unit');
+        }
+    }
+}