std.bitmanip

Bit-level manipulation facilities.

Authors:
Walter Bright, Andrei Alexandrescu

template bitfields(T...)

Allows creating bit fields inside structs and classes.

Example:

struct A
{
    int a;
    mixin(bitfields!(
        uint, "x",    2,
        int,  "y",    3,
        uint, "z",    2,
        bool, "flag", 1));
}
A obj;
obj.x = 2;
obj.z = obj.x;

The example above creates a bitfield pack of eight bits, which fit in one ubyte. The bitfields are allocated starting from the least significant bit, i.e. x occupies the two least significant bits of the bitfields storage.

The sum of all bit lengths in one bitfield instantiation must be exactly 8, 16, 32, or 64. If padding is needed, just allocate one bitfield with an empty name.

Example:

struct A
{
    mixin(bitfields!(
        bool, "flag1",    1,
        bool, "flag2",    1,
        uint, "",         6));
}

The type of a bit field can be any integral type or enumerated type. The most efficient type to store in bitfields is bool, followed by unsigned types, followed by signed types.

struct FloatRep;

Allows manipulating the fraction, exponent, and sign parts of a float separately. The definition is:

struct FloatRep
{
    union
    {
        float value;
        mixin(bitfields!(
                  uint,  "fraction", 23,
                  ubyte, "exponent",  8,
                  bool,  "sign",      1));
    }
    enum uint bias = 127, fractionBits = 23, exponentBits = 8, signBits = 1;
}

struct DoubleRep;

Allows manipulating the fraction, exponent, and sign parts of a double separately. The definition is:

struct DoubleRep
{
    union
    {
        double value;
        mixin(bitfields!(
                  ulong,   "fraction", 52,
                  ushort,  "exponent", 11,
                  bool,    "sign",      1));
    }
    enum uint bias = 1023, signBits = 1, fractionBits = 52, exponentBits = 11;
}

struct BitArray;

An array of bits.

const const @property size_t dim();

Gets the amount of native words backing this BitArray.

const const @property size_t length();

Gets the amount of bits in the BitArray.

@property void length(size_t newlen);

Sets the amount of bits in the BitArray.

const bool opIndex(size_t i);

Gets the i'th bit in the BitArray.

bool opIndexAssign(bool b, size_t i);

Sets the i'th bit in the BitArray.

@property BitArray dup();

Duplicates the BitArray and its contents.

int opApply(scope int delegate(ref bool) dg); int opApply(scope int delegate(ref uint, ref bool) dg);

Support for foreach loops for BitArray.

@property BitArray reverse();

Reverses the bits of the BitArray.

@property BitArray sort();

Sorts the BitArray's elements.

const const bool opEquals(ref const BitArray a2);

Support for operators == and != for BitArray.

int opCmp(BitArray a2);

Supports comparison operators for BitArray.

void init(bool[] ba);

Set this BitArray to the contents of ba.

void init(void[] v, size_t numbits);

Map the BitArray onto v, with numbits being the number of bits in the array. Does not copy the data.

This is the inverse of opCast.

void[] opCast(T : void[])();

Convert to void[].

size_t[] opCast(T : size_t[])();

Convert to size_t[].

BitArray opCom();

Support for unary operator ~ for BitArray.

BitArray opAnd(BitArray e2);

Support for binary operator & for BitArray.

BitArray opOr(BitArray e2);

Support for binary operator | for BitArray.

BitArray opXor(BitArray e2);

Support for binary operator ^ for BitArray.

BitArray opSub(BitArray e2);

Support for binary operator - for BitArray.

a - b for BitArray means the same thing as a & ~b.

BitArray opAndAssign(BitArray e2);

Support for operator &= for BitArray.

BitArray opOrAssign(BitArray e2);

Support for operator |= for BitArray.

BitArray opXorAssign(BitArray e2);

Support for operator ^= for BitArray.

BitArray opSubAssign(BitArray e2);

Support for operator -= for BitArray.

a -= b for BitArray means the same thing as a &= ~b.

BitArray opCatAssign(bool b); BitArray opCatAssign(BitArray b);

Support for operator ~= for BitArray.

BitArray opCat(bool b); BitArray opCat_r(bool b); BitArray opCat(BitArray b);

Support for binary operator ~ for BitArray.

pure nothrow @safe T swapEndian(T)(T val);

Swaps the endianness of the given integral value or character.

pure nothrow @safe auto nativeToBigEndian(T)(T val);

Converts the given value from the native endianness to big endian and returns it as a ubyte[n] where n is the size of the given type.

Returning a ubyte[n] helps prevent accidentally using a swapped value as a regular one (and in the case of floating point values, it's necessary, because the FPU will mess up any swapped floating point values. So, you can't actually have swapped floating point values as floating point values).

real is not supported, because its size is implementation-dependent and therefore could vary from machine to machine (which could make it unusable if you tried to transfer it to another machine).

Examples:

int i = 12345;
ubyte[4] swappedI = nativeToBigEndian(i);
assert(i == bigEndianToNative!int(swappedI));

double d = 123.45;
ubyte[8] swappedD = nativeToBigEndian(d);
assert(d == bigEndianToNative!double(swappedD));

pure nothrow @safe T bigEndianToNative(T, size_t n)(ubyte[n] val);

Converts the given value from big endian to the native endianness and returns it. The value is given as a ubyte[n] where n is the size of the target type. You must give the target type as a template argument, because there are multiple types with the same size and so the type of the argument is not enough to determine the return type.

Taking a ubyte[n] helps prevent accidentally using a swapped value as a regular one (and in the case of floating point values, it's necessary, because the FPU will mess up any swapped floating point values. So, you can't actually have swapped floating point values as floating point values).

Examples:

ushort i = 12345;
ubyte[2] swappedI = nativeToBigEndian(i);
assert(i == bigEndianToNative!ushort(swappedI));

dchar c = 'D';
ubyte[4] swappedC = nativeToBigEndian(c);
assert(c == bigEndianToNative!dchar(swappedC));

pure nothrow @safe auto nativeToLittleEndian(T)(T val);

Converts the given value from the native endianness to little endian and returns it as a ubyte[n] where n is the size of the given type.

Examples:

int i = 12345;
ubyte[4] swappedI = nativeToLittleEndian(i);
assert(i == littleEndianToNative!int(swappedI));

double d = 123.45;
ubyte[8] swappedD = nativeToLittleEndian(d);
assert(d == littleEndianToNative!double(swappedD));

pure nothrow @safe T littleEndianToNative(T, size_t n)(ubyte[n] val);

Converts the given value from little endian to the native endianness and returns it. The value is given as a ubyte[n] where n is the size of the target type. You must give the target type as a template argument, because there are multiple types with the same size and so the type of the argument is not enough to determine the return type.

real is not supported, because its size is implementation-dependent and therefore could vary from machine to machine (which could make it unusable if you tried to transfer it to another machine).

Examples:

ushort i = 12345;
ubyte[2] swappedI = nativeToLittleEndian(i);
assert(i == littleEndianToNative!ushort(swappedI));

dchar c = 'D';
ubyte[4] swappedC = nativeToLittleEndian(c);
assert(c == littleEndianToNative!dchar(swappedC));

std

etc

core

std.bitmanip