Add StringDecimal type with tryFromString, alias, and unit tests

- Introduced `StringDecimal` class for representing validated MariaDB DECIMAL values as strings.
- Added `fromString` and `tryFromString` methods, returning `Undefined` for invalid inputs.
- Included `DecimalStringTypeException` to handle malformed or non-representable values.
- Implemented strict `toFloat` method for exact round-trip float conversions with error handling.
- Updated `Usage` examples to demonstrate `StringDecimal` usage, `toFloat` limitations, and `tryFromString` behavior.
- Added comprehensive unit tests to validate creation, exception handling, and `Undefined` behavior for invalid input.

Author: georgedeploy

src/Exception/DecimalStringTypeException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Exception;
+
+class DecimalStringTypeException extends TypeException
+{
+}

src/String/MariaDb/StringDecimal.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String\MariaDb;
+
+use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\DecimalStringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function preg_match;
+use function sprintf;
+
+/**
+ * MariaDB DECIMAL value represented as a string.
+ *
+ * Example "123", "-5", "3.14"
+ *
+ * Note: Use toFloat() only when the decimal can be represented exactly by PHP float.
+ *       The method verifies exact round-trip: (string)(float)$src must equal the original string.
+ *
+ * @psalm-immutable
+ */
+readonly class StringDecimal extends StrType
+{
+    protected string $value;
+
+    /**
+     * @throws DecimalStringTypeException
+     */
+    public function __construct(string $value)
+    {
+        self::assertDecimalString($value);
+        $this->value = $value;
+    }
+
+    /**
+     * @throws DecimalStringTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        return new static($value);
+    }
+
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public function value(): string
+    {
+        return $this->value;
+    }
+
+    /**
+     * Convert to float only if the string representation matches exactly string-casted float.
+     *
+     * @throws DecimalStringTypeException
+     */
+    public function toFloat(): float
+    {
+        $src = $this->value;
+        $casted = (string) ((float) $src);
+        if ($src !== $casted) {
+            throw new DecimalStringTypeException(sprintf('Unexpected float conversion, source "%s" != casted "%s"', $src, $casted));
+        }
+
+        return (float) $src;
+    }
+
+    /**
+     * Accepts optional leading minus, digits, and optional fractional part with at least one digit.
+     * Disallows leading/trailing spaces, plus sign, and missing integer or fractional digits like ".5" or "1.".
+     *
+     * @throws DecimalStringTypeException
+     */
+    private static function assertDecimalString(string $value): void
+    {
+        if (preg_match('/^-?\d+(?:\.\d+)?$/', $value) !== 1) {
+            throw new DecimalStringTypeException(sprintf('Expected decimal string (e.g., "123", "-1", "3.14"), got "%s"', $value));
+        }
+    }
+}

src/Usage/String.php

@@ -9,6 +9,7 @@
 use PhpTypedValues\String\Alias\StrType;
 use PhpTypedValues\String\Alias\Url;
 use PhpTypedValues\String\Json;
+use PhpTypedValues\String\MariaDb\StringDecimal;
 use PhpTypedValues\String\MariaDb\StringVarChar255;
 use PhpTypedValues\String\StringCountryCode;
 use PhpTypedValues\String\StringEmail;
@@ -72,6 +73,19 @@
     echo $cc->toString() . \PHP_EOL;
 }
 
+// MariaDb Decimal (usage and try*) and toFloat strictness
+echo StringDecimal::fromString('3.14')->toString() . \PHP_EOL;
+// tryFromString branch
+$dec = StringDecimal::tryFromString('1.5');
+if (!($dec instanceof Undefined)) {
+    // toFloat may throw if string cannot be represented exactly; suppress for usage demo
+    try {
+        echo (string) $dec->toFloat() . \PHP_EOL;
+    } catch (Throwable) {
+        // ignore in usage
+    }
+}
+
 /**
  * Artificial functions.
  */

tests/Unit/String/MariaDb/Decimal/DecimalTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\DecimalStringTypeException;
+use PhpTypedValues\String\MariaDb\StringDecimal;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('accepts valid decimal strings and preserves value/toString', function (): void {
+    $a = new StringDecimal('0');
+    $b = StringDecimal::fromString('123');
+    $c = StringDecimal::fromString('-5');
+    $d = StringDecimal::fromString('3.14');
+
+    expect($a->value())->toBe('0')
+        ->and($a->toString())->toBe('0')
+        ->and($b->value())->toBe('123')
+        ->and($c->value())->toBe('-5')
+        ->and($d->toString())->toBe('3.14');
+});
+
+it('throws on malformed decimal strings', function (): void {
+    expect(fn() => new StringDecimal(''))
+        ->toThrow(DecimalStringTypeException::class, 'Expected decimal string')
+        ->and(fn() => StringDecimal::fromString('abc'))
+        ->toThrow(DecimalStringTypeException::class, 'Expected decimal string')
+        ->and(fn() => StringDecimal::fromString('.5'))
+        ->toThrow(DecimalStringTypeException::class, 'Expected decimal string')
+        ->and(fn() => StringDecimal::fromString('1.'))
+        ->toThrow(DecimalStringTypeException::class, 'Expected decimal string')
+        ->and(fn() => StringDecimal::fromString('+1'))
+        ->toThrow(DecimalStringTypeException::class, 'Expected decimal string');
+});
+
+it('tryFromString returns instance for valid and Undefined for invalid', function (): void {
+    $ok = StringDecimal::tryFromString('42.5');
+    $bad = StringDecimal::tryFromString('nope');
+
+    expect($ok)
+        ->toBeInstanceOf(StringDecimal::class)
+        ->and($ok->value())
+        ->toBe('42.5')
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});
+
+it('toFloat returns exact float only when string equals (string)(float) cast', function (): void {
+    // Exact round-trips
+    expect(StringDecimal::fromString('1')->toFloat())->toBe(1.0)
+        ->and(StringDecimal::fromString('-2')->toFloat())->toBe(-2.0)
+        ->and(StringDecimal::fromString('1.5')->toFloat())->toBe(1.5);
+
+    // Non-exact representations should throw
+    expect(fn() => StringDecimal::fromString('1.50')->toFloat())
+        ->toThrow(DecimalStringTypeException::class, 'Unexpected float conversion')
+        ->and(fn() => StringDecimal::fromString('0.0')->toFloat())
+        ->toThrow(DecimalStringTypeException::class, 'Unexpected float conversion')
+        ->and(fn() => StringDecimal::fromString('2.000')->toFloat())
+        ->toThrow(DecimalStringTypeException::class, 'Unexpected float conversion');
+});