Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/numeric/math/exp2"

From cppreference.com
< cpp‎ | numeric‎ | math
(-f and -l variants)
(→‎Example: harmonise error handling with ldexp instead)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{cpp/title|exp2|exp2f|exp2l}}
 
{{cpp/title|exp2|exp2f|exp2l}}
 
{{cpp/numeric/math/navbar}}
 
{{cpp/numeric/math/navbar}}
−
{{dcl begin}}
+
{{cpp/numeric/math/declarations
−
{{dcl header | cmath}}
+
|family=exp2
−
{{dcl | since=c++11 |num=1|
+
|param1=num
−
float      exp2 ( float n );
+
|constexpr_since=26
−
float      exp2f( float n );
+
|desc=Computes 2 raised to the given power {{c|num}}.
 
}}
 
}}
−
{{dcl | since=c++11 |num=2|
 
−
double      exp2 ( double n );
 
−
}}
 
−
{{dcl | since=c++11 |num=3|
 
−
long double exp2 ( long double n );
 
−
long double exp2l( long double n );
 
−
}}
 
−
{{dcl | since=c++11 |num=4|
 
−
double      exp2 ( IntegralType n );
 
−
}}
 
−
{{dcl end}}
 
−
 
−
@1-3@ Computes 2 raised to the given power {{tt|n}}
 
