core.bitop

This module contains a collection of bit-level operations.

License:

Boost License 1.0

Authors:

Don Clugston, Sean Kelly, Walter Bright, Alex Rønne Petersen, Thomas Stuart Bockman

Source

core/bitop.d

pure nothrow @nogc @safe int bsf(uint v);

pure nothrow @nogc @safe int bsf(ulong v);

Scans the bits in v starting with bit 0, looking for the first set bit.

Returns:

The bit number of the first bit set. The return value is undefined if v is zero.

Examples:

assert(bsf(0x21) == 0);
assert(bsf(ulong.max << 39) == 39);

pure nothrow @nogc @safe int bsr(uint v);

pure nothrow @nogc @safe int bsr(ulong v);

Scans the bits in v from the most significant bit to the least significant bit, looking for the first set bit.

Returns:

The bit number of the first bit set. The return value is undefined if v is zero.

Examples:

assert(bsr(0x21) == 5);
assert(bsr((ulong.max >> 15) - 1) == 48);

pure nothrow @nogc @system int bt(scope const size_t* p, size_t bitnum);

Tests the bit. (No longer an intrisic - the compiler recognizes the patterns in the body.)

Examples:

size_t[2] array;

array[0] = 2;
array[1] = 0x100;

assert(bt(array.ptr, 1));
assert(array[0] == 2);
assert(array[1] == 0x100);

pure nothrow @nogc @system int btc(size_t* p, size_t bitnum);

Tests and complements the bit.

pure nothrow @nogc @system int btr(size_t* p, size_t bitnum);

Tests and resets (sets to 0) the bit.

pure nothrow @nogc @system int bts(size_t* p, size_t bitnum);

Tests and sets the bit.

Parameters:

size_t* p	a non-NULL pointer to an array of size_ts.
size_t bitnum	a bit number, starting with bit 0 of p[0], and progressing. It addresses bits like the expression: p[index / (size_t.sizeof*8)] & (1 << (index & ((size_t.sizeof*8) - 1)))

Returns:

A non-zero value if the bit was set, and a zero if it was clear.

Examples:

size_t[2] array;

array[0] = 2;
array[1] = 0x100;

assert(btc(array.ptr, 35) == 0);
if (size_t.sizeof == 8)
{
    assert(array[0] == 0x8_0000_0002);
    assert(array[1] == 0x100);
}
else
{
    assert(array[0] == 2);
    assert(array[1] == 0x108);
}

assert(btc(array.ptr, 35));
assert(array[0] == 2);
assert(array[1] == 0x100);

assert(bts(array.ptr, 35) == 0);
if (size_t.sizeof == 8)
{
    assert(array[0] == 0x8_0000_0002);
    assert(array[1] == 0x100);
}
else
{
    assert(array[0] == 2);
    assert(array[1] == 0x108);
}

assert(btr(array.ptr, 35));
assert(array[0] == 2);
assert(array[1] == 0x100);

struct BitRange;

Range over bit set. Each element is the bit number that is set.

This is more efficient than testing each bit in a sparsely populated bit set. Note that the first bit in the bit set would be bit 0.

Examples:

import core.stdc.stdlib : malloc, free;
import core.stdc.string : memset;

// initialize a bit array
enum nBytes = (100 + BitRange.bitsPerWord - 1) / 8;
size_t *bitArr = cast(size_t *)malloc(nBytes);
scope(exit) free(bitArr);
memset(bitArr, 0, nBytes);

// set some bits
bts(bitArr, 48);
bts(bitArr, 24);
bts(bitArr, 95);
bts(bitArr, 78);

enum sum = 48 + 24 + 95 + 78;

// iterate
size_t testSum;
size_t nBits;
foreach (b; BitRange(bitArr, 100))
{
    testSum += b;
    ++nBits;
}

assert(testSum == sum);
assert(nBits == 4);

enum ulong bitsPerWord;

Number of bits in each size_t

pure nothrow @nogc @system this(const(size_t)* bitarr, size_t numBits);

