diff options
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | src/NextAfter.php | 59 |
2 files changed, 62 insertions, 3 deletions
@@ -5,7 +5,7 @@ A PHP library that provides a port of Java's `Math.nextAfter()` family of functi ## Overview -This library implements IEEE 754 floating-point manipulation functions that return the next representable floating-point value in a given direction: +This library implements IEEE 754 floating-point manipulation functions that return the next representable floating-point number in a given direction: - `nextAfter($x, $y)` - Returns the adjacent float in the direction of another value - `nextUp($x)` - Returns the next float toward positive infinity @@ -61,7 +61,7 @@ Returns the floating-point number adjacent to `$x` in the direction of `$y`. If ### `nextUp(float $x): float` -Returns the floating-point value adjacent to `$x` in the direction of positive infinity. +Returns the floating-point number adjacent to `$x` in the direction of positive infinity. This is semantically equivalent to `nextAfter($x, INF)`. @@ -75,7 +75,7 @@ This is semantically equivalent to `nextAfter($x, INF)`. ### `nextDown(float $x): float` -Returns the floating-point value adjacent to `$x` in the direction of negative infinity. +Returns the floating-point number adjacent to `$x` in the direction of negative infinity. This is semantically equivalent to `nextAfter($x, -INF)`. diff --git a/src/NextAfter.php b/src/NextAfter.php index 678de25..d985e6f 100644 --- a/src/NextAfter.php +++ b/src/NextAfter.php @@ -20,6 +20,26 @@ final class NextAfter } /** + * Returns the floating-point number adjacent to $x in the direction of $y. + * If $x equals $y, returns $y. + * + * Special Cases: + * + * - If either argument is NaN, the result is NaN + * - If both arguments equal, $y is returned as it is + * - If $x is minValue() and $y is greater than $x, the result is positive zero + * - If $x is -minValue() and $y is less than $x, the result is negative zero + * - If $x is infinity and $y is not, PHP_FLOAT_MAX is returned + * - If $x is negative infinity and $y is not, -PHP_FLOAT_MAX is returned + * - If $x is PHP_FLOAT_MAX and $y is infinity, infinity is returned + * - If $x is -PHP_FLOAT_MAX and $y is negative infinity, negative infinity is returned + * + * @param float $x + * Starting floating-point number + * @param float $y + * Floating-point number indicating the direction + * @return float + * The floating-point number adjacent to $x in the direction of $y * @phpstan-pure */ public static function nextAfter(float $x, float $y): float @@ -34,6 +54,22 @@ final class NextAfter } /** + * Returns the floating-point number adjacent to $x in the direction of positive infinity. + * + * This is semantically equivalent to nextAfter($x, INF). + * + * Special Cases: + * + * - If $x is NaN, the result is NaN + * - If $x is positive infinity, the result is positive infinity + * - If $x is zero, the result is minValue() + * - If $x is -minValue(), the result is negative zero + * - If $x is PHP_FLOAT_MAX, infinity is returned + * + * @param float $x + * Starting floating-point number + * @return float + * The floating-point number adjacent to $x in the direction of positive infinity * @phpstan-pure */ public static function nextUp(float $x): float @@ -54,6 +90,22 @@ final class NextAfter } /** + * Returns the floating-point number adjacent to $x in the direction of negative infinity. + * + * This is semantically equivalent to nextAfter($x, -INF). + * + * Special Cases: + * + * - If $x is NaN, the result is NaN + * - If $x is negative infinity, the result is negative infinity + * - If $x is zero, the result is -minValue() + * - If $x is minValue(), the result is positive zero + * - If $x is -PHP_FLOAT_MAX, negative infinity is returned + * + * @param float $x + * Starting floating-point number + * @return float + * The floating-point number adjacent to $x in the direction of negative infinity * @phpstan-pure */ public static function nextDown(float $x): float @@ -74,6 +126,13 @@ final class NextAfter } /** + * Returns the minimum representable non-zero floating-point number. + * + * Note that this is a subnormal number and is not the same as PHP_FLOAT_MIN, + * which is the smallest *normal* number. + * + * @return float + * The minimum representable non-zero floating-point number * @phpstan-pure */ public static function minValue(): float |