Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | numeric‎ | math
m (Text replace - "Integral arg" to "IntegralType arg")
m (.)
 
(7 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{{cpp/title|logb}}
+
{{cpp/title|logb|logbf|logbl}}
 
{{cpp/numeric/math/navbar}}
 
{{cpp/numeric/math/navbar}}
−
{{dcl begin}}
+
{{cpp/numeric/math/declarations
−
{{dcl header | cmath}}
+
|family=logb
−
{{dcl | since=c++11 | num=1|
+
|param1=num
−
float      logb( float arg );
+
|constexpr_since=23
 +
|desc=Extracts the value of the unbiased radix-independent exponent from the floating-point argument {{c|num}}, and returns it as a floating-point value.
 
}}
 
}}
−
{{dcl | since=c++11 | num=2|
 
−
double      logb( double arg );
 
−
}}
 
−
{{dcl | since=c++11 | num=3|
 
−
long double logb( long double arg );
 
−
}}
 
−
{{dcl | since=c++11 | num=4|
 
−
double      logb( IntegralType arg );
 
−
}}
 
−
{{dcl end}}
 
−
 
−
@1-3@ Extracts the value of the unbiased radix-independent exponent from the floating-point argument {{tt|arg}}, and returns it as a floating-point value.
 
−
@4@ A set of overloads or a function template accepting an argument of any [[cpp/types/is_integral|integral type]]. Equivalent to {{v|2}} (the argument is cast to {{c|double}}).
 
  
−
Formally, the unbiased exponent is the signed integral part of {{math|log{{su|b=r}}{{!}}arg{{!}}}} (returned by this function as a floating-point value), for non-zero arg, where {{tt|r}} is {{c|std::numeric_limits<T>::radix}} and {{tt|T}} is the floating-point type of {{tt|arg}}. If {{tt|arg}} is subnormal, it is treated as though it was normalized.
+
Formally, the unbiased exponent is the signed integral part of {{math|log{{su|b=r}}{{!}}num{{!}}}} (returned by this function as a floating-point value), for non-zero {{c|num}}, where {{c|r}} is {{c|std::numeric_limits<T>::radix}} and {{tt|T}} is the floating-point type of {{c|num}}. If {{c|num}} is subnormal, it is treated as though it was normalized.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | arg | floating point value}}
+
{{par|num|floating-point or integer value}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
If no errors occur, the unbiased exponent of {{tt|arg}} is returned as a signed floating-point value.
+
If no errors occur, the unbiased exponent of {{c|num}} is returned as a signed floating-point value.
  
−
If a domain error occurs, an implementation-defined value is returned
+
If a domain error occurs, an implementation-defined value is returned.
  
−
If a pole error occurs, {{tt|-HUGE_VAL}}, {{tt|-HUGE_VALF}}, or {{tt|-HUGE_VALL}} is returned.
+
If a pole error occurs, {{lc|HUGE_VAL|-HUGE_VAL}}, {{tt|-HUGE_VALF}}, or {{tt|-HUGE_VALL}} is returned.
  
 
===Error handling===
 
===Error handling===
−
Errors are reported as specified in [[cpp/numeric/math/math_errhandling|math_errhandling]]
+
Errors are reported as specified in {{lc|math_errhandling}}.
  
−
Domain or range error may occur if {{tt|arg}} is zero.
+
Domain or range error may occur if {{c|num}} is zero.
  
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
−
* If {{tt|arg}} is ±0, -∞ is returned and {{lc|FE_DIVBYZERO}} is raised.
+
* If {{c|num}} is ±0, -∞ is returned and {{lc|FE_DIVBYZERO}} is raised.
−
* If {{tt|arg}} is ±∞, +∞ is returned
+
* If {{c|num}} is ±∞, +∞ is returned.
−
* If {{tt|arg}} is NaN, NaN is returned.
+
* If {{c|num}} is NaN, NaN is returned.
−
* In all other cases, the result is exact ({{lc|FE_INEXACT}} is never raised) and [[cpp/numeric/fenv/FE_round|the current rounding mode]] is ignored
+
* In all other cases, the result is exact ({{lc|FE_INEXACT}} is never raised) and [[cpp/numeric/fenv/FE_round|the current rounding mode]] is ignored.
  
 
===Notes===
 
===Notes===
−
[http://pubs.opengroup.org/onlinepubs/9699919799/functions/logb.html POSIX requires] that a pole error occurs if {{tt|arg}} is ±0.
+
[https://pubs.opengroup.org/onlinepubs/9699919799/functions/logb.html POSIX requires] that a pole error occurs if {{c|num}} is ±0.
  
−
The value of the exponent returned by {{tt|std::logb}} is always 1 less than the exponent retuned by {{lc|std::frexp}} because of the different normalization requirements: for the exponent {{tt|e}} returned by {{tt|std::logb}}, {{math|{{!}}arg*r{{su|p=-e}}{{!}}}} is between 1 and {{tt|r}} (typically between {{c|1}} and {{c|2}}), but for the exponent {{tt|e}} returned by {{lc|std::frexp}}, {{math|{{!}}arg*2{{su|p=-e}}{{!}}}} is between {{c|0.5}} and {{c|1}}.
+
The value of the exponent returned by {{tt|std::logb}} is always 1 less than the exponent returned by {{lc|std::frexp}} because of the different normalization requirements: for the exponent {{c|e}} returned by {{tt|std::logb}}, {{math|{{!}}num*r{{su|p=-e}}{{!}}}} is between {{c|1}} and {{c|r}} (typically between {{c|1}} and {{c|2}}), but for the exponent {{c|e}} returned by {{lc|std::frexp}}, {{math|{{!}}num*2{{su|p=-e}}{{!}}}} is between {{c|0.5}} and {{c|1}}.
 +
 
 +
{{cpp/numeric/math/additional integer overload note|logb}}
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| Compares different floating-point decomposition functions
+
|Compares different floating-point decomposition functions:
−
| code=
+
|code=
−
#include <iostream>
+
#include <cfenv>
 
#include <cmath>
 
#include <cmath>
 +
#include <iostream>
 
#include <limits>
 
#include <limits>
−
#include <cfenv>
+
// #pragma STDC FENV_ACCESS ON
−
#pragma STDC FENV_ACCESS ON
+
 
 
int main()
 
int main()
 
{
 
{
Line 64: Line 55:
 
     std::cout << "Given the number " << f << " or " << std::hexfloat
 
     std::cout << "Given the number " << f << " or " << std::hexfloat
 
               << f << std::defaultfloat << " in hex,\n";
 
               << f << std::defaultfloat << " in hex,\n";
−
 
+
   
 
     double f3;
 
     double f3;
 
     double f2 = std::modf(f, &f3);
 
     double f2 = std::modf(f, &f3);
 
     std::cout << "modf() makes " << f3 << " + " << f2 << '\n';
 
     std::cout << "modf() makes " << f3 << " + " << f2 << '\n';
−
 
+
   
 
     int i;
 
     int i;
 
     f2 = std::frexp(f, &i);
 
     f2 = std::frexp(f, &i);
 
     std::cout << "frexp() makes " << f2 << " * 2^" << i << '\n';
 
     std::cout << "frexp() makes " << f2 << " * 2^" << i << '\n';
−
 
+
   
 
     i = std::ilogb(f);
 
     i = std::ilogb(f);
−
     std::cout << "logb()/ilogb() make " << f/std::scalbn(1.0, i) << " * "
+
     std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * "
 
               << std::numeric_limits<double>::radix
 
               << std::numeric_limits<double>::radix
 
               << "^" << std::ilogb(f) << '\n';
 
               << "^" << std::ilogb(f) << '\n';
−
 
+
   
 
     // error handling
 
     // error handling
 
     std::feclearexcept(FE_ALL_EXCEPT);
 
     std::feclearexcept(FE_ALL_EXCEPT);
 +
   
 
     std::cout << "logb(0) = " << std::logb(0) << '\n';
 
     std::cout << "logb(0) = " << std::logb(0) << '\n';
−
     if(std::fetestexcept(FE_DIVBYZERO))
+
     if (std::fetestexcept(FE_DIVBYZERO))
 
         std::cout << "    FE_DIVBYZERO raised\n";
 
         std::cout << "    FE_DIVBYZERO raised\n";
 
}
 
}
−
| p=true
+
|p=true
−
| output=
+
|output=
 
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
 
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
 
modf() makes 123 + 0.45
 
modf() makes 123 + 0.45
Line 95: Line 87:
  
 
===See also===
 
===See also===
−
 
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/numeric/math/dsc frexp}}
+
{{dsc inc|cpp/numeric/math/dsc frexp}}
−
{{dsc inc | cpp/numeric/math/dsc ilogb}}
+
{{dsc inc|cpp/numeric/math/dsc ilogb}}
−
{{dsc inc | cpp/numeric/math/dsc scalbn}}
+
{{dsc inc|cpp/numeric/math/dsc scalbn}}
−
{{dsc see c | c/numeric/math/logb}}
+
{{dsc see c|c/numeric/math/logb}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/numeric/math/logb]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/numeric/math/logb]]
+
−
[[fr:cpp/numeric/math/logb]]
+
−
[[it:cpp/numeric/math/logb]]
+
−
[[ja:cpp/numeric/math/logb]]
+
−
[[pt:cpp/numeric/math/logb]]
+
−
[[ru:cpp/numeric/math/logb]]
+
−
[[zh:cpp/numeric/math/logb]]
+