Construct a BitRange.

Parameters:

const(size_t)* bitarr	The array of bits to iterate over
size_t numBits	The total number of valid bits in the given bit array

pure nothrow @nogc @safe size_t front();

const pure nothrow @nogc @safe bool empty();

pure nothrow @nogc @system void popFront();

Range functions

pure nothrow @nogc @safe ushort byteswap(ushort x);

Swaps bytes in a 2 byte ushort.

Parameters:

ushort x

value

Returns:

x with bytes swapped

Examples:

assert(byteswap(cast(ushort)0xF234) == 0x34F2);
static ushort xx = 0xF234;
assert(byteswap(xx) == 0x34F2);

pure nothrow @nogc @safe uint bswap(uint v);

Swaps bytes in a 4 byte uint end-to-end, i.e. byte 0 becomes byte 3, byte 1 becomes byte 2, byte 2 becomes byte 1, byte 3 becomes byte 0.

Examples:

assert(bswap(0x01020304u) == 0x04030201u);
static uint xx = 0x10203040u;
assert(bswap(xx) == 0x40302010u);

pure nothrow @nogc @safe ulong bswap(ulong v);

Swaps bytes in an 8 byte ulong end-to-end, i.e. byte 0 becomes byte 7, byte 1 becomes byte 6, etc. This is meant to be recognized by the compiler as an intrinsic.

Examples:

assert(bswap(0x01020304_05060708uL) == 0x08070605_04030201uL);
static ulong xx = 0x10203040_50607080uL;
assert(bswap(xx) == 0x80706050_40302010uL);

nothrow @nogc @system ubyte inp(uint port_address);

nothrow @nogc @system ushort inpw(uint port_address);

nothrow @nogc @system uint inpl(uint port_address);

Reads I/O port at port_address.

nothrow @nogc @system ubyte outp(uint port_address, ubyte value);

nothrow @nogc @system ushort outpw(uint port_address, ushort value);

nothrow @nogc @system uint outpl(uint port_address, uint value);

Writes and returns value to I/O port at port_address.

pure nothrow @nogc @safe int popcnt(uint x);

pure nothrow @nogc @safe int popcnt(ulong x);

Calculates the number of set bits in an integer.

pure nothrow @nogc @safe ushort _popcnt(ushort x);

pure nothrow @nogc @safe int _popcnt(uint x);

pure nothrow @nogc @safe int _popcnt(ulong x);

Calculates the number of set bits in an integer using the X86 SSE4 POPCNT instruction. POPCNT is not available on all X86 CPUs.

pure nothrow @nogc @safe uint bitswap(uint x);

Reverses the order of bits in a 32-bit integer.

pure nothrow @nogc @safe ulong bitswap(ulong x);

Reverses the order of bits in a 64-bit integer.

pure T rol(T)(const T value, const uint count)
Constraints: if (__traits(isIntegral, T) && __traits(isUnsigned, T));

pure T ror(T)(const T value, const uint count)
Constraints: if (__traits(isIntegral, T) && __traits(isUnsigned, T));

pure T rol(uint count, T)(const T value)
Constraints: if (__traits(isIntegral, T) && __traits(isUnsigned, T));

pure T ror(uint count, T)(const T value)
Constraints: if (__traits(isIntegral, T) && __traits(isUnsigned, T));

Bitwise rotate value left (rol) or right (ror) by count bit positions.

Examples:

ubyte a = 0b11110000U;
ulong b = ~1UL;

assert(rol(a, 1) == 0b11100001);
assert(ror(a, 1) == 0b01111000);
assert(rol(a, 3) == 0b10000111);
assert(ror(a, 3) == 0b00011110);

assert(rol(a, 0) == a);
assert(ror(a, 0) == a);

assert(rol(b, 63) == ~(1UL << 63));
assert(ror(b, 63) == ~2UL);

assert(rol!3(a) == 0b10000111);
assert(ror!3(a) == 0b00011110);