−
@4@ A set of overloads or a function template accepting an argument of any [[cpp/types/is_integral|integral type]]. Equivalent to (2) (the argument is cast to {{c|double}}).
 
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | n | value of floating-point or [[cpp/types/is_integral|Integral type]]}}
+
{{par|num|floating-point or integer value}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
If no errors occur, the base-''2'' exponential of {{tt|n}} ({{math|2{{su|p=n}}}}) is returned.
+
If no errors occur, the base-''2'' exponential of {{c|num}} ({{math|2{{su|p=num}}}}) is returned.
  
−
If a range error due to overflow occurs, {{tt|+HUGE_VAL}}, {{tt|+HUGE_VALF}}, or {{tt|+HUGE_VALL}} is returned.
+
If a range error due to overflow occurs, {{lc|HUGE_VAL|+HUGE_VAL}}, {{tt|+HUGE_VALF}}, or {{tt|+HUGE_VALL}} is returned.
  
 
If a range error occurs due to underflow, the correct result (after rounding) is returned.
 
If a range error occurs due to underflow, the correct result (after rounding) is returned.
Line 38: Line 24:
  
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
−
* If the argument is ±0, 1 is returned
+
* If the argument is ±0, 1 is returned.
−
* If the argument is -∞, +0 is returned
+
* If the argument is -∞, +0 is returned.
−
* If the argument is +∞, +∞ is returned
+
* If the argument is +∞, +∞ is returned.
−
* If the argument is NaN, NaN is returned
+
* If the argument is NaN, NaN is returned.
 +
 
 +
===Notes===
 +
{{cpp/numeric/math/additional integer overload note|exp2}}
 +
 
 +
For integral exponents, it may be preferable to use {{lc|std::ldexp}}.
  
 
===Example===
 
===Example===
 
{{example
 
{{example
 
|code=
 
|code=
−
#include <iostream>
 
−
#include <cmath>
 
 
#include <cerrno>
 
#include <cerrno>
−
#include <cstring>
 
 
#include <cfenv>
 
#include <cfenv>
−
#pragma STDC FENV_ACCESS ON
+
#include <cmath>
 +
#include <cstring>
 +
#include <iostream>
 +
 
 +
// #pragma STDC FENV_ACCESS ON
 +
 
 
int main()
 
int main()
 
{
 
{
Line 57: Line 50:
 
               << "exp2(0.5) = " << std::exp2(0.5) << '\n'
 
               << "exp2(0.5) = " << std::exp2(0.5) << '\n'
 
               << "exp2(-4) = " << std::exp2(-4) << '\n';
 
               << "exp2(-4) = " << std::exp2(-4) << '\n';
 +
   
 
     // special values
 
     // special values
 
     std::cout << "exp2(-0) = " << std::exp2(-0.0) << '\n'
 
     std::cout << "exp2(-0) = " << std::exp2(-0.0) << '\n'
 
               << "exp2(-Inf) = " << std::exp2(-INFINITY) << '\n';
 
               << "exp2(-Inf) = " << std::exp2(-INFINITY) << '\n';
 +
   
 
     // error handling
 
     // error handling
 
     errno = 0;
 
     errno = 0;
 
     std::feclearexcept(FE_ALL_EXCEPT);
 
     std::feclearexcept(FE_ALL_EXCEPT);
−
     std::cout << "exp2(1024) = " << std::exp2(1024) << '\n';
+
     const double inf = std::exp2(1024);
−
     if (errno == ERANGE)
+
    const bool is_range_error = errno == ERANGE;
−
         std::cout << "    errno == ERANGE: " << std::strerror(errno) << '\n';
+
 
 +
    std::cout << "exp2(1024) = " << inf << '\n';
 +
     if (is_range_error)
 +
         std::cout << "    errno == ERANGE: " << std::strerror(ERANGE) << '\n';
 
     if (std::fetestexcept(FE_OVERFLOW))
 
     if (std::fetestexcept(FE_OVERFLOW))
 
         std::cout << "    FE_OVERFLOW raised\n";
 
         std::cout << "    FE_OVERFLOW raised\n";
Line 83: Line 81:
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/numeric/math/dsc exp}}
+
{{dsc inc|cpp/numeric/math/dsc exp}}
−
{{dsc inc | cpp/numeric/math/dsc expm1}}
+
{{dsc inc|cpp/numeric/math/dsc expm1}}
−
{{dsc inc | cpp/numeric/math/dsc log2}}
+
{{dsc inc|cpp/numeric/math/dsc ldexp}}
−
{{dsc see c | c/numeric/math/exp2}}
+
{{dsc inc|cpp/numeric/math/dsc log2}}
 +
{{dsc see c|c/numeric/math/exp2}}
 
{{dsc end}}
 
{{dsc end}}
  
 
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
 
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 04:18, 18 May 2024

 
C++
 
Numerics library
Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Basic linear algebra algorithms (C++26)
Floating-point environment (C++11)
Complex numbers
Numeric array (valarray)
Pseudo-random number generation
Factor operations
(C++17)
(C++17)
Interpolations
(C++20)
(C++20)
Saturation arithmetic
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)

Generic numeric operations
Bit operations
(C++20)    
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++20)
 
Common mathematical functions
Functions
Basic operations
(C++11)  
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
Exponential functions
exp2
(C++11)
(C++11)

(C++11)
(C++11)
Power functions
(C++11)
(C++11)
Trigonometric and
hyperbolic functions
(C++11)
(C++11)
(C++11)

Error and gamma functions
(C++11)
(C++11)
(C++11)
(C++11)
Nearest integer floating point operations
(C++11)(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
Floating point manipulation functions
(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)
(C++11)
Classification and comparison
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Types
(C++11)
(C++11)
(C++11)
Macro constants
 
Defined in header <cmath>
(1)
float       exp2 ( float num );

double      exp2 ( double num );

long double exp2 ( long double num );
 (until C++23)
/* floating-point-type */
            exp2 ( /* floating-point-type */ num );
 (since C++23)
(constexpr since C++26)
float       exp2f( float num );
 (2) (since C++11)
(constexpr since C++26)
long double exp2l( long double num );
 (3) (since C++11)
(constexpr since C++26)
Additional overloads (since C++11)
Defined in header <cmath>
template< class Integer >
double      exp2 ( Integer num );
 (A) (constexpr since C++26)
1-3) Computes 2 raised to the given power num. The library provides overloads of std::exp2 for all cv-unqualified floating-point types as the type of the parameter.(since C++23)
A) Additional overloads are provided for all integer types, which are treated as double.
 (since C++11)

Contents

[edit] Parameters

num - floating-point or integer value

[edit] Return value

If no errors occur, the base-2 exponential of num (2num) is returned.

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

If a range error occurs due to underflow, the correct result (after rounding) is returned.

[edit] Error handling

Errors are reported as specified in math_errhandling.

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

  • If the argument is ±0, 1 is returned.
  • If the argument is -∞, +0 is returned.
  • If the argument is +∞, +∞ is returned.
  • If the argument is NaN, NaN is returned.

[edit] Notes

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::exp2(num) has the same effect as std::exp2(static_cast<double>(num)).

For integral exponents, it may be preferable to use std::ldexp.

[edit] Example

Run this code
#include <cerrno>
#include <cfenv>
#include <cmath>
#include <cstring>
#include <iostream>
 
// #pragma STDC FENV_ACCESS ON
 
int main()
{
    std::cout << "exp2(4) = " << std::exp2(4) << '\n'
              << "exp2(0.5) = " << std::exp2(0.5) << '\n'
              << "exp2(-4) = " << std::exp2(-4) << '\n';
 
    // special values
    std::cout << "exp2(-0) = " << std::exp2(-0.0) << '\n'
              << "exp2(-Inf) = " << std::exp2(-INFINITY) << '\n';
 
    // error handling
    errno = 0;
    std::feclearexcept(FE_ALL_EXCEPT);
    const double inf = std::exp2(1024);
    const bool is_range_error = errno == ERANGE;
 
    std::cout << "exp2(1024) = " << inf << '\n';
    if (is_range_error)
        std::cout << "    errno == ERANGE: " << std::strerror(ERANGE) << '\n';
    if (std::fetestexcept(FE_OVERFLOW))
        std::cout << "    FE_OVERFLOW raised\n";
}

Possible output: 

exp2(4) = 16
exp2(0.5) = 1.41421
exp2(-4) = 0.0625
exp2(-0) = 1
exp2(-Inf) = 0
exp2(1024) = inf
    errno == ERANGE: Numerical result out of range
    FE_OVERFLOW raised

[edit] See also

(C++11)(C++11)
 returns e raised to the given power (ex)
(function) [edit]
(C++11)(C++11)(C++11)
 returns e raised to the given power, minus one (ex-1)
(function) [edit]
(C++11)(C++11)
 multiplies a number by 2 raised to an integral power
(function) [edit]
(C++11)(C++11)(C++11)
 base 2 logarithm of the given number (log2(x))
(function) [edit]
C documentation for exp2
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/exp2&oldid=171857"