Latest revision as of 21:46, 15 October 2023

 
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)
(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)
logb
(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       logb ( float num );

double      logb ( double num );

long double logb ( long double num );
 (until C++23)
constexpr /* floating-point-type */
            logb ( /* floating-point-type */ num );
 (since C++23)
float       logbf( float num );
 (2) (since C++11)
(constexpr since C++23)
long double logbl( long double num );
 (3) (since C++11)
(constexpr since C++23)
Additional overloads (since C++11)
Defined in header <cmath>
template< class Integer >
double      logb ( Integer num );
 (A) (constexpr since C++23)
1-3) Extracts the value of the unbiased radix-independent exponent from the floating-point argument num, and returns it as a floating-point value. The library provides overloads of std::logb 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)

Formally, the unbiased exponent is the signed integral part of logr|num| (returned by this function as a floating-point value), for non-zero num, where r is std::numeric_limits<T>::radix and T is the floating-point type of num. If num is subnormal, it is treated as though it was normalized.

Contents

[edit] Parameters

num - floating-point or integer value

[edit] Return value

If no errors occur, the unbiased exponent of num is returned as a signed floating-point value.

If a domain error occurs, an implementation-defined value is returned.

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

[edit] Error handling

Errors are reported as specified in math_errhandling.

Domain or range error may occur if num is zero.

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

  • If num is ±0, -∞ is returned and FE_DIVBYZERO is raised.
  • If num is ±∞, +∞ is returned.
  • If num is NaN, NaN is returned.
  • In all other cases, the result is exact (FE_INEXACT is never raised) and the current rounding mode is ignored.

