|
| 1 | +# Design |
| 2 | + |
| 3 | +## Goal |
| 4 | + |
| 5 | +The goal of this exercise is to teach the student advanced aspects of the Concept of Enums in [C#][docs.microsoft.com-bitwise-and-shift-operators]. We'll do this in the form of working with [flag][docs.microsoft.com-flagsattribute] enums, which are enums whose values are interpreted as bitwise flags that can be manipulated through bitwise operations. |
| 6 | + |
| 7 | +## Things to teach |
| 8 | + |
| 9 | +After completing this exercise, the student should: |
| 10 | + |
| 11 | +- Know what a flags enumeration is. |
| 12 | +- Know how to define a flags enumeration. |
| 13 | +- Know how to check if a flag has been set on an enum value. |
| 14 | +- Know how to set a flag on an enum value. |
| 15 | +- Know how to unset a flag on an enum value. |
| 16 | +- Know that an enum's underlying type can be changed. |
| 17 | + |
| 18 | +## Things not to teach |
| 19 | + |
| 20 | +As this is an advanced exercise, there are no enum-related things that we should explicitly _not_ teach. |
| 21 | + |
| 22 | +## Resources to refer to |
| 23 | + |
| 24 | +Here are some suggestions for resources to use in the exercise's documentation file(s): |
| 25 | + |
| 26 | +### Hints |
| 27 | + |
| 28 | +- [`switch` statement][docs.microsoft.com-switch-keyword] |
| 29 | +- [Bitwise and shift operators][docs.microsoft.com-bitwise-and-shift-operators] |
| 30 | + |
| 31 | +### After |
| 32 | + |
| 33 | +- [Working with enums as bit flags][docs.microsoft.com-enumeration-types-as-bit-flags]. |
| 34 | +- [Enum flags and bitwise operators][alanzucconi.com-enum-flags-and-bitwise-operators] |
| 35 | + |
| 36 | +## Concepts |
| 37 | + |
| 38 | +The Concepts this exercise unlocks are: |
| 39 | + |
| 40 | +- `enums-advanced`: know how to define a "flags" enum; know how to add, remove or check for flags; know how to change the underlying type of an enum. |
| 41 | + |
| 42 | +## Prequisites |
| 43 | + |
| 44 | +This exercise's prerequisites Concepts are: |
| 45 | + |
| 46 | +- `enums-basic`: know how to define the `enum`. |
| 47 | +- `attributes-basic`: know how to annotate the enum with the `[Flags]` attribute. |
| 48 | +- `bitwise-operations`: know how to use bitwise operations to work with the flag enum values. |
| 49 | + |
| 50 | +## Representer |
| 51 | + |
| 52 | +This exercise does not require any specific representation logic to be added to the [representer][representer]. |
| 53 | + |
| 54 | +## Analyzer |
| 55 | + |
| 56 | +This exercise could benefit from having an [analyzer][analyzer] that can comment on: |
| 57 | + |
| 58 | +- Verify that the `Permission` enum is marked with the `[Flags]` attribute. |
| 59 | +- Suggest using `byte` as the enum's backing type if no backing type was explicitly specified. |
| 60 | + |
| 61 | +[analyzer]: https://github.com/exercism/csharp-analyzer |
| 62 | +[representer]: https://github.com/exercism/csharp-representer |
| 63 | +[docs.microsoft.com-enumeration-types-as-bit-flags]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/enumeration-types#enumeration-types-as-bit-flags |
| 64 | +[docs.microsoft.com-bitwise-and-shift-operators]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators |
| 65 | +[docs.microsoft.com-switch-keyword]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/switch |
| 66 | +[docs.microsoft.com-binary-notation]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types#integer-literals |
| 67 | +[docs.microsoft.com-flagsattribute]: https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=netcore-3.1 |
| 68 | +[alanzucconi.com-enum-flags-and-bitwise-operators]: https://www.alanzucconi.com/2015/07/26/enum-flags-and-bitwise-operators/ |
| 69 | +[concept-bitwise-manipulation]: ../../../../../reference/concepts/bitwise_manipulation.md |
0 commit comments