Chapter 7: Delegates and Events

Declaring Delegates in C#

When you want to use a class in C#, you do so in two stages. First, you need to define the class - that is, you need to tell the compiler what fields and methods make up the class. Then (unless you are using only static methods), you instantiate an object of that class. With delegates it is the same thing. You have to start off by defining the delegates you want to use. In the case of delegates, defining them means telling the compiler what kind of method a delegate of that type will represent. Then, you have to create one or more instances of that delegate. Behind the scenes, the compiler creates a class that represents the delegate.

The syntax for defining delegates looks like this:

delegate void IntMethodInvoker(int x);

In this case, you have defined a delegate called IntMethodInvoker, and you have indicated that each instance of this delegate can hold a reference to a method that takes one int parameter and returns void. The crucial point to understand about delegates is that they are very type-safe. When you define the delegate, you have to give full details of the signature and the return type of the method that it is going to represent.

Suppose that you wanted to define a delegate called TwoLongsOp that will represent a method that takes two longs as its parameters and returns a double. You could do it like this:

delegate double TwoLongsOp(long first, long second);

Or, to define a delegate that will represent a method that takes no parameters and returns a string, you might write this:

delegate string GetAString();

The syntax is similar to that for a method definition, except that there is no method body and the definition is prefixed with the keyword delegate. Because what you are doing here is basically defining a new class, you can define a delegate in any of the same places that you would define a class - that is to say either inside another class or outside of any class and in a namespace as a top-level object. Depending on how visible you want your definition to be, you can apply any of the normal access modifiers to delegate definitions - public, private, protected, and so on:

public delegate string GetAString();

After you have defined a delegate, you can create an instance of it so that you can use it to store details of a particular method.

Using Delegates in C#

The following code snippet demonstrates the use of a delegate. It is a rather long-winded way of calling the ToString() method on an int:

private delegate string GetAString();

static void Main()
{
   int x = 40;
   GetAString firstStringMethod = new GetAString(x.ToString);
   Console.WriteLine("String is" + firstStringMethod());
   // With firstStringMethod initialized to x.ToString(),
   // the above statement is equivalent to saying
   // Console.WriteLine("String is" + x.ToString());
}

In this code, you instantiate a delegate of type GetAString, and you initialize it so that it refers to the ToString() method of the integer variable x. Delegates in C# always syntactically take a one-parameter constructor, the parameter being the method to which the delegate will refer. This method must match the signature with which you originally defined the delegate. So in this case, you would get a compilation error if you tried to initialize the variable firstStringMethod with any method that did not take any parameters and return a string. Notice that because int.ToString() is an instance method (as opposed to a static one) you need to specify the instance (x) as well as the name of the method to initialize the delegate properly.

The next line actually uses the delegate to display the string. In any code, supplying the name of a delegate instance, followed by brackets containing any parameters, has exactly the same effect as calling the method wrapped by the delegate. Hence, in the preceding code snippet, the Console.WriteLine() statement is completely equivalent to the commented-out line.

In fact, supplying braces to the delegate instance is the same as invoking the Invoke() method of the delegate class. Because firstStringMethod is a variable of a delegate type, the C# compiler replaces firstStringMethod() with firstStringMethod.Invoke().

firstStringMethod();
firstStringMethod.Invoke();

One feature of delegates is that they are type-safe to the extent that they ensure the signature of the method being called is correct. However, interestingly, they do not care what type of object the method is being called against or even whether the method is a static method or an instance method.

To demonstrate this, the following example expands the previous code snippet so that it uses the firstStringMethod delegate to call a couple of other methods on another object - an instance method and a static method. For this, you use the Currency struct, which is defined as follows:

struct Currency
{
  public uint Dollars;
  public ushort Cents;

  public Currency(uint dollars, ushort cents)
  {
     this.Dollars = dollars;
     this.Cents = cents;
  }

  public override string ToString()
  {
     return string.Format("${0}.{1,-2:00}", Dollars,Cents);
  }

  public static explicit operator Currency (float value)
  {
     checked
     {
        uint dollars = (uint)value;
        ushort cents = (ushort)((value-dollars)*100);
        return new Currency(dollars, cents);
     }
  }

  public static implicit operator float (Currency value)
  {
     return value.Dollars + (value.Cents/100.0f);
  }

  public static implicit operator Currency (uint value)
  {
     return new Currency(value, 0);
  }

  public static implicit operator uint (Currency value)
  {
     return value.Dollars;
  }
}

Notice that the Currency struct has its own overload of ToString().To demonstrate using delegates with static methods, this code also adds a static method with the same signature to Currency:

struct Currency
{
   public static string GetCurrencyUnit()
   {
      return "Dollar";
   }

Now you can use your GetAString instance as follows:

private delegate string GetAString();

static void Main()
{
   int x = 40;
   GetAString firstStringMethod = new GetAString(x.ToString);
   Console.WriteLine("String is " + firstStringMethod());

   Currency balance = new Currency(34, 50);

   // firstStringMethod references an instance method
   firstStringMethod = new GetAString(balance.ToString);
   Console.WriteLine("String is " + firstStringMethod()); 

   // firstStringMethod references a static method 
   firstStringMethod = new GetAString(Currency.GetCurrencyUnit);
   Console.WriteLine("String is " + firstStringMethod());
}

This code shows how you can call a method via a delegate and subsequently reassign the delegate to refer to different methods on different instances of classes, even static methods or methods against instances of different types of class, provided that the signature of each method matches the delegate definition.

Running the application, you get the output from the different methods that are referenced by the delegate:

String is 40
String is $34.50
String is Dollar

However, you still haven’t seen the process of actually passing a delegate to another method. Nor have you actually achieved anything particularly useful yet. It is possible to call the ToString() method of int and Currency objects in a much more straightforward way than using delegates! Unfortunately, the nature of delegates requires a fairly complex example before you can really appreciate their usefulness. The next section presents two delegate examples. The first one simply uses delegates to call a couple of different operations. It illustrates how to pass delegates to methods and how you can use arrays of delegates - although arguably it still doesn’t do much that you couldn’t do a lot more simply without delegates. Then, a second, much more complex example of a BubbleSorter class is presented, which implements a method to sort out arrays of objects into increasing order. This class would be difficult to write without delegates.