## Flag Enums ##

A common programming problem is to represent a value from a set of boolean flags, each of which can be either on or off. C already has enums and bitfields, which can be naturally used to represent the individual flags, but are un-ergonomic to combine together. This proposal introduces "flag enums", a variant of the usual enums specialized to represent flags in a more ergonomic way.

As an example, a flag enum for the TCP control bits could be defined as follows:

	```
	enum TCP_Flags {
		FIN,
		SYN,
		RST,
		PSH,
		ACK,
		URG,
		ECE,
		CWR,
		NS
	} __attribute__((flag));
	```

The `__attribute__` syntax is ugly, but represents the smallest backwards compatibility break; a new SUE for enum flags (e.g. `flag enum TCP_Flags { ... };` or even `flag TCP_Flags { ... };`) might also be reasonable.

A flag enum would be different than a normal enum in two ways: it would auto-generate discriminant values differently, and it would have a number of bitwise operators defined on it by default.

Normal enums generate their discriminant values sequentially starting at zero (`0, 1, 2, 3, ...`), while a flag enum would generate its discriminant values as successive powers of two starting at `1`. E.g. the `TCP_Flags` declaration above would codegen to an enum like below:

	```
	enum TCP_Flags {
		FIN = 0x1,
		SYN = 0x2,
		RST = 0x4,
		PSH = 0x8,
		ACK = 0x10,
		URG = 0x20,
		ECE = 0x40,
		CWR = 0x80,
		NS = 0x100
	};
	```

The precise rule used would be that if no enum discriminant is given, the discriminant is the smallest power of two larger than the previous discriminant (`1` if there is no previous discriminant). This would allow some flexibility for cases like these:

	```
	enum FunFlags {
		NONE = 0,           // Named empty value
		FOO,  // == 0x1
		BAZ = 0x6,          // Multi-bit flag: 0x4 | 0x2
		BAR,  // == 0x8
		FOOBAR = FOO | BAR  // Named combination flag
	} __attribute__((flag));
	```

Secondly, we would auto-generate a number of useful operators for any flag enum, as follows:
* The default constructor for any flag enum would be defined, and would produce a flag with an underlying value of 0.
* Assignment from and equality/inequality to `zero_t` should also be defined based on the underlying enum value.
* The bitwise operators `?&?, ?|?, ?^?, ~?` and their assignment variants `?&=?, ?|=?, ?^=?` shall be defined with the semantics of the underlying enum value; `?-?` and `?-=?` should also be defined such that `a - b == a & ~b` (a set difference operation).

With these operations defined, flag enums would support a full set of useful flag operations, using existing, known syntax, as follows:

	```
	FunFlags f = some_val();
	if ( f ) { sout | "f has some flag(s) set" | endl; }
	if ( f & FOO ) { sout | "f has FOO set" | endl; }
	f |= FOO; // set FOO
	f -= FOO; // unset FOO
	f ^= FOO; // toggle FOO
	```

In each of the cases above, `FOO` could be replaced by `(BAR | BAZ)` to do the same operation or test on multiple flags at once.

### Related Work ###
C# has the [`[Flags]`][1] enum attribute, but their proposal does not go as far; specifically, the flag discriminants must be manually specified, and they do not automatically implement the bitwise operators on the flags. 

Java has [`EnumSet`][2] which represents the set of flags for a given enum (C++ [`bitset`][3] can be used similarly). The main disadvantage of applying this approach to Cforall is that C enum types already implicitly convert to int, and the bitwise operators already have interpretations on enums with `int` results based on this conversion. As such, all flags need to be wrapped in a set to be used type-safely with the bitwise operators.

[1]: https://msdn.microsoft.com/en-us/library/system.enum.hasflag(v=vs.110).aspx
[2]: http://docs.oracle.com/javase/7/docs/api/java/util/EnumSet.html
[3]: http://en.cppreference.com/w/cpp/utility/bitset