martinmoene/bit-lite

bit-lite - C++20 bit operations for C++98 and later in a single-file header-only library

bit-lite - C++20 bit operations for C++98 and later in a single-file header-only library.

Contents

• Example usage
• In a nutshell
• License
• Dependencies
• Installation
• Synopsis
• Features
• Reported to work with
• Building the tests
• Other implementations of bit
• Notes and references
• Appendix

Example usage

#include "nonstd/bit.hpp"
#include <iostream>

using namespace nonstd;

int main()
{
    std::cout
        << "Consecutive ones at the right in 0x17: " << countr_one( 0x17u )
        << "\nBit width of 0x13: " << bit_width( 0x13u ) << '\n';
}

Compile and run

prompt> g++ -Wall -I../include -o 01-basic.exe 01-basic.cpp && 01-basic.exe
Consecutive ones at the right in 0x17: 3
Bit width of 0x13: 5

In a nutshell

bit lite is a single-file header-only library to provide the tools from the C++20 header <bit> for use with C++98 and later. If available, the standard header is used, unless configured otherwise.

Features and properties of bit lite are ease of installation (single header), freedom of dependencies other than the standard library.

Limitations of bit lite are ... .

License

bit lite is distributed under the Boost Software License.

Dependencies

bit lite has no other dependencies than the C++ standard library.

Installation

bit lite is a single-file header-only library. Put bit.hpp in the include folder directly into the project source tree or somewhere reachable from your project.

Synopsis

Contents

Documentation of standard header <bit>
Non-standard extensions
Configuration

Documentation of standard header <bit>

Depending on the compiler and C++-standard used, bit lite behaves less or more like C++20 standard <bit>. To get an idea of the capabilities of bit lite with your configuration, look at the output of the tests, issuing bit-main.t --pass @. For C++20 standard <bit>, see its documentation at cppreference.

Non-standard extensions

Kind	Extension type or function	Notes
Type	big_endian_type	type based on endian::big
	little_endian_type	type based on endian::little
	native_endian_type	type based on endian::native
Free function	template<class T> T to_big_endian(T v)	convert unconditionally
	template<class T, class EN> T to_big_endian(T v, EN)	convert if EN is little_endian_type EN specifies endianness of v
	template<class T> T to_little_endian(T v)	convert unconditionally
	template<class T, class EN> T to_little_endian(T v, EN)	convert if EN is big_endian_type EN specifies endianness of v
	template<class T> T to_native_endian(T v)	identity
	template<class T, class EN> T to_native_endian(T v, EN)	convert if EN represents non-native endianness for v
	template<class T> T as_big_endian(T v)	convert if native is little endian
	template<class T> T as_little_endian(T v)	convert if native is big endian
	template<class T> T as_native_endian(T v)	identity

Configuration

Standard selection macro

-Dbit_CPLUSPLUS=199711L
Define this macro to override the auto-detection of the supported C++ standard, if your compiler does not set the __cplusplus macro correctly.

Select C++20 standard <bit> or nonstd <bit>

At default, bit lite uses the C++20 standard header <bit> if it is available and lets you use it via namespace nonstd. You can however override this default and explicitly request to use the standard C++20 header or bit lite's header via the following macros.

-Dbit_CONFIG_SELECT_BIT=bit_BIT_DEFAULT
Define this to bit_BIT_STD to select C++20 standard header <bit>. Define this to bit_BIT_NONSTD to select bit lite. Default is undefined, which has the same effect as defining to bit_BIT_DEFAULT.

Strict C++20 mode

-Dbit_CONFIG_STRICT=1
Define this to 1 to omit the non C++20 standard extensions. Default is undefined, which has the same effect as 0, non-strict mode.

Reported to work with

TBD

Building the tests

TBD

Other implementations of <bit>

TBD

Notes and references

Interface and specification

• Cppreference. Header <bit>
• Cppreference. bit_cast
• Cppreference. enum class endian

Proposals

• p0463 - endendian, Just endian. Howard E. Hinnant. 2017.
• p0476 - Bit-casting object representations. JF Bastien. 2017.
• p0553 - Bit operations. Jens Maurer. 2019.

Articles

• Overload 160. What is the Strict Aliasing Rule and Why Do We Care?. Anonymous. December 2020.

Appendix

The test program provides information on the compiler, the C++ language and library capabilities and the tests performed.

A.1 Compile-time information

The version of bit lite is available via tag [.version]. The following tags are available for information on the compiler and on the C++ standard library used: [.compiler], [.stdc++], [.stdlanguage] and [.stdlibrary].

A.2 Bit lite test specification

bit_cast<>(): successfully roundtrips uint64_t via double [bit.cast]
has_single_bit(): single bit yields false for no bits set [bit.pow.two]
has_single_bit(): single bit yields true for single bits set [bit.pow.two]
has_single_bit(): single bit yields false for multiple bits set [bit.pow.two]
bit_ceil(): let N be the smallest power of 2 greater than or equal to x [bit.pow.two]
bit_floor(): x == 0, 0; otherwise the maximal value y such that has_single_bit(y) is true and y <= x [bit.pow.two]
bit_width: x == 0, 0; otherwise one plus the base-2 logarithm of x, with any fractional part discarded [bit.pow.two]
rotl(): r is 0, x; if r is positive, (x << r) | (x >> (N - r)); if r is negative, rotr(x, -r) [bit.rotate]
rotr(): r is 0, x; if r is positive, (x >> r) | (x << (N - r)); if r is negative, rotl(x, -r) [bit.rotate]
countl_zero(): the number of consecutive 0 bits in the value of x, starting from the most significant bit [bit.count]
countl_one(): the number of consecutive 1 bits in the value of x, starting from the most significant bit [bit.count]
countr_zero(): the number of consecutive 0 bits in the value of x, starting from the least significant bit [bit.count]
countr_one(): the number of consecutive 1 bits in the value of x, starting from the least significant bit [bit.count]
popcount(): the number of 1 bits in the value of x [bit.count]
endian: little differs from big (corner-case when all scalars have size of 1 byte) [bit.endian]
to_big_endian(): convert native, or little or big endian specified unsigned to big endian [bit.endian.extension]
to_little_endian(): convert native, or little or big endian specified unsigned to little endian [bit.endian.extension]
to_native_endian(): convert native, or little or big endian specified unsigned to native endian [bit.endian.extension]
as_big_endian(): provide native unsigned as big endian [bit.endian.extension]
as_little_endian(): provide native unsigned as little endian [bit.endian.extension]
as_native_endian(): provide native unsigned as native endian (identity) [bit.endian.extension]