move deprecated exercises back to concept section

Author: fridewald

concepts/iterators/.meta/config.json

@@ -0,0 +1,8 @@
+{
+  "blurb": "Iterators in Gleam are lazily evaluated sequences.",
+  "authors": [
+    "lpil"
+  ],
+  "contributors": [
+  ]
+}

concepts/iterators/about.md

@@ -0,0 +1,39 @@
+# About
+
+An `Iterator` in Gleam is similar to a list in that it is an ordered collection of values, where all values are of the same type. It differs from a list in that it is lazy, meaning that it does not store all of its values in memory at once, but instead calculates them as they are needed.
+
+This is useful when working with sequences that are very large or even infinite in size, as it allows us to work with them when we do not have enough free memory to store them all at once.
+
+The `gleam/iterator` module defines the `Iterator` type as well as functions for working with iterators.
+
+Many of the functions for lists also exist for iterators, such as `map`, `filter`, and `take`. These functions return iterators, so the functions do not actually perform any work until the iterator is consumed.
+
+```gleam
+let iter = 
+  [1, 2, 3, 4, 5, 6]
+  |> iterator.from_list
+  |> iterator.filter(fn(x) { x > 2 })
+  |> iterator.take(2)
+
+// No work has been done yet as the iterator has not been consumed
+
+// Consume the iterator and collect the values into a list
+iterator.to_list(iter)
+// -> [3, 4]
+```
+
+The `unfold` function can be used to create iterators from a function that is called repeatedly to produce the next value in the sequence.
+
+Here the `unfold` function is used to create an iterator that produces the Fibonacci sequence:
+
+```gleam 
+iterator.unfold(#(0, 1), fn(pair) {
+  let x = pair.0 + pair.1
+  iterator.Next(element: x, accumulator: #(pair.1, x))
+})
+|> iterator.take(6)
+|> iterator.to_list
+// -> [1, 2, 3, 5, 8, 13]
+```
+
+The sequence here is infinite, so the `take` function is used to make it finite before collecting the values into a list. If `to_list` is called on an infinite iterator the program will run until the program runs out of memory and crashes.

concepts/iterators/introduction.md

@@ -0,0 +1,39 @@
+# Introduction
+
+An `Iterator` in Gleam is similar to a list in that it is an ordered collection of values, where all values are of the same type. It differs from a list in that it is lazy, meaning that it does not store all of its values in memory at once, but instead calculates them as they are needed.
+
+This is useful when working with sequences that are very large or even infinite in size, as it allows us to work with them when we do not have enough free memory to store them all at once.
+
+The `gleam/iterator` module defines the `Iterator` type as well as functions for working with iterators.
+
+Many of the functions for lists also exist for iterators, such as `map`, `filter`, and `take`. These functions return iterators, so the functions do not actually perform any work until the iterator is consumed.
+
+```gleam
+let iter = 
+  [1, 2, 3, 4, 5, 6]
+  |> iterator.from_list
+  |> iterator.filter(fn(x) { x > 2 })
+  |> iterator.take(2)
+
+// No work has been done yet as the iterator has not been consumed
+
+// Consume the iterator and collect the values into a list
+iterator.to_list(iter)
+// -> [3, 4]
+```
+
+The `unfold` function can be used to create iterators from a function that is called repeatedly to produce the next value in the sequence.
+
+Here the `unfold` function is used to create an iterator that produces the Fibonacci sequence:
+
+```gleam 
+iterator.unfold(#(0, 1), fn(pair) {
+  let x = pair.0 + pair.1
+  iterator.Next(element: x, accumulator: #(pair.1, x))
+})
+|> iterator.take(6)
+|> iterator.to_list
+// -> [1, 2, 3, 5, 8, 13]
+```
+
+The sequence here is infinite, so the `take` function is used to make it finite before collecting the values into a list. If `to_list` is called on an infinite iterator the program will run until the program runs out of memory and crashes.

concepts/iterators/links.json

@@ -0,0 +1,6 @@
+[
+  {
+    "url": "https://hexdocs.pm/gleam_stdlib/gleam/iterator.html",
+    "description": "gleam/iterator module documentation"
+  }
+]

concepts/queues/.meta/config.json

@@ -0,0 +1,8 @@
+{
+  "blurb": "Queues in Gleam are immutable sequences of values that can be accessed quickly from the front or the back.",
+  "authors": [
+    "lpil"
+  ],
+  "contributors": [
+  ]
+}

concepts/queues/about.md

