Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/numeric/bit ceil"

From cppreference.com
< cpp‎ | numeric
m (→‎Example: C++2a is C++20, use P1956R1 instead)
m (fmt.)
 
(17 intermediate revisions by 6 users not shown)
Line 3: Line 3:
 
{{ddcl|since=c++20|header=bit|
 
{{ddcl|since=c++20|header=bit|
 
template< class T >
 
template< class T >
−
constexpr T bit_ceil(T x);
+
constexpr T bit_ceil( T x );
 
}}
 
}}
  
−
Calculates the smallest integral power of two that is not smaller than {{tt|x}}. If that value is not representable in {{tt|T}}, the behavior is undefined.
+
Calculates the smallest integral power of two that is not smaller than {{c|x}}.
  
−
This function is constexpr only if the result is representable in {{tt|T}}.
+
If that value is not representable in {{tt|T}}, the behavior is undefined. Call to this function is permitted in [[cpp/language/constant expression|constant evaluation]] only if the undefined behavior does not occur.
  
−
{{cpp/enable_if|{{tt|T}} is an unsigned integer type (that is, {{c|unsigned char}}, {{c|unsigned short}}, {{c|unsigned int}}, {{c|unsigned long}}, {{c|unsigned long long}}, or an extended unsigned integer type)}}.
+
{{cpp/enable_if|{{tt|T}} is an unsigned integer type (that is, {{c/core|unsigned char}}, {{c/core|unsigned short}}, {{c/core|unsigned int}}, {{c/core|unsigned long}}, {{c/core|unsigned long long}}, or an extended unsigned integer type)}}.
  
−
=== Parameters ===
+
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | x | values of unsigned integer type}}
+
{{par|x|value of unsigned integer type}}
 
{{par end}}
 
{{par end}}
  
−
=== Return value ===
+
===Return value===
−
The smallest integral power of two that is not smaller than {{tt|x}}.
+
The smallest integral power of two that is not smaller than {{c|x}}.
  
−
=== Exceptions ===
+
===Exceptions===
−
(none)
+
Throws nothing.
  
