Fix TODOs in concepts (#1571)

Author: ErikSchierboom

concepts/arrays/about.md

@@ -1,6 +1,5 @@
 # About
 
-TODO: about.md files and links.json files are the same for arrays, for-loops and foreach. Consider how to prise these apart of otherwise treat these closely coupled concepts.
 Data structures that can hold zero or more elements are known as _collections_. An **array** is a collection that has a fixed size/length and whose elements must all be of the same type. Elements can be assigned to an array or retrieved from it using an index. C# arrays are zero-based, meaning that the first element's index is always zero:
 
 ```csharp
@@ -28,6 +27,8 @@ int[] threeIntsV3 = { 4, 9, 7 };
 
 Arrays can be manipulated by either calling an array instance's [methods][array-methods] or [properties][array-properties], or by using the static methods defined in the [`Array` class][array-class].
 
+## Iteration
+
 An array is also a _collection_, which means that you can iterate over _all_ its values using a [`foreach` loop][foreach-statement]:
 
 ```csharp

concepts/bit-manipulation/about.md

@@ -1,70 +1,15 @@
 # About
 
-TODO: See #2112. We need to reconsider the text below now that it is a stand alone concept or maybe bitwise manipulation should be introduced in a separate exercise and the flag-enums exercise and concept should take that as a dependency showing how bitwise manipulation is used in the context of enums.
+C# has several operators to do bitwise manipulation:
 
-To allow a single enum instance to represent multiple values (usually referred to as _flags_), one can annotate the enum with the `[Flags]` attribute. By carefully assigning the values of the enum members such that specific bits are set to `1`, bitwise operators can be used to set or unset flags.
+- [`&`][and-operator]: bitwise AND
+- [`|`][or-operator]: bitwise OR
+- [`~`][complement-operator]: bitwise COMPLEMENT
+- [`<<`][left-shift-operator]: bitwise shift left
+- [`>>`][right-shift-operator]: bitwise shift right
 
-```csharp
-[Flags]
-enum PhoneFeatures
-{
-    Call = 1,
-    Text = 2
-}
-```
-
-Besides using regular integers to set the flag enum members' values, one can also use [binary literals or the bitwise shift operator][binary-literals].
-
-```csharp
-[Flags]
-enum PhoneFeaturesBinary
-{
-    Call = 0b00000001,
-    Text = 0b00000010
-}
-
-[Flags]
-enum PhoneFeaturesBitwiseShift
-{
-    Call = 1 << 0,
-    Text = 1 << 1
-}
-```
-
-An enum member's value can refer to other enum members values:
-
-```csharp
-[Flags]
-enum PhoneFeatures
-{
-    Call = 0b00000001,
-    Text = 0b00000010,
-    All  = Call | Text
-}
-```
-
-Setting a flag can be done through the [bitwise OR operator][or-operator] (`|`) and unsetting a flag through a combination of the [bitwise AND operator][and-operator] (`&`) and the [bitwise complement operator][bitwise-complement-operator] (`~`). While checking for a flag can be done through the bitwise AND operator, one can also use the enum's [`HasFlag()` method][has-flag].
-
-```csharp
-var features = PhoneFeatures.Call;
-
-// Set the Text flag
-features = features | PhoneFeatures.Text;
-
-features.HasFlag(PhoneFeatures.Call); // => true
-features.HasFlag(PhoneFeatures.Text); // => true
-
-// Unset the Call flag
-features = features & ~PhoneFeatures.Call;
-
-features.HasFlag(PhoneFeatures.Call); // => false
-features.HasFlag(PhoneFeatures.Text); // => true
-```
-
-[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
-[alanzucconi.com-enum-flags-and-bitwise-operators]: https://www.alanzucconi.com/2015/07/26/enum-flags-and-bitwise-operators/
 [or-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#logical-or-operator-
 [and-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#logical-and-operator-
-[bitwise-complement-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#bitwise-complement-operator-
-[binary-literals]: https://riptutorial.com/csharp/example/6327/binary-literals
-[has-flag]: https://docs.microsoft.com/en-us/dotnet/api/system.enum.hasflag?view=netcore-3.1
+[complement-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#bitwise-complement-operator-
+[left-shift-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#left-shift-operator-
+[right-shift-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#right-shift-operator-

concepts/bit-manipulation/introduction.md

@@ -1,3 +1,9 @@
 # Introduction
 
-TODO: add introduction for bit-manipulation concept
+C# has several operators to do bitwise manipulation:
+
+- `&`: bitwise AND
+- `|`: bitwise OR
+- `~`: bitwise COMPLEMENT
+- `<<`: bitwise shift left
+- `>>`: bitwise shift right

concepts/casting/about.md

@@ -6,7 +6,7 @@ The [C# documentation][type-testing-and-cast-operators] classifies type conversi
 
 In C# very often, outside of the realm of numeric values and class hierarchies, you will have to make a conversion by calling some member of the "to" type such as [`Int32.Parse()`][int32-parse] which converts a string to an integer or by calling a member of the "from" type e.g. `object.ToString()`. Javascript and developers in other dynamic languages should be aware.
 
-Note that implicit an explicit cast [operators][operator-overloading] (discussed in (TODO cross-ref-tba)) are available which can bring fairly arbitrary casting to your own types.
+Note that implicit an explicit cast [operators][operator-overloading] (discussed in [concept:csharp/operator-overloading]()) are available which can bring fairly arbitrary casting to your own types.
 
 ## Casting Primitive Types - Implicit
 
@@ -114,7 +114,7 @@ The [`as`][as-operator] keyword fulfills a similar function to `is` e.g. `var fo
 
 ## Custom Cast Operator
 
-Types can define their own custom explicit and implicit [cast operators][custom-casts]. See (TODO cross-ref-tba) for coverage of this..
+Types can define their own custom explicit and implicit [cast operators][custom-casts].
 
 Examples of [explicit][big-integer-explicit] and [implicit][big-integer-implicit] casts in the BCL is conversions from the `BigInteger` struct to and from other numeric types
 

concepts/compound-assignment/about.md

@@ -1,8 +1,6 @@
 # About
 
-TODO: See issue #2112. I think we need a different exercise to introduce compound assignments (one that shows it being used in a more conventional numeric or string context. flag-enums could then take that as a dependency and show how it is used in this more unusual context.
-
-The bitwise operators can also be used as [compound assignments][compound-assignment], which are a shorthand notation where `x = op y` can be written as `x op= y`:
+Many operators can also be used as [compound assignments][compound-assignment], which are a shorthand notation where `x = op y` can be written as `x op= y`:
 
 ```csharp
 var features = PhoneFeatures.Call;
@@ -11,4 +9,4 @@ features &= ~PhoneFeatures.Call;
 ```
 
 [compound-assignment]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#compound-assignment
-[compound-assignment-alt]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/expressions#compound-assignment
+[compound-assignment-alt]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/expressions#compound-assignment

concepts/compound-assignment/introduction.md

@@ -1,3 +1,9 @@
 # Introduction
 
-TODO: add introduction for compound-assignment concept
+Many operators can also be used as compound assignments, which are a shorthand notation where `x = op y` can be written as `x op= y`:
+
+```csharp
+var features = PhoneFeatures.Call;
+features |= PhoneFeatures.Text;
+features &= ~PhoneFeatures.Call;
+```

concepts/const-readonly/.meta/config.json

@@ -1,7 +1,5 @@
 {
   "blurb": "A const allows you to specify fields where their value is known at compile time and will not change during the runtime of the program.",
-  "authors": ["TODO: add author"],
-  "contributors": [
-    "yzAlvin"
-  ]
+  "authors": ["erikschierboom"],
+  "contributors": ["yzAlvin"]
 }

concepts/const-readonly/about.md

@@ -1,3 +1,15 @@
 # About
 
-TODO: add information on const-readonly concept
+By default, values in C# are _mutable_, that is they can change over time. To make a value _immutable_, there are two options:
+
+1. Add the [`const` modifier](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/const)
+2. Add the [`readonly` modifier](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/readonly#readonly-field-example)
+
+The `const` modifier has some restrictions:
+
+1. It can only be applied to "constant" types: strings, booleans and numbers.
+1. The `const` value must be initialized immediately.
+
+See [definining constants](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/how-to-define-constants) for more information.
+
+If your value is a non-constant type or you need to initialize the value in a constructor, `readonly` can be used to enforce immutability.

concepts/const-readonly/introduction.md

@@ -1,3 +1,13 @@
 # Introduction
 
-TODO: add introduction for const-readonly concept
+By default, values in C# are _mutable_, that is they can change over time. To make a value _immutable_, there are two options:
+
+1. Add the `const` modifier
+2. Add the `readonly` modifier
+
+The `const` modifier has some restrictions:
+
+1. It can only be applied to "constant" types: strings, booleans and numbers.
+1. The `const` value must be initialized immediately.
+
+If your value is a non-constant type or you need to initialize the value in a constructor, `readonly` can be used to enforce immutability.

concepts/enumerables/.meta/config.json

@@ -1,5 +1,5 @@
 {
   "blurb": "Enumerables are values that can be iterated over.",
-  "authors": ["TODO: add author"],
+  "authors": ["erikschierboom"],
   "contributors": []
 }

concepts/enumerables/about.md

@@ -1,3 +1,20 @@
 # About
 
-TODO: complete document
+Types that implement the [`IEnumerable<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ienumerable-1?view=net-5.0) interface are known as being _enumerable_. All built-in collection types implement this interface.
+
+An enumerable type can be iterated over using a `foreach` loop:
+
+```csharp
+var primes = new[] { 2, 3, 5, 7 };
+foreach (var prime in primes)
+{
+    Console.Write(prime);
+}
+// => 2357
+```
+
+To implement `IEnumerable<T>`, a type has to implement one method: `IEnumerator<T> GetEnumerator()`. As seen, an enumerable defers the actual iterating over a collection to an `IEnumerator<T>` type. This interface has one property and three methods to implement:
+
+- `public T Current { get; }`: get the current element.
+- `public bool MoveNext ();`: move to the next element, returning `true` if the move to the next element was successful, and `false` if not (no more elements).
+- `public void Reset ();`: reset the enumerator to its initial state (before the first element).

concepts/enumerables/introduction.md

@@ -1,3 +1,20 @@
 # Introduction
 
-TODO: complete document
+Types that implement the `IEnumerable<T>` interface are known as being _enumerable_. All built-in collection types implement this interface.
+
+An enumerable type can be iterated over using a `foreach` loop:
+
+```csharp
+var primes = new[] { 2, 3, 5, 7 };
+foreach (var prime in primes)
+{
+    Console.Write(prime);
+}
+// => 2357
+```
+
+To implement `IEnumerable<T>`, a type has to implement one method: `IEnumerator<T> GetEnumerator()`. As seen, an enumerable defers the actual iterating over a collection to an `IEnumerator<T>` type. This interface has one property and three methods to implement:
+
+- `public T Current { get; }`: get the current element.
+- `public bool MoveNext ();`: move to the next element, returning `true` if the move to the next element was successful, and `false` if not (no more elements).
+- `public void Reset ();`: reset the enumerator to its initial state (before the first element).

concepts/exception-filtering/about.md

@@ -1,6 +1,5 @@
 # About
 
-TODO: This may need a more rounded introduction to filtering here.
 `when` is the keyword in filtering exceptions. It is placed after the catch
 statement and can take a boolean expression containing any values in scope at the time. They don't just have to be members of the exception itself. If the type of the exception matches and the expression evaluates to true then the block associated with that `catch` statement is executed otherwise the next `catch` statement, if any, is checked.
 

concepts/explicit-casts/.meta/config.json

@@ -1,5 +1,5 @@
 {
   "blurb": "When there is no built-in implicit conversion between two types, an explicit cast has to be used.",
-  "authors": ["TODO: add author"],
+  "authors": ["erikschierboom"],
   "contributors": []
 }

concepts/explicit-casts/about.md

@@ -1,3 +1,19 @@
 # About
 
-TODO: add information on explicit-casts concept
+Where types cannot be cast implicitly, you must use an explicit cast [operator][cast-operator].
+The cast operator is nothing more than the target type in parentheses before the value you want to cast:
+
+```csharp
+
+int i = 7;
+byte b = (byte)i; // Explicit cast from int to byte
+```
+
+Using an explicit cast is potentially dangerous. The two most common errors are:
+
+- Casting to an incompatible type. This will throw an exception at runtime.
+- Casting to a numeric value that is insufficiently "wide". This can result in a sign conflict or an overflow exception being thrown in the case of integers
+
+Note: an expression of type `int` can be explicitly cast to `char`. This may result in an invalid `char`.
+
+[cast-operator]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/type-testing-and-cast#cast-expression

concepts/explicit-casts/introduction.md

@@ -1,3 +1,10 @@
 # Introduction
 
-TODO: add introduction for explicit-casts concept
+Where types cannot be cast implicitly, you must use an explicit cast operator.
+The cast operator is nothing more than the target type in parentheses before the value you want to cast:
+
+```csharp
+
+int i = 7;
+byte b = (byte)i; // Explicit cast from int to byte
+```

concepts/for-loops/about.md

@@ -1,62 +1,26 @@
 # About
 
-TODO: about.md files and links.json files are the same for arrays, for-loops and foreach. Consider how to prise these apart of otherwise treat these closely coupled concepts.
-Data structures that can hold zero or more elements are known as _collections_. An **array** is a collection that has a fixed size/length and whose elements must all be of the same type. Elements can be assigned to an array or retrieved from it using an index. C# arrays are zero-based, meaning that the first element's index is always zero:
+A [`for` loop][for-statement] allows one to repeatedly execute code in a loop until a condition is met.
 
 ```csharp
-// Declare array with explicit size (size is 2)
-int[] twoInts = new int[2];
-
-// Assign second element by index
-twoInts[1] = 8;
-
-// Retrieve the second element by index
-twoInts[1] == 8; // => true
-
-// Check the length of the array
-twoInts.Length == 2; // => true
-```
-
-Arrays can also be defined using a shortcut notation that allows you to both create the array and set its value. As the compiler can now tell how many elements the array will have, the length can be omitted:
-
-```csharp
-// Three equivalent ways to declare and initialize an array (size is 3)
-int[] threeIntsV1 = new int[] { 4, 9, 7 };
-int[] threeIntsV2 = new[] { 4, 9, 7 };
-int[] threeIntsV3 = { 4, 9, 7 };
-```
-
-Arrays can be manipulated by either calling an array instance's [methods][array-methods] or [properties][array-properties], or by using the static methods defined in the [`Array` class][array-class].
-
-An array is also a _collection_, which means that you can iterate over _all_ its values using a [`foreach` loop][foreach-statement]:
-
-```csharp
-char[] vowels = new [] { 'a', 'e', 'i', 'o', 'u' };
-
-foreach (char vowel in vowels)
+for (int i = 0; i < 5; i++)
 {
-    // Output the vowel
-    System.Console.Write(vowel);
+    System.Console.Write(i);
 }
 
-// => aeiou
+// => 01234
 ```
 
-One could use a [`for` loop][for-statement] to iterate over an array:
-
-```csharp
-char[] vowels = new [] { 'a', 'e', 'i', 'o', 'u' };
+A `for` loop consists of four parts:
 
-for (int i = 0; i < vowels.Length; i++)
-{
-    // Output the vowel
-    System.Console.Write(vowels[i]);
-}
+1. The initializer: executed once before entering the loop. Usually used to define variables used within the loop.
+2. The condition: executed before each loop iteration. The loop continues to execute while this evaluates to `true`.
+3. The iterator: execute after each loop iteration. Usually used to modify (often: increment/decrement) the loop variable(s).
+4. The body: the code that gets executed each loop iteration.
 
-// => aeiou
-```
+## for vs foreach loops
 
-However, generally a `foreach` loop is preferrable over a `for` loop for the following reasons:
+In general [concept:csharp/foreach-loops]() are preferrable over `for` loops for the following reasons:
 
 - A `foreach` loop is guaranteed to iterate over _all_ values. With a `for` loop, it is easy to miss elements, for example due to an off-by-one error.
 - A `foreach` loop is more _declarative_, your code is communicating _what_ you want it to do, instead of a `for` loop that communicates _how_ you want to do it.
@@ -83,13 +47,6 @@ A `for` loop does have some advantages over a `foreach` loop:
 - You can process collections from back to front by counting down.
 - You can use `for` loops in scenarios that don't involve collections.
 
-Related Topics:
-
-- You should be aware that C# supports [multi-dimensional arrays][multi-dimensional-arrays] like `int[,] arr = new int[10, 5]` which can be very useful.
-- You should also be aware that you can instantiate objects of type [`System.Array`][system-array-object] with `Array.CreateInstance`. Such objects are of little use - mainly for interop with VB.NET code. They are not interchangeable with standard arrays (`T[]`). They can have a non-zero lower bound.
-
-Both the above topics are discussed more fully in a later exercise.
-
 [implicitly-typed-arrays]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/implicitly-typed-arrays
 [array-foreach]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/using-foreach-with-arrays
 [single-dimensional-arrays]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/single-dimensional-arrays