@@ -0,0 +1,65 @@
+# About
+
+The Gleam standard library implements a `Queue` type in the `gleam/queue` module. It is similar to the `List` type, but with a few key differences:
+
+- The `Queue` type doesn't have a literal syntax that can be used to construct queues or pattern match on them.
+- Elements can be efficiently added to and removed from both the front and back of the `Queue` type, while the `List` type can only efficiently add and remove elements from the front.
+
+Most of the time you will want to use the `List` type, but when you need to be able to add and remove from the end of a collection, the `Queue` type is a good choice.
+
+Queues can be created using the `queue.new` and `queue.from_list` functions:
+
+```gleam
+let empty = queue.new()
+let one_to_four = queue.from_list([1, 2, 3, 4])
+```
+
+Elements can be added to the queue using the `queue.push_front` and `queue.push_back` functions:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+let one_to_five = queue.push_back(one_to_four, 5)
+let zero_to_five = queue.push_front(one_to_five, 0)
+```
+
+Elements can be removed from the queue using the `queue.pop_front` and `queue.pop_back` functions:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+
+queue.pop_back(one_to_four)
+// -> Ok(#(4, queue.from_list([1, 2, 3])))
+
+queue.pop_front(one_to_four)
+// -> Ok(#(1, queue.from_list([2, 3, 4])))
+
+queue.pop_front(queue.new())
+// -> Error(Nil)
+```
+
+A queue can be converted into a list using the `queue.to_list` function:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+queue.to_list(one_to_four)
+// -> [1, 2, 3, 4]
+```
+
+## Queue equality
+
+Due to how queues are implemented, two queues with the same elements in the same order may not be equal according to the `==` operator, which compares values structurally. For example:
+
+```gleam
+let empty = queue.new()
+let a = queue.push_front(empty, 1)
+let b = queue.push_back(empty, 1)
+a == b
+// -> False
+```
+
+If you need to compare two queues for equality use can use the `queue.is_logically_equal` function.
+
+```gleam
+queue.is_logically_equal(a, b, fn(x, y) { x == y })))
+// -> True
+```

concepts/queues/introduction.md

@@ -0,0 +1,65 @@
+# Introduction
+
+The Gleam standard library implements a `Queue` type in the `gleam/queue` module. It is similar to the `List` type, but with a few key differences:
+
+- The `Queue` type doesn't have a literal syntax that can be used to construct queues or pattern match on them.
+- Elements can be efficiently added to and removed from both the front and back of the `Queue` type, while the `List` type can only efficiently add and remove elements from the front.
+
+Most of the time you will want to use the `List` type, but when you need to be able to add and remove from the end of a collection, the `Queue` type is a good choice.
+
+Queues can be created using the `queue.new` and `queue.from_list` functions:
+
+```gleam
+let empty = queue.new()
+let one_to_four = queue.from_list([1, 2, 3, 4])
+```
+
+Elements can be added to the queue using the `queue.push_front` and `queue.push_back` functions:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+let one_to_five = queue.push_back(one_to_four, 5)
+let zero_to_five = queue.push_front(one_to_five, 0)
+```
+
+Elements can be removed from the queue using the `queue.pop_front` and `queue.pop_back` functions:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+
+queue.pop_back(one_to_four)
+// -> Ok(#(4, queue.from_list([1, 2, 3])))
+
+queue.pop_front(one_to_four)
+// -> Ok(#(1, queue.from_list([2, 3, 4])))
+
+queue.pop_front(queue.new())
+// -> Error(Nil)
+```
+
+A queue can be converted into a list using the `queue.to_list` function:
+
+```gleam
+let one_to_four = queue.from_list([1, 2, 3, 4])
+queue.to_list(one_to_four)
+// -> [1, 2, 3, 4]
+```
+
+## Queue equality
+
+Due to how queues are implemented, two queues with the same elements in the same order may not be equal according to the `==` operator, which compares values structurally. For example:
+
+```gleam
+let empty = queue.new()
+let a = queue.push_front(empty, 1)
+let b = queue.push_back(empty, 1)
+a == b
+// -> False
+```
+
+If you need to compare two queues for equality you can use the `queue.is_logically_equal` function.
+
+```gleam
+queue.is_logically_equal(a, b, fn(x, y) { x == y })))
+// -> True
+```

concepts/queues/links.json

@@ -0,0 +1,6 @@
+[
+  {
+    "url": "https://hexdocs.pm/gleam_stdlib/gleam/queue.html",
+    "description": "gleam/queue module documentation"
+  }
+]

concepts/regular-expressions/.meta/config.json

@@ -0,0 +1,8 @@
+{
+  "blurb": "Regular expressions in Gleam follow the PCRE specification (Perl Compatible Regular Expressions), and can be used to work with patterns in strings.",
+  "authors": [
+    "lpil"
+  ],
+  "contributors": [
+  ]
+}

concepts/regular-expressions/about.md

@@ -0,0 +1,62 @@
+# About
+
+Regular expressions in Gleam follow the **PCRE** specification (**P**erl **C**ompatible **R**egular **E**xpressions), similarly to other popular languages like Java, JavaScript, or Ruby.
+
+The `gleam/regex` module offers functions for working with regular expressions.
+
+~~~~exercism/note
+This exercise assumes that you already know regular expression syntax, including character classes, quantifiers, groups, and captures.
+
+if you need to refresh your regular expression knowledge, check out one of those sources: [Regular-Expressions.info](https://www.regular-expressions.info), [Rex Egg](https://www.rexegg.com/), [RegexOne](https://regexone.com/), [Regular Expressions 101](https://regex101.com/), [RegExr](https://regexr.com/).
+~~~~
+
+The most common way to create regular expressions is using the `regex.from_string` function.
+
+```gleam
+let assert Ok(re) = regex.from_string("test")
+```
+
+The `regex.from_string` function yields an `Error` if the regular expression syntax is invalid, so a let-assertion has been used here to ensure the regular expression is valid.
+
+The `regex.check` function can be used to check if a regular expression matches a string.
+
+```gleam
+let assert Ok(re) = regex.from_string("test")
+
+regex.check(re, "this is a test")
+// -> True
+
+regex.check(re, "this is too")
+// -> False
+```
+
+
+## Captures
+
+If you wish to capture substrings using a regular expression, the `regex.scan` function can be used to return a list of matches.
+
+```gleam
+let assert Ok(re) = regex.from_string("[oi]n a (\\w+)")
+regex.scan(with: re, content: "I am on a boat in a lake.")
+// -> [
+//   Match(
+//     content: "on a boat",
+//     submatches: [Some("boat")]
+//   ),
+//   Match(
+//     content: "in a lake",
+//     submatches: [Some("lake")]
+//   )
+// ]
+```
+
+## Modifiers
+
+The behaviour of a regular expression can be modified by creating it with the `regex.compile` function and passing in options.
+
+```gleam
+let options = regex.Options(case_insensitive: True, multi_line: False)
+let assert Ok(re) = regex.compile("[A-Z]", with: options)
+regex.check(re, "abc123")
+// -> True
+```