Updated notes on CList as ICollection.

Author: aubertc

source/Makefile

@@ -232,7 +232,9 @@ PANDOC_OPTIONS_ALT = $(PANDOC_OPTIONS) --lua-filter $(FIL_TEMPLATES)default-code
 PANDOC_HTM = $(PANDOC_OPTIONS_ALT) --toc --default-image-extension=svg --standalone --template=$(HTM_TEMPLATES)template.html --metadata title="ℙrinciples of ℂomputer ℙrogramming"
 
 # PDF build options
-PANDOC_PDF:= $(PANDOC_OPTIONS_ALT) --toc --default-image-extension=svg --pdf-engine=xelatex --include-in-header=$(PDF_TEMPLATES)header.tex -V pdfstandard=ua-2
+PANDOC_PDF:= $(PANDOC_OPTIONS_ALT) --toc --default-image-extension=svg --pdf-engine=xelatex --include-in-header=$(PDF_TEMPLATES)header.tex 
+# -V pdfstandard=ua-2
+# ! Package tagpdf Error: there is no open structure on the stack
 
 # ODT build options
 PANDOC_ODT:= $(PANDOC_OPTIONS_ALT) --default-image-extension=png --reference-doc=$(ODT_TEMPLATES)custom-reference.odt
@@ -342,7 +344,8 @@ CLEAN-PREREQ:
 #	&& echo "](./$(basename $<).svg)" >> $@
 
 $(CLA_DIR)%.md: $(CLA_DIR)%.txt | $(CLA_DIR)%.svg $(CLA_DIR)%.png
-	echo "![A UML diagram for the $$(sed 's-class \(.*\){-\1-g' $< | sed 's/<|--/⇽/' | sed 's/<|../◁┈/' | sed -n '1p' ) class ([text version](./$(basename $@).txt), [image version](./$(basename $@).png), [svg version](./$(basename $@).svg))]($(notdir $(basename $@)).png)" > $@
+# In the following substitution, 's/~T~/<T>/' is for generic type parameter. 
+	echo "![A UML diagram for the \`$$(sed 's-class \(.*\){-\1-g' $< | sed 's/~T~/<T>/' | sed 's/<|--/⇽/' | sed 's/<|../◁┈/' | sed -n '1p' )\` class ([text version](./$(basename $@).txt), [image version](./$(basename $@).png), [svg version](./$(basename $@).svg))]($(notdir $(basename $@)).png)" > $@
 
 $(CLA_DIR)%.svg: $(CLA_DIR)%.txt
 	@echo "Creating $@"

source/code/projects/CList_ICollection/CList_ICollection/CList.cs

@@ -39,30 +39,50 @@ private class Cell
   }
 
   /* Done with Cell.*/
-
-  // Empty
-  public bool IsEmpty()
+  
+  public int Count
   {
-    return first == null;
+    get
+    {
+      int size = 0;
+      Cell cCell = first;
+      while (cCell != null)
+      {
+        cCell = cCell.Next;
+        size++;
+      }
+      return size;
+    }
   }
 
-  // Add is simply "AddF", slightly revisited.
+  public bool isReadOnly = false;
+  // This attribute is not required by the interface,
+  // but convenient to have.
+  public bool IsReadOnly
+  {
+    get { return isReadOnly; }
+    set { isReadOnly = value; }
+    // Note that set is not required by the interface
+  }
+  
+  // Add is simply "AddF", slightly revisited
+  // to account for IsReadOnly attribute.
   public void Add(T value)
   {
-    if (isReadonly)
+    if (isReadOnly)
     {
       throw new InvalidOperationException(
         "List is read-only."
       );
     }
     first = new Cell(value, first);
   }
-
+  
   public void Clear()
   {
     first = null;
   }
-
+  
   public bool Contains(T value)
   {
     bool found = false;
@@ -77,8 +97,8 @@ public bool Contains(T value)
     }
     return found;
   }
-
-  // Copies the elements of the ICollection to an Array, starting at a particular Array index.
+  
+    // Copies the elements of the ICollection to an Array, starting at a particular Array index.
   public void CopyTo(T[] array, int arrayIndex)
   {
     if (array == null)
@@ -103,13 +123,38 @@ public void CopyTo(T[] array, int arrayIndex)
       cCell = cCell.Next;
     }
   }
