Skip to content

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

License

Notifications You must be signed in to change notification settings

martinmoene/bit-lite

Repository files navigation

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

Language License Build Status Build status Version download Conan Try it online Try it on godbolt online

Contents

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

Proposals

Articles

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]