Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# core.bitop

This module contains a collection of bit-level operations.
License:
Authors:
Don Clugston, Sean Kelly, Walter Bright, Alex RĂ¸nne Petersen, Thomas Stuart Bockman
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 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.
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.
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`)
if (__traits(isIntegral, T) && __traits(isUnsigned, T));

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

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

pure T `ror`(uint count, T)(const T `value`)
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);
```