+  
+    public IEnumerator<T> GetEnumerator()
+  {
+    Cell cCell = first;
+    while (cCell != null)
+    {
+      yield return cCell.Data;
+      cCell = cCell.Next;
+    }
+  }
+
+  IEnumerator IEnumerable.GetEnumerator()
+  {
+    return this.GetEnumerator(); // call the generic version of the method
+  }
+
+  /* We are done realizing the ICollection class. */
+  
+  // Some additional methods.
+
+  // Empty
+  public bool IsEmpty()
+  {
+    return first == null;
+  }
 
   // Remove the first node containing the value
   // if it exists and returns true,
   // returns false otherwise.
   public bool Remove(T value)
   {
-    if (isReadonly)
+    if (isReadOnly)
     {
       throw new InvalidOperationException(
         "List is read-only"
@@ -143,50 +188,11 @@ public bool Remove(T value)
     return removed;
   }
 
-  public int Count
-  {
-    get
-    {
-      int size = 0;
-      Cell cCell = first;
-      while (cCell != null)
-      {
-        cCell = cCell.Next;
-        size++;
-      }
-      return size;
-    }
-  }
-
-  public bool isReadonly = false;
-  public bool IsReadOnly
-  {
-    get { return isReadonly; }
-    set { isReadonly = value; }
-  }
-
-  public IEnumerator<T> GetEnumerator()
-  {
-    Cell cCell = first;
-    while (cCell != null)
-    {
-      yield return cCell.Data;
-      cCell = cCell.Next;
-    }
-  }
-
-  IEnumerator IEnumerable.GetEnumerator()
-  {
-    return this.GetEnumerator(); // call the generic version of the method
-  }
-
-  /* We are done realizing the ICollection class. */
-
   // One last method, to remove the last cell and
   // returns its value.
   public T RemoveL()
   {
-    if (isReadonly)
+    if (isReadOnly)
     {
       throw new InvalidOperationException(
         "List is read-only"

source/code/projects/CList_ICollection/CList_ICollection/Program.cs

@@ -26,6 +26,7 @@ static void Main(string[] args)
     {
       Console.Write(item + " ");
     }
+    // Done with first example.
     Console.WriteLine("");
 
     Console.Write(

source/diag/cla/ICollection.txt

@@ -9,5 +9,3 @@ class ICollection~T~{
     + GetEnumerator() IEnumerator
     + Remove(item: T) bool
 }
-
-    

source/lectures/data/CList_as_ICollection.md

@@ -5,16 +5,32 @@ tags:
 
 # List as ICollection
 
-Another way of implementing lists is to make our class realize the [ICollection interface](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.icollection-1?view=net-9.0):
+## Motivation
 
+Another way of implementing lists is to make our class realize the [ICollection interface](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.icollection-1?view=net-9.0).
 
-!include diag/cla/ICollection.md
+Quoting [C# 12 in a Nutshell](https://www.albahari.com/nutshell/): 
+
+> `ICollection<T>` is the standard interface for countable collections of objects. It provides the ability to determine the size of a collection (`Count`), determine whether an item exists in the collection (`Contains`), copy the collection into an array (`ToArray`), and determine whether the collection is read-only (`IsReadOnly`).
+
+Its UML diagram is as follows:
 
-This requires implementing a series of properties and methods:
+!include diag/cla/ICollection.md
 
+Providing a way of constructing a `IEnumerator<T>` object let C# iterate over our custom lists using `foreach`, so that we can for example write
 
 ```{download="./code/projects/CList_ICollection.zip"}
-!include`snippetStart="/* Done with Cell.*/", snippetEnd="/* We are done realizing the ICollection class. */"` code/projects/CList_ICollection/CList_ICollection/CList.cs
+!include`snippetStart="// is that we can iterate over elements of lists now:", snippetEnd="// Done with first example."` code/projects/CList_ICollection/CList_ICollection/Program.cs
 ```
 
+for `myList1` a `CList<int>` object.
+
+Implementing interfaces is an excellent way of signaling to C# that our class respects certain convention on one hand, and to help programmer follow usual guidelines on the other.
 
+## Implementation
+
+In addition to signaling that our class realizes the interface, using `public class CList<T> : ICollection<T>`, we need to implement the following properties and methods:
+
+```{download="./code/projects/CList_ICollection.zip"}
+!include`snippetStart="/* Done with Cell.*/", snippetEnd="/* We are done realizing the ICollection class. */"` code/projects/CList_ICollection/CList_ICollection/CList.cs
+```