C#/.NET Little Wonders: The Generic Func Delegates

Posted by James Michael Hare on Geeks with Blogs See other posts from Geeks with Blogs or by James Michael Hare
Published on Fri, 11 Nov 2011 00:17:44 GMT Indexed on 2011/11/11 17:54 UTC
Read the original article Hit count: 367

Filed under:

Once again, in this series of posts I look at the parts of the .NET Framework that may seem trivial, but can help improve your code by making it easier to write and maintain. The index of all my past little wonders posts can be found here.

Back in one of my three original “Little Wonders” Trilogy of posts, I had listed generic delegates as one of the Little Wonders of .NET. Later, someone posted a comment saying said that they would love more detail on the generic delegates and their uses, since my original entry just scratched the surface of them.

Last week, I began our look at some of the handy generic delegates built into .NET with a description of delegates in general, and the Action family of delegates. For this week, I’ll launch into a look at the Func family of generic delegates and how they can be used to support generic, reusable algorithms and classes.

Quick Delegate Recap

Delegates are similar to function pointers in C++ in that they allow you to store a reference to a method. They can store references to either static or instance methods, and can actually be used to chain several methods together in one delegate.

Delegates are very type-safe and can be satisfied with any standard method, anonymous method, or a lambda expression. They can also be null as well (refers to no method), so care should be taken to make sure that the delegate is not null before you invoke it.

Delegates are defined using the keyword delegate, where the delegate’s type name is placed where you would typically place the method name:

// This delegate matches any method that takes string, returns nothing   

public delegate void Log(string message);

This delegate defines a delegate type named Log that can be used to store references to any method(s) that satisfies its signature (whether instance, static, lambda expression, etc.).

Delegate instances then can be assigned zero (null) or more methods using the operator = which replaces the existing delegate chain, or by using the operator += which adds a method to the end of a delegate chain:

// creates a delegate instance named currentLogger defaulted to Console.WriteLine (static method)

Log currentLogger = Console.Out.WriteLine;   

  

// invokes the delegate, which writes to the console out

currentLogger("Hi Standard Out!");   

  

// append a delegate to Console.Error.WriteLine to go to std error

currentLogger += Console.Error.WriteLine;

  

// invokes the delegate chain and writes message to std out and std err

currentLogger("Hi Standard Out and Error!");

While delegates give us a lot of power, it can be cumbersome to re-create fairly standard delegate definitions repeatedly, for this purpose the generic delegates were introduced in various stages in .NET. These support various method types with particular signatures.

Note: a caveat with generic delegates is that while they can support multiple parameters, they do not match methods that contains ref or out parameters. If you want to a delegate to represent methods that takes ref or out parameters, you will need to create a custom delegate.

We’ve got the Func… delegates

Just like it’s cousin, the Action delegate family, the Func delegate family gives us a lot of power to use generic delegates to make classes and algorithms more generic. Using them keeps us from having to define a new delegate type when need to make a class or algorithm generic.

Remember that the point of the Action delegate family was to be able to perform an “action” on an item, with no return results. Thus Action delegates can be used to represent most methods that take 0 to 16 arguments but return void. You can assign a method

The Func delegate family was introduced in .NET 3.5 with the advent of LINQ, and gives us the power to define a function that can be called on 0 to 16 arguments and returns a result. Thus, the main difference between Action and Func, from a delegate perspective, is that Actions return nothing, but Funcs return a result.

The Func family of delegates have signatures as follows:

Func<TResult> – matches a method that takes no arguments, and returns value of type TResult.
Func<T, TResult> – matches a method that takes an argument of type T, and returns value of type TResult.
Func<T1, T2, TResult> – matches a method that takes arguments of type T1 and T2, and returns value of type TResult.
Func<T1, T2, …, TResult> – and so on up to 16 arguments, and returns value of type TResult.

These are handy because they quickly allow you to be able to specify that a method or class you design will perform a function to produce a result as long as the method you specify meets the signature.

For example, let’s say you were designing a generic aggregator, and you wanted to allow the user to define how the values will be aggregated into the result (i.e. Sum, Min, Max, etc…). To do this, we would ask the user of our class to pass in a method that would take the current total, the next value, and produce a new total.

A class like this could look like:

public sealed class Aggregator<TValue, TResult>

{

    // holds method that takes previous result, combines with next value, creates new result

    private Func<TResult, TValue, TResult> _aggregationMethod;

  

    // gets or sets the current result of aggregation

    public TResult Result { get; private set; }

  

    // construct the aggregator given the method to use to aggregate values

    public Aggregator(Func<TResult, TValue, TResult>  aggregationMethod = null)

    {

        if (aggregationMethod == null) throw new ArgumentNullException("aggregationMethod");

  

        _aggregationMethod = aggregationMethod;

    }

  

    // method to add next value

    public void Aggregate(TValue nextValue)

    {

        // performs the aggregation method function on the current result and next and sets to current result

        Result = _aggregationMethod(Result, nextValue);

    }

}

