BitFlags

A typesafe structure for storing combinations of enum values.

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

struct BitFlags (

Flag!"unsafe" unsafe = No.unsafe

) if (

unsafe ||

isBitFlagEnum!(E)

) {}

Examples

Set values with the | operator and test with &

1 enum Enum
2 {
3     A = 1 << 0,
4 }
5 
6 // A default constructed BitFlags has no value set
7 immutable BitFlags!Enum flags_empty;
8 assert(!flags_empty.A);
9 
10 // Value can be set with the | operator
11 immutable flags_A = flags_empty | Enum.A;
12 
13 // and tested using property access
14 assert(flags_A.A);
15 
16 // or the & operator
17 assert(flags_A & Enum.A);
18 // which commutes.
19 assert(Enum.A & flags_A);

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

Binary operations: subtracting and intersecting flags

1 enum Enum
2 {
3     A = 1 << 0,
4     B = 1 << 1,
5     C = 1 << 2,
6 }
7 immutable BitFlags!Enum flags_AB = BitFlags!Enum(Enum.A, Enum.B);
8 immutable BitFlags!Enum flags_BC = BitFlags!Enum(Enum.B, Enum.C);
9 
10 // Use the ~ operator for subtracting flags
11 immutable BitFlags!Enum flags_B = flags_AB & ~BitFlags!Enum(Enum.A);
12 assert(!flags_B.A && flags_B.B && !flags_B.C);
13 
14 // use & between BitFlags for intersection
15 assert(flags_B == (flags_BC & flags_AB));

All the binary operators work in their assignment version

1 enum Enum
2 {
3     A = 1 << 0,
4     B = 1 << 1,
5 }
6 
7 BitFlags!Enum flags_empty, temp, flags_AB;
8 flags_AB = Enum.A | Enum.B;
9 
10 temp |= flags_AB;
11 assert(temp == (flags_empty | flags_AB));
12 
13 temp = flags_empty;
14 temp |= Enum.B;
15 assert(temp == (flags_empty | Enum.B));
16 
17 temp = flags_empty;
18 temp &= flags_AB;
19 assert(temp == (flags_empty & flags_AB));
20 
21 temp = flags_empty;
22 temp &= Enum.A;
23 assert(temp == (flags_empty & Enum.A));

Conversion to bool and int

1 enum Enum
2 {
3     A = 1 << 0,
4     B = 1 << 1,
5 }
6 
7 BitFlags!Enum flags;
8 
9 // BitFlags with no value set evaluate to false
10 assert(!flags);
11 
12 // BitFlags with at least one value set evaluate to true
13 flags |= Enum.A;
14 assert(flags);
15 
16 // This can be useful to check intersection between BitFlags
17 BitFlags!Enum flags_AB = Enum.A | Enum.B;
18 assert(flags & flags_AB);
19 assert(flags & Enum.A);
20 
21 // You can of course get you raw value out of flags
22 auto value = cast(int) flags;
23 assert(value == Enum.A);

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

1 enum UnsafeEnum
2 {
3     A = 1,
4     B = 2,
5     C = 4,
6     BC = B|C
7 }
8 static assert(!__traits(compiles, { BitFlags!UnsafeEnum flags; }));
9 BitFlags!(UnsafeEnum, Yes.unsafe) flags;
10 
11 // property access tests for exact match of unsafe enums
12 flags.B = true;
13 assert(!flags.BC); // only B
14 flags.C = true;
15 assert(flags.BC); // both B and C
16 flags.B = false;
17 assert(!flags.BC); // only C
18 
19 // property access sets all bits of unsafe enum group
20 flags = flags.init;
21 flags.BC = true;
22 assert(!flags.A && flags.B && flags.C);
23 flags.A = true;
24 flags.BC = false;
25 assert(flags.A && !flags.B && !flags.C);

BitFlags

Examples

Meta

Source