[bit] - C++17 → C++20

Files changed (1) hide show

tmp/tmpo0bbyz2a/{from.md → to.md} +252 -0

tmp/tmpo0bbyz2a/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,252 @@

+## Bit manipulation <a id="bit">[[bit]]</a>
+### General <a id="bit.general">[[bit.general]]</a>
+The header `<bit>` provides components to access, manipulate and process
+both individual bits and bit sequences.
+### Header `<bit>` synopsis <a id="bit.syn">[[bit.syn]]</a>
+``` cpp
+namespace std {
+  // [bit.cast], bit_cast
+  template<class To, class From>
+    constexpr To bit_cast(const From& from) noexcept;
+  // [bit.pow.two], integral powers of 2
+  template<class T>
+    constexpr bool has_single_bit(T x) noexcept;
+  template<class T>
+    constexpr T bit_ceil(T x);
+  template<class T>
+    constexpr T bit_floor(T x) noexcept;
+  template<class T>
+    constexpr T bit_width(T x) noexcept;
+  // [bit.rotate], rotating
+  template<class T>
+    [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
+  template<class T>
+    [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
+  // [bit.count], counting
+  template<class T>
+    constexpr int countl_zero(T x) noexcept;
+  template<class T>
+    constexpr int countl_one(T x) noexcept;
+  template<class T>
+    constexpr int countr_zero(T x) noexcept;
+  template<class T>
+    constexpr int countr_one(T x) noexcept;
+  template<class T>
+    constexpr int popcount(T x) noexcept;
+  // [bit.endian], endian
+  enum class endian {
+    little = see below,
+    big    = see below,
+    native = see below
+  };
+}
+```
+### Function template `bit_cast` <a id="bit.cast">[[bit.cast]]</a>
+``` cpp
+template<class To, class From>
+  constexpr To bit_cast(const From& from) noexcept;
+```
+*Constraints:*
+- `sizeof(To) == sizeof(From)` is `true`;
+- `is_trivially_copyable_v<To>` is `true`; and
+- `is_trivially_copyable_v<From>` is `true`.
+*Returns:* An object of type `To`. Implicitly creates objects nested
+within the result [[intro.object]]. Each bit of the value representation
+of the result is equal to the corresponding bit in the object
+representation of `from`. Padding bits of the result are unspecified.
+For the result and each object created within it, if there is no value
+of the object’s type corresponding to the value representation produced,
+the behavior is undefined. If there are multiple such values, which
+value is produced is unspecified.
+*Remarks:* This function is `constexpr` if and only if `To`, `From`, and
+the types of all subobjects of `To` and `From` are types `T` such that:
+- `is_union_v<T>` is `false`;
+- `is_pointer_v<T>` is `false`;
+- `is_member_pointer_v<T>` is `false`;
+- `is_volatile_v<T>` is `false`; and
+- `T` has no non-static data members of reference type.
+### Integral powers of 2 <a id="bit.pow.two">[[bit.pow.two]]</a>
+``` cpp
+template<class T>
+  constexpr bool has_single_bit(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* `true` if `x` is an integral power of two; `false` otherwise.
+``` cpp
+template<class T>
+  constexpr T bit_ceil(T x);
+```
+Let N be the smallest power of 2 greater than or equal to `x`.
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Preconditions:* N is representable as a value of type `T`.
+*Returns:* N.
+*Throws:* Nothing.
+*Remarks:* A function call expression that violates the precondition in
+the *Preconditions:* element is not a core constant
+expression [[expr.const]].
+``` cpp
+template<class T>
+  constexpr T bit_floor(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* If `x == 0`, `0`; otherwise the maximal value `y` such that
+`has_single_bit(y)` is `true` and `y <= x`.
+``` cpp
+template<class T>
+  constexpr T bit_width(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* If `x == 0`, `0`; otherwise one plus the base-2 logarithm of
+`x`, with any fractional part discarded.
+### Rotating <a id="bit.rotate">[[bit.rotate]]</a>
+In the following descriptions, let `N` denote
+`numeric_limits<T>::digits`.
+``` cpp
+template<class T>
+  [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+Let `r` be `s % N`.
+*Returns:* If `r` is `0`, `x`; if `r` is positive,
+`(x << r) | (x >> (N - r))`; if `r` is negative, `rotr(x, -r)`.
+``` cpp
+template<class T>
+  [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+Let `r` be `s % N`.
+*Returns:* If `r` is `0`, `x`; if `r` is positive,
+`(x >> r) | (x << (N - r))`; if `r` is negative, `rotl(x, -r)`.
+### Counting <a id="bit.count">[[bit.count]]</a>
+In the following descriptions, let `N` denote
+`numeric_limits<T>::digits`.
+``` cpp
+template<class T>
+  constexpr int countl_zero(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* The number of consecutive `0` bits in the value of `x`,
+starting from the most significant bit.
+[*Note 1*: Returns `N` if `x == 0`. — *end note*]
+``` cpp
+template<class T>
+  constexpr int countl_one(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* The number of consecutive `1` bits in the value of `x`,
+starting from the most significant bit.
+[*Note 2*: Returns `N` if
+`x == numeric_limits<T>::max()`. — *end note*]
+``` cpp
+template<class T>
+  constexpr int countr_zero(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* The number of consecutive `0` bits in the value of `x`,
+starting from the least significant bit.
+[*Note 3*: Returns `N` if `x == 0`. — *end note*]
+``` cpp
+template<class T>
+  constexpr int countr_one(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* The number of consecutive `1` bits in the value of `x`,
+starting from the least significant bit.
+[*Note 4*: Returns `N` if
+`x == numeric_limits<T>::max()`. — *end note*]
+``` cpp
+template<class T>
+  constexpr int popcount(T x) noexcept;
+```
+*Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
+*Returns:* The number of `1` bits in the value of `x`.
+### Endian <a id="bit.endian">[[bit.endian]]</a>
+Two common methods of byte ordering in multibyte scalar types are
+big-endian and little-endian in the execution environment. Big-endian is
+a format for storage of binary data in which the most significant byte
+is placed first, with the rest in descending order. Little-endian is a
+format for storage of binary data in which the least significant byte is
+placed first, with the rest in ascending order. This subclause describes
+the endianness of the scalar types of the execution environment.
+``` cpp
+enum class endian {
+  little = see below,
+  big    = see below,
+  native = see below
+};
+```
+If all scalar types have size 1 byte, then all of `endian::little`,
+`endian::big`, and `endian::native` have the same value. Otherwise,
+`endian::little` is not equal to `endian::big`. If all scalar types are
+big-endian, `endian::native` is equal to `endian::big`. If all scalar
+types are little-endian, `endian::native` is equal to `endian::little`.
+Otherwise, `endian::native` is not equal to either `endian::big` or
+`endian::little`.

Diff to HTML by rtfpessoa