Of course, LINQ already has an Aggregate extension method, but that works on a sequence of IEnumerable<T>, whereas this is designed to work more with aggregating single results over time (such as keeping track of a max response time for a service).

We could then use this generic aggregator to find the sum of a series of values over time, or the max of a series of values over time (among other things):

// creates an aggregator that adds the next to the total to sum the values

var sumAggregator = new Aggregator<int, int>((total, next) => total + next);

  

// creates an aggregator (using static method) that returns the max of previous result and next

var maxAggregator = new Aggregator<int, int>(Math.Max);

So, if we were timing the response time of a web method every time it was called, we could pass that response time to both of these aggregators to get an idea of the total time spent in that web method, and the max time spent in any one call to the web method:

// total will be 13 and max 13

int responseTime = 13;

sumAggregator.Aggregate(responseTime);

maxAggregator.Aggregate(responseTime);

  

// total will be 20 and max still 13

responseTime = 7;

sumAggregator.Aggregate(responseTime);

maxAggregator.Aggregate(responseTime);

  

// total will be 40 and max now 20

responseTime = 20;

sumAggregator.Aggregate(responseTime);

maxAggregator.Aggregate(responseTime);

The Func delegate family is useful for making generic algorithms and classes, and in particular allows the caller of the method or user of the class to specify a function to be performed in order to generate a result.

What is the result of a Func delegate chain?

If you remember, we said earlier that you can assign multiple methods to a delegate by using the += operator to chain them. So how does this affect delegates such as Func that return a value, when applied to something like the code below?

Func<int, int, int> combo = null;

  

// What if we wanted to aggregate the sum and max together?

combo += (total, next) => total + next;

combo += Math.Max;

  

// what is the result?

var comboAggregator = new Aggregator<int, int>(combo);

Well, in .NET if you chain multiple methods in a delegate, they will all get invoked, but the result of the delegate is the result of the last method invoked in the chain. Thus, this aggregator would always result in the Math.Max() result. The other chained method (the sum) gets executed first, but it’s result is thrown away:

// result is 13

int responseTime = 13;

comboAggregator.Aggregate(responseTime);

  

// result is still 13

responseTime = 7;

comboAggregator.Aggregate(responseTime);

  

// result is now 20

responseTime = 20;

comboAggregator.Aggregate(responseTime);

So remember, you can chain multiple Func (or other delegates that return values) together, but if you do so you will only get the last executed result.

Func delegates and co-variance/contra-variance in .NET 4.0

Just like the Action delegate, as of .NET 4.0, the Func delegate family is contra-variant on its arguments. In addition, it is co-variant on its return type. To support this, in .NET 4.0 the signatures of the Func delegates changed to:

Func<out TResult> – matches a method that takes no arguments, and returns value of type TResult (or a more derived type).
Func<in T, out TResult> – matches a method that takes an argument of type T (or a less derived type), and returns value of type TResult(or a more derived type).
Func<in T1, in T2, out TResult> – matches a method that takes arguments of type T1 and T2 (or less derived types), and returns value of type TResult (or a more derived type).
Func<in T1, in T2, …, out TResult> – and so on up to 16 arguments, and returns value of type TResult (or a more derived type).

Notice the addition of the in and out keywords before each of the generic type placeholders. As we saw last week, the in keyword is used to specify that a generic type can be contra-variant -- it can match the given type or a type that is less derived. However, the out keyword, is used to specify that a generic type can be co-variant -- it can match the given type or a type that is more derived.

On contra-variance, if you are saying you need an function that will accept a string, you can just as easily give it an function that accepts an object. In other words, if you say “give me an function that will process dogs”, I could pass you a method that will process any animal, because all dogs are animals.

On the co-variance side, if you are saying you need a function that returns an object, you can just as easily pass it a function that returns a string because any string returned from the given method can be accepted by a delegate expecting an object result, since string is more derived. Once again, in other words, if you say “give me a method that creates an animal”, I can pass you a method that will create a dog, because all dogs are animals.

It really all makes sense, you can pass a more specific thing to a less specific parameter, and you can return a more specific thing as a less specific result. In other words, pay attention to the direction the item travels (parameters go in, results come out). Keeping that in mind, you can always pass more specific things in and return more specific things out.

For example, in the code below, we have a method that takes a Func<object> to generate an object, but we can pass it a Func<string> because the return type of object can obviously accept a return value of string as well:

// since Func<object> is co-variant, this will access Func<string>, etc...

public static string Sequence(int count, Func<object> generator)

{

    var builder = new StringBuilder();

  

    for (int i=0; i<count; i++)

    {

        object value = generator();

        builder.Append(value);

    }

  

    return builder.ToString();

}

Even though the method above takes a Func<object>, we can pass a Func<string> because the TResult type placeholder is co-variant and accepts types that are more derived as well:

// delegate that's typed to return string.

Func<string> stringGenerator = () => DateTime.Now.ToString();

  

// This will work in .NET 4.0, but not in previous versions

Sequence(100, stringGenerator);

