Merge branch 'main' into elyses-enchantments

Author: colinleach

.github/workflows/exercise-tests.yml

@@ -58,7 +58,7 @@ jobs:
         run: julia --color=yes --project runtestrunner.jl
 
       - name: Upload reports as artifact
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1
         with:
           name: test-reports
           path: ${{ steps.generate-reports.outputs.results-path }}

concepts.wip/conditionals/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "authors": [
+    "colinleach"
+  ],
+  "contributors": [
+    "BNAndras"
+  ],
+  "blurb": "Julia has boolean values true and false, operators ! (not), && (and), || (or)."
+}

concepts.wip/conditionals/about.md

@@ -0,0 +1,119 @@
+# About
+
+## Booleans in Julia
+
+True or false values are represented by the `Bool` type.
+It contains only two values: `true` and `false`.
+
+```julia-repl
+julia> true
+true
+
+julia> false
+false
+
+julia> typeof(true)
+Bool
+```
+
+In contrast to several other languages, Julia deliberately has no concept of "truthiness", and only expressions which evaluate to `true` or `false` will be treated as a `Bool`.
+
+Specifically, empty arrays or strings will *not* be interpreted as `false`.
+There must be an appropriate test such as `isempty()` if you want special handling for empty values.
+
+## Boolean operators
+
+There are three [Boolean operators][boolean-operators] in Julia.
+
+`&&` is Boolean "and".
+It evaluates to `true` if the expressions on *both* sides of `&&` are `true`.
+
+```julia-repl
+julia> true && true
+true
+
+julia> true && false
+false
+```
+
+`||` is Boolean "or".
+It evaluates to `true` if an expression on *either* side of `||` is `true`.
+
+```julia-repl
+julia> true || true
+true
+
+julia> false || true
+true
+```
+
+`!` is Boolean "not".
+It exchanges (inverts) `true` and `false` values.
+
+```julia-repl
+julia> !true
+false
+
+julia> !false
+true
+```
+
+Similar operators will be conceptually familiar to users of many other languages, though the precise syntax may vary between languages.
+
+## Operator precedence
+
+In more complex expressions, it can be useful to know that `&&` has a slightly higher [precedence][operator-precedence] than `||` *(in the same way that `*` is applied before `+` in arithmetic expressions)*.
+
+Relying on this can be confusing and error-prone.
+For clarity, use parentheses to make your intention clear.
+
+## Short-circuit evaluation
+
+Does the expression `true || x` depend on the value of `x`, or can the compiler ignore `x`?
+
+Julia evaluates Boolean expressions from left to right, and stops when it has an unambiguous result.
+
+For example, `true || x` must be `true`, regardless of `x`, so `x` is not evaluated.
+Similarly, `false && y` is `false`, with no need to evaluate `y`.
+
+Conversely, `true && x` is `true` *only if* `x` is `true`, so `x` must be evaluated.
+
+Similarly, if we chain multiple operators:
+
+```julia-repl
+julia> true && false && something_else
+false
+```
+
+Because `true && false` must be `false`, the `something_else` is unimportant and is ignored by the compiler.
+
+In this case, `something_else` did not exist as a variable, but including it in this context gave no error *(test this in the REPL if you doubt it)*.
+
+Such short-circuit evaluation is quite often used by Julia programmers as a shortcut to trap runtime problems and edge cases:
+
+```julia
+all_ok || do_something()
+
+is_problem && do_something_else()
+```
+
+For example, the `do_something` might be an early `return` from the function if `all_ok` is `false`, or assigning a default value to a variable before continuing.
+
+This is a slight abuse of Boolean syntax, but it can be very convenient.
+
+## How Bools work internally
+
+If a Bool is included in an *arithmetic* expression, `true` is interpreted as `1` and `false` as `0`, reflecting how they are stored.
+
+If you are used to lower-level languages (C and similar), *please* avoid using this often.
+It will reduce code readability and make debugging harder.
+
+You may sometimes see the numerical values used as a quick way to count how many things are `true`.
+
+```julia-repl
+julia> true + false + true
+2
+```
+
+[operator-precedence]: https://docs.julialang.org/en/v1/manual/mathematical-operations/#Operator-Precedence-and-Associativity
+[boolean-operators]: https://docs.julialang.org/en/v1/manual/mathematical-operations/#Boolean-Operators

concepts.wip/conditionals/introduction.md

