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

Latest revision as of 21:46, 15 October 2023

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 $log r |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.

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

frexpfrexpffrexpl (C++11)(C++11)	decomposes a number into significand and base-2 exponent (function) [edit]
ilogbilogbfilogbl (C++11)(C++11)(C++11)	extracts exponent of the number (function) [edit]
scalbnscalbnfscalbnlscalblnscalblnfscalblnl (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

@@ Line 1: / Line 1: @@
-{{cpp/title|logb}}
+{{cpp/title|logb|logbf|logbl}}
-{{cpp/numeric/math/sidebar}}
+{{cpp/numeric/math/navbar}}
-{{ddcl list begin}}
+{{cpp/numeric/math/declarations
-{{ddcl list header | cmath}}
+|family=logb
-{{ddcl list item |notes={{mark since c++11}}|
+|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.
 }}
-{{ddcl list item |notes={{mark since c++11}}|
-double      logb( double arg );
-}}
-{{ddcl list item |notes={{mark since c++11}}|
-long double logb( long double arg );
-}}
-{{ddcl list item |notes={{mark since c++11}}|
-double      logb( Integral arg );
-}}
-{{ddcl list end}}
-Extracts the value of the exponent from the floating-point argument {{tt|arg}}, and returns it as a floating-point value. Formally, the result is the integral part of {{math|log{{su|b=r}}{{!}}arg{{!}}}} as a signed floating-point value, for non-zero arg, where {{tt|r}} is {{cpp|std::numeic_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===
-{{param list begin}}
+{{par begin}}
-{{param list item | arg | floating point value}}
+{{par|num|floating-point or integer value}}
-{{param list end}}
+{{par end}}
 ===Return value===
+If no errors occur, the unbiased exponent of {{c|num}} is returned as a signed floating-point value.
-The floating-point exponent.
+If a domain error occurs, an implementation-defined value is returned.
-Domain or range error may occur if {{tt|arg}} is zero.
+If a pole error occurs, {{lc|HUGE_VAL|-HUGE_VAL}}, {{tt|-HUGE_VALF}}, or {{tt|-HUGE_VALL}} is returned.
+===Error handling===
+Errors are reported as specified in {{lc|math_errhandling}}.
+Domain or range error may occur if {{c|num}} is zero.
+If the implementation supports IEEE floating-point arithmetic (IEC 60559),
+* If {{c|num}} is ±0, -∞ is returned and {{lc|FE_DIVBYZERO}} is raised.
+* If {{c|num}} is ±∞, +∞ 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.
 ===Notes===
-The value of the exponent returned by {{cpp|std::logb}} is always 1 less than the exponent retuned by {{cpp|std::frexp}} because of the different normalization requirements: for the exponent {{tt|e}} returned by {{cpp|std::logb}}, {{math|{{!}}arg*r{{su|p=-e}}{{!}}}} is between 1 and {{tt|r}} (typically between {{cpp|1}} and {{cpp|2}}), but for the exponent {{tt|e}} returned by {{cpp|std::frexp}}, {{math|{{!}}arg*2{{su|p=-e}}{{!}}}} is between {{cpp|0.5}} and {{cpp|1}}.
+[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 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 cpp
+{{example
- | Compares different floating-point decomposition functions
+|Compares different floating-point decomposition functions:
- | code=
+|code=
-#include <iostream>
+#include <cfenv>
 #include <cmath>
+#include <iostream>
 #include <limits>
+// #pragma STDC FENV_ACCESS ON
 int main()
 {
@@ Line 45: / Line 55: @@
      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::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";
 }
- | output=
+|p=true
+|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
 }}
 ===See also===
+{{dsc begin}}
+{{dsc inc|cpp/numeric/math/dsc frexp}}
+{{dsc inc|cpp/numeric/math/dsc ilogb}}
+{{dsc inc|cpp/numeric/math/dsc scalbn}}
+{{dsc see c|c/numeric/math/logb}}
+{{dsc end}}
-{{dcl list begin}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-{{dcl list template | cpp/numeric/math/dcl list frexp}}
-{{dcl list template | cpp/numeric/math/dcl list ilogb}}
-{{dcl list template | cpp/numeric/math/dcl list scalbn}}
-{{dcl list end}}

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)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

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

Latest revision as of 21:46, 15 October 2023

Contents

[edit] Parameters

[edit] Return value

[edit] Error handling

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox