C math.h nexttoward() Function

nexttoward() Function

The nexttoward() function in C returns the next representable floating-point value after a given number, moving in the direction of another value. It is useful in scenarios requiring fine-grained control over floating-point increments and precision, especially when comparing floating-point numbers or iterating over them.

---

Syntax of nexttoward()

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

Parameters

Parameter	Description
x	The starting floating-point value from which to move.
y	The target value toward which the next representable value is sought. If x and y compare equal, the function returns y (converted to the return type).

This function behaves similarly to nextafter() but allows for a potentially more precise specification of the target value through its extended precision type for the second parameter. If the base value is the largest finite number representable, and the result would overflow or be not representable, an overflow range error is signaled by setting errno to ERANGE or by raising FE_OVERFLOW if the corresponding error handling is enabled.

---

Examples for nexttoward()

Example 1: Moving Upward from a Double Value

This example demonstrates how to obtain the next representable double value when moving upward from a base value toward a higher target.

Program

#include <stdio.h>
#include <math.h>

int main(void) {
    double x = 1.0;
    double y = 2.0;
    double result = nexttoward(x, (long double)y);
    printf("Next representable value after %f toward %Lf is %f\n", x, (long double)y, result);
    return 0;
}

Explanation:

1. Initialize a double variable x with 1.0 and set the target y to 2.0.
2. Call nexttoward() to get the next representable value after 1.0 in the direction of 2.0.
3. Print the result, which shows a slight increment from 1.0.

Program Output:

Next representable value after 1.000000 toward 2.000000 is 1.0000000000000002

Example 2: Moving Downward from a Double Value

This example shows how to obtain the next representable value when decreasing from a given double value toward a lower target.

Program

#include <stdio.h>
#include <math.h>

int main(void) {
    double x = 1.0;
    double y = 0.0;
    double result = nexttoward(x, (long double)y);
    printf("Next representable value after %f toward %Lf is %f\n", x, (long double)y, result);
    return 0;
}

Explanation:

1. Set the starting value x to 1.0 and the target y to 0.0.
2. Call nexttoward() to compute the next representable value in the direction of 0.0, resulting in a value slightly less than 1.0.
3. The program prints this decremental change.

Program Output:

Next representable value after 1.000000 toward 0.000000 is 0.9999999999999999

Example 3: Handling Equal Values with nexttoward()

This example demonstrates the behavior when the base value and the target value are equal; the function simply returns the target value.

Program

#include <stdio.h>
#include <math.h>

int main(void) {
    double x = 3.14;
    double y = 3.14;
    double result = nexttoward(x, (long double)y);
    printf("Next representable value after %f toward %Lf is %f\n", x, (long double)y, result);
    return 0;
}

Explanation:

1. Both x and y are set to 3.14.
2. Since the two values are equal, nexttoward() returns the target value, effectively resulting in no change.
3. The output confirms that the returned value is identical to the input.

Example 4: Using nexttowardf() for Single-Precision Floating-Point Values

This example illustrates the use of the single-precision version, nexttowardf(), to obtain the next representable float value when moving toward a specified target.

Program

#include <stdio.h>
#include <math.h>

int main(void) {
    float x = 1.0f;
    float y = 2.0f;
    float result = nexttowardf(x, (long double)y);
    printf("Next representable float value after %f toward %Lf is %f\n", x, (long double)y, result);
    return 0;
}

Explanation:

1. Initialize a float variable x with 1.0f and the target y with 2.0f.
2. Call nexttowardf() to compute the next representable float value after 1.0f in the direction of 2.0f.
3. The program prints the result, showing the minimal increment in single-precision representation.

Program Output:

Next representable float value after 1.000000 toward 2.000000 is 1.0000001192092896