D Programming Language 2.0

- Comments
- D
- Search
- Home

Last update Tue Dec 13 15:30:22 2011

# std.bitmanip

Bit-level manipulation facilities.

License:
Boost License 1.0.

Authors:
Walter Bright, Andrei Alexandrescu

Source:
std/bitmanip.d

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 bool opIndex(size_t i);
  bool opIndexAssign(bool b, size_t i);
    Support for [index] operation for BitArray.

  @property BitArray dup();
    Support for array.dup property for BitArray.

  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();
    Support for array.reverse property for BitArray.

  @property BitArray sort();
    Support for array.sort property for BitArray.

  const const bool opEquals(ref const BitArray a2);
    Support for operators == and != for bit arrays.

  int opCmp(BitArray a2);
    Implement comparison operators.

  void init(bool[] ba);
    Set BitArray to contents of ba[]

  void init(void[] v, size_t numbits);
    Map 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();
    Convert to void[].

  BitArray opCom();
    Support for unary operator ~ for bit arrays.

  BitArray opAnd(BitArray e2);
    Support for binary operator & for bit arrays.

  BitArray opOr(BitArray e2);
    Support for binary operator | for bit arrays.

  BitArray opXor(BitArray e2);
    Support for binary operator ^ for bit arrays.

  BitArray opSub(BitArray e2);
    Support for binary operator - for bit arrays.

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

  BitArray opAndAssign(BitArray e2);
    Support for operator &= bit arrays.

  BitArray opOrAssign(BitArray e2);
    Support for operator |= for bit arrays.

  BitArray opXorAssign(BitArray e2);
    Support for operator ^= for bit arrays.

  BitArray opSubAssign(BitArray e2);
    Support for operator -= for bit arrays.

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

  BitArray opCatAssign(bool b);
  BitArray opCatAssign(BitArray b);
    Support for operator ~= for bit arrays.

  BitArray opCat(bool b);
  BitArray opCat_r(bool b);
  BitArray opCat(BitArray b);
    Support for binary operator ~ for bit arrays.

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.

  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).

  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.

  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).

  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));

Copyright Digital Mars 2007 - 2011. | Page generated by Ddoc.