Skip to content

Commit

Permalink
Convert backtick (`) admonition fences to tildes (~).
Browse files Browse the repository at this point in the history
  • Loading branch information
ErikSchierboom committed Sep 21, 2023
1 parent 7d7afcd commit 08efea6
Show file tree
Hide file tree
Showing 28 changed files with 84 additions and 84 deletions.
8 changes: 4 additions & 4 deletions exercises/practice/bank-account/.approaches/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,12 @@ Whilst using locks (or mutexes) makes for simple code, they come at a small perf
Lock-free programming aims to provide alternative means of safe concurrent updating.
One such mechanism is to use an atomic CPU instruction called [_compare and swap_][compare-and-swap].

```exercism/note
~~~~exercism/note
The compare and swap instruction takes three arguments: the address of the memory you want to update, its current value and the new value.
The memory will only be updated if the current value is equal to the provided value.
If this is not the case, some other code must have updated the value, so in that case it is not safe to update the value.
The instruction's return value indicates if the compare and swap exchange succeeded, and if not, you could retry with the newly updated value.
```
~~~~

The .NET framework allows using this instruction via the [`Interlocked.CompareExchange()`][interlocked.compare-exchange] method.
Unfortunately, we can't use this to solve in this exercise, as the value that we want to update is a `decimal` and compare and swap is not supported for `decimal` values.
Expand All @@ -94,9 +94,9 @@ This is due to decimals required too much memory to be swapped atomically.
While both approaches basically are almost identical, the `lock` version is more idiomatic.
They do offer different levels of concurrency guarantees though.

```exercism/caution
~~~~exercism/caution
Locks offer protection against concurrent access via threads, but mutexes even offer protection against concurrent access via processes.
```
~~~~

[approach-lock-statement]: https://exercism.org/tracks/csharp/exercises/bank-account/approaches/lock-statement
[approach-mutex]: https://exercism.org/tracks/csharp/exercises/bank-account/approaches/mutex
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ private decimal _balance;
private bool _isOpen;
```

```exercism/caution
~~~~exercism/caution
When dealing with monetary amount, _always_ use `decimal` instead of `float` or `double`, as the later suffer from rounding errors.
```
~~~~

The `Open()` and `Close()` methods change the open state:

Expand Down Expand Up @@ -101,7 +101,7 @@ lock (_lock)

As our lock object is unique per instance of the `BankAccount` class, we won't have any issues with locking other bank accounts when we lock on that object.

````exercism/note
~~~~exercism/note
The `lock` statement is syntactic sugar for calls to `Monitor.Enter()` and `Monitor.Exit()`, using a `try/finally` block.
```csharp
Expand All @@ -124,7 +124,7 @@ finally
Monitor.Exit(_lock);
}
```
````
~~~~

## Shortening

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/bank-account/.approaches/mutex/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ private decimal _balance;
private bool _isOpen;
```

```exercism/caution
~~~~exercism/caution
When dealing with monetary amount, _always_ use `decimal` instead of `float` or `double`, as the later suffer from rounding errors.
```
~~~~

The `Open()` and `Close()` methods change the open state:

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/bob/.approaches/answer-array/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ The correct answer is selected from the array by using the score as the array in
The `String` [TrimEnd][trimend] method is applied to the input to eliminate any whitespace at the end of the input.
If the string has no characters left, it returns the response for saying nothing.

```exercism/caution
~~~~exercism/caution
Note that a `null` `string` would be different from a `string` of all whitespace.
A `null` `string` would throw an `Exception` if `TrimEnd` were applied to it.
To test a string that might be `null` or only whitespace, the [IsNullOrWhiteSpace](https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorwhitespace) method of `String` would be used.
```
~~~~

The first half of the shout condition

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/bob/.approaches/if/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,11 @@ This is because the second half of the condition tests that the uppercased input
If the input were only `"123"` it would equal itself uppercased, but without letters it would not be a yell.
The uppercasing is done by using the `String` method [ToUpperInvariant][toupperinvariant].

```exercism/note
~~~~exercism/note
The invariant culture represents a culture that is culture-insensitive.
It is associated with the English language but not with a specific country or region.
For more information, see the [CultureInfo.InvariantCulture](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.invariantculture) property.
```
~~~~

## Extension methods

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@ public static class Bob
In this approach you have a series of `if` statements using private methods that use [regular expressions][regular-expressions] to evaluate the conditions.
As soon as the right condition is found, the correct response is returned.

```exercism/note
~~~~exercism/note
Note that there are no `else if` or `else` statements.
If an `if` statement returns, then an `else if` or `else` is not needed.
Execution will either return or will continue to the next statement anyway.
```
~~~~

### Silence

Expand All @@ -60,9 +60,9 @@ To match on this regular expression, we use [`Regex.IsMatch()`][regex-ismatch],
Regex.IsMatch(message, @"^\s*$");
```

```exercism/note
~~~~exercism/note
When defining regular expression patterns, consider defining them with a verbatim string literal (prefixed with `@`) to prevent having to escape any backslash characters.
```
~~~~

### Yell

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/bob/.approaches/switch-on-tuple/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ The `switch` returns the right response for a question, shout, shouted question,
The `String` [TrimEnd][trimend] method is applied to the input to eliminate any whitespace at the end of the input.
If the string has no characters left, it returns the response for saying nothing.

```exercism/caution
~~~~exercism/caution
Note that a `null` `string` would be different from a `string` of all whitespace.
A `null` `string` would throw an `Exception` if `TrimEnd` were applied to it.
To test a `string` that might be `null` or only whitespace, the [IsNullOrWhiteSpace](https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorwhitespace) method of `String` would be used.
```
~~~~

Next a [tuple][tuple] is made from the conditions for a queston and a shout.
The first half of the shout condition
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ The next step is to call the overload `Steps()` method and return its value.
return Steps(number, 0);
```

````exercism/note
~~~~exercism/note
For someone new to the code, it might not be clear what the `0` argument in the `Steps(number, 0)` call represents.
You could introduce an appropriately named variable and use that as the argument:
Expand All @@ -53,7 +53,7 @@ This is already much better, but another option is to use a [named argument](htt
```csharp
return Steps(number, stepCount: 0);
```
````
~~~~

Let's examine the overload `Steps()` method, which looks like this:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,9 @@ private static IEnumerable<int> Sequence(int number)

First, we start out with assigning the `number` parameter to a `currentNumber` variable, which we'll use to keep track of where in the collatz conjecture sequence we currently are.

```exercism/note
~~~~exercism/note
Re-assiging values to a parameter _is_ possible, but it is considered good practice to not do that.
```
~~~~

Then a `while` loop starts by checking whether the current number is not equal to `1`; if it is, the method terminates:

Expand Down Expand Up @@ -102,9 +102,9 @@ Note that even though we are yield indidivual elements, what is returned from a
Methods that use a `yield` statement are also _lazy_, which means that calling `Sequence(number)` by itself does not do anything.
It is only when we call `Count()` on the sequence, that we're forcing iteration over the elements in the sequence.

```exercism/note
~~~~exercism/note
Using `yield` statement to generate a lazy sequence allows one to work with "infinite" sequences efficiently, as only the element to be returned (and the generated state machine) take up memory.
```
~~~~

## Shortening

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ var currentNumber = number;
var stepCount = 0;
```

```exercism/note
~~~~exercism/note
Re-assiging values to a parameter _is_ possible, but it is considered good practice to not do that.
```
~~~~

Then a `while` loop starts by checking whether the current number is not equal to `1`; if it is, the method terminates:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ public static BigInteger PrivateKey(BigInteger p)

This will generate a number `>= 1` and `< p`.

```exercism/note
~~~~exercism/note
The `Random.Shared` instance if guaranteed to be thread-safe, so is usually preferrable over creating your own `Random` instance.
```
~~~~

## Calculate public key and secret

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/gigasecond/.approaches/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ As C# `DateTime` instances are immutable, this means that you'll need to return

A gigasecond is equal to one billion seconds, which we can write as `1_000_000_000`.

```exercism/note
~~~~exercism/note
Using underscores as digit separators can help make large numbers a lot more readable.
```
~~~~

Alternative, scientific notation can be used for a more compact notation: `1e9`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,9 @@ else
_roster[grade] = new SortedSet<string> { student };
```

```exercism/note
~~~~exercism/note
Not that we don't worry about sorting, this will all happen transparently due to our choice of data structures.
```
~~~~

We could also rewrite this to:

Expand Down Expand Up @@ -161,14 +161,14 @@ public IEnumerable<string> Grade(int grade)
}
```

```exercism/note
~~~~exercism/note
The pattern of checking if a dictionary contains a key followed by accessing that value by key after that check is slightly wasteful, as it will require accessing the dictionary twice.
For this pattern, you should instead use `TryGetValue()`, which returns a `bool` value indicating if the key exists and has an `out` parameter for the retrieved value (if any)
```
~~~~

```exercism/note
~~~~exercism/note
We're using [`Enumerable.Empty<string>()`](https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.empty), which is best practice when returning an empty enumerable (for performance reasons).
```
~~~~

With this knowledge, let's rewrite out method a bit:

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/hamming/.approaches/for-loop/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,9 @@ We then use a [`for`-loop][for-statement] to iterate over each index of the firs
for (var i = 0; i < strand1.Length; i++)
```

```exercism/note
~~~~exercism/note
We could equally well have used `i < strand2.Length`, as both strings are guaranteed to have the same length.
```
~~~~

Within the loop, we can then use a simple [`if`-statement][if-statement] to check if the two strings have different characters at the specified index, and if so, increment the `distance` by one:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ else

We use `TryGetValue()` to check if there already is an existing count associated with the key, and if so, we increment the existing value, otherwise we'll assign a new value.

```exercism/note
~~~~exercism/note
You don't have to worry about any concurrent updates to the dictionary, PLINQ will handle this for you.
```
~~~~

Finally, we'll return the updated accumulator value:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,10 @@ The regex pattern then becomes:

As we are now using a backslash that should be interpreted as an escape character, we prefix the string with the `@` character, making it a [_verbatim string_](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/verbatim).
```exercism/note
~~~~exercism/note
Verbatim strings ensure that characters like a backslash are not interpreted as escape characters, but instead inserted literally.
This is especially convenient when working with regular expressions, as one often uses backslashes.
```
~~~~

The next step is to replace all the words in our sentence using our regex pattern, which we can do with [`Regex.Replace()`][regex-replace].
This method takes an input, a matching pattern _and_ a replacement pattern.
Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/proverb/.approaches/for-loop/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,9 @@ var lines = new string[subjects.Length];

To reiterate, there will be one line in the returned array for each adjacent subject pair.

```exercism/note
~~~~exercism/note
Breaking up of a collection into adjacent sub-collection of a certain size of sometimes also referred to as a _sliding window_.
```
~~~~

Let's look at an example, where the subjects array contains `"nail"`, `"shoe"` and `"horse"`.
There are two adjacent subject pairs in this array:
Expand Down
12 changes: 6 additions & 6 deletions exercises/practice/proverb/.approaches/linq/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ if (!subjects.Any())
return Array.Empty<string>();
```

```exercism/note
~~~~exercism/note
As the `!` operator can be easy to miss whilst reading code, try to write code that doesn't use negation (where possible).
```
~~~~

## Subjects: one

Expand All @@ -74,9 +74,9 @@ This has the benefit of being more expressive _and_ would also work for collecti
Handling multiple subjects is where the fun begins!
To reiterate, there will be one line in the returned array for each adjacent subject pair.

```exercism/note
~~~~exercism/note
Breaking up of a collection into adjacent sub-collection of a certain size of sometimes also referred to as a _sliding window_.
```
~~~~

Let's look at an example, where the subjects array contains `"nail"`, `"shoe"` and `"horse"`.
There are two adjacent subject pairs in this array:
Expand All @@ -94,9 +94,9 @@ We can use a little trick by calling the [`Zip()` method][enumerable.zip] on the

What `Zip()` does is that it works on two enumerables and creates a new enumerable where element is a pair (tuple) of values, the first element being the n-th value of the first enumerable and the second element being the n-th value of the second enumerable.

```exercism/note
~~~~exercism/note
The number of elements returned by `Zip()` is equal to the minimum of the lengths of both enumerables.
```
~~~~

As an example:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ public static class ReverseString

The `string` class' [`ToCharArray()`][to-char-array] method returns the string's characters as a `char[]`.

```exercism/caution
~~~~exercism/caution
The `char[]` returned by `ToCharArray()` is a **copy** of the `string`'s characters.
Modifying the values in the `char[]` does **not** update the `string` it was created from.
```
~~~~

We then pass the `char[]` to the [`Array.Reverse()`][array-reverse] method, which will reverse the array's content _in-place_ (meaning the argument is modified).

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/reverse-string/.approaches/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ The key to this exercise is to reverse a string's characters whilst C# strings b

- The most common way to create a new `string` (apart from hardcoding a string literal) is to call the [constructor that takes an array of characters][constructor-array-chars] (`char []`).

```exercism/note
~~~~exercism/note
C# strings represent text as a sequence of UTF-16 code units.
This means that you don't have to worry about multi-byte Unicode characters, as those are treated as one character.
```
~~~~

## Approach: LINQ

Expand Down
4 changes: 2 additions & 2 deletions exercises/practice/reverse-string/.approaches/span/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,10 @@ Span<char> chars = stackalloc char[input.Length];

With this version, the memory allocated for the `Span<char>` is all on the stack and no garbage collection is needed for that data.

```exercism/caution
~~~~exercism/caution
The stack has a finite amount of memory.
This means that for large strings, the above code will result in a `StackOverflowException` being thrown.
```
~~~~

So what is the limit for the amount of memory we can allocate?
Well, this depends on how memory has already been allocated on the stack.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ public static class ReverseString
Strings can also be created using the [`StringBuilder`][string-builder] class.
The purpose of this class is to efficiently and incrementally build a `string`.

```exercism/note
~~~~exercism/note
A `StringBuilder` is often overkill when used to create short strings, but can be very useful to create larger strings.
```
~~~~

The first step is to create a `StringBuilder`.
We then use a `for`-loop to walk through the string's characters in reverse order, appending them to the `StringBuilder` via its [`Append()`][string-builder-append] method.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,9 @@ The `Span<T>` approach has the downside of being more error-prone to write and f

The two slowest approaches, LINQ and `StringBuilder`, are also the ones that allocate (the most) memory.

```exercism/note
~~~~exercism/note
Reducing memory allocation is often a great way to improve performance.
```
~~~~

[approaches]: https://exercism.org/tracks/csharp/exercises/reverse-string/approaches
[approach-linq]: https://exercism.org/tracks/csharp/exercises/reverse-string/approaches/linq
Expand Down
Loading

0 comments on commit 08efea6

Please sign in to comment.