Menu
Search

API Documentation

version 2.108.1

overview

View source code
Display the source code in std/typecons.d from which this page was generated on github.
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 local clone.

Struct std.typecons.BitFlags

A typesafe structure for storing combinations of enum values.

struct BitFlags(E, Flag!("unsafe") unsafe = No.unsafe)
  
if (unsafe || isBitFlagEnum!E);

This template defines a simple struct to represent bitwise OR combinations of enum values. It can be used if all the enum values are integral constants with a bit count of at most 1, or if the unsafe parameter is explicitly set to Yes. This is much safer than using the enum itself to store the OR combination, which can produce surprising effects like this: 

enum E
{
    A = 1 << 0,
    B = 1 << 1
}
E e = E.A | E.B;
// will throw SwitchError
final switch (e)
{
    case E.A:
        return;
    case E.B:
        return;
}

Example

Set values with the | operator and test with & 

enum Enum
{
    A = 1 << 0,
}

// A default constructed BitFlags has no value set
immutable BitFlags!Enum flags_empty;
assert(!flags_empty.A);

// Value can be set with the | operator
immutable flags_A = flags_empty | Enum.A;

// and tested using property access
assert(flags_A.A);

// or the & operator
assert(flags_A & Enum.A);
// which commutes.
assert(Enum.A & flags_A);

Example

A default constructed BitFlags has no value set 

enum Enum
{
    None,
    A = 1 << 0,
    B = 1 << 1,
    C = 1 << 2
}

immutable BitFlags!Enum flags_empty;
assert(!(flags_empty & (Enum.A | Enum.B | Enum.C)));
assert(!(flags_empty & Enum.A) && !(flags_empty & Enum.B) && !(flags_empty & Enum.C));

Example

Binary operations: subtracting and intersecting flags 

enum Enum
{
    A = 1 << 0,
    B = 1 << 1,
    C = 1 << 2,
}
immutable BitFlags!Enum flags_AB = BitFlags!Enum(Enum.A, Enum.B);
immutable BitFlags!Enum flags_BC = BitFlags!Enum(Enum.B, Enum.C);

// Use the ~ operator for subtracting flags
immutable BitFlags!Enum flags_B = flags_AB & ~BitFlags!Enum(Enum.A);
assert(!flags_B.A && flags_B.B && !flags_B.C);

// use & between BitFlags for intersection
writeln(flags_B); // (flags_BC & flags_AB)

Example

All the binary operators work in their assignment version 

enum Enum
{
    A = 1 << 0,
    B = 1 << 1,
}

BitFlags!Enum flags_empty, temp, flags_AB;
flags_AB = Enum.A | Enum.B;

temp |= flags_AB;
writeln(temp); // (flags_empty | flags_AB)

temp = flags_empty;
temp |= Enum.B;
writeln(temp); // (flags_empty | Enum.B)

temp = flags_empty;
temp &= flags_AB;
writeln(temp); // (flags_empty & flags_AB)

temp = flags_empty;
temp &= Enum.A;
writeln(temp); // (flags_empty & Enum.A)

Example

Conversion to bool and int 

enum Enum
{
    A = 1 << 0,
    B = 1 << 1,
}

BitFlags!Enum flags;

// BitFlags with no value set evaluate to false
assert(!flags);

// BitFlags with at least one value set evaluate to true
flags |= Enum.A;
assert(flags);

// This can be useful to check intersection between BitFlags
BitFlags!Enum flags_AB = Enum.A | Enum.B;
assert(flags & flags_AB);
assert(flags & Enum.A);

// You can of course get you raw value out of flags
auto value = cast(int) flags;
writeln(value); // Enum.A

Example

You need to specify the unsafe parameter for enums with custom values 

enum UnsafeEnum
{
    A = 1,
    B = 2,
    C = 4,
    BC = B|C
}
static assert(!__traits(compiles, { BitFlags!UnsafeEnum flags; }));
BitFlags!(UnsafeEnum, Yes.unsafe) flags;

// property access tests for exact match of unsafe enums
flags.B = true;
assert(!flags.BC); // only B
flags.C = true;
assert(flags.BC); // both B and C
flags.B = false;
assert(!flags.BC); // only C

// property access sets all bits of unsafe enum group
flags = flags.init;
flags.BC = true;
assert(!flags.A && flags.B && flags.C);
flags.A = true;
flags.BC = false;
assert(flags.A && !flags.B && !flags.C);

Authors

Andrei Alexandrescu, Bartosz Milewski, Don Clugston, Shin Fujishiro, Kenji Hara

License

Boost License 1.0.