Ldexp

In computing, ldexp is a function that multiplies a double precision floating point value by a specified integral power of two, returning the result if it is a valid floating point value for the representation used for double precision floating point values in the execution environment.

Location

It one of the the C programming language's math library routines and is declared in the header file math.h.

Definition

The function ldexp is defined in the C programming language standard, ISO/IEC 9899 [ [http://www.open-std.org/jtc1/sc22/wg14/www/standards.html ISO/IEC 9899 Standard for the C Programming Language] ] as follows:

7.12.6.6 The ldexp functions Synopsis

#include <math.h>
double ldexp(double x, int exp);
double ldexpf(float x, int exp);
long double ldexpl(long double x, int exp);

Description
The ldexp functions multiply a floating-point number by an integral power of 2. Arange error may occur.

Returns
The ldexp functions return x×2^exp

The Open Group Single Unix Specification expands on the interface definition for ldexp in a Unix^tm hosted environment. [ [http://www.opengroup.org/onlinepubs/009695399/functions/ldexp.html Open Group Base Specifications Issue 6, ldexp() definition] ]

:The Description section has the following additional information:::An application wishing to check for error situations should set errno to zero and call feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.

:The "Returns" section is expanded with the following clauses::: If these functions would cause overflow, a range error shall occur and ldexp(), ldexpf(), and ldexpl() shall return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (according to the sign of x), respectively.:: If the correct value would cause underflow, and is not representable, a range error may occur, and either 0.0 (if supported), or an implementation-defined value shall be returned.:: If x is NaN, a NaN shall be returned.:: If x is ±0 or ±Inf, x shall be returned.:: If exp is 0, x shall be returned.:: If the correct value would cause underflow, and is representable, a range error may occur and the correct value shall be returned.

:It also adds an "Errors section", as follows:::These functions shall fail if::::Range Error::::The result overflows.:::::If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, then errno shall be set to [ERANGE] . If the integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow floating-point exception shall be raised.

Implementation

For binary exponent based floating point representations such as IEEE 754, ldexp can be implemented by simply extracting the exponent from the value of x and adding exp to it and if the result is within the valid exponent values for the representation, replacing x's exponent with the result. If the calculated exponent value is too high the function returns +∞ or -∞ (depending on the sign of x), and if the value is too low, the function returns 0.0.

References

ee also

*math.h
*exp (programming)
*pow (programming)
*log2 (programming)
*scalb (programming)
*Binary logarithm

External links

* [http://www.open-std.org/jtc1/sc22/wg14/www/standards.html ISO/IEC 9899 Standard for the C Programming Language]
* [http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap01.html IEEE Std 1003.1-2001 (POSIX.1)]
* [http://www.opengroup.org/onlinepubs/009695399 Open Group Base Specifications Issue 6]