−
=== Example ===
+
===Notes===
 +
{{petty|Prior to {{stddoc|P1956R1}}, the proposed name for this function template was {{tt|ceil2}}.}}
 +
 
 +
{{feature test macro|__cpp_lib_int_pow2|std=C++20|value=202002L|[[cpp/numeric#Bit manipulation (since C++20)|Integral power-of-2 operations]]}}
 +
 
 +
===Possible implementation===
 +
See possible implementations in [https://github.com/gcc-mirror/gcc/blob/62c25d7adb1a5664982449dda0e7f9ca63cf4735/libstdc%2B%2B-v3/include/std/bit#L217-L248 libstdc++ (gcc)] and [https://github.com/llvm/llvm-project/blob/llvmorg-14.0.4/libcxx/include/bit#L304-L321 libc++ (clang)].
 +
{{eq fun|1=
 +
template<std::unsigned_integral T>
 +
    requires !std::same_as<T, bool> && !std::same_as<T, char> &&
 +
            !std::same_as<T, char8_t> && !std::same_as<T, char16_t> &&
 +
            !std::same_as<T, char32_t> && !std::same_as<T, wchar_t>
 +
constexpr T bit_ceil(T x) noexcept
 +
{
 +
    if (x <= 1u)
 +
        return T(1);
 +
    if constexpr (std::same_as<T, decltype(+x)>)
 +
        return T(1) << std::bit_width(T(x - 1));
 +
    else
 +
    {  // for types subject to integral promotion
 +
        constexpr int offset_for_ub =
 +
            std::numeric_limits<unsigned>::digits - std::numeric_limits<T>::digits;
 +
        return T(1u << (std::bit_width(T(x - 1)) + offset_for_ub) >> offset_for_ub);
 +
    }
 +
}
 +
}}
 +
 
 +
===Example===
 
{{example
 
{{example
−
|
+
|code=
−
| code=
+
 
#include <bit>
 
#include <bit>
 
#include <bitset>
 
#include <bitset>
 
#include <iostream>
 
#include <iostream>
  
−
auto main() -> int
+
int main()
 
{
 
{
 
     using bin = std::bitset<8>;
 
     using bin = std::bitset<8>;
−
 
+
     for (auto x{0U}; 0XA != x; ++x)
−
     for (unsigned x{0}; x != 10; ++x)
+
         std::cout << "bit_ceil( " << bin(x) << " ) = "
−
    {
+
                  << bin(std::bit_ceil(x)) << '\n';
−
        auto const z = std::bit_ceil(x); // `ceil2` before P1956R1
+
−
 
+
−
         std::cout << "bit_ceil(" << bin(x) << ") = " << bin(z) << '\n';
+
−
    }
+
 
}
 
}
−
| output=
+
|output=
−
bit_ceil(00000000) = 00000001
+
bit_ceil( 00000000 ) = 00000001
−
bit_ceil(00000001) = 00000001
+
bit_ceil( 00000001 ) = 00000001
−
bit_ceil(00000010) = 00000010
+
bit_ceil( 00000010 ) = 00000010
−
bit_ceil(00000011) = 00000100
+
bit_ceil( 00000011 ) = 00000100
−
bit_ceil(00000100) = 00000100
+
bit_ceil( 00000100 ) = 00000100
−
bit_ceil(00000101) = 00001000
+
bit_ceil( 00000101 ) = 00001000
−
bit_ceil(00000110) = 00001000
+
bit_ceil( 00000110 ) = 00001000
−
bit_ceil(00000111) = 00001000
+
bit_ceil( 00000111 ) = 00001000
−
bit_ceil(00001000) = 00001000
+
bit_ceil( 00001000 ) = 00001000
−
bit_ceil(00001001) = 00010000
+
bit_ceil( 00001001 ) = 00010000
 
}}
 
}}
  
−
{{langlinks|es|ja|zh}}
+
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/numeric/dsc bit_floor}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 13:49, 2 November 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)
bit_ceil
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++20)
 
Defined in header <bit>
template< class T >
constexpr T bit_ceil( T x );
 (since C++20)

Calculates the smallest integral power of two that is not smaller than x.

If that value is not representable in T, the behavior is undefined. Call to this function is permitted in constant evaluation only if the undefined behavior does not occur.

This overload participates in overload resolution only if T is an unsigned integer type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned long long, or an extended unsigned integer type).

Contents

[edit] Parameters

x - value of unsigned integer type

[edit] Return value

The smallest integral power of two that is not smaller than x.

[edit] Exceptions

Throws nothing.

[edit] Notes

Prior to P1956R1, the proposed name for this function template was ceil2.

Feature-test macro Value Std Feature
__cpp_lib_int_pow2 202002L (C++20) Integral power-of-2 operations

[edit] Possible implementation

See possible implementations in libstdc++ (gcc) and libc++ (clang). 

template<std::unsigned_integral T>
    requires !std::same_as<T, bool> && !std::same_as<T, char> &&
             !std::same_as<T, char8_t> && !std::same_as<T, char16_t> &&
             !std::same_as<T, char32_t> && !std::same_as<T, wchar_t>
constexpr T bit_ceil(T x) noexcept
{
    if (x <= 1u)
        return T(1);
    if constexpr (std::same_as<T, decltype(+x)>)
        return T(1) << std::bit_width(T(x - 1));
    else
    {   // for types subject to integral promotion
        constexpr int offset_for_ub =
            std::numeric_limits<unsigned>::digits - std::numeric_limits<T>::digits;
        return T(1u << (std::bit_width(T(x - 1)) + offset_for_ub) >> offset_for_ub);
    }
}

[edit] Example

Run this code
#include <bit>
#include <bitset>
#include <iostream>
 
int main()
{
    using bin = std::bitset<8>;
    for (auto x{0U}; 0XA != x; ++x)
        std::cout << "bit_ceil( " << bin(x) << " ) = "
                  << bin(std::bit_ceil(x)) << '\n';
}

Output: 

bit_ceil( 00000000 ) = 00000001
bit_ceil( 00000001 ) = 00000001
bit_ceil( 00000010 ) = 00000010
bit_ceil( 00000011 ) = 00000100
bit_ceil( 00000100 ) = 00000100
bit_ceil( 00000101 ) = 00001000
bit_ceil( 00000110 ) = 00001000
bit_ceil( 00000111 ) = 00001000
bit_ceil( 00001000 ) = 00001000
bit_ceil( 00001001 ) = 00010000

[edit] See also

(C++20)
 finds the largest integral power of two not greater than the given value
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/bit_ceil&oldid=177492"