nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, or nexttowardl Subroutine

Purpose

Computes the next representable floating-point number.

Syntax

#include <math.h>

float nextafterf (x, y)
float x;
float y;

long double nextafterl (x, y)
long double x;
long double y;

double nextafter (x, y)
double x, y;

double nexttoward (x, y)
double x;
long double y;

float nexttowardf (x, y)
float x;
long double y;

long double nexttowardl (x, y)
long double x;
long double y;

Description

The nextafterf, nextafterl, and nextafter subroutines compute the next representable floating-point value following x in the direction of y. Thus, if y is less than x, the nextafter subroutine returns the largest representable floating-point number less than x.

The nextafter, nextafterf, and nextafterl subroutines return y if x equals y.

The nexttoward, nexttowardf, and nexttowardl subroutines are equivalent to the corresponding nextafter subroutine, except that the second parameter has type long double and the subroutines return y converted to the type of the subroutine if x equals y.

An application wishing to check for error situations should set the errno global variable to zero and call feclearexcept(FE_ALL_EXCEPT) before calling these subroutines. Upon return, if errno is nonzero or fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is nonzero, an error has occurred.

Parameters

Item Description
x Specifies the starting value. The next representable floating-point number is found from x in the direction specified by y.
y Specifies the direction.

Return Values

Upon successful completion, the nextafterf, nextafterl, nextafter, nexttoward, nexttowardf, and nexttowardl subroutines return the next representable floating-point value following x in the direction of y.

If x==y, y (of the type x) is returned.

If x is finite and the correct function value would overflow, a range error occurs and ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (with the same sign as x) is returned as appropriate for the return type of the function.

If x or y is NaN, a NaN is returned.

If x!=y and the correct subroutine value is subnormal, zero, or underflows, a range error occurs, and either the correct function value (if representable) or 0.0 is returned.

Error Codes

For the nextafter subroutine, if the x parameter is finite and the correct function value would overflow, HUGE_VAL is returned and errno is set to ERANGE.