update TOC, fix details

Author: despadam

11_functional_programming.ipynb

@@ -14,24 +14,24 @@
     "## Table of Contents\n",
     "  - [References](#References)\n",
     "  - [Introduction](#Introduction)\n",
-    "  - [Why Functional Programming](#Why-Functional-Programming)\n",
+    "  - [Why Functional Programming?](#Why-Functional-Programming?)\n",
     "  - [The basic principles of functional programming](#The-basic-principles-of-functional-programming)\n",
     "    - [Pure Functions (Purity)](#Pure-Functions-(Purity))\n",
-    "      - [Example](#Example)\n",
+    "      - [Exercise on pure functions](#Exercise-on-pure-functions)\n",
     "      - [Quiz on pure functions](#Quiz-on-pure-functions)\n",
     "    - [Immutability](#Immutability)\n",
     "    - [Composition](#Composition)\n",
-    "      - [Example](#Example)\n",
+    "      - [Exercise on composition](#Exercise-on-composition)\n",
     "    - [Higher Order Functions / Functions as Values](#Higher-Order-Functions-/-Functions-as-Values)\n",
     "    - [Referential transparency](#Referential-transparency)\n",
     "    - [Type systems](#Type-systems)\n",
     "  - [Mapping / Iteration ](#Mapping-/-Iteration)\n",
     "    - [Mapping](#Mapping)\n",
     "    - [Filtering](#Filtering)\n",
     "    - [Reducing](#Reducing)\n",
-    "    - [Examples: Iteration and Mapping](#Examples:-Iteration-and-Mapping)\n",
+    "      - [Exercises on Iteration and Mapping](#Exercises-on-Iteration-and-Mapping)\n",
     "  - [List comprehensions](#List-comprehensions)\n",
-    "      - [Example: Keeping only multiples of n](#Example:-Keeping-only-multiples-of-n)\n",
+    "      - [Exercise: Keeping only multiples of `n`](#Exercise:-Keeping-only-multiples-of-n)\n",
     "  - [Combinining and splitting iterators](#Combinining-and-splitting-iterators)\n",
     "  - [Exercises](#Exercises)\n",
     "      - [Exercise 1: Transposing a Matrix](#Exercise-1:-Transposing-a-Matrix)\n",
@@ -269,11 +269,11 @@
     "%%ipytest\n",
     "\n",
     "def solution_pure_function(array: list, new_element: str):\n",
-    "    \"\"\"A function that appends a given array with a given element.\n",
+    "    \"\"\"A pure function that appends a given array with a given element.\n",
     "\n",
     "    Args:\n",
     "        array: the initial list\n",
-    "        new_element: the element to be added to the initial list\n",
+    "        new_element: the element to be added to the list\n",
     "    Returns:\n",
     "        - the appended list\n",
     "    \"\"\"\n",
@@ -311,6 +311,28 @@
     "## Immutability"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Previously, we saw this example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x = [\"short\", \"list\"] \n",
+    "def do_something(y: str) -> None:\n",
+    "    x.append(y)\n",
+    "\n",
+    "print(x)\n",
+    "do_something(\"a\")\n",
+    "print(x)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -320,9 +342,9 @@
     "tags": []
    },
    "source": [
-    "When writing programs in functional style, we usually avoid functions like `do_something`.\n",
-    "Instead of modifying existing data (*mutation*), you write functions that transform your data and return new objects.\n",
-    "Another way to rewrite the function above could be:"
+    "But when writing programs in functional style, we prefer to avoid functions like `do_something`.\n",
+    "Instead of modifying existing data (*mutation*), we write functions that transform the data and return new objects.\n",
+    "So, another way to rewrite the function above could be:"
    ]
   },
   {
@@ -621,8 +643,10 @@
     }
    },
    "source": [
-    "If `transparent_function` is referentially transparent, we can replace its value in the expression `y1 = transparent_function(1) + 5` and we obtain the same value.\n",
-    "In other words, the value of `y` does not change if we execute it again, as shown in the code above: we have two expressions `y1` and `y2` that use the same code and because `x` is referentially transparent, their values are equal.\n",
+    "If `transparent_function` is referentially transparent, we can replace the function call `transparent_function(1)` with its result without changing the meaning of the expression.\n",
+    "For example, in `y1 = transparent_function(1) + 5`, the result of `y1` will always be the same every time the code runs.\n",
+    "This is demonstrated by two expressions, `y1` and `y2`, that both use `transparent_function(1)`, and because the function is referentially transparent, `y1` and `y2` will have equal values.\n",
+    "\n",
     "\n",
     "In this case, this is true because the value of `x` is simply 1 and is invariant.\n",
     "\n",
@@ -1300,7 +1324,7 @@
     "\n",
     "<div class=\"alert alert-block alert-warning\">\n",
     "    <h4><b>Question</b></h4>\n",
-    "    Given a list <code>L</code> of integers, write a function that only keeps the numbers that are multiples of a given constant <code>k</code>.\n",
+    "    Given a list of integers, write a function that only keeps the numbers that are multiples of a given constant <code>k</code>.\n",
     "    <ul>\n",
     "        <li>\n",
     "            <strong>Example 1</strong>: given <code>nums = [1, 2, 3, 4, 5]</code>, and <code>k = 2</code>, the result must be <code>[2, 4]</code>\n",
@@ -1339,13 +1363,13 @@
     "    \"\"\"A function that keeps only the multiples of k from a given list.\n",
     "\n",
     "    Args:\n",
-    "        l: the initial list\n",
+    "        my_list: the initial list\n",
     "        k: the integer number\n",
     "    Returns:\n",
     "        - the filtered list\n",
     "    \"\"\"\n",
     "\n",
-    "    return [a for a in my_list if a % k == 0]"
+    "    return"
    ]
   },
   {