Ldexp
Defined in header <cmath>
.
Description
Multiplies a floating point value num
by the number 2
raised to the exp
power.
The library provides overloads of std::ldexp for all cv-unqualified floating-point types as the type of the parameter num
(od C++23).
Additional Overloads are provided for all integer types, which are treated as double (od C++11).
Declarations
- C++23
- C++11
// 1)
constexpr /* floating-point-type */
ldexp ( /* floating-point-type */ num, int exp )
// 2)
constexpr float ldexpf( float num, int exp );
// 3)
constexpr long double ldexpl( long double num, int exp );
// 4)
template< class Integer >
constexpr double ldexp ( Integer num, int exp );
// 1)
float ldexp ( float num, int exp );
// 2)
double ldexp ( double num, int exp );
// 3)
long double ldexp ( long double num, int exp );
// 4)
float ldexpf( float num, int exp );
// 5)
long double ldexpl( long double num, int exp );
// 6)
template< class Integer >
double ldexp ( Integer num, int exp );
Parameters
num
- floating-point or integer value
exp
- integer value
Return value
If no errors occur, num
multiplied by 2 to the power of exp
(num×2exp) is returned.
If a range error due to overflow occurs, ±HUGE_VAL
, ±HUGE_VALF
, or ±HUGE_VALL
is returned.
If a range error due to underflow occurs, the correct result (after rounding) is returned.
Error handling
Errors are reported as specified in math_errhandling.
If the implementation supports IEEE floating-point arithmetic (IEC 60559):
Unless a range error occurs, FE_INEXACT is never raised (the result is exact)
Unless a range error occurs, the current rounding mode is ignored
If num
is ±0
, it is returned, unmodified
If num
is ±∞
, it is returned, unmodified
If exp
is 0, then num
is returned, unmodified
If num
is NaN, NaN is returned
Notes
On binary systems (where FLT_RADIX is 2), std::ldexp
is equivalent to std::scalbn
.
The function std::ldexp
("load exponent"), together with its dual, std::frexp
,
can be used to manipulate the representation of a floating-point number without direct bit manipulations.
On many implementations, std::ldexp
is less efficient than multiplication or division by a power of two using arithmetic operators.
The additional overloads are not required to be provided exactly as Additional Overloads.
They only need to be sufficient to ensure that for their argument num
of integer type,
std::ldexp(num, exp)
has the same effect as std::ldexp(static_cast<double>(num), exp)
.
Examples
#include <cerrno>
#include <cfenv>
#include <cmath>
#include <cstring>
#include <iostream>
// #pragma STDC FENV_ACCESS ON
int main()
{
std::cout
<< "ldexp(7, -4) = "
<< std::ldexp(7, -4) << '\n'
<< "ldexp(1, -1074) = "
<< std::ldexp(1, -1074)
<< " (minimum positive subnormal double)\n"
<< "ldexp(nextafter(1,0), 1024) = "
<< std::ldexp(std::nextafter(1,0), 1024)
<< " (largest finite double)\n";
// special values
std::cout
<< "ldexp(-0, 10) = "
<< std::ldexp(-0.0, 10) << '\n'
<< "ldexp(-Inf, -1) = "
<< std::ldexp(-INFINITY, -1) << '\n';
// error handling
errno = 0;
std::feclearexcept(FE_ALL_EXCEPT);
std::cout
<< "ldexp(1, 1024) = "
<< std::ldexp(1, 1024) << '\n';
if (errno == ERANGE)
std::cout
<< "errno == ERANGE: "
<< std::strerror(errno) << '\n';
if (std::fetestexcept(FE_OVERFLOW))
std::cout
<< "FE_OVERFLOW raised\n";
}
ldexp(7, -4) = 0.4375
ldexp(1, -1074) = 4.94066e-324 (minimum positive subnormal double)
ldexp(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double)
ldexp(-0, 10) = -0
ldexp(-Inf, -1) = -inf
ldexp(1, 1024) = inf
errno == ERANGE: Numerical result out of range
FE_OVERFLOW raised