nexttoward(), nexttowardf(), nexttowardl() — Calculate the next representable value
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
C99 |
both | z/OS V1R7 |
Format
#define _ISOC99_SOURCE
#include <math.h>
double nexttoward(double x, long double y);
float nexttowardf(float x, long double y);
long double nexttowardl(long double x, long double y);
C++
TR1 C99:
#define _TR1_C99
#include <math.h>
float nexttoward(float x, long double y);
long double nexttoward(long double x, long double y);
General description
The nexttoward() family of functions compute the next representable floating-point value following x in the direction of y.
Note: The following
table shows the viable formats for these functions. See IEEE binary floating-point for more information about IEEE
Binary Floating-Point.
Function | Hex | IEEE |
---|---|---|
nexttoward | X | X |
nexttowardf | X | X |
nexttowardl | X | X |
Restriction: The
nexttowardf() function does not support the _FP_MODE_VARIABLE feature
test macro.
Returned value
If successful, they return the next representable value in the specified format after x in the direction of y.
If... | Then... |
---|---|
x equals y | y (of type x) is returned. |
x is less than y | the next representable value after x is returned. |
x is greater than y | the largest representable floating-point number less than x is returned. |
x is finite and the correct function value would overflow | a range error occurs and +/-HUGE_VAL, +/-HUGE_VALF, or +/-HUGE_VALL (with the same sign as x) is returned by nexttoward(), nexttowardf() or nexttowardl() respectively. |
x does not equal y and the correct subroutine value is subnormal, 0, or underflows | a range error occurs and either the correct function value (if representable) or 0.0 is returned. |
x or y is a NaN | a NaN is returned. |
Example
/*
* This program illustrates the use of nexttoward() function
*/
#define _ISOC99_SOURCE
#include <math.h>
#include <stdio.h>
void PrintBytes(char *str, double x)
{
static union {
unsigned char bytes[sizeof(double)];
double val;
} dbl;
int i;
dbl.val = x;
printf("%s ",str);
for (i=0; i<sizeof(double); ++i) {
printf("%02x", dbl.bytes[i]);
}
printf("\n");
}
void main() {
double nextvalue;
double x=1.5;
long double y=2.0;
printf("Illustrates the nexttoward() function\n");
printf("\nTest1 (x<y) x = %f y = %Lf\n",x,y);
PrintBytes("x in hex =",x);
nextvalue = nexttoward(x,y);
printf ("nexttoward(x,y) = %f\n", nextvalue);
PrintBytes("nexttoward(x,y) in hex =",nextvalue);
x=1.5; y=1.0;
printf("\nTest2 (x>y) x = %f y = %Lf\n",x,y);
nextvalue = nexttoward(x,y);
printf ("nexttoward(x,y) = %f\n", nextvalue);
PrintBytes("nexttoward(x,y) in hex =",nextvalue);
}
Output
Illustrates the nexttoward() function
Test1 (x<y) x = 1.500000 y = 2.000000
x in hex = 3ff8000000000000
nexttoward(x,y) = 1.500000
nexttoward(x,y) in hex = 3ff8000000000001
Test2 (x>y) x = 1.500000 y = 1.000000
nexttoward(x,y) = 1.500000
nexttoward(x,y) in hex = 3ff7ffffffffffff