std::ldexp, std::ldexpf, std::ldexpl

Defined in header `<cmath>`
	(1)
float ldexp ( float num, int exp ); double ldexp ( double num, int exp ); long double ldexp ( long double num, int exp );			(until C++23)
constexpr /* floating-point-type / ldexp ( / floating-point-type */ num, int exp );			(since C++23)
float ldexpf( float num, int exp );		(2)	(since C++11) (constexpr since C++23)
long double ldexpl( long double num, int exp );		(3)	(since C++11) (constexpr since C++23)
Additional overloads (since C++11)
Defined in header `<cmath>`
template< class Integer > double ldexp ( Integer num, int exp );		(A)	(since C++11) (constexpr since C++23)

1-3) 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. (since C++23)

A) Additional overloads are provided for all integer types, which are treated as double.

(since C++11)

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\times2 exp$ ) 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 (A). 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).

Example

Run this code

#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";
}

Output:

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

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries

Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Floating-point environment (C++11)
Complex numbers
Numeric arrays
Pseudo-random number generation
Factor operations
gcd (C++17)
lcm (C++17)
Interpolations
midpoint (C++20)
lerp (C++20)
Generic numeric operations
iota (C++11)
ranges::iota (C++23)
accumulate
inner_product
adjacent_difference
partial_sum
reduce (C++17)
transform_reduce (C++17)
inclusive_scan (C++17)
exclusive_scan (C++17)
transform_inclusive_scan (C++17)
transform_exclusive_scan (C++17)
Bit operations
bit_cast (C++20)
byteswap (C++23)
has_single_bit (C++20)
bit_ceil (C++20)
bit_floor (C++20)
bit_width (C++20)
rotl (C++20)
rotr (C++20)
countl_zero (C++20)
countl_one (C++20)
countr_zero (C++20)
countr_one (C++20)
popcount (C++20)
endian (C++20)

frexpfrexpffrexpl (C++11)(C++11)	decomposes a number into significand and a power of 2 (function)
scalbnscalbnfscalbnlscalblnscalblnfscalblnl (C++11)(C++11)(C++11)(C++11)(C++11)(C++11)	multiplies a number by FLT_RADIX raised to a power (function)