notebooks/0103-MethodsEvents.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# Session 3: Making our own Types - Methods, Events, Delegates\n",
    "\n",
    "We learned in our last session about how to make classes with properties, constructors, and fields.  We're going to continue adding features to our classes so that we can act on our classes and receive notifications about our classes.\n",
    "\n",
    "## Methods\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    Previously in Session 2, we wrote constructors to allow you to control the creation of classes.  These are _methods_ but this time we will expand on what we've previously learned\n",
    "</div>\n",
    "\n",
    "[Methods are defined in the official documentation](https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/methods?WT.mc_id=visualstudio-twitch-jefritz) as a code block containing a series of statements that the program can execute.  We're going to expand on that definition to also state that a method can (but is not required) return values to its caller. We typically think of methods as an action that our class _performs_ or an _acting on_ the class.\n",
    "\n",
    "A method has a **signature** that defines how you can interact with it.  The signature is followed immediately by curly braces **{ }** that wrap the code to be executed in the method and takes the following format:\n",
    "\n",
    "_\\[Access Modifier]*_ **Return Type** **Name**(_\\[Parameters]_)  \n",
    "\n",
    "By default a method with no access modifiers is considered `private`\n",
    "\n",
    "Parameters are comma-delimited and defined similar to our variables with their type and name of the parameter:\n",
    "\n",
    "`int myFirstParameter`\n",
    "\n",
    "Let's take a look at some simple methods in a `Student` class:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    public void Enroll() {\r\n",
    "        // do enrollment steps\r\n",
    "    }\r\n",
    "    \r\n",
    "    internal void LeaveClassEarly(DateTime departureTime) {\r\n",
    "        // leave class code\r\n",
    "    }\r\n",
    "    \r\n",
    "    public decimal CalculateGradeForClass(string className) {\r\n",
    "        \r\n",
    "        // grade calculation code\r\n",
    "        \r\n",
    "        // This method returns a value of type decimal \r\n",
    "        return 0.95m;\r\n",
    "    }\r\n",
    "    \r\n",
    "    public class Grade {\r\n",
    "        \r\n",
    "        public string NameOfClass { get; set; }\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "display(s.CalculateGradeForClass(\"Quantum Physics\"));\r\n",
    "\r\n",
    "var g = new Student.Grade();\r\n",
    "display(g);\r\n"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "\r\n",
       "<div>\r\n",
       "    <div id='dotnet-interactive-this-cell-26992.b1b9e0ebe05f4c528245537894ac84a4' style='display: none'>\r\n",
       "        The below script needs to be able to find the current output cell; this is an easy method to get it.\r\n",
       "    </div>\r\n",
       "    <script type='text/javascript'>\r\n",
       "// ensure `require` is available globally\r\n",
       "if (typeof require !== typeof Function || typeof require.config !== typeof Function) {\r\n",
       "    let require_script = document.createElement('script');\r\n",
       "    require_script.setAttribute('src', 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js');\r\n",
       "    require_script.setAttribute('type', 'text/javascript');\r\n",
       "    require_script.onload = function () {\r\n",
       "        loadDotnetInteractiveApi();\r\n",
       "    };\r\n",
       "\r\n",
       "    document.getElementsByTagName('head')[0].appendChild(require_script);\r\n",
       "}\r\n",
       "else {\r\n",
       "    loadDotnetInteractiveApi();\r\n",
       "}\r\n",
       "\r\n",
       "async function probeAddresses(probingAddresses) {\r\n",
       "    function timeout(ms, promise) {\r\n",
       "        return new Promise(function (resolve, reject) {\r\n",
       "            setTimeout(function () {\r\n",
       "                reject(new Error('timeout'))\r\n",
       "            }, ms)\r\n",
       "            promise.then(resolve, reject)\r\n",
       "        })\r\n",
       "    }\r\n",
       "\r\n",
       "    if (Array.isArray(probingAddresses)) {\r\n",
       "        for (let i = 0; i < probingAddresses.length; i++) {\r\n",
       "\r\n",
       "            let rootUrl = probingAddresses[i];\r\n",
       "\r\n",
       "            if (!rootUrl.endsWith('/')) {\r\n",
       "                rootUrl = `${rootUrl}/`;\r\n",
       "            }\r\n",
       "\r\n",
       "            try {\r\n",
       "                let response = await timeout(1000, fetch(`${rootUrl}discovery`, {\r\n",
       "                    method: 'POST',\r\n",
       "                    cache: 'no-cache',\r\n",
       "                    mode: 'cors',\r\n",
       "                    timeout: 1000,\r\n",
       "                    headers: {\r\n",
       "                        'Content-Type': 'text/plain'\r\n",
       "                    },\r\n",
       "                    body: probingAddresses[i]\r\n",
       "                }));\r\n",
       "\r\n",
       "                if (response.status == 200) {\r\n",
       "                    return rootUrl;\r\n",
       "                }\r\n",
       "            }\r\n",
       "            catch (e) { }\r\n",
       "        }\r\n",
       "    }\r\n",
       "}\r\n",
       "\r\n",
       "function loadDotnetInteractiveApi() {\r\n",
       "    probeAddresses([\"http://192.168.1.71:1002/\", \"http://172.29.80.1:1002/\", \"http://127.0.0.1:1002/\"])\r\n",
       "        .then((root) => {\r\n",
       "            // use probing to find host url and api resources\r\n",
       "            // load interactive helpers and language services\r\n",
       "            let dotnet_require = require.config({\r\n",
       "                context: '26992.b1b9e0ebe05f4c528245537894ac84a4',\r\n",
       "                paths: {\r\n",
       "                    'dotnet-interactive': `${root}resources`\r\n",
       "                }\r\n",
       "            }) || require;\r\n",
       "            if (!window.dotnet_require) {\r\n",
       "                window.dotnet_require = dotnet_require;\r\n",
       "            }\r\n",
       "        \r\n",
       "            dotnet_require([\r\n",
       "                    'dotnet-interactive/dotnet-interactive'\r\n",
       "                ],\r\n",
       "                function (dotnet) {\r\n",
       "                    dotnet.init(window);\r\n",
       "                },\r\n",
       "                function (error) {\r\n",
       "                    console.log(error);\r\n",
       "                }\r\n",
       "            );\r\n",
       "        })\r\n",
       "        .catch(error => {console.log(error);});\r\n",
       "    }\r\n",
       "    </script>\r\n",
       "</div>"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "0.95"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "<table><thead><tr><th>NameOfClass</th></tr></thead><tbody><tr><td>&lt;null&gt;</td></tr></tbody></table>"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Method access modifiers can be `public`, `protected`, `private`, `internal`, `protected internal`.  They can also be marked `static` to indicate that the method runs for all instances of the class and cannot access individual fields and properties of the class.  We'll see more about `static` and other modifiers like `override`, `virtual` and `abstract` in session 4.\n",
    "\n",
    "### Overloading Methods\n",
    "\n",
    "Just like we can provide multiple constructors, as shown in Session 2, we can also provide multiple methods with the same name and different parameters and return types.  This is called **Method Overloading** and can be very valuable to provide alternate interactions with your class that have the same intention.  \n",
    "\n",
    "Let's revisit the `CalculateGradeForClass` method in our last example.  Typically, we would _assume_ that we are calculating the grade for a student for the current semester or year.  What if we wanted to go back and recalculate for a different time?  A different method with a similar signature, but additionally accepting a year parameter could be added to provide additional context.  "
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    public void Enroll() {\r\n",
    "        // do enrollment steps\r\n",
    "    }\r\n",
    "\r\n",
    "    // This signature assumes calculating the grade for a class THIS YEAR\r\n",
    "    public decimal CalculateGradeForClass(string className) {\r\n",
    "        \r\n",
    "        // Let's delegate the calculation to the OTHER implementation of CalculateGradeForClass and pass this year\r\n",
    "        return CalculateGradeForClass(className, DateTime.Now.Year);\r\n",
    "        \r\n",
    "    }\r\n",
    "\r\n",
    "    public decimal CalculateGradeForClass(int yearEnrolled) {\r\n",
    "        \r\n",
    "        return 0.8m; //CalculateGradeForClass(className, DateTime.Now.Year);\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    // public decimal CalculateGradeForClass(int classScheduleBlock) {\r\n",
    "        \r\n",
    "    //     return 0.8m; //CalculateGradeForClass(className, DateTime.Now.Year);\r\n",
    "        \r\n",
    "    // }\r\n",
    "    \r\n",
    "\r\n",
    "    public decimal CalculateGradeForClass(string className, int yearEnrolled) {\r\n",
    "        \r\n",
    "        // grade calculation code\r\n",
    "        \r\n",
    "        return 0.80m;\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    public class Grade {\r\n",
    "        \r\n",
    "        public string NameOfClass { get; set; }\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "display(\"Grade for this year: \" + s.CalculateGradeForClass(\"Quantum Physics\"));\r\n",
    "display(\"Grade for 2019: \" + s.CalculateGradeForClass(\"Quantum Physics\", 2019));"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Grade for this year: 0.80"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Grade for 2019: 0.80"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### The Magic params Parameter and Optional Parameters\n",
    "\n",
    "There is a special 'catch-all' `params` keyword you can use in your methods that will catch any arguments that are passed in to the method.  Let's update our student with the ability to calculate grade point average:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "\r\n",
    "\r\n",
    "    public decimal CalculateGradePointAverage(\r\n",
    "        int yearOfStudy, \r\n",
    "        params string[] classes) {\r\n",
    "        \r\n",
    "        foreach(var c in classes) {\r\n",
    "            display(\"Calculating for class \" + c);\r\n",
    "        }\r\n",
    "        \r\n",
    "        HelloWorld();\r\n",
    "\r\n",
    "        return 0.9m;\r\n",
    "        \r\n",
    "    }\r\n",
    "\r\n",
    "    /// <summary>\r\n",
    "    /// A method to say Hello World!\r\n",
    "    /// </summary>\r\n",
    "    public void HelloWorld() {\r\n",
    "        display(\"Hello world!\");\r\n",
    "    }\r\n",
    "\r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "display(s.CalculateGradePointAverage(2020, \"Algebra\", \"History\", \"Computer Science\", \"Art\", \"English\", \"German\", \"Gym\", \"Study Hall\"));"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Calculating for class Algebra"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class History"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Computer Science"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Art"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class English"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class German"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Gym"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Study Hall"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Hello world!"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">0.9</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Other arguments can be made optional by adding a default value to them:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    public decimal CalculateGradePointAverage(\r\n",
    "        short enrollmentYear = 2020, \r\n",
    "        params string[] classes) {\r\n",
    "\r\n",
    "        display(\"Calculating GPA for year \" + enrollmentYear);\r\n",
    "        \r\n",
    "        foreach(var c in classes) {\r\n",
    "            display(\"Calculating for class \" + c);\r\n",
    "        }\r\n",
    "        \r\n",
    "        return 0.9m;\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    public decimal CalculateGradePointAverage(\r\n",
    "        short enrollmentYear = 0) {\r\n",
    "        \r\n",
    "        if (enrollmentYear == 0) enrollmentYear = (short)DateTime.Now.Year;\r\n",
    "        \r\n",
    "        display(\"Calculating GPA for all classes in the year \" + enrollmentYear);\r\n",
    "        \r\n",
    "        return CalculateGradePointAverage(enrollmentYear, \"Art\", \"History\", \"Physics\");\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "display(s.CalculateGradePointAverage(2019, \"Algebra\", \"History\", \"Computer Science\"));\r\n",
    "display(s.CalculateGradePointAverage(classes: new [] {\"Algebra\", \"History\", \"Computer Science\"}));\r\n",
    "display(s.CalculateGradePointAverage());"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Calculating GPA for year 2019"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Algebra"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class History"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Computer Science"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">0.9</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating GPA for year 2020"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Algebra"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class History"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Computer Science"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">0.9</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating GPA for all classes in the year 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating GPA for year 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Art"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class History"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Calculating for class Physics"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">0.9</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Out and Ref\n",
    "\n",
    "Parameters passed into the method can **ALSO** take modifiers to set their interactions with the method.  The parameters can be passed both in and **OUT** as well as by value and by reference into the method.  This may seem a litle strange, so let's take a look at some samples.\n",
    "\n",
    "We'll look at the `out` and `ref` keywords in this demo.  `out` specifies that a parameter is set as an output and `ref` indicates that a parameter is passed by reference.  If these keywords are used in a method's parameter signature, they must also be used when executing the method."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    // Enroll and return a success indicator as well as the new StudentId\r\n",
    "    public bool Enroll(\r\n",
    "        short year, \r\n",
    "        out string studentId) {\r\n",
    "        \r\n",
    "        // Enrollment code\r\n",
    "        \r\n",
    "        studentId = \"1234567\";\r\n",
    "        return true;\r\n",
    "        \r\n",
    "    }\r\n",
    "\r\n",
    "    public void DoSomething(ref int myValue) {\r\n",
    "        myValue++;\r\n",
    "        display(\"Inside of DoSomething myValue is: \" + myValue);\r\n",
    "    }\r\n",
    "    \r\n",
    "    public void Hello(ref string myName) {\r\n",
    "        myName = myName + \" Jones\";\r\n",
    "        display(\"Hello: \" + myName);\r\n",
    "    }\r\n",
    "    \r\n",
    "    public void DeleteItemsFromShoppingCart(ref int numberOfItems) {\r\n",
    "        numberOfItems = 0;\r\n",
    "    }\r\n",
    "\r\n",
    "}\r\n",
    "\r\n",
    "var s= new Student();\r\n",
    "// string id = \"\";\r\n",
    "short year = 2020;\r\n",
    "\r\n",
    "// You can declare the output variable inline\r\n",
    "// by declaring its type like this:\r\n",
    "// display(s.Enroll(year, out string id));\r\n",
    "\r\n",
    "display(s.Enroll(year, out id));\r\n",
    "display(\"student id: \" + id);\r\n",
    "display(\"Year: \" + year);\r\n",
    "\r\n",
    "\r\n",
    "int myVar = 2020;\r\n",
    "s.DoSomething(ref myVar);\r\n",
    "display(\"myVar is: \" + myVar);\r\n",
    "\r\n",
    "\r\n",
    "var myName = \"Jeff\";\r\n",
    "s.Hello(ref myName);\r\n",
    "display(myName);\r\n"
   ],
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">True</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "student id: 1234567"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Year: 2020"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Inside of DoSomething myValue is: 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "myVar is: 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Hello: Jeff Jones"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Jeff Jones"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "The id is set in our method and MUST be set before the method ends to be returned properly.  Let's look at the `DoSomething` method that receives a value **ByReference** as indicated by the `ref` keyword.  Check out the behavior of `myValue` and tinker with adding and removing the `ref` keyword to see its behavior."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "int myValue = 10;\r\n",
    "s.DoSomething(ref myValue);\r\n",
    "display(myValue);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Inside of DoSomething myValue is: 11"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "11"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "The `myValue` integer is a **value type** and is passed as a reference into the `DoSomething` method where it is modified.  The reference to the `myValue` variable is updated inside the method, and its value reflects that update.\n",
    "\n",
    "Reference types, those types we create with the `class` keyword like `Student` are **ALWAYS** passed by reference into methods. "
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "\r\n",
    "    // Grade as a reference type is always passed by reference\r\n",
    "    public void CalculateGrade(Grade g) {\r\n",
    "        \r\n",
    "        g.FinalScore = 0.9m;\r\n",
    "        \r\n",
    "        /*\r\n",
    "        g = new Grade {\r\n",
    "            NameOfClass = \"Calculus\",\r\n",
    "            FinalScore = 0.75m\r\n",
    "        }; */\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    public class Grade {\r\n",
    "        public string NameOfClass {get; set;}\r\n",
    "        public decimal FinalScore { get; set; }\r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s= new Student();\r\n",
    "var g= new Student.Grade() { NameOfClass=\"Physics\", FinalScore=0.7m};\r\n",
    "\r\n",
    "display(g);\r\n",
    "s.CalculateGrade(g);\r\n",
    "display(g);\r\n",
    "\r\n"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "<table><thead><tr><th>NameOfClass</th><th>FinalScore</th></tr></thead><tbody><tr><td>Physics</td><td>0.7</td></tr></tbody></table>"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "<table><thead><tr><th>NameOfClass</th><th>FinalScore</th></tr></thead><tbody><tr><td>Physics</td><td>0.9</td></tr></tbody></table>"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Delegates\n",
    "\n",
    "Now that we know what a method is and how to interact with them, sometimes we want to pass a pointer to that method around our program.  This pointer to the method is called a **Delegate** and allows us to call the method from another location.  Delegates are defined with the method signature that they need to match in order to reference that method.  The [official documentation on delegates](https://docs.microsoft.com/dotnet/csharp/programming-guide/delegates?WT.mc_id=visualstudio-twitch-jefritz) has more on defining a delegate.\n",
    "\n",
    "Delegates are sometimes referred to as **Callback Functions**\n",
    "\n",
    "Let's take a look at passing a delegate for a pointer into another method."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "\r\n",
    "class Student {\r\n",
    "    \r\n",
    "    public delegate int CalculateHandler(\r\n",
    "        int myArg1, \r\n",
    "        int myArg2);\r\n",
    "    \r\n",
    "    public int Calculate(\r\n",
    "        int arg1, \r\n",
    "        int arg2, \r\n",
    "        CalculateHandler handler) {\r\n",
    "        \r\n",
    "        var output = handler(arg1, arg2);\r\n",
    "        return output;\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    public int Add(int arg1, int arg2) {\r\n",
    "        var output = arg1 + arg2;\r\n",
    "        display(\"Added: \" + output);\r\n",
    "        return output;\r\n",
    "    }\r\n",
    "    \r\n",
    "    public int Subtract(int arg1, int arg2) {\r\n",
    "        var output = arg1 - arg2;\r\n",
    "        display(\"Subtracted: \" + output);\r\n",
    "        return output;\r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "\r\n",
    "// instantiating a delegate is used with \r\n",
    "// a NEW keyword wrapping the name of \r\n",
    "// the method to be assigned\r\n",
    "var calcHandler = new Student.CalculateHandler(s.Add);\r\n",
    "s.Calculate(10, 5, calcHandler);"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Added: 15"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "We can also assign **anonymous methods** to a delegate to be passed around.  An anonymous method is defined with some paraenthesis enclosing the parameter list and an expression body indicated with the fat-arrow `=>` notation.  \n",
    "\n",
    "Consider this code to work with our Student CalculateHandler:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "var s = new Student();\r\n",
    "\r\n",
    "var multiply = new Student.CalculateHandler(\r\n",
    "    (foo, bar) => foo * bar);\r\n",
    "display(s.Calculate(10, 5, multiply));"
   ],
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"dni-plaintext\">50</div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "We can also directly cast a delegate when the type is specifed, allowing for implicit conversion to the delegate type.  This makes our code a little more terse, but the intent is still clear:\n"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "var s = new Student();\r\n",
    "\r\n",
    "s.Calculate(10, 5, s.Add);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Added: 15"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Multicast delegates\n",
    "\n",
    "Defined delegate types can be [**multicast**](https://docs.microsoft.com/dotnet/csharp/programming-guide/delegates/how-to-combine-delegates-multicast-delegates?WT.mc_id=visualstudio-twitch-jefritz) allowing them to point to multiple methods to be called.  This sounds a LITTLE weird, but it means that we can stack executions and pass that entire stack into another method.  Let's take a look at that `Student` and `CalculateHandler` from our previous example again."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "var s = new Student();\r\n",
    "\r\n",
    "// Define an initial delegate variable\r\n",
    "var calculation =  new Student.CalculateHandler(s.Subtract);\r\n",
    "calculation += new Student.CalculateHandler(s.Add);\r\n",
    "\r\n",
    "calculation += new Student.CalculateHandler((arg1, arg2) => {\r\n",
    "    var outValue = arg1 * arg2;\r\n",
    "    display(\"Multiplied: \" + outValue);\r\n",
    "    return outValue;\r\n",
    "});\r\n",
    "\r\n",
    "calculation -= new Student.CalculateHandler(s.Subtract);\r\n",
    "\r\n",
    "s.Calculate(10, 5, calculation);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Added: 15"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Multiplied: 50"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Delegates can be combined with `+` and `-` operators to stack them and remove them from the stack to be executed.  As we'll see with **Events** in the next section, adding and removing references to delegates is very important.\n",
    "\n",
    "This is different from executing a collection of delegates as seen below."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "\r\n",
    "class Student {\r\n",
    "    \r\n",
    "    public delegate int CalculateHandler(int myArg1, int myArg2);\r\n",
    "    \r\n",
    "    public int Calculate(int arg1, int arg2, params CalculateHandler[] handlers) {\r\n",
    "        \r\n",
    "        foreach (var handler in handlers) {\r\n",
    "            display(handler(arg1, arg2));\r\n",
    "        }\r\n",
    "\r\n",
    "        return 0;\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "    public int Add(int arg1, int arg2) {\r\n",
    "        var output = arg1 + arg2;\r\n",
    "        display(\"Added: \" + output);\r\n",
    "        return output;\r\n",
    "    }\r\n",
    "    \r\n",
    "    public int Subtract(int arg1, int arg2) {\r\n",
    "        var output = arg1 - arg2;\r\n",
    "        display(\"Subtracted: \" + output);\r\n",
    "        return output;\r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "\r\n",
    "// instantiating a delegate is used with a NEW keyword wrapping the name of the method to be assigned\r\n",
    "s.Calculate(10, 5, s.Subtract, s.Add);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Subtracted: 5"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "5"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/plain": [
       "Added: 15"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "15"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Events\n",
    "\n",
    "[Events](https://docs.microsoft.com/dotnet/csharp/programming-guide/events?WT.mc_id=visualstudio-twitch-jefritz) allow us to notify when something has happened inside of our class.  Events build on the concept of delegates as they reference another method that should be called when the event is **raised**.  We define an event with access modifiers and by .NET standard practice, two arguments:  \n",
    "\n",
    "- the sender \n",
    "- a class that contains any arguments about the event being raised.  \n",
    "\n",
    "The return type from an event is a delegate of type `EventHandler` that defines these two arguments.  \n",
    "\n",
    "Let's look at a simple example:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class EnrolledEventArgs : EventArgs {\r\n",
    "    public short YearEnrolled {get; set;}\r\n",
    "}\r\n",
    "\r\n",
    "class Student {\r\n",
    "    \r\n",
    "    \r\n",
    "    public delegate void EnrolledEventHandler(\r\n",
    "        object sender, \r\n",
    "        EnrolledEventArgs args);\r\n",
    "    public event EnrolledEventHandler Enrolled;\r\n",
    "    \r\n",
    "    public void Enroll() {\r\n",
    "        \r\n",
    "        // do some long running process on another service, another machine, somewhere else\r\n",
    "        \r\n",
    "        Enrolled(this, \r\n",
    "            new EnrolledEventArgs {\r\n",
    "                YearEnrolled = 2021\r\n",
    "            });\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "s.Enrolled += (sender, args) \r\n",
    "    => display(\"I'm now enrolled for the year \" + args.YearEnrolled);\r\n",
    "s.Enroll();"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "I'm now enrolled for the year 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Generic EventHandler definition\n",
    "\n",
    "Insted of writing your own delegate for each event, [you can use a generic `EventHandler<T>`](https://docs.microsoft.com/dotnet/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines?WT.mc_id=visualstudio-twitch-jefritz#example) and specify the type of the `EventArgs` that you would like the Event to return."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    // A generic event handler that has the same signature and EventArguments of the type inside <>\r\n",
    "    public event EventHandler<EnrolledEventArgs> Enrolled;\r\n",
    "    \r\n",
    "    public void Enroll() {\r\n",
    "        \r\n",
    "        // do some long running process on another service, another machine, somewhere else\r\n",
    "        \r\n",
    "        Enrolled(this, new EnrolledEventArgs {YearEnrolled = 2021});\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "s.Enrolled += (sender, args) => display(\"I'm now enrolled for the year \" + args.YearEnrolled);\r\n",
    "s.Enroll();"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "I'm now enrolled for the year 2021"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Partial Keyword\n",
    "\n",
    "Classes can be defined across multiple files in separate class code blocks and then stitched together as a single class object.  This type of file layout and class design helps facilitate generating a class from metadata and allowing customization of that class in a second or third file.  You can use the [`partial` keyword to define each of the parts of the class](https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods?WT.mc_id=visualstudio-twitch-jefritz).\n",
    "\n",
    "Check out the use of the `partial` keyword to define two partial `Teacher` classes and even a **partial method** called `GetAge` that is defined in one part and executed from the other.  Try removing the implementation of `GetAge` from the second class and see how the `DisplayAge` reflects this."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "// This is one part of the class and would be stored in one file\r\n",
    "public partial class Teacher {\r\n",
    "    \r\n",
    "    public string Name { get; set; }\r\n",
    "    \r\n",
    "    public void DisplayAge() {\r\n",
    "        GetAge();\r\n",
    "    }\r\n",
    "\r\n",
    "    // Definition of the GetAge method\r\n",
    "    partial void GetAge(); \r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "public partial class Teacher {\r\n",
    "    \r\n",
    "    private DateTime _BirthDate;\r\n",
    "    \r\n",
    "    public DateTime BirthDate {\r\n",
    "        get { return _BirthDate; }\r\n",
    "        set { _BirthDate = value;}\r\n",
    "    }\r\n",
    "    \r\n",
    "    // Implementation of the GetAge method\r\n",
    "    partial void GetAge()  {\r\n",
    "        display(\"Get Age: \" + (int)DateTime.Now.Subtract(_BirthDate).TotalDays / 365);\r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var t = new Teacher { Name=\"Fritz\", BirthDate = new DateTime(2000, 8, 28)};\r\n",
    "display(t);\r\n",
    "t.DisplayAge();\r\n"
   ],
   "outputs": [
    {
     "data": {
      "text/html": [
       "<table><thead><tr><th>Name</th><th>BirthDate</th></tr></thead><tbody><tr><td><div class=\"dni-plaintext\">Fritz</div></td><td><div class=\"dni-plaintext\">2000-08-28 00:00:00Z</div></td></tr></tbody></table>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Get Age: 21"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Enumerations\n",
    "\n",
    "An [enumeration type](https://docs.microsoft.com/dotnet/csharp/language-reference/builtin-types/enum?WT.mc_id=visualstudio-twitch-jefritz) is a value type that can be used to describe a collection of related named constants that actually reference an integral type.  We use the `enum` keyword to define these types with an access modifier and the name of the type.  Values are then listed, separated by commas inside the enum block.\n",
    "\n",
    "By default,  underlying values start with the value `0` and increment by `1`.  Let's take a look at an example that describes the values of a dimmer lightswitch:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "public enum LightSwitch {\r\n",
    "    Off,\r\n",
    "    FiftyPercent,\r\n",
    "    Bright,\r\n",
    "    Nuclear,\r\n",
    "    On\r\n",
    "}\r\n",
    "\r\n",
    "LightSwitch hall = LightSwitch.Bright;\r\n",
    "display(hall);\r\n",
    "\r\n",
    "// We can force a value back to an integer with a simple cast:\r\n",
    "display((int)LightSwitch.Off)"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "Bright"
      ]
     },
     "metadata": {}
    },
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "0"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Enumerations can be defined inside and outside of classes, and be used anywhere another variable type would be referenced.  We can assign different values to the constants inside the enum with an `=` operator and the numeric value to be assigned."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "class Student {\r\n",
    "    \r\n",
    "    public enum EnrolledState {\r\n",
    "        NotEnrolled = 0,\r\n",
    "        Enrolled = 5,\r\n",
    "        OnMentorship = 10,\r\n",
    "        Internship = 11,\r\n",
    "        MilitaryLeave = 20\r\n",
    "    }\r\n",
    "    \r\n",
    "    public EnrolledState Enroll() {\r\n",
    "        \r\n",
    "        // evaluate student's scenario, make a decision\r\n",
    "        \r\n",
    "        return EnrolledState.MilitaryLeave;\r\n",
    "        \r\n",
    "    }\r\n",
    "    \r\n",
    "}\r\n",
    "\r\n",
    "var s = new Student();\r\n",
    "display(s.Enroll());"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "MilitaryLeave"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Enum Flags\n",
    "\n",
    "Enums can also be used with bitwise operations so that you can store and pass along any number of values stored in one variable.  Use the `[Flags]` attribute to instruct the C# compiler to enable this feature and set explicit binary values for the enum constants.  You can use both integer values or binary values in your definitions.\n",
    "\n",
    "Then, you can store multiple values by using the bitwise OR operator `|` and can interact with those values [using other bitwise operators](https://docs.microsoft.com/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#enumeration-logical-operators?WT.mc_id=visualstudio-twitch-jefritz)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "[Flags]\r\n",
    "public enum FileAccess {\r\n",
    "\r\n",
    "    // We can define values using integers and the powers of 2:\r\n",
    "    Read = 1,\r\n",
    "    Write = 2,\r\n",
    "    Execute = 4\r\n",
    "}\r\n",
    "\r\n",
    "var access = FileAccess.Read | FileAccess.Write | FileAccess.Execute;\r\n",
    "display(access);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "Read, Write, Execute"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "source": [
    "[Flags]\r\n",
    "public enum DaysOfWeek\r\n",
    "{\r\n",
    "    // We can also use binary values directly by using the 0b binary prefix.\r\n",
    "    // The _ character is used as a separator and is ignored by the compiler\r\n",
    "    None      = 0b_0000_0000,  // 0\r\n",
    "    Monday    = 0b_0000_0001,  // 1\r\n",
    "    Tuesday   = 0b_0000_0010,  // 2\r\n",
    "    Wednesday = 0b_0000_0100,  // 4\r\n",
    "    Thursday  = 0b_0000_1000,  // 8\r\n",
    "    Friday    = 0b_0001_0000,  // 16\r\n",
    "    Saturday  = 0b_0010_0000,  // 32\r\n",
    "    Sunday    = 0b_0100_0000,  // 64\r\n",
    "    Weekend   = Saturday | Sunday\r\n",
    "}\r\n",
    "\r\n",
    "var workWeek = DaysOfWeek.Monday | \r\n",
    "    DaysOfWeek.Tuesday | \r\n",
    "    DaysOfWeek.Wednesday | \r\n",
    "    DaysOfWeek.Thursday | \r\n",
    "    DaysOfWeek.Friday;\r\n",
    "display(workWeek);"
   ],
   "outputs": [
    {
     "output_type": "display_data",
     "data": {
      "text/html": [
       "Monday, Tuesday, Wednesday, Thursday, Friday"
      ]
     },
     "metadata": {}
    }
   ],
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".NET (C#)",
   "language": "C#",
   "name": ".net-csharp"
  },
  "language_info": {
   "file_extension": ".cs",
   "mimetype": "text/x-csharp",
   "name": "C#",
   "pygments_lexer": "csharp",
   "version": "8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}