nexttoward(), nexttowardf(), nexttowardl() — Calculate the next representable value

Standards

Standards / Extensions	C or C++	Dependencies
C99 Single UNIX Specification, Version 3 C++ TR1 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