1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
# php-next-after
[](https://packagist.org/packages/nsfisis/next-after)
[](https://github.com/nsfisis/php-next-after/actions/workflows/test.yaml)
A PHP library that provides a port of Java's `Math.nextAfter()` family of functions.
## Overview
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
- `nextDown($x)` - Returns the next float toward negative infinity
## Requirements
- PHP 8.3 or higher
- Little-endian 64-bit integers
- IEEE 754 double-precision floats (binary64)
The library performs runtime assertions to verify these constraints are met on the current system.
## Installation
```bash
$ composer require nsfisis/next-after
```
## Exapmles
```php
use Nsfisis\NextAfter\NextAfter;
// Get the next representable float after 1.0.
$next = NextAfter::nextAfter(1.0, 2.0); // => 1.0000000000000002
// Get the next float toward positive infinity.
$up = NextAfter::nextUp(1.0); // => 1.0000000000000002
// Get the next float toward negative infinity.
$down = NextAfter::nextDown(1.0); // => 0.9999999999999999
```
## API Reference
### `nextAfter(float $x, float $y): float`
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
### `nextUp(float $x): float`
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
### `nextDown(float $x): float`
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
### `minValue(): float`
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.
## License
See the [LICENSE](./LICENSE) file.
## Credits
This library is a PHP port of Java's `java.lang.Math.nextAfter()`, `nextUp()`, and `nextDown()` methods.
Reference: [Java Math Documentation](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html)
|
