Using Collections

One of the classes in the Systems.Collections namespace, System.Collections.ArrayList, also implements IList, ICollection, and IEnumerable, but does so in a more sophisticated way than System.Array. Whereas arrays are fixed in size (you can't add or remove elements), this class can be used to represent a variable-length list of items. To give you more of a feel for what is possible with such a highly advanced collection, the following Try It Out uses this class, as well as a simple array.

Defining Collections

Now that you know what is possible using more advanced collection classes, it's time to learn how to create your own strongly typed collection. One way of doing this is to implement the required methods manually, but this can be a time-consuming and complex process. Alternatively, you can derive your collection from a class, such as System.Collections.CollectionBase, an abstract class that supplies much of the implementation of a collection for you. This option is strongly recommended.

The CollectionBase class exposes the interfaces IEnumerable, ICollection, and IList but provides only some of the required implementation — notably, the Clear() and RemoveAt() methods of IList and the Count property of ICollection. You need to implement everything else yourself if you want the functionality provided.

To facilitate this, CollectionBase provides two protected properties that enable access to the stored objects themselves. You can use List, which gives you access to the items through an IList interface, and InnerList, which is the ArrayList object used to store items.

For example, the basics of a collection class to store Animal objects could be defined as follows (you'll see a fuller implementation shortly):

public class Animals : CollectionBase
{
   public void Add(Animal newAnimal)
   {
      List.Add(newAnimal);
   }
   public void Remove(Animal oldAnimal)
   {
      List.Remove(oldAnimal);
   }
   public Animals() {}
}

Here, Add() and Remove() have been implemented as strongly typed methods that use the standard Add() method of the IList interface used to access the items. The methods exposed will now only work with Animal classes or classes derived from Animal, unlike the ArrayList implementations shown earlier, which work with any object.

The CollectionBase class enables you to use the foreach syntax with your derived collections. For example, you can use code such as this:

WriteLine("Using custom collection class Animals:");
Animals animalCollection = new Animals();
animalCollection.Add(new Cow("Lea"));
foreach (Animal myAnimal in animalCollection)
{
   WriteLine($"New { myAnimal.ToString()} object added to custom " +
             $"collection, Name = {myAnimal.Name}");
}

You can't, however, do the following:

animalCollection[0].Feed();

To access items via their indices in this way, you need to use an indexer.

Indexers

An indexer is a special kind of property that you can add to a class to provide array-like access. In fact, you can provide more complex access via an indexer, because you can define and use complex parameter types with the square bracket syntax as you want. Implementing a simple numeric index for items, however, is the most common usage.

You can add an indexer to the Animals collection of Animal objects as follows:

   public class Animals : CollectionBase
   {
      …
      public Animal this[int animalIndex]
      {
         get { return (Animal)List[animalIndex]; }
         Set { List[animalIndex] = value; }
      }
   }

The this keyword is used along with parameters in square brackets, but otherwise the indexer looks much like any other property. This syntax is logical, because you access the indexer by using the name of the object followed by the index parameter(s) in square brackets (for example, MyAnimals[0]).

The indexer code uses an indexer on the List property (that is, on the IList interface that provides access to the ArrayList in CollectionBase that stores your items):

return (Animal)List[animalIndex];

Explicit casting is necessary here, as the IList.List property returns a System.Object object. The important point to note here is that you define a type for this indexer. This is the type that will be obtained when you access an item by using this indexer. This strong typing means that you can write code such as

animalCollection[0].Feed();

rather than:

((Animal)animalCollection[0]).Feed();

This is another handy feature of strongly typed custom collections. In the following Try It Out, you expand the previous Try It Out to put this into action.

Adding a Cards Collection to CardLib

In the last chapter, you created a class library project called Ch10CardLib that contained a Card class representing a playing card, and a Deck class representing a deck of cards — that is, a collection of Card classes. This collection was implemented as a simple array.

In this chapter, you'll add a new class to this library, renamed Ch11CardLib. This new class, Cards, will be a custom collection of Card objects, giving you all the benefits described earlier in this chapter. Create a new class library called Ch11CardLib in the C:BegVCSharpChapter11 directory. Next, delete the autogenerated Class1.cs file; select Project Add Existing Item; select the Card.cs, Deck.cs, Suit.cs, and Rank.cs files from the C:BegVCSharpChapter10Ch10CardLibCh10CardLib directory; and add the files to your project. As with the previous version of this project, introduced in Chapter 10, these changes are presented without using the standard Try It Out format. Should you want to jump straight to the code, feel free to open the version of this project included in the downloadable code for this chapter.

If you decide to create this project yourself, add a new class called Cards and modify the code in Cards.cs as follows:

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace Ch11CardLib
{
   public class Cards : CollectionBase
   {
      public void Add(Card newCard)
      {
         List.Add(newCard);
      }
      public void Remove(Card oldCard)
      {
         List.Remove(oldCard);
      }
      public Card this[int cardIndex]
      {
         get { return (Card)List[cardIndex]; }
         set { List[cardIndex] = value; }
      }
      /// <summary>
      /// Utility method for copying card instances into another Cards
      /// instance—used in Deck.Shuffle(). This implementation assumes that
      /// source and target collections are the same size.
      /// </summary>
      public void CopyTo(Cards targetCards)
      {
         for (int index = 0; index < this.Count; index++)
         {
            targetCards[index] = this[index];
         }
      }
      /// <summary>
      /// Check to see if the Cards collection contains a particular card.
      /// This calls the Contains() method of the ArrayList for the collection,
      /// which you access through the InnerList property.
      /// </summary>
      public bool Contains(Card card) => InnerList.Contains(card);
   }
}

Next, modify Deck.cs to use this new collection, rather than an array:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace Ch11CardLib
{
   public class Deck
   {
      private Cards cards = new Cards();
      public Deck()
      {
         // Line of code removed here
         for (int suitVal = 0; suitVal < 4; suitVal++)
         {
            for (int rankVal = 1; rankVal < 14; rankVal++)
            {
               cards.Add(new Card((Suit)suitVal, (Rank)rankVal));
            }
         }
      }
      public Card GetCard(int cardNum)
      {
         if (cardNum >= 0 && cardNum <= 51)
            return cards[cardNum];
         else
            throw (new System.ArgumentOutOfRangeException("cardNum", cardNum,
                   "Value must be between 0 and 51."));
      }
      public void Shuffle()
      {
         Cards newDeck = new Cards();
         bool[] assigned = new bool[52];
         Random sourceGen = new Random();
         for (int i = 0; i < 52; i++)
         {
            int sourceCard = 0;
            bool foundCard = false;
            while (foundCard == false)
            {
               sourceCard = sourceGen.Next(52);
               if (assigned[sourceCard] == false)
                  foundCard = true;
            }
            assigned[sourceCard] = true;
            newDeck.Add(cards[sourceCard]);
         }
         newDeck.CopyTo(cards);
      }
   }
}

Not many changes are necessary here. Most of them involve changing the shuffling logic to allow for the fact that cards are added to the beginning of the new Cards collection newDeck from a random index in cards, rather than to a random index in newDeck from a sequential position in cards.

The client console application for the Ch10CardLib solution, Ch10CardClient, can be used with this new library with the same result as before, as the method signatures of Deck are unchanged. Clients of this class library can now make use of the Cards collection class, however, rather than rely on arrays of Card objects — for example, to define hands of cards in a card game application.

Keyed Collections and IDictionary

Instead of implementing the IList interface, it is also possible for collections to implement the similar IDictionary interface, which allows items to be indexed via a key value (such as a string name), rather than an index. This is also achieved using an indexer, although here the indexer parameter used is a key associated with a stored item, rather than an int index, which can make the collection a lot more user-friendly.

As with indexed collections, there is a base class you can use to simplify implementation of the IDictionary interface: DictionaryBase. This class also implements IEnumerable and ICollection, providing the basic collection-manipulation capabilities that are the same for any collection.

DictionaryBase, like CollectionBase, implements some (but not all) of the members obtained through its supported interfaces. Like CollectionBase, the Clear and Count members are implemented, although RemoveAt() isn't because it's a method on the IList interface and doesn't appear on the IDictionary interface. IDictionary does, however, have a Remove() method, which is one of the methods you should implement in a custom collection class based on DictionaryBase.

The following code shows an alternative version of the Animals class, this time derived from DictionaryBase. Implementations are included for Add(), Remove(), and a key-accessed indexer:

public class Animals : DictionaryBase
{
   public void Add(string newID, Animal newAnimal)
   {
      Dictionary.Add(newID, newAnimal);
   }
   public void Remove(string animalID)
   {
      Dictionary.Remove(animalID);
   }
   public Animals() {}
   public Animal this[string animalID]
   {
      get { return (Animal)Dictionary[animalID]; }
      set { Dictionary[animalID] = value; }
   }
}

The differences in these members are as follows:

• Add() — Takes two parameters, a key and a value, to store together. The dictionary collection has a member called Dictionary inherited from DictionaryBase, which is an IDictionary interface. This interface has its own Add() method, which takes two object parameters. Your implementation takes a string value as a key and an Animal object as the data to store alongside this key.
• Remove() — Takes a key parameter, rather than an object reference. The item with the key value specified is removed.
• Indexer — Uses a string key value, rather than an index, which is used to access the stored item via the Dictionary inherited member. Again, casting is necessary here.

One other difference between collections based on DictionaryBase and collections based on CollectionBase is that foreach works slightly differently. The collection from the last section allowed you to extract Animal objects directly from the collection. Using foreach with the DictionaryBase derived class gives you DictionaryEntry structs, another type defined in the System.Collections namespace. To get to the Animal objects themselves, you must use the Value member of this struct, or you can use the Key member of the struct to get the associated key. To get code equivalent to the earlier

foreach (Animal myAnimal in animalCollection)
{
   WriteLine($"New {myAnimal.ToString()} object added to custom " +
             $"collection, Name = {myAnimal.Name}");
}

you need the following:

foreach (DictionaryEntry myEntry in animalCollection)
{
   WriteLine($"New {myEntry.Value.ToString()} object added to " +
      $"custom collection, Name = {((Animal)myEntry.Value).Name}");
}

It is possible to override this behavior so that you can access Animal objects directly through foreach. There are several ways to do this, the simplest being to implement an iterator.

Iterators

Earlier in this chapter, you saw that the IEnumerable interface enables you to use foreach loops. It's often beneficial to use your classes in foreach loops, not just collection classes such as those shown in previous sections.

However, overriding this behavior, or providing your own custom implementation of it, is not always simple. To illustrate this, it's necessary to take a detailed look at foreach loops. The following steps show you what actually happens in a foreach loop iterating through a collection called collectionObject:

1. collectionObject.GetEnumerator() is called, which returns an IEnumerator reference. This method is available through implementation of the IEnumerable interface, although this is optional.
2. The MoveNext() method of the returned IEnumerator interface is called.
3. If MoveNext() returns true, then the Current property of the IEnumerator interface is used to get a reference to an object, which is used in the foreach loop.
4. The preceding two steps repeat until MoveNext() returns false, at which point the loop terminates.

To enable this behavior in your classes, you must override several methods, keep track of indices, maintain the Current property, and so on. This can be a lot of work to achieve very little.

A simpler alternative is to use an iterator. Effectively, using iterators generates a lot of the code for you behind the scenes and hooks it all up correctly. Moreover, the syntax for using iterators is much easier to get a grip on.

A good definition of an iterator is a block of code that supplies all the values to be used in a foreach block in sequence. Typically, this block of code is a method, although you can also use property accessors and other blocks of code as iterators. To keep things simple, you'll just look at methods here.

Whatever the block of code is, its return type is restricted. Perhaps contrary to expectations, this return type isn't the same as the type of object being enumerated. For example, in a class that represents a collection of Animal objects, the return type of the iterator block can't be Animal. Two possible return types are the interface types mentioned earlier, IEnumerable or IEnumerator. You use these types as follows:

• To iterate over a class, use a method called GetEnumerator() with a return type of IEnumerator.
• To iterate over a class member, such as a method, use IEnumerable.

Within an iterator block, you select the values to be used in the foreach loop by using the yield keyword. The syntax for doing this is as follows:

yield return <value>;

That information is all you need to build a very simple example, as follows (you can find this code in SimpleIteratorsProgram.cs):

      public static IEnumerable SimpleList()
      {
         yield return "string 1";
         yield return "string 2";
         yield return "string 3";
      }
      static void Main(string[] args)
      {
         foreach (string item in SimpleList())
            WriteLine(item);
         ReadKey();
      }

Here, the static method SimpleList() is the iterator block. Because it is a method, you use a return type of IEnumerable. SimpleList() uses the yield keyword to supply three values to the foreach block that uses it, each of which is written to the screen. The result is shown in Figure 11.3.

Obviously, this iterator isn't a particularly useful one, but it does show how this works in action and how simple the implementation can be. Looking at the code, you might wonder how the code knows to return string type items. In fact, it doesn't; it returns object type values. As you know, object is the base class for all types, so you can return anything from the yield statements.

However, the compiler is intelligent enough that you can interpret the returned values as whatever type you want in the context of the foreach loop. Here, the code asks for string type values, so those are the values you get to work. Should you change one of the yield lines so that it returns, say, an integer, you would get a bad cast exception in the foreach loop.

One more thing about iterators. It is possible to interrupt the return of information to the foreach loop by using the following statement:

yield break;

When this statement is encountered in an iterator, the iterator processing terminates immediately, as does the foreach loop using it.

Now it's time for a more complicated — and useful! — example. In this Try It Out, you'll implement an iterator that obtains prime numbers.

Iterators and Collections

Earlier you were promised an explanation of how iterators can be used to iterate over the objects stored in a dictionary-type collection without having to deal with DictionaryItem objects. In the downloadable code for this chapter, you will find the code for the next project in the DictionaryAnimals folder. Recall the collection class Animals:

public class Animals : DictionaryBase
{
   public void Add(string newID, Animal newAnimal)
   {
      Dictionary.Add(newID, newAnimal);
   }
   public void Remove(string animalID)
   {
      Dictionary.Remove(animalID);
   }
   public Animal this[string animalID]
   {
      get { return (Animal)Dictionary[animalID]; }
      set { Dictionary[animalID] = value; }
   }
}

You can add this simple iterator to the code to get the desired behavior:

      public new IEnumerator GetEnumerator()
      {
         foreach (object animal in Dictionary.Values)
            yield return (Animal)animal;
      }

Now you can use the following code to iterate through the Animal objects in the collection:

         foreach (Animal myAnimal in animalCollection)
         {
            WriteLine($"New {myAnimal.ToString()} object added to " +
                      $" custom collection, Name = {myAnimal.Name}");
         }

Deep Copying

Chapter 9 described how you can perform shallow copying with the System.Object.MemberwiseClone() protected method, by using a method like the GetCopy() one shown here:

public class Cloner
{
   public int Val;
   public Cloner(int newVal)
   {
      Val = newVal;
   }
   public object GetCopy() => MemberwiseClone();
}

Suppose you have fields that are reference types, rather than value types (for example, objects):

public class Content
{
   public int Val;
}
public class Cloner
{
   public Content MyContent = new Content();
   public Cloner(int newVal)
   {
      MyContent.Val = newVal;
   }
   public object GetCopy() => MemberwiseClone();
}

In this case, the shallow copy obtained though GetCopy() has a field that refers to the same object as the original object. The following code, which uses this Cloner class, illustrates the consequences of shallow copying reference types:

Cloner mySource = new Cloner(5);
Cloner myTarget = (Cloner)mySource.GetCopy();
WriteLine($"myTarget.MyContent.Val = {myTarget.MyContent.Val}");
mySource.MyContent.Val = 2;
WriteLine($"myTarget.MyContent.Val = {myTarget.MyContent.Val}");

The fourth line, which assigns a value to mySource.MyContent.Val, the Val public field of the MyContent public field of the original object, also changes the value of myTarget.MyContent.Val. That's because mySource.MyContent refers to the same object instance as myTarget.MyContent. The output of the preceding code is as follows:

myTarget.MyContent.Val = 5
myTarget.MyContent.Val = 2

To get around this, you need to perform a deep copy. You could just modify the GetCopy() method used previously to do this, but it is preferable to use the standard .NET Framework way of doing things: implement the ICloneable interface, which has the single method Clone(). This method takes no parameters and returns an object type result, giving it a signature identical to the GetCopy() method used earlier.

To modify the preceding classes, try using the following deep copy code:

public class Content
{
   public int Val;
}
public class Cloner : ICloneable
{
   public Content MyContent = new Content();
   public Cloner(int newVal)
   {
      MyContent.Val = newVal;
   }
   public object Clone()
   {
      Cloner clonedCloner = new Cloner(MyContent.Val);
      return clonedCloner;
   }
}

This created a new Cloner object by using the Val field of the Content object contained in the original Cloner object (MyContent). This field is a value type, so no deeper copying is necessary.

Using code similar to that just shown to test the shallow copy — but using Clone() instead of GetCopy() — gives you the following result:

myTarget.MyContent.Val = 5
myTarget.MyContent.Val = 5

This time, the contained objects are independent. Note that sometimes calls to Clone() are made recursively, in more complex object systems. For example, if the MyContent field of the Cloner class also required deep copying, then you might need the following:

public class Cloner : ICloneable
{
   public Content MyContent = new Content();
   …
   public object Clone()
   {
      Cloner clonedCloner = new Cloner();
      clonedCloner.MyContent = MyContent.Clone();
      return clonedCloner;
   }
}

You're calling the default constructor here to simplify the syntax of creating a new Cloner object. For this code to work, you would also need to implement ICloneable on the Content class.

Adding Deep Copying to CardLib

You can put this into practice by implementing the capability to copy Card, Cards, and Deck objects by using the ICloneable interface. This might be useful in some card games, where you might not necessarily want two decks with references to the same set of Card objects, although you might conceivably want to set up one deck to have the same card order as another.

Implementing cloning functionality for the Card class in Ch11CardLib is simple because shallow copying is sufficient (Card contains only value-type data, in the form of fields). Begin by making the following changes to the class definition:

   public class Card : ICloneable
   {
      public object Clone() => MemberwiseClone();

This implementation of ICloneable is just a shallow copy. There is no rule determining what should happen in the Clone() method, and this is sufficient for your purposes.

Next, implement ICloneable on the Cards collection class. This is slightly more complicated because it involves cloning every Card object in the original collection — so you need to make a deep copy:

   public class Cards : CollectionBase, ICloneable
   {
      public object Clone()
      {
         Cards newCards = new Cards();
         foreach (Card sourceCard in List)
         {
            newCards.Add((Card)sourceCard.Clone());
         }
         return newCards;
      }

Finally, implement ICloneable on the Deck class. Note a slight problem here: The Deck class in Ch11CardLib has no way to modify the cards it contains, short of shuffling them. There is no way, for example, to modify a Deck instance to have a given card order. To get around this, define a new private constructor for the Deck class that allows a specific Cards collection to be passed in when the Deck object is instantiated. Here's the code to implement cloning in this class:

   public class Deck : ICloneable
   {
      public object Clone()
      {
         Deck newDeck = new Deck(cards.Clone() as Cards);
         return newDeck;
      }
      private Deck(Cards newCards)
      {
         cards = newCards;
      }

Again, you can test this with some simple client code. As before, place this code within the Main() method of a client project for testing (you can find this code in Ch11CardClientProgram.cs in the chapter's online download):

Deck deck1 = new Deck();
Deck deck2 = (Deck)deck1.Clone();
WriteLine($"The first card in the original deck is: {deck1.GetCard(0)}");
WriteLine($"The first card in the cloned deck is: {deck2.GetCard(0)}");
deck1.Shuffle();
WriteLine("Original deck shuffled.");
WriteLine($"The first card in the original deck is: {deck1.GetCard(0)}");
WriteLine($"The first card in the cloned deck is: {deck2.GetCard(0)}");
ReadKey();

The output will be similar to what is shown in Figure 11.5.

Type Comparisons

When comparing objects, you often need to know their type, which enables you to determine whether a value comparison is possible. In Chapter 9 you saw the GetType() method, which all classes inherit from System.Object, and how this method can be used in combination with the typeof() operator to determine (and take action depending on) object types:

if (myObj.GetType() == typeof(MyComplexClass))
{
   // myObj is an instance of the class MyComplexClass.
}

You've also seen how the default implementation of ToString(), also inherited from System.Object, will get you a string representation of an object's type. You can compare these strings too, although that's a rather messy way to accomplish this.

This section demonstrates a handy shorthand way of doing things: the is operator. This operator allows for much more readable code and, as you will see, has the advantage of examining base classes. Before looking at the is operator, though, you need to be aware of what often happens behind the scenes when dealing with value types (as opposed to reference types): boxing and unboxing.

struct MyStruct
{
   public int Val;
}

MyStruct valType1 = new MyStruct();
valType1.Val = 5;
object refType = valType1;

valType1.Val = 6;
MyStruct valType2 = (MyStruct)refType;
WriteLine($"valType2.Val = {valType2.Val}");

valType2.Val = 5

class MyStruct
{
   public int Val;
}

valType2.Val = 6

interface IMyInterface {}
struct MyStruct : IMyInterface
{
   public int Val;
}

MyStruct valType1 = new MyStruct();
IMyInterface refType = valType1;

MyStruct ValType2 = (MyStruct)refType;

<operand> is <type>

Value Comparisons

Consider two Person objects representing people, each with an integer Age property. You might want to compare them to see which person is older. You can simply use the following code:

if (person1.Age > person2.Age)
{
   …
}

This works fine, but there are alternatives. You might prefer to use syntax such as the following:

if (person1 > person2)
{
   …
}

This is possible using operator overloading, which you'll look at in this section. This is a powerful technique, but it should be used judiciously. In the preceding code, it is not immediately obvious that ages are being compared — it could be height, weight, IQ, or just general “greatness.”

Another option is to use the IComparable and IComparer interfaces, which enable you to define how objects will be compared to each other in a standard way. This technique is supported by the various collection classes in the .NET Framework, making it an excellent way to sort objects in a collection.

public class AddClass1
{
   public int val;
}

AddClass1 op1 = new AddClass1();
op1.val = 5;
AddClass1 op2 = new AddClass1();
op2.val = 5;
AddClass1 op3 = op1 + op2;

AddClass1 op1 = new AddClass1();
op1.val = 5;
AddClass1 op2 = new AddClass1();
op2.val = 5;
bool op3 = op1 == op2;

public class AddClass1
{
   public int val;
   public static AddClass1 operator +(AddClass1 op1, AddClass1 op2)
   {
      AddClass1 returnVal = new AddClass1();
      returnVal.val = op1.val + op2.val;
      return returnVal;
   }
}

AddClass1 op3 = op1 + op2;

public class AddClass1
{
   public int val;
   public static AddClass1 operator +(AddClass1 op1, AddClass1 op2)
   {
      AddClass1 returnVal = new AddClass1();
      returnVal.val = op1.val + op2.val;
      return returnVal;
   }
   public static AddClass1 operator -(AddClass1 op1)
   {
      AddClass1 returnVal = new AddClass1();
      returnVal.val = -op1.val;
      return returnVal;
   }
}

public class AddClass1
{
   public int val;
   public static AddClass3 operator +(AddClass1 op1, AddClass2 op2)
   {
      AddClass3 returnVal = new AddClass3();
      returnVal.val = op1.val + op2.val;
      return returnVal;
   }
}
public class AddClass2
{
   public int val;
}
public class AddClass3
{
   public int val;
}

AddClass1 op1 = new AddClass1();
op1.val = 5;
AddClass2 op2 = new AddClass2();
op2.val = 5;
AddClass3 op3 = op1 + op2;

AddClass3 op3 = op2 + op1;

public static AddClass3 operator +(AddClass2 op1, AddClass1 op2)
{
   AddClass3 returnVal = new AddClass3();
   returnVal.val = op1.val + op2.val;
   return returnVal;
}

public class AddClass1
{
   public int val;
   public static bool operator >=(AddClass1 op1, AddClass1 op2)
          => (op1.val >= op2.val);
   public static bool operator <(AddClass1 op1, AddClass1 op2)
          => !(op1 >= op2);
   // Also need implementations for <= and > operators.
}

public class AddClass1
{
   public int val;
   public static bool operator ==(AddClass1 op1, AddClass1 op2)
          => (op1.val == op2.val);
   public static bool operator !=(AddClass1 op1, AddClass1 op2)
          => !(op1 == op2);
   public override bool Equals(object op1) => val == ((AddClass1)op1).val;
   public override int GetHashCode() => val;
}

   public override bool Equals(object op1)
   {
      if (op1 is AddClass1)
      {
         return val == ((AddClass1)op1).val;
      }
      else
      {
         throw new ArgumentException(
            "Cannot compare AddClass1 objects with objects of type "
            + op1.GetType().ToString());
      }
   }

   if (op1.GetType() == typeof(AddClass1))

Adding Operator Overloads to CardLib

Now you'll upgrade your Ch11CardLib project again, adding operator overloading to the Card class. Again, you can find the code for the classes that follow in the Ch11CardLib folder of this chapter's code download. First, though, you'll add the extra fields to the Card class that allow for trump suits and an option to place aces high. You make these static, because when they are set, they apply to all Card objects:

   public class Card
   {
      /// <summary>
      /// Flag for trump usage. If true, trumps are valued higher
      /// than cards of other suits.
      /// </summary>
      public static bool useTrumps = false;
      /// <summary>
      /// Trump suit to use if useTrumps is true.
      /// </summary>
      public static Suit trump = Suit.Club;
      /// <summary>
      /// Flag that determines whether aces are higher than kings or lower
      /// than deuces.
      /// </summary>
      public static bool isAceHigh = true;

These rules apply to all Card objects in every Deck in an application. It's not possible to have two decks of cards with cards contained in each that obey different rules. That's fine for this class library, however, as you can safely assume that if a single application wants to use separate rules, then it could maintain these itself, perhaps setting the static members of Card whenever decks are switched.

Because you have done this, it is worth adding a few more constructors to the Deck class to initialize decks with different characteristics:

      /// <summary>
      /// Nondefault constructor. Allows aces to be set high.
      /// </summary>
      public Deck(bool isAceHigh) : this()
      {
         Card.isAceHigh = isAceHigh;
      }
      /// <summary>
      /// Nondefault constructor. Allows a trump suit to be used.
      /// </summary>
      public Deck(bool useTrumps, Suit trump) : this()
      {
         Card.useTrumps = useTrumps;
         Card.trump = trump;
      }
      /// <summary>
      /// Nondefault constructor. Allows aces to be set high and a trump suit
      /// to be used.
      /// </summary>
      public Deck(bool isAceHigh, bool useTrumps, Suit trump) : this()
      {
         Card.isAceHigh = isAceHigh;
         Card.useTrumps = useTrumps;
         Card.trump = trump;
      }

Each of these constructors is defined by using the : this() syntax shown in Chapter 9, so in all cases the default constructor is called before the nondefault one, initializing the deck.

Now add your operator overloads (and suggested overrides) to the Card class:

      public static bool operator ==(Card card1, Card card2)
         => card1?.suit == card2?.suit) && (card1?.rank == card2?.rank);
      public static bool operator !=(Card card1, Card card2)
             => !(card1 == card2);
      public override bool Equals(object card) => this == (Card)card;
      public override int GetHashCode()
                      => return 13 * (int)suit + (int)rank;
      public static bool operator >(Card card1, Card card2)
      {
         if (card1.suit == card2.suit)
         {
            if (isAceHigh)
            {
               if (card1.rank == Rank.Ace)
               {
                  if (card2.rank == Rank.Ace)
                     return false;
                  else
                     return true;
               }
               else
               {
                  if (card2.rank == Rank.Ace)
                     return false;
                  else
                     return (card1.rank > card2?.rank);
               }
            }
            else
            {
               return (card1.rank > card2.rank);
            }
         }
         else
         {
            if (useTrumps && (card2.suit == Card.trump))
               return false;
            else
               return true;
         }
      }
      public static bool operator <(Card card1, Card card2)
             => !(card1 >= card2);
      public static bool operator >=(Card card1, Card card2)
      {
         if (card1.suit == card2.suit)
         {
            if (isAceHigh)
            {
               if (card1.rank == Rank.Ace)
               {
                  return true;
               }
               else
               {
                  if (card2.rank == Rank.Ace)
                     return false;
                  else
                     return (card1.rank >= card2.rank);
               }
            }
            else
            {
               return (card1.rank >= card2.rank);
            }
         }
         else
         {
            if (useTrumps && (card2.suit == Card.trump))
               return false;
            else
               return true;
         }
      }
      public static bool operator <=(Card card1, Card card2)
             => !(card1 > card2);

There's not much to note here, except perhaps the slightly lengthy code for the > and >= overloaded operators. If you step through the code for >, you can see how it works and why these steps are necessary.

You are comparing two cards, card1 and card2, where card1 is assumed to be the first one laid down on the table. As discussed earlier, this becomes important when you are using trump cards, because a trump will beat a non-trump even if the non-trump has a higher rank. Of course, if the suits of the two cards are identical, then whether the suit is the trump suit or not is irrelevant, so this is the first comparison you make:

public static bool operator >(Card card1, Card card2)
{
   if (card1.suit == card2.suit)
   {

If the static isAceHigh flag is true, then you can't compare the cards' ranks directly via their value in the Rank enumeration, because the rank of ace has a value of 1 in this enumeration, which is less than that of all other ranks. Instead, use the following steps:

• If the first card is an ace, then check whether the second card is also an ace. If it is, then the first card won't beat the second. If the second card isn't an ace, then the first card wins:

              if (isAceHigh)
              {
                 if (card1.rank == Rank.Ace)
                 {
                    if (card2.rank == Rank.Ace)
                       return false;
                    else
                       return true;
                 }

• If the first card isn't an ace, then you also need to check whether the second one is. If it is, then the second card wins; otherwise, you can compare the rank values because you know that aces aren't an issue:

                 else
                 {
                    if (card2.rank == Rank.Ace)
                       return false;
                    else
                       return (card1.rank > card2?.rank);
                 }
              }

• If aces aren't high, then you just compare the rank values:

              else
              {
                 return (card1.rank > card2.rank);
              }

The remainder of the code concerns the case where the suits of card1 and card2 are different. Here, the static useTrumps flag is important. If this flag is true and card2 is of the trump suit, then you can say definitively that card1 isn't a trump (because the two cards have different suits); and trumps always win, so card2 is the higher card:

   else
   {
      if (useTrumps && (card2.suit == Card.trump))
         return false;

If card2 isn't a trump (or useTrumps is false), then card1 wins, because it was the first card laid down:

      else
         return true;
   }
}

Only one other operator (>=) uses code similar to this, and the other operators are very simple, so there's no need to go into more detail about them.

The following simple client code tests these operators. Simply place it in the Main() method of a client project to test it, like the client code shown earlier in the CardLib examples (you can find this code in Ch11CardClientProgram.cs):

Card.isAceHigh = true;
WriteLine("Aces are high.");
Card.useTrumps = true;
Card.trump = Suit.Club;
WriteLine("Clubs are trumps.");
Card card1, card2, card3, card4, card5;
card1 = new Card(Suit.Club, Rank.Five);
card2 = new Card(Suit.Club, Rank.Five);
card3 = new Card(Suit.Club, Rank.Ace);
card4 = new Card(Suit.Heart, Rank.Ten);
card5 = new Card(Suit.Diamond, Rank.Ace);
WriteLine($"{card1.ToString()} == {card2.ToString()} ? {card1 == card2}");
WriteLine($"{card1.ToString()} != {card3.ToString()} ? {card1 != card3}");
WriteLine($"{card1.ToString()}.Equals({card4.ToString()}) ? " +
      $" { card1.Equals(card4)}");
WriteLine($"Card.Equals({card3.ToString()}, {card4.ToString()}) ? " +
      $" { Card.Equals(card3, card4)}");
WriteLine($"{card1.ToString()} > {card2.ToString()} ? {card1 > card2}");
WriteLine($"{card1.ToString()} <= {card3.ToString()} ? {card1 <= card3}");
WriteLine($"{card1.ToString()} > {card4.ToString()} ? {card1 > card4}");
WriteLine($"{card4.ToString()} > {card1.ToString()} ? {card4 > card1}");
WriteLine($"{card5.ToString()} > {card4.ToString()} ? {card5 > card4}");
WriteLine($"{card4.ToString()} > {card5.ToString()} ? {card4 > card5}");
ReadKey();

The results are as shown in Figure 11.7.

In each case, the operators are applied taking the specified rules into account. This is particularly apparent in the last four lines of output, demonstrating how trump cards always beat non-trumps.

if (person1.CompareTo(person2) == 0)
{
   WriteLine("Same age");
}
else if (person1.CompareTo(person2) > 0)
{
   WriteLine("person 1 is Older");
}
else
{
   WriteLine("person1 is Younger");
}

if (personComparer.Compare(person1, person2) == 0)
{
   WriteLine("Same age");
}
else if (personComparer.Compare(person1, person2) > 0)
{
   WriteLine("person 1 is Older");
}
else
{
   WriteLine("person1 is Younger");
}

string firstString = "First String";
string secondString = "Second String";
WriteLine($"Comparing '{firstString}' and '{secondString}', " +
         $"result: {Comparer.Default.Compare(firstString, secondString)}");
int firstNumber = 35;
int secondNumber = 23;
WriteLine($"Comparing '{firstNumber}' and '{ secondNumber }', " +
         $"result: {Comparer.Default.Compare(firstNumber, secondNumber)}");

Comparing 'First String' and 'Second String', result: -1
Comparing '35' and '23', result: 1

Overloading Conversion Operators

As well as overloading mathematical operators, as shown earlier, you can define both implicit and explicit conversions between types. This is necessary if you want to convert between types that aren't related — if there is no inheritance relationship between them and no shared interfaces, for example.

Suppose you define an implicit conversion between ConvClass1 and ConvClass2. This means that you can write code such as the following:

ConvClass1 op1 = new ConvClass1();
ConvClass2 op2 = op1;

Alternatively, you can define an explicit conversion:

ConvClass1 op1 = new ConvClass1();
ConvClass2 op2 = (ConvClass2)op1;

As an example, consider the following code:

public class ConvClass1
{
   public int val;
   public static implicit operator ConvClass2(ConvClass1 op1)
   {
      ConvClass2 returnVal = new ConvClass2();
      returnVal.val = op1.val;
      return returnVal;
   }
}
public class ConvClass2
{
   public double val;
   public static explicit operator ConvClass1(ConvClass2 op1)
   {
      ConvClass1 returnVal = new ConvClass1();
      checked {returnVal.val = (int)op1.val;};
      return returnVal;
   }
}

Here, ConvClass1 contains an int value and ConvClass2 contains a double value. Because int values can be converted into double values implicitly, you can define an implicit conversion between ConvClass1 and ConvClass2. The reverse is not true, however, and you should define the conversion operator between ConvClass2 and ConvClass1 as explicit.

You specify this using the implicit and explicit keywords as shown. With these classes, the following code is fine:

ConvClass1 op1 = new ConvClass1();
op1.val = 3;
ConvClass2 op2 = op1;

A conversion in the other direction, however, requires the following explicit casting conversion:

ConvClass2 op1 = new ConvClass2();
op1.val = 3e15;
ConvClass1 op2 = (ConvClass1)op1;

Because you have used the checked keyword in your explicit conversion, you will get an exception in the preceding code, as the val property of op1 is too large to fit into the val property of op2.

The as Operator

The as operator converts a type into a specified reference type, using the following syntax:

<operand> as <type>

This is possible only in certain circumstances:

• If <operand> is of type <type>
• If <operand> can be implicitly converted to type <type>
• If <operand> can be boxed into type <type>

If no conversion from <operand> to <type> is possible, then the result of the expression will be null.

Conversion from a base class to a derived class is possible by using an explicit conversion, but it won't always work. Consider the two classes ClassA and ClassD from an earlier example, where ClassD inherits from ClassA:

   class ClassA : IMyInterface {}
   class ClassD : ClassA {}

The following code uses the as operator to convert from a ClassA instance stored in obj1 into the ClassD type:

ClassA obj1 = new ClassA();
ClassD obj2 = obj1 as ClassD;

This will result in obj2 being null.

However, it is possible to store ClassD instances in ClassA-type variables by using polymorphism. The following code illustrates this, using the as operator to convert from a ClassA-type variable containing a ClassD-type instance into the ClassD type:

ClassD obj1 = new ClassD();
ClassA obj2 = obj1;
ClassD obj3 = obj2 as ClassD;

This time the result is that obj3 ends up containing a reference to the same object as obj1, not null.

This functionality makes the as operator very useful, because the following code (which uses simple casting) results in an exception being thrown:

ClassA obj1 = new ClassA();
ClassD obj2 = (ClassD)obj1;

The as equivalent of this code results in a null value being assigned to obj2 — no exception is thrown. This means that code such as the following (using two of the classes developed earlier in this chapter, Animal and a class derived from Animal called Cow) is very common in C# applications:

public void MilkCow(Animal myAnimal)
{
   Cow myCow = myAnimal as Cow;
   if (myCow != null)
   {
      myCow.Milk();
   }
   else
   {
     WriteLine($"{myAnimal.Name} isn't a cow, and so can't be milked.");
   }
}

This is much simpler than checking for exceptions!