`nextafter` and `nexttoward`: why this particular interface?

What exactly is the reason behind this peculiar interface of `nextafter` (and `nexttoward`) [functions][1]? We specify the *direction* by specifying the value we want to move *toward*.

At the first sight it feels as if something non-obvious is hidden behind this idea. In my (naive) opinion the first choice for such functions would be something like a pair of single-parameter functions `nextafter(a)`/`nextbefore(a)`. The next choice would be a two-parameter function `nextafter(a, dir)` in which the direction `dir` is specified explicitly (`-1` and `+1`, some standard enum, etc.).

But instead we have to specify a *value* we want to move *toward*. Hence a number of questions

1. (A vague one). There might be some clever idea or idiomatic pattern that is so valuable that it influenced this choice of interface in these standard functions. Is there?

2. What if decide to just blindly use `-DBL_MAX` and `+DBL_MAX` as the second argument for `nextafter` to specify the negative and positive direction respectively. Are there any pitfalls in doing so?

3. (A refinement of 2). If I know for sure that `b` is [slightly] greater than `a`, is there any reason to prefer `nextafter(a, b)` over `nextafter(a, DBL_MAX)`? E.g. is there a chance of better performance for `nextafter(a, b)` version?

4. Is `nextafter` generally a *heavy* operation? I know that it is implementation-dependent. But, again, assuming an implementation that is based in IEEE 754 representations, is it fairly "difficult" to find the adjacent floating-point value?


[1]:

[To see links please register here]

With IEEE-754 binary floating point representations, if both arguments of `nextafter` are finite and the two arguments are not equal, then the result can be computed by either adding one to or subtracting one from the representation of the number reinterpreted as an unsigned integer [Note 1]. The (slight) complexity results from correctly dealing with the corner cases which do not meet those preconditions, but in general you'll find that it is extremely fast.

Aside from NaNs, the only thing that matters about the second argument is whether it is greater than, less than, or equal to the first argument.

The interface basically provides additional clarity for the corner case results, but it is also sometimes useful. In particular, the usage `nextafter(x, 0)`, which truncates regardless of sign, is often convenient. You can also take advantage of the fact that `nextafter(x, x);` is `x` to clamp the result at an arbitrary value.


The difference between `nextafter` and `nexttowards` is that the latter allows you to use the larger dynamic range of `long double`; again, that helps with certain corner cases.

---

1. Strictly speaking, if the first argument is a zero of some sign and the other argument is a valid non-zero number of the opposite sign, then the argument needs to have its sign bit flipped before the increment. But it seemed too much legalese to add that to the list, and it is still hardly a complicated transform.