Previous versions of .NET implemented some forms of co-variance and contra-variance before, but .NET 4.0 goes one step further and allows you to pass or assign an Func<A, BResult> to a Func<Y, ZResult> as long as A is less derived (or same) as Y, and BResult is more derived (or same) as ZResult.

Sidebar: The Func and the Predicate

A method that takes one argument and returns a bool is generally thought of as a predicate. Predicates are used to examine an item and determine whether that item satisfies a particular condition. Predicates are typically unary, but you may also have binary and other predicates as well.

Predicates are often used to filter results, such as in the LINQ Where() extension method:

var numbers = new[] { 1, 2, 4, 13, 8, 10, 27 };

  

// call Where() using a predicate which determines if the number is even

var evens = numbers.Where(num => num % 2 == 0);

As of .NET 3.5, predicates are typically represented as Func<T, bool> where T is the type of the item to examine. Previous to .NET 3.5, there was a Predicate<T> type that tended to be used (which we’ll discuss next week) and is still supported, but most developers recommend using Func<T, bool> now, as it prevents confusion with overloads that accept unary predicates and binary predicates, etc.:

// this seems more confusing as an overload set, because of Predicate vs Func

public static SomeMethod(Predicate<int> unaryPredicate) { }

public static SomeMethod(Func<int, int, bool> binaryPredicate) { }

  

// this seems more consistent as an overload set, since just uses Func

public static SomeMethod(Func<int, bool> unaryPredicate) { }

public static SomeMethod(Func<int, int, bool> binaryPredicate) { }

Also, even though Predicate<T> and Func<T, bool> match the same signatures, they are separate types! Thus you cannot assign a Predicate<T> instance to a Func<T, bool> instance and vice versa:

// the same method, lambda expression, etc can be assigned to both

Predicate<int> isEven = i => (i % 2) == 0;

Func<int, bool> alsoIsEven = i => (i % 2) == 0;

  

// but the delegate instances cannot be directly assigned, strongly typed!

// ERROR: cannot convert type...

isEven = alsoIsEven;

  

// however, you can assign by wrapping in a new instance:

isEven = new Predicate<int>(alsoIsEven);

alsoIsEven = new Func<int, bool>(isEven);

So, the general advice that seems to come from most developers is that Predicate<T> is still supported, but we should use Func<T, bool> for consistency in .NET 3.5 and above.

Sidebar: Func as a Generator for Unit Testing

One area of difficulty in unit testing can be unit testing code that is based on time of day. We’d still want to unit test our code to make sure the logic is accurate, but we don’t want the results of our unit tests to be dependent on the time they are run.

One way (of many) around this is to create an internal generator that will produce the “current” time of day. This would default to returning result from DateTime.Now (or some other method), but we could inject specific times for our unit testing. Generators are typically methods that return (generate) a value for use in a class/method.

For example, say we are creating a CacheItem<T> class that represents an item in the cache, and we want to make sure the item shows as expired if the age is more than 30 seconds. Such a class could look like:

// responsible for maintaining an item of type T in the cache

public sealed class CacheItem<T>

{

    // helper method that returns the current time

    private static Func<DateTime> _timeGenerator = () => DateTime.Now;

  

    // allows internal access to the time generator

    internal static Func<DateTime> TimeGenerator

    {

        get { return _timeGenerator; }

        set { _timeGenerator = value; }

    }

  

    // time the item was cached

    public DateTime CachedTime { get; private set; }

  

    // the item cached

    public T Value { get; private set; }

  

    // item is expired if older than 30 seconds

    public bool IsExpired

    {

        get { return _timeGenerator() - CachedTime > TimeSpan.FromSeconds(30.0); }

    }

  

    // creates the new cached item, setting cached time to "current" time

    public CacheItem(T value)

    {

        Value = value;

        CachedTime = _timeGenerator();

    }

}

Then, we can use this construct to unit test our CacheItem<T> without any time dependencies:

var baseTime = DateTime.Now;

  

// start with current time stored above (so doesn't drift)

CacheItem<int>.TimeGenerator = () => baseTime;

  

var target = new CacheItem<int>(13);

  

// now add 15 seconds, should still be non-expired

CacheItem<int>.TimeGenerator = () => baseTime.AddSeconds(15);

  

Assert.IsFalse(target.IsExpired);

  

// now add 31 seconds, should now be expired

CacheItem<int>.TimeGenerator = () => baseTime.AddSeconds(31);

  

Assert.IsTrue(target.IsExpired);

Now we can unit test for 1 second before, 1 second after, 1 millisecond before, 1 day after, etc. Func delegates can be a handy tool for this type of value generation to support more testable code.

Summary

Generic delegates give us a lot of power to make truly generic algorithms and classes. The Func family of delegates is a great way to be able to specify functions to calculate a result based on 0-16 arguments.

Stay tuned in the weeks that follow for other generic delegates in the .NET Framework!

Technorati Tags: .NET, C#, CSharp, Little Wonders, Generics, Func, Delegates

Developer IT