20.8.5 Setting and modifying single bits of FP values

There are some operations that are too complicated or expensive to perform by hand on floating-point numbers. ISO C99 defines functions to do these operations, which mostly involve changing single bits.

Function: double copysign (double x, double y)

Function: float copysignf (float x, float y)

Function: long double copysignl (long double x, long double y)

Function: _FloatN copysignfN (_FloatN x, _FloatN y)

Function: _FloatNx copysignfNx (_FloatNx x, _FloatNx y)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

These functions return x but with the sign of y. They work even if x or y are NaN or zero. Both of these can carry a sign (although not all implementations support it) and this is one of the few operations that can tell the difference.

copysign never raises an exception.

This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854).

Function: int signbit (float-type x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

signbit is a generic macro which can work on all floating-point types. It returns a nonzero value if the value of x has its sign bit set.

This is not the same as x < 0.0, because IEEE 754 floating point allows zero to be signed. The comparison -0.0 < 0.0 is false, but signbit (-0.0) will return a nonzero value.

Function: double nextafter (double x, double y)

Function: float nextafterf (float x, float y)

Function: long double nextafterl (long double x, long double y)

Function: _FloatN nextafterfN (_FloatN x, _FloatN y)

Function: _FloatNx nextafterfNx (_FloatNx x, _FloatNx y)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The nextafter function returns the next representable neighbor of x in the direction towards y. The size of the step between x and the result depends on the type of the result. If x = y the function simply returns y. If either value is NaN, NaN is returned. Otherwise a value corresponding to the value of the least significant bit in the mantissa is added or subtracted, depending on the direction. nextafter will signal overflow or underflow if the result goes outside of the range of normalized numbers.

This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854).

Function: double nexttoward (double x, long double y)

Function: float nexttowardf (float x, long double y)

Function: long double nexttowardl (long double x, long double y)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

These functions are identical to the corresponding versions of nextafter except that their second argument is a long double.

Function: double nextup (double x)

Function: float nextupf (float x)

Function: long double nextupl (long double x)

Function: _FloatN nextupfN (_FloatN x)

Function: _FloatNx nextupfNx (_FloatNx x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The nextup function returns the next representable neighbor of x in the direction of positive infinity. If x is the smallest negative subnormal number in the type of x the function returns -0. If x = 0 the function returns the smallest positive subnormal number in the type of x. If x is NaN, NaN is returned. If x is +∞, +∞ is returned. nextup is from TS 18661-1:2014 and TS 18661-3:2015. nextup never raises an exception except for signaling NaNs.

Function: double nextdown (double x)

Function: float nextdownf (float x)

Function: long double nextdownl (long double x)

Function: _FloatN nextdownfN (_FloatN x)

Function: _FloatNx nextdownfNx (_FloatNx x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The nextdown function returns the next representable neighbor of x in the direction of negative infinity. If x is the smallest positive subnormal number in the type of x the function returns +0. If x = 0 the function returns the smallest negative subnormal number in the type of x. If x is NaN, NaN is returned. If x is -∞, -∞ is returned. nextdown is from TS 18661-1:2014 and TS 18661-3:2015. nextdown never raises an exception except for signaling NaNs.

Function: double nan (const char *tagp)

Function: float nanf (const char *tagp)

Function: long double nanl (const char *tagp)

Function: _FloatN nanfN (const char *tagp)

Function: _FloatNx nanfNx (const char *tagp)

Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The nan function returns a representation of NaN, provided that NaN is supported by the target platform. nan ("n-char-sequence") is equivalent to strtod ("NAN(n-char-sequence)").

The argument tagp is used in an unspecified manner. On IEEE 754 systems, there are many representations of NaN, and tagp selects one. On other systems it may do nothing.

Function: int canonicalize (double *cx, const double *x)

Function: int canonicalizef (float *cx, const float *x)

Function: int canonicalizel (long double *cx, const long double *x)

Function: int canonicalizefN (_FloatN *cx, const _FloatN *x)

Function: int canonicalizefNx (_FloatNx *cx, const _FloatNx *x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

In some floating-point formats, some values have canonical (preferred) and noncanonical encodings (for IEEE interchange binary formats, all encodings are canonical). These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, attempt to produce a canonical version of the floating-point value pointed to by x; if that value is a signaling NaN, they raise the invalid exception and produce a quiet NaN. If a canonical value is produced, it is stored in the object pointed to by cx, and these functions return zero. Otherwise (if a canonical value could not be produced because the object pointed to by x is not a valid representation of any floating-point value), the object pointed to by cx is unchanged and a nonzero value is returned.

Note that some formats have multiple encodings of a value which are all equally canonical; when such an encoding is used as an input to this function, any such encoding of the same value (or of the corresponding quiet NaN, if that value is a signaling NaN) may be produced as output.

Function: double getpayload (const double *x)

Function: float getpayloadf (const float *x)

Function: long double getpayloadl (const long double *x)

Function: _FloatN getpayloadfN (const _FloatN *x)

Function: _FloatNx getpayloadfNx (const _FloatNx *x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

IEEE 754 defines the payload of a NaN to be an integer value encoded in the representation of the NaN. Payloads are typically propagated from NaN inputs to the result of a floating-point operation. These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, return the payload of the NaN pointed to by x (returned as a positive integer, or positive zero, represented as a floating-point number); if x is not a NaN, they return an unspecified value. They raise no floating-point exceptions even for signaling NaNs.

Function: int setpayload (double *x, double payload)

Function: int setpayloadf (float *x, float payload)

Function: int setpayloadl (long double *x, long double payload)

Function: int setpayloadfN (_FloatN *x, _FloatN payload)

Function: int setpayloadfNx (_FloatNx *x, _FloatNx payload)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, set the object pointed to by x to a quiet NaN with payload payload and a zero sign bit and return zero. If payload is not a positive-signed integer that is a valid payload for a quiet NaN of the given type, the object pointed to by x is set to positive zero and a nonzero value is returned. They raise no floating-point exceptions.

Function: int setpayloadsig (double *x, double payload)

Function: int setpayloadsigf (float *x, float payload)

Function: int setpayloadsigl (long double *x, long double payload)

Function: int setpayloadsigfN (_FloatN *x, _FloatN payload)

Function: int setpayloadsigfNx (_FloatNx *x, _FloatNx payload)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, set the object pointed to by x to a signaling NaN with payload payload and a zero sign bit and return zero. If payload is not a positive-signed integer that is a valid payload for a signaling NaN of the given type, the object pointed to by x is set to positive zero and a nonzero value is returned. They raise no floating-point exceptions.