Implement formatters for common units

Includes formatters that perform unit promotion. We DO NOT do
unit conversion (for example, inches to centimeters), we only
choose within the appropriate system (metric or imperial) the
best representation for a given value.

For example, saying `10cm` is much better than saying `0.1m`.
Both are still within the metric system.

Considerations made during this change:

 - We only use unit symbols, not the full names. This simplifies
   aspects such as translations, since most units are universal
   but their localized full names are not. There is some space
   for later accepting full names (new MetricFormatter('meter'))
   and deciding the output representation automatically. This is
   also the reason why PHP enums were not used as the source of
   truth for supported units.
 - Time unit symbols are *not universal*, but they were considered
   for inclusion for their value in technical systems (simplifying
   a log entry or measure).
 - The SI (colloquially known as "metric system") is the widest
   adopted standard, so only "Imperial" was prefixed. We used the
   "Metric" name to denote SI Length units.

Author: alganet

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 = 'ft²')`
+
+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 = 'in')`
+
+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 = 'lb')`
+
+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,46 @@
+````markdown
+<!--
+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 = 'g')`
+
+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,63 @@
+````markdown
+<!--
+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 = 'm')`
+
+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 = 's')`
+
+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');
+        }
+    }
+}