From a6cab031275157f7735d27c57d37d1d28549340a Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Wed, 30 Dec 2020 20:34:34 +0200 Subject: [PATCH] Add documentation for bit.hpp --- doc/bit.qbk | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/core.qbk | 1 + 2 files changed, 204 insertions(+) create mode 100644 doc/bit.qbk diff --git a/doc/bit.qbk b/doc/bit.qbk new file mode 100644 index 0000000..e8d5fce --- /dev/null +++ b/doc/bit.qbk @@ -0,0 +1,203 @@ +[/ + Copyright 2020 Peter Dimov + + Distributed under the Boost Software License, Version 1.0. + + See accompanying file LICENSE_1_0.txt + or copy at http://boost.org/LICENSE_1_0.txt +] + +[section:bit bit] + +[simplesect Authors] + +* Peter Dimov + +[endsimplesect] + +[section Header ] + +The header `` implements, in a portable way, +the C++20 `` header. + +[section Synopsis] + +`` +namespace boost +{ +namespace core +{ + +// bit_cast + +template +To bit_cast(From const& from) noexcept; + +// Integral powers of 2 + +template +constexpr bool has_single_bit(T x) noexcept; + +template +constexpr T bit_ceil(T x) noexcept; + +template +constexpr T bit_floor(T x) noexcept; + +template +constexpr T bit_width(T x) noexcept; + +// Rotating + +template +constexpr T rotl(T x, int s) noexcept; + +template +constexpr T rotr(T x, int s) noexcept; + +// Counting + +template +constexpr int countl_zero(T x) noexcept; + +template +constexpr int countl_one(T x) noexcept; + +template +constexpr int countr_zero(T x) noexcept; + +template +constexpr int countr_one(T x) noexcept; + +template +constexpr int popcount(T x) noexcept; + +// Endian + +enum class endian +{ + little = see below, + big = see below, + native = see below +}; + +using endian_type = endian; // portable alias for C++03 code + +} // namespace core +} // namespace boost +`` + +Note: even though the functions are shown as `constexpr` in the synopsis, since they are implemented +via compiler-specific intrinsics, portable code cannot generally rely on their being usable in a +constant expression context. + +[endsect] + +[section bit_cast] + +`template To bit_cast(From const& from) noexcept;` + +* *Requires:* `To` and `From` must be trivially copyable and `sizeof(To)` must be the same as `sizeof(From)`. +* *Returns:* A value of type `To` with the storage bytes copied from `from`. + +[endsect] + +[section Integral powers of 2] + +`template constexpr bool has_single_bit(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type (i.e. one of `unsigned char`, `unsigned short`, `unsigned int`, `unsigned long`, `unsigned long long`). +* *Returns:* `true` if `x` is an integral power of two, `false` otherwise. (`has_single_bit(0u)` is false.) + +`template constexpr T bit_ceil(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The smallest integral power of 2 greater than or equal to `x`. If this value is not representable in `T`, behavior is undefined. + +`template constexpr T bit_floor(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* If `x == 0`, 0; otherwise the maximal value `y` such that `has_single_bit(y)` is `true` and `y <= x`. + +`template constexpr T bit_width(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* If `x == 0`, 0; otherwise one plus the base-2 logarithm of `x`, with any fractional part discarded. + +[endsect] + +[section Rotating] + +In the following descriptions, `N` denotes `numeric_limits::digits` and `r` denotes `s % N`. + +`template constexpr T rotl(T x, int s) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* If `s` is negative, `rotr(x, -s)`; if `r` is 0, `x`; if `r` is positive, `(x << r) | (x >> (N - r))`. + +`template constexpr T rotr(T x, int s) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* If `s` is negative, `rotl(x, -s)`; if `r` is 0, `x`; if `r` is positive, `(x >> r) | (x << (N - r))`. + +[endsect] + +[section Counting] + +`template constexpr int countl_zero(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The number of consecutive 0 bits in the value of `x`, starting from the most significant ("left") bit. + +`template constexpr int countl_one(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The number of consecutive 1 bits in the value of `x`, starting from the most significant bit. + +`template constexpr int countr_zero(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The number of consecutive 0 bits in the value of `x`, starting from the least significant ("right") bit. + +`template constexpr int countr_one(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The number of consecutive 1 bits in the value of `x`, starting from the least significant bit. + +`template constexpr int popcount(T x) noexcept;` + +* *Requires:* `T` must be an unsigned integer type. +* *Returns:* The number of 1 bits in the value of `x`. + +[endsect] + +[section Endian] + +Under C++11, `endian` is defined as `enum class endian` as shown in the synopsis. Under C++03, its definition is + +`` +namespace endian +{ +enum type +{ + little = see below, + big = see below, + native = see below +}; +} + +typedef endian::type endian_type; +`` + +The values of `endian::big` and `endian::little` are distinct. `endian::native` is equal to `endian::big` on +big endian platforms, equal to `endian::little` on little endian platforms, and a distinct value on platforms +that are neither. + +Note that you should not rely on `little` and `big` having any specific values, because the C++20 standard +leaves these unspecified. + +[endsect] + +[endsect] + +[endsect] diff --git a/doc/core.qbk b/doc/core.qbk index 83a67f9..b8db584 100644 --- a/doc/core.qbk +++ b/doc/core.qbk @@ -41,6 +41,7 @@ criteria for inclusion is that the utility component be: [include addressof.qbk] [include allocator_access.qbk] [include alloc_construct.qbk] +[include bit.qbk] [include checked_delete.qbk] [include cmath.qbk] [include default_allocator.qbk]