[edit] Notes

POSIX requires that a pole error occurs if num is ±0.

The value of the exponent returned by std::logb is always 1 less than the exponent returned by std::frexp because of the different normalization requirements: for the exponent e returned by std::logb, |num*r-e| is between 1 and r (typically between 1 and 2), but for the exponent e returned by std::frexp, |num*2-e| is between 0.5 and 1.

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

[edit] Example

Compares different floating-point decomposition functions:

Run this code
#include <cfenv>
#include <cmath>
#include <iostream>
#include <limits>
// #pragma STDC FENV_ACCESS ON
 
int main()
{
    double f = 123.45;
    std::cout << "Given the number " << f << " or " << std::hexfloat
              << f << std::defaultfloat << " in hex,\n";
 
    double f3;
    double f2 = std::modf(f, &f3);
    std::cout << "modf() makes " << f3 << " + " << f2 << '\n';
 
    int i;
    f2 = std::frexp(f, &i);
    std::cout << "frexp() makes " << f2 << " * 2^" << i << '\n';
 
    i = std::ilogb(f);
    std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * "
              << std::numeric_limits<double>::radix
              << "^" << std::ilogb(f) << '\n';
 
    // error handling
    std::feclearexcept(FE_ALL_EXCEPT);
 
    std::cout << "logb(0) = " << std::logb(0) << '\n';
    if (std::fetestexcept(FE_DIVBYZERO))
        std::cout << "    FE_DIVBYZERO raised\n";
}

Possible output: 

Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
modf() makes 123 + 0.45
frexp() makes 0.964453 * 2^7
logb()/ilogb() make 1.92891 * 2^6
logb(0) = -Inf
    FE_DIVBYZERO raised

[edit] See also

(C++11)(C++11)
 decomposes a number into significand and base-2 exponent
(function) [edit]
(C++11)(C++11)(C++11)
 extracts exponent of the number
(function) [edit]
(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)
 multiplies a number by FLT_RADIX raised to a power
(function) [edit]
C documentation for logb
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/logb&oldid=160772"