Struct std.typecons.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;
}
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