Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | numeric‎ | math
m (link swap)
(+detail, example)
Line 3: Line 3:
 
{{dcl begin}}
 
{{dcl begin}}
 
{{dcl header | cmath}}
 
{{dcl header | cmath}}
−
{{dcl | since=c++11 |
+
{{dcl | since=c++11 |num=1 |
 
float      expm1( float arg );
 
float      expm1( float arg );
 
}}
 
}}
−
{{dcl | since=c++11 |
+
{{dcl | since=c++11 |num=2 |
 
double      expm1( double arg );
 
double      expm1( double arg );
 
}}
 
}}
−
{{dcl | since=c++11 |
+
{{dcl | since=c++11 |num=3 |
 
long double expm1( long double arg );
 
long double expm1( long double arg );
 
}}
 
}}
−
{{dcl | since=c++11 |
+
{{dcl | since=c++11 |num=4 |
 
double      expm1( Integral arg );
 
double      expm1( Integral arg );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Computes the ''e'' (Euler's number, {{tt|2.7182818}}) raised to the given power {{tt|arg}}, minus {{c|1}}. This function is more accurate than the expression {{c|std::exp(arg)-1}} if {{tt|arg}} is close to zero.
+
@1-3@ Computes the ''e'' (Euler's number, {{tt|2.7182818}}) raised to the given power {{tt|arg}}, minus {{c|1.0}}. This function is more accurate than the expression {{c|std::exp(arg)-1.0}} if {{tt|arg}} is close to zero.
 +
@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===
Line 25: Line 26:
  
 
===Return value===
 
===Return value===
−
{{math|e{{su|p=arg}}-1}}
+
If no errors occur {{math|e{{su|p=arg}}-1}} is returned.
  
−
If the result is too large for the underlying type, range error occurs and {{lc|HUGE_VAL}} 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 occurs due to underflow, the correct result (after rounding) is returned.
 +
 
 +
===Error handling===
 +
Errors are reported as specified in [[cpp/numeric/math/math_errhandling|math_errhandling]]
 +
 
 +
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
 +
* If the argument is ±0, it is returned, unmodified
 +
* If the argument is -∞, -1 is returned
 +
* If the argument is +∞, +∞ is returned
 +
* If the argument is NaN, NaN is returned
 +
 
 +
===Notes===
 +
The functions {{tt|std::expm1}} and {{lc|std::log1p}} are useful for financial calculations, for example, when calculating small daily interest rates: {{math|(1+x){{su|p=n}}-1}} can be expressed as {{c|std::expm1(n * std::log1p(x))}}. These functions also simplify writing accurate inverse hyperbolic functions.
 +
 
 +
For IEEE-compatible type {{c|double}}, overflow is guaranteed if {{math|709.8 < arg}}
 +
 
 +
===Example===
 +
{{example |
 +
| code=
 +
#include <iostream>
 +
#include <cmath>
 +
#include <cerrno>
 +
#include <cstring>
 +
#include <cfenv>
 +
#pragma STDC FENV_ACCESS ON
 +
int main()
 +
{
 +
    std::cout << "expm1(1) = " << std::expm1(1) << '\n'
 +
              << "FV of $100, compounded daily at 1%\n"
 +
              << "on a 30/360 calendar for 30 years = "
 +
              << 100*(1+std::expm1(360*30*std::log1p(0.01/360))) << '\n'
 +
              << "exp(1e-16)-1 = " << std::exp(1e16)-1
 +
              << ", but expm1(1e-16) = " << expm1(1e-16) << '\n';
 +
    // special values
 +
    std::cout << "expm1(-0) = " << std::expm1(-0.0) << '\n'
 +
              << "expm1(-Inf) = " << std::expm1(-INFINITY) << '\n';
 +
    // error handling
 +
    errno=0; std::feclearexcept(FE_ALL_EXCEPT);
 +
    std::cout << "expm1(710) = " << std::expm1(710) << '\n';
 +
    if(errno == ERANGE)
 +
        std::cout << "    errno == ERANGE: " << std::strerror(errno) << '\n';
 +
    if(std::fetestexcept(FE_OVERFLOW))
 +
        std::cout << "    FE_OVERFLOW raised\n";
 +
}
 +
| p=true
 +
| output=
 +
expm1(1) = 1.71828
 +
FV of $100, compounded daily at 1%
 +
on a 30/360 calendar for 30 years = 134.985
 +
exp(1e-16)-1 = inf, but expm1(1e-16) = 1e-16
 +
expm1(-0) = -0
 +
expm1(-Inf) = -1
 +
expm1(710) = inf
 +
    errno == ERANGE: Result too large
 +
    FE_OVERFLOW raised
 +
}}
  
 
===See also===
 
===See also===

Revision as of 11:44, 2 June 2014

 
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
(C++11)
expm1
(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>
float       expm1( float arg );
 (1) (since C++11)
double      expm1( double arg );
 (2) (since C++11)
long double expm1( long double arg );
 (3) (since C++11)
double      expm1( Integral arg );
 (4) (since C++11)
1-3) Computes the e (Euler's number, 2.7182818) raised to the given power arg, minus 1.0. This function is more accurate than the expression std::exp(arg)-1.0 if arg is close to zero.
4) A set of overloads or a function template accepting an argument of any integral type. Equivalent to 2) (the argument is cast to double).

Contents

Parameters

arg - value of floating-point or Integral type

Return value

If no errors occur earg-1 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.

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, it is returned, unmodified
  • If the argument is -∞, -1 is returned
  • If the argument is +∞, +∞ is returned
  • If the argument is NaN, NaN is returned

Notes

The functions std::expm1 and std::log1p are useful for financial calculations, for example, when calculating small daily interest rates: (1+x)n-1 can be expressed as std::expm1(n * std::log1p(x)). These functions also simplify writing accurate inverse hyperbolic functions.

For IEEE-compatible type double, overflow is guaranteed if 709.8 < arg

Example

Run this code
#include <iostream>
#include <cmath>
#include <cerrno>
#include <cstring>
#include <cfenv>
#pragma STDC FENV_ACCESS ON
int main()
{
    std::cout << "expm1(1) = " << std::expm1(1) << '\n'
              << "FV of $100, compounded daily at 1%\n"
              << "on a 30/360 calendar for 30 years = "
              << 100*(1+std::expm1(360*30*std::log1p(0.01/360))) << '\n'
              << "exp(1e-16)-1 = " << std::exp(1e16)-1
              << ", but expm1(1e-16) = " << expm1(1e-16) << '\n';
    // special values
    std::cout << "expm1(-0) = " << std::expm1(-0.0) << '\n'
              << "expm1(-Inf) = " << std::expm1(-INFINITY) << '\n';
    // error handling
    errno=0; std::feclearexcept(FE_ALL_EXCEPT);
    std::cout << "expm1(710) = " << std::expm1(710) << '\n';
    if(errno == ERANGE)
        std::cout << "    errno == ERANGE: " << std::strerror(errno) << '\n';
    if(std::fetestexcept(FE_OVERFLOW))
        std::cout << "    FE_OVERFLOW raised\n";
}

Possible output: 

expm1(1) = 1.71828
FV of $100, compounded daily at 1%
on a 30/360 calendar for 30 years = 134.985
exp(1e-16)-1 = inf, but expm1(1e-16) = 1e-16
expm1(-0) = -0
expm1(-Inf) = -1
expm1(710) = inf
    errno == ERANGE: Result too large
    FE_OVERFLOW raised

See also

(C++11)(C++11)
 returns e raised to the given power (ex)
(function) [edit]
(C++11)(C++11)(C++11)
 returns 2 raised to the given power (2x)
(function) [edit]
(C++11)(C++11)(C++11)
 natural logarithm (to base e) of 1 plus the given number (ln(1+x))
(function) [edit]
C documentation for expm1
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/expm1&oldid=70913"