Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | numeric‎ | math
m (Minor fix.)
m (., http -> https)
 
Line 58: Line 58:
 
A domain error or range error may occur if {{c|num}} is zero, infinite, or NaN.
 
A domain error or range error may occur if {{c|num}} is zero, infinite, or NaN.
  
−
If the correct result is greater than {{lc|INT_MAX}} or smaller than {{lc|INT_MIN}}, a domain error or a range error may occur.<!-- this is DR 410 against C11, which makes the wording match lrint and lround -->
+
If the correct result is greater than {{lc|INT_MAX}} or smaller than {{lc|INT_MIN}}, a domain error or a range error may occur.<!--this is DR 410 against C11, which makes the wording match lrint and lround-->
  
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
 
If the implementation supports IEEE floating-point arithmetic (IEC 60559),
Line 66: Line 66:
  
 
===Notes===
 
===Notes===
−
If {{c|num}} is not zero, infinite, or NaN, the value returned is exactly equivalent to {{c|static_cast<int>(std::logb(num))}}
+
If {{c|num}} is not zero, infinite, or NaN, the value returned is exactly equivalent to {{c|static_cast<int>(std::logb(num))}}.
  
−
[http://pubs.opengroup.org/onlinepubs/9699919799/functions/ilogb.html POSIX requires] that a domain error occurs if {{c|num}} is zero, infinite, NaN, or if the correct result is outside of the range of {{c/core|int}}.
+
[https://pubs.opengroup.org/onlinepubs/9699919799/functions/ilogb.html POSIX requires] that a domain error occurs if {{c|num}} is zero, infinite, NaN, or if the correct result is outside of the range of {{c/core|int}}.
  
 
POSIX also requires that, on XSI-conformant systems, the value returned when the correct result is greater than {{lc|INT_MAX}} is {{lc|INT_MAX}} and the value returned when the correct result is less than {{lc|INT_MIN}} is {{lc|INT_MIN}}.
 
POSIX also requires that, on XSI-conformant systems, the value returned when the correct result is greater than {{lc|INT_MAX}} is {{lc|INT_MAX}} and the value returned when the correct result is less than {{lc|INT_MIN}} is {{lc|INT_MIN}}.

Latest revision as of 22:22, 14 September 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)
ilogb
(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)
int ilogb ( float num );

int ilogb ( double num );

int ilogb ( long double num );
 (since C++11)
(until C++23)
constexpr int ilogb( /* floating-point-type */ num );
 (since C++23)
int ilogbf( float num );
 (2) (since C++11)
(constexpr since C++23)
int ilogbl( long double num );
 (3) (since C++11)
(constexpr since C++23)
#define FP_ILOGB0   /* implementation-defined */
 (4) (since C++11)
#define FP_ILOGBNAN /* implementation-defined */
 (5) (since C++11)
Defined in header <cmath>
template< class Integer >
int ilogb ( Integer num );
 (A) (since C++11)
(constexpr since C++23)
1-3) Extracts the value of the unbiased exponent from the floating-point argument num, and returns it as a signed integer value. The library provides overloads of std::ilogb for all cv-unqualified floating-point types as the type of the parameter num.(since C++23)
4) Expands to integer constant expression whose value is either INT_MIN or -INT_MAX.
5) Expands to integer constant expression whose value is either INT_MIN or +INT_MAX.
A) Additional overloads are provided for all integer types, which are treated as double.

Formally, the unbiased exponent is the integral part of logr|num| as a signed integral value, for non-zero num, where r is std::numeric_limits<T>::radix and T is the floating-point type of num.

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 int value.

If num is zero, FP_ILOGB0 is returned.

If num is infinite, INT_MAX is returned.

If num is a NaN, FP_ILOGBNAN is returned.

If the correct result is greater than INT_MAX or smaller than INT_MIN, the return value is unspecified.

[edit] Error handling

Errors are reported as specified in math_errhandling.

A domain error or range error may occur if num is zero, infinite, or NaN.

If the correct result is greater than INT_MAX or smaller than INT_MIN, a domain error or a range error may occur.

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

[edit] Notes

If num is not zero, infinite, or NaN, the value returned is exactly equivalent to static_cast<int>(std::logb(num)).

POSIX requires that a domain error occurs if num is zero, infinite, NaN, or if the correct result is outside of the range of int.

POSIX also requires that, on XSI-conformant systems, the value returned when the correct result is greater than INT_MAX is INT_MAX and the value returned when the correct result is less than INT_MIN is INT_MIN.

The correct result can be represented as int on all known implementations. For overflow to occur, INT_MAX must be less than LDBL_MAX_EXP * std::log2(FLT_RADIX) or INT_MIN must be greater than LDBL_MIN_EXP - LDBL_MANT_DIG) * std::log2(FLT_RADIX).

The value of the exponent returned by std::ilogb is always 1 less than the exponent retuned by std::frexp because of the different normalization requirements: for the exponent e returned by std::ilogb, |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::ilogb(num) has the same effect as std::ilogb(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 << "ilogb(0) = " << std::ilogb(0) << '\n';
    if (std::fetestexcept(FE_INVALID))
        std::cout << "    FE_INVALID 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
ilogb(0) = -2147483648
    FE_INVALID 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 ilogb
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/ilogb&oldid=159057"