Add tryFromString and tryFromFloat methods for float types with accompanying tests

- Implemented `tryFromString` and `tryFromFloat` methods in `FloatStandard`, `FloatNonNegative`, and `FloatPositive` to return `Undefined` on invalid input.
- Updated `FloatTypeInterface` to include declarations for new methods.
- Refactored exception handling for string and float parsing logic.
- Added comprehensive unit tests to validate behavior of new methods for valid and invalid cases.

Author: georgedeploy

src/Abstract/Float/FloatTypeInterface.php

@@ -4,6 +4,8 @@
 
 namespace PhpTypedValues\Abstract\Float;
 
+use PhpTypedValues\Undefined\Alias\Undefined;
+
 /**
  * @psalm-immutable
  */
@@ -17,5 +19,9 @@ public function toString(): string;
 
     public static function fromString(string $value): static;
 
+    public static function tryFromString(string $value): static|Undefined;
+
+    public static function tryFromFloat(float $value): static|Undefined;
+
     public function __toString(): string;
 }

src/Float/FloatNonNegative.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Float\FloatType;
 use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -26,7 +28,7 @@
     public function __construct(float $value)
     {
         if ($value < 0) {
-            throw new FloatTypeException(sprintf('Expected non-negative float, got "%d"', $value));
+            throw new FloatTypeException(sprintf('Expected non-negative float, got "%s"', $value));
         }
 
         $this->value = $value;
@@ -40,6 +42,24 @@ public static function fromFloat(float $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 static function tryFromFloat(float $value): static|Undefined
+    {
+        try {
+            return static::fromFloat($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws FloatTypeException
      */

src/Float/FloatPositive.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Float\FloatType;
 use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -40,6 +42,24 @@ public static function fromFloat(float $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 static function tryFromFloat(float $value): static|Undefined
+    {
+        try {
+            return static::fromFloat($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws FloatTypeException
      */

src/Float/FloatStandard.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Float\FloatType;
 use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Represents any PHP float (double).
@@ -28,6 +30,20 @@ public static function fromFloat(float $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 static function tryFromFloat(float $value): static|Undefined
+    {
+        return static::fromFloat($value);
+    }
+
     /**
      * @throws FloatTypeException
      */

src/Usage/Float.php

@@ -7,7 +7,9 @@
 use PhpTypedValues\Float\Alias\NonNegativeFloat;
 use PhpTypedValues\Float\Alias\PositiveFloat;
 use PhpTypedValues\Float\FloatNonNegative;
+use PhpTypedValues\Float\FloatPositive;
 use PhpTypedValues\Float\FloatStandard;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Float.
@@ -24,6 +26,22 @@
 testPositiveFloat(FloatNonNegative::fromFloat(0.5)->value());
 echo FloatNonNegative::fromString('3.14159')->toString() . \PHP_EOL;
 
+// try* usages to satisfy Psalm (ensure both success and failure branches are referenced)
+$ts = FloatStandard::tryFromString('1.23');
+if (!($ts instanceof Undefined)) {
+    echo $ts->toString() . \PHP_EOL;
+}
+
+$ti = FloatPositive::tryFromFloat(2.2);
+if (!($ti instanceof Undefined)) {
+    echo $ti->toString() . \PHP_EOL;
+}
+
+$tn = FloatNonNegative::tryFromString('-1'); // will likely be Undefined
+if (!($tn instanceof Undefined)) {
+    echo $tn->toString() . \PHP_EOL;
+}
+
 /**
  * Artificial functions.
  */

tests/Unit/Float/FloatNonNegative/FloatNonNegativeTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Float\FloatNonNegative;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('FloatNonNegative::tryFromString returns value for >= 0.0 and Undefined otherwise', function (): void {
+    $ok0 = FloatNonNegative::tryFromString('0');
+    $ok = FloatNonNegative::tryFromString('0.5');
+    $bad = FloatNonNegative::tryFromString('-0.1');
+    $badStr = FloatNonNegative::tryFromString('abc');
+
+    expect($ok0)
+        ->toBeInstanceOf(FloatNonNegative::class)
+        ->and($ok0->value())->toBe(0.0)
+        ->and($ok)
+        ->toBeInstanceOf(FloatNonNegative::class)
+        ->and($ok->value())->toBe(0.5)
+        ->and($bad)->toBeInstanceOf(Undefined::class)
+        ->and($badStr)->toBeInstanceOf(Undefined::class);
+});
+
+it('FloatNonNegative::tryFromFloat returns value for >= 0 and Undefined otherwise', function (): void {
+    $ok = FloatNonNegative::tryFromFloat(0);
+    $bad = FloatNonNegative::tryFromFloat(-1);
+
+    expect($ok)
+        ->toBeInstanceOf(FloatNonNegative::class)
+        ->and($ok->value())
+        ->toBe(0.0)
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});
+
+it('FloatNonNegative throws on negative values in ctor and fromFloat', function (): void {
+    expect(fn() => new FloatNonNegative(-0.1))
+        ->toThrow(FloatTypeException::class, 'Expected non-negative float, got "-0.1"')
+        ->and(fn() => FloatNonNegative::fromFloat(-1.0))
+        ->toThrow(FloatTypeException::class, 'Expected non-negative float, got "-1"');
+});
+
+it('FloatNonNegative::fromString enforces numeric and non-negativity', function (): void {
+    // Non-numeric
+    expect(fn() => FloatNonNegative::fromString('abc'))
+        ->toThrow(FloatTypeException::class, 'String "abc" has no valid float value');
+
+    // Non-negativity
+    expect(fn() => FloatNonNegative::fromString('-0.5'))
+        ->toThrow(FloatTypeException::class, 'Expected non-negative float, got "-0.5"');
+
+    // Success path
+    $v = FloatNonNegative::fromString('0.75');
+    expect($v->value())->toBe(0.75);
+});

tests/Unit/Float/FloatPositive/FloatPositiveTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Float\FloatPositive;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('FloatPositive::tryFromString returns value for > 0.0 and Undefined otherwise', function (): void {
+    $ok = FloatPositive::tryFromString('0.1');
+    $badZero = FloatPositive::tryFromString('0');
+    $badNeg = FloatPositive::tryFromString('-0.1');
+    $badStr = FloatPositive::tryFromString('abc');
+
+    expect($ok)
+        ->toBeInstanceOf(FloatPositive::class)
+        ->and($ok->value())->toBe(0.1)
+        ->and($badZero)->toBeInstanceOf(Undefined::class)
+        ->and($badNeg)->toBeInstanceOf(Undefined::class)
+        ->and($badStr)->toBeInstanceOf(Undefined::class);
+});
+
+it('FloatPositive::tryFromFloat returns value for positive int and Undefined otherwise', function (): void {
+    $ok = FloatPositive::tryFromFloat(2);
+    $bad = FloatPositive::tryFromFloat(0);
+
+    expect($ok)
+        ->toBeInstanceOf(FloatPositive::class)
+        ->and($ok->value())
+        ->toBe(2.0)
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});
+
+it('FloatPositive throws on non-positive values in ctor and fromFloat', function (): void {
+    expect(fn() => new FloatPositive(0.0))
+        ->toThrow(FloatTypeException::class, 'Expected positive float, got "0"')
+        ->and(fn() => FloatPositive::fromFloat(-1.0))
+        ->toThrow(FloatTypeException::class, 'Expected positive float, got "-1"');
+});
+
+it('FloatPositive::fromString enforces numeric and positivity', function (): void {
+    // Non-numeric
+    expect(fn() => FloatPositive::fromString('abc'))
+        ->toThrow(FloatTypeException::class, 'String "abc" has no valid float value');
+
+    // Positivity
+    expect(fn() => FloatPositive::fromString('0'))
+        ->toThrow(FloatTypeException::class, 'Expected positive float, got "0"');
+
+    // Success path
+    $v = FloatPositive::fromString('1.25');
+    expect($v->value())->toBe(1.25);
+});

tests/Unit/Float/FloatStandard/FloatStandardTest.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\FloatTypeException;
+use PhpTypedValues\Float\FloatStandard;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('FloatStandard::tryFromString returns value on valid float string', function (): void {
+    $v = FloatStandard::tryFromString('1.5');
+
+    expect($v)
+        ->toBeInstanceOf(FloatStandard::class)
+        ->and($v->value())
+        ->toBe(1.5)
+        ->and($v->toString())
+        ->toBe('1.5');
+});
+
+it('FloatStandard::tryFromString returns Undefined on invalid float string', function (): void {
+    $v = FloatStandard::tryFromString('abc');
+
+    expect($v)->toBeInstanceOf(Undefined::class);
+});
+
+it('FloatStandard::tryFromFloat returns value for any int', function (): void {
+    $v = FloatStandard::tryFromFloat(2);
+
+    expect($v)
+        ->toBeInstanceOf(FloatStandard::class)
+        ->and($v->value())
+        ->toBe(2.0);
+});
+
+it('FloatStandard::fromString throws on non-numeric strings', function (): void {
+    expect(fn() => FloatStandard::fromString('NaN'))
+        ->toThrow(FloatTypeException::class, 'String "NaN" has no valid float value');
+});