@@ -0,0 +1,58 @@
+# Introduction
+
+## Booleans in Julia
+
+True or false values are represented by the `Bool` type.
+It contains only two values: `true` and `false`.
+
+```julia-repl
+julia> true
+true
+
+julia> false
+false
+```
+
+## Boolean Operators
+
+There are three Boolean operators in Julia.
+
+`&&` is Boolean "and".
+It evaluates to `true` if the expressions on *both* sides of `&&` are `true`.
+
+```julia-repl
+julia> true && true
+true
+
+julia> true && false
+false
+```
+
+`||` is Boolean "or".
+It evaluates to `true` if an expression on *either* side of `||` is `true`.
+
+```julia-repl
+julia> true || true
+true
+
+julia> false || true
+true
+```
+
+`!` is Boolean "not".
+It exchanges `true` and `false` values.
+
+```julia-repl
+julia> !true
+false
+
+julia> !false
+true
+```
+
+For longer and more complicated expressions, it is best to use parentheses to make your intention clear.
+
+```julia-repl
+julia> (true || false) && (false && true)
+false
+```

concepts.wip/conditionals/links.json

@@ -0,0 +1,6 @@
+[
+  {
+    "url": "https://docs.julialang.org/en/v1/manual/mathematical-operations/#Boolean-Operators",
+    "description": "Boolean Operators, section in the manual"
+  }
+]

concepts/functions/.meta/config.json renamed to concepts.wip/functions/.meta/config.json

@@ -0,0 +1,7 @@
+{
+  "authors": [
+    "colinleach"
+  ],
+  "contributors": [],
+  "blurb": "The conditionals 'if', 'elseif' ('else + if'), and 'else' are used to control the flow of execution and make decisions in a program."
+}

concepts/functions/about.md renamed to concepts.wip/functions/about.md

@@ -0,0 +1,100 @@
+# About
+
+## Comparison operators
+
+[Comparison operators in Julia][numeric-comparisons] are similar to many other languages, though with some extra options for math-lovers.
+
+For equality, the operators are `==` (equal) and `!=` or `≠` (not equal).
+
+```julia
+txt = "abc"
+txt == "abc"  # true
+txt != "abc"  # false
+txt ≠ "abc"  # false (synonym for !=)
+```
+
+In addition, we have the various greater/less than operators.
+
+```julia
+1 < 3  # true
+3 > 3  # false
+3 <= 3  # true
+3 ≤ 3  # true (synonym for <=)
+4 >= 3  # true
+4 ≥ 3  # true (synonym for >=)
+```
+
+As often with Julia, an appropriate editor makes use of the mathematical symbol easy.
+Type `\ne`, `\le` or `\ge` then `TAB` to get `≠`, `≤` or `≥`.
+
+The previous example uses only numbers, but we will see in other parts of the syllabus that various additional types have a sense of ordering and can be tested for greater/less than.
+
+Comparison operators can be chained, which allows a clear and concise syntax:
+
+```julia
+n = 3
+1 ≤ n ≤ 5  # true (n "between" two limits)
+```
+
+The previous example is a synonym for `1 ≤ n && n ≤ 5`.
+
+## Branching with `if`
+
+This is the full form of an [`if` statement][conditional-eval]:
+
+```julia
+if conditional1
+    statements...
+elseif conditional2
+    statements...
+else
+    statements...
+end
+```
+
+There is no need for parentheses `()` or braces `{}`, and indentation is "only" to improve readability _(but readability is very important!)_.
+
+Both `elseif` and `else` are optional, and there can be multiple `elseif` blocks.
+However, the `end` is required.
+
+It is possible to nest `if` statements, though you might want to help readability with the thoughtful use of parentheses, indents and comments.
+
+The shortest form of an `if` statement would be something like this:
+
+```julia
+if n < 0
+    n = 0
+end
+```
+
+As a reminder: only expressions that evaluate to `true` or `false` can be used as conditionals.
+Julia deliberately avoids any concept of "truthiness", so zero values, empty strings and empty arrays are _not_ equivalent to `false`. 
+
+## Ternary operator
+
+A simple and common situation is picking one of two values based on a conditional.
+
+Julia, like many languages, has a ternary operator to make this more concise.
+
+The syntax is `conditional ? value_if_true : value_if_false`.
+
+So the previous example could be rewritten:
+
+```julia
+n = n < 0 ? 0 : n
+```
+
+Parentheses are not required by the compiler, but may improve readability.
+
+## Does Julia have a `match` statement?
+
+No match/case structure is currently part of the base language.
+
+For simple cases, use of `if..elseif..else` is recommended.
+
+For sophisticated pattern matching, similar to Scala, the `Match.jl` package is popular.
+However, as with most third-party packages, `Match` is not available in the Exercism test runner.
+
+
+[numeric-comparisons]: https://docs.julialang.org/en/v1/manual/mathematical-operations/#Numeric-Comparisons
+[conditional-eval]: https://docs.julialang.org/en/v1/manual/control-flow/#man-conditional-evaluation