jaredpar's WebLog : Patterns

If you implement IEquatable you still must override Object’s Equals and GetHashCode

Jared Parsons — Thu, 15 Jan 2009 16:00:00 GMT

CLR 2.0 introduced IEquatable<T> which is an interface that allows for type safe equality comparisons. Previously, the best available method for comparing equality was the virtual Object Equals method. The method is loosely typed since it takes an object as a parameter. This is easy enough to deal with on the client with a simple cast to the appropriate type.

class Student {
    public override bool Equals(object obj) {
        var other = obj as Student;
        if (other == null) {
            return false;
        }
        // rest of comparison
    }
}

IEquatable<T> is a significant improvement over this pattern because it provides a strongly typed equals method. This protects both the caller and callee from passing incompatible object types. Additionally it avoids the overhead of boxing for value types.

These benefits are nice but if you implement IEquatable<T> you still must override Equals(object) and GetHashCode. Not doing so is wrong and will cause you pain down the road. I’ve explored this topic briefly in the past but wanted to expand on it a bit with some concrete examples.

Before we get into the technical details of why, lets look at this from an expectation point of view. Implementing IEquatable<T> is a statement that “this object knows what it means to be equal.” This in effect adds a contract to your class declaring that it knows how to be compared for equality. Your object should live up to these expectations in order to avoid confusing other programmers who aren’t intimately familiar with your class. Confusing programmers is rarely a good idea.

Issue #1: IEqualityComparer<T> requires GetHashCode()

Strongly typed collections such as Dictionary<TKey,TValue> and HashSet<T> must be able to compare objects for equality in order to function. Starting in 2.0, the BCL provides an interface by which object equality semantics can be performed: IEqualityComparer<T>. This class is used in many other places besides collections, but inspecting the collection classes is the easiest way to get a feel for it’s use.

Lets take a look at the definition of IEqualityComparer<T>

public interface IEqualityComparer<T> {
    bool Equals(T x, T y);
    int GetHashCode(T obj);
}

The default definition is an internal class in the BCL named GenericEqualityComparer<T>. The default implementation of IEqualityComparer<T> relies on IEquatable<T> for it’s implementation.

But if it uses IEquatable<T> for it’s implementation how can it possible implement GetHashCode()? Simple, it uses Object.GetHashCode(). This means an object must implement IEquatable<T> and GetHashCode() in order to function correctly in places where IEqualityComparer<T> is used.

But wait, I don’t actually implement IEqualityComparer<T> anywhere so I’m safe right? Unfortunately no. Very few people actually implement IEqualityComparer<T>. Instead they use EqualityComparere<T>.Default to access a given IEqualityComparer<T> for a given type T.

In fact, the standard pattern for methods which take an IEqualityComparer<T> is to have an overload that doesn’t and pass EqualityComparer<T>.Default to the one that does.

public static class Example {
    public static IEnumerable<T> Distinct<T>(this IEnumerable<T> source) {
        return Distinct(source, EqualityComparer<T>.Default);
    }
    public static IEnumerable<T> Distinct<T>(
        this IEnumerable<T> source, 
        IEqualityComparer<T> comparer) {
        // implementation
    }
}

If your object implements IEquatable<T> this will eventually cause it to create an instance of GenericEqualityComparer<T> and hence a reliance on GetHashCode.

Issue #2: Non-Strongly typed collections and Frameworks don’t use IEquatable<T>

IEquatable<T> only provides equality comparisons in strongly typed scenarios. It is not convenient to access this interface in less strongly typed scenarios. Consider for instance the original 1.0 collection classes: ArrayList, Hashtable, etc … These are all object based collections and have no way in which to cast to IEquatable<T>. Instead these collections must rely on the Object based methods of Equality.

Without implementing Object.Equals and Object.GetHashCode your type will not actually do any sort of comparison. This will cause lots of incorrect behavior for programmers who expect the class to understand equality.

class Person : IEquatable<Person> {
    public readonly string Name;
    public Person(string name) {
        Name = name;
    }
    public bool Equals(Person other) {
        if (other == null) {
            return false;
        }
        return StringComparer.Ordinal.Equals(Name, other.Name);
    }
}

static void EqualityCheck() {
    var p = new Person("Bob");
    var list = new ArrayList();
    list.Add(p);
    Console.WriteLine(list.Contains(p)); // Prints: True
    Console.WriteLine(list.Contains(new Person("Bob")));    // Prints: False
}

This goes against expectation. Both Person instances in this case are equal by definition of Person yet Contains fails. Implementing Object.Equals and Object.GetHashCode will remove this confusion.

The list of frameworks which still use loosely typed collections include WinForms, WPF, WebForms, etc … It’s almost inevitable that you will end up using a loosely typed collection in your project somewhere.

Isssue #3: Equality and hash codes are linked in the BCL

Rightly or wrongly, equality and hash codes are unbreakably linked in the BCL. If an object can be compared for equality it also must be able to produce a hashcode. This implicit contract exists many places throughout the framework.

As previously displayed, implementing Object.Equals() after implementing IEquatable<T> is straight forward and boiler plate code. Object.GetHashCode can be a bit trickier because there are many implicit contracts for GetHashCode. Often mutable objects cannot provide an efficient hashing mechanism. In that case just return 1. This will satisfy all of the implicit contracts around GetHashCode() and takes little time to do. Yes, it will cause a Dictionary to effectively be a linked list. But that’s a heck of a lot better than simply not working at all.

Comparing Continuations in F# and C#

Jared Parsons — Mon, 10 Nov 2008 16:00:00 GMT

Lately I’ve been playing quite a bit with F#. I have several hobby projects I’m working on that take up a bit of my time. But when I’m not playing around with F# I’m exploring ways to apply certain functional patterns to actual coding on the job and/or porting to my functional library: RantPack.

Recently I’ve been playing around with continuations in F#. I thought this was a great topic to do a F# comparison with other languages. In this case C#.

Let’s examine a classic use of continuations: a right fold on a list. For a detailed explanation of fold right and the use of a continuation I suggest taking a look at Brian's discussion. If you’re unfamiliar with continuations I highly suggest that you take a look at this post as Brian gives a great breakdown of continuations and their uses.

Here's a quick refresher on continuations by example. Fold right is an operation which reduces a sequence of elements into a single element by processing the list from right to left. It’s similar to the LINQ Aggregate method except Aggregate operations left to right.

For this post we’ll be writing FoldRight against a sequence. I chose sequence vs. the traditional list because it’s present in both languages (F# = seq<’a>, C# = IEnumerable<T>). It is possible to other F# data structures in C# but the comparison is cleaner when using a type that is native to both languages.

Sequences are a left to right data structure so processing it right to left is not natural. After all, with a sequence all the developer has is current and whether or not there is a next element. Processing the list in a right to left fashion can be done by such acts as reversing the list, or doing a head recursive call. Both have their detractors.

Continuations are a different way to process the list. Instead of processing the list directly we process the list a single element at a time building up a continuation along the way. For each element a lambda expression is generated representing the work needed to be done for that element. The value calculated within the lambda will then be passed to the lambda calculated for the previous element. Once we hit the end of the list, we essentially have a chain of lambda expressions which process each element in the list in reverse order. All that is needed is to call the final lambda with the starting value and we will effectively process the list in reverse order.

Simple enough? Lets take a look at the code.

F# Code

let FoldRight combine (sequence:seq<'a>) acc = 
    use e = sequence.GetEnumerator()
    let rec inner cont = 
        match e.MoveNext() with
            | true -> 
                let cur = e.Current
                inner (fun racc -> cont (combine cur racc))
            | false -> cont acc
    inner (fun x -> x )

C# Code

public static TAcc FoldRight<TSource, TAcc>(
    this IEnumerable<TSource> enumerable, 
    Func<TAcc, TSource, TAcc> combine, 
    TAcc start) {

    using (var e = enumerable.GetEnumerator()) {
        Func<Func<TAcc, TAcc>, TAcc> inner = null;
        inner = (cont) => {
              if (e.MoveNext()) {
                  var cur = e.Current;
                  Func<TAcc, TAcc> innerCont = (x) => cont(combine(x, cur));
                  return inner(innerCont);
              } else {
                  return cont(start);
              }
          };
        return inner(x => x);
    }
}

My immediate reaction to the two samples is the conciseness of the F# code. This is a not a criticism of C# though. F# is designed to be a concise language and it’s delivery on that goal is evident in this sample.

What makes the big difference here is the type inference power of F#. In the C# sample there are 6 explicit types listed in the code sample. The F# sample only has a single type listed. The compiler is able to infer and/or generate the rest of the signatures. F# also requires less explicit generic parameters 1 vs. 2 in C#.

The next big difference I see is the awkward way in which the inner lambda expression must be declared in C#. The lambda expression is called recursively in order to setup the continuation. In order to do that in C# the lambda must be declared and defined in separate expressions. Otherwise, a self reference of “inner” inside the body of “inner” will generate a used before defined warning from the compiler.

The IL

Examining the full IL of both functions would take several blog posts. Not to mention that trying to read disassembled F# much less IL, is like trying to read disassembled C++. An interesting exercise but a bit time consuming.

I did want to focus a bit on one portion of the generated IL. There is a very significant difference in the way the recursive call to the “inner” lambda is made.

    L_0032: ldarg.1 
    L_0033: ldarg.0 
    L_0034: ldfld !0 Test/clo@6T::acc
    L_0039: tail 
    L_003b: callvirt instance !1 [FSharp.Core]Microsoft.FSharp.Core.FastFunc`2::Invoke(!0)

    
    L_0077: ldarg.0 
    L_0078: ldfld class [System.Core]System.Func`2, !1> ConsoleApplication1.Extensions/<>c__DisplayClass8::inner
    L_007d: ldloc.0 
    L_007e: callvirt instance !1 [System.Core]System.Func`2, !TAcc>::Invoke(!0)
    L_0083: stloc.3

In both cases the first 3 lines are building up the 2 parameters necessary for the recursive lambda call. The closures are structured somewhat differently but the same basic operation is being done.

The key difference between the languages is F#’s use of the tail opcode. This opcode tells the CLR the to call the next method in a tail recursive fashion. This causes the CLR to remove the current method frame from the stack before the next method is called. Because the method is removed from the stack, the recursive call takes up no additional stack space. This is true no matter how many times the function is called.

The C# IL does not have this opcode. So the recursive call will happen with the current method on the frame. With a big enough sequence this will cause the process to run out of stack space and generate a StackOverflowException. This creates a limitation on the number of elements the C# sample can process.

Limits

I explored the limits of both samples on my home laptop. I generated a simple example to sum the sequence with the fold right. Note: For a sum of ints, a fold left is just as good, but it serves fine for this sample.

let sum = FoldRight (fun x y -> x + y) [1..1000000] 0
printfn "%d" sum

var source = Enumerable.Range(1, 9397);
var result = source.FoldRight((x, y) => x + y, 0);
Console.WriteLine("{0}", result);

The C# sample can process a maximum size of 9397 elements. After that I encounter a stackoverflow exception. The F# sample however can easily process 1,000,000 elements.

Closing note. This not meant to be a post criticizing C#. It’s meant to be a general comparison of the same technique in two managed languages. This is a scenario that is far less likely to occur in a C# program. In an F# program it’s quite simply an expectation and hence the F# compiler is optimized for this scenario.

Custom Exceptions: When should you create them?

Jared Parsons — Mon, 20 Oct 2008 15:00:27 GMT

I think the best answer is: rarely. It's really hard to go straight to a justification here though. I find that answering a different question will eventually shed led on when to create a new exception.

"What are the benefits of creating a new/custom exception?"

The answers I come up with or have heard before are ...

Provides a type safe mechanism for a developer to detect an error condition.
Without a custom exception a developer would be forced to compare an existing value on an existing exception class in order to determine if a particular error occurred. To ensure this was unique across applications and environments a unique identifier would need to be inserted as well (likely a GUID). The resulting code would be quite ugly and maintainability would be a question mark.
Add situation specific data to an exception
Ideally this data would help another developer track down the source of the error.

But an entirely new exception is not needed to achieve this goal. The base Exception class contains a property named Data which is an open dictionary. Any code which raises an exception is free to add custom data into the exception. This data can then be accessed by the handling code. Unique values still need to be dealt with. But in my experience, accessing a GUID based custom property is a bit more accepted than catching an exception based on some GUID property.

This is especially true now with extension methods. The lack of type safety in the dictionary and potentially constant string sharing for property names could be hidden inside an extension method
No existing exception adequately described my problem
I'd argue against this because of InvalidOperationException. Invalid operation should cover most exceptional cases

So of these reasons only #1 is a stand alone benefit of a new exception. Now lets re-state this advantage in the context of the original question.

Creating a new exception allows a developer to catch them

Simple right? But what benefit does this give to a developer? From my experience there are only two reasons to catch an exception.

It's a particular for which the underlying exceptional problem can be corrected. Perhaps the user is prompted to fix the condition by performing some outside action (like re-inserting a disk).
Logging errors for post-mortem debugging. Note: You could also use the Data dictionary and extension methods above to introduce a new method ShouldLog(). This would allow you to avoid creating a new exception type.

Now I think we can answer the original question of this blog post.

You should only create a new exception if you expect developers to take corrective action for the problem or to log for post mortem debugging.

Otherwise, what benefit does creating this exception give you?

If it's not broken, maybe you should fix it anyway

Jared Parsons — Mon, 13 Oct 2008 15:00:27 GMT

I know this is goes against conventional wisdom but it's something I believe in. Every sufficiently large project has that section of code nobody wants to go near. The mere mention of it causes people to leave the room. It usually has a couple of properties

Old and Stagnant
Critical or important routine
Fragile
Written by a developer who doesn't work there anymore
Undocumented
Untested
Poorly understood

But it works and usually has for several releases. By conventional wisdom it is considered "unbroken" and not worthy of changing.

I disagree. Very often I find towards the end of the cycle more and more bugs start popping up in this code. It's a pattern I've seen in many groups across releases. These bugs are extremely expensive to fix because they are a) at the end of the cycle and b) being make in a piece of code that no one understands. Since it's not broken nobody bothered with the code and hence it stayed poorly understood (and likely just as untested). The bugs are doubly worse because no one wants to go near that code for fear of breaking the world.

Why let this code hang around in it's current state? It's bad and no one understands why. It's a constant source of pain late in the cycle and often in the middle.

I prefer to take a more proactive approach; fix it.

At the end of a product cycle I like to identify these pieces of code and attack them in-between releases. This is a relatively safe point in the release cycle to change poorly understood code. There is an entire release cycle ahead to catch the bugs introduced (and there will be some).

I don't break this code without thought. I prefer to take a pragmatic approach to the code in the following steps.

Attempt to understand the intent of the code (easier said than done). I contact the original author if possible
Poll the more senior developers on their understanding of what the code does
Design a new architecture if needed
Design a test plan (this is the absolute most important step. Why fix this if you don't bother testing it?)
Make the change

I've done this, or overseen someone else, on several pieces of code over the last few years. Thus far it's been a very big success.

Unfold

Jared Parsons — Tue, 07 Oct 2008 15:00:34 GMT

F# has a handy method called Unfold. Think of it as the logical opposite of an Aggregate function. Aggregates take a sequence of elements and convert them to a single element. An unfold method will take a single element and turn it into a (potentially infinite) sequence of elements.

The API is straight forward. It takes two parameters

A seed/start value
A function which takes in a seed value and returns either an Empty option to indicate the end of a sequence or a value of Type tuple with two arguments. The first is the next element in the sequence and the second is the next seed value passed into the function.

This is a very powerful function which allows you to quickly build all sorts of interesting functions. Lets look at a potential implementation of Enumerable.Range as an unfold expression.

public static IEnumerable<int> Range(int start, int count)
{
    return Enumerable.Unfold(
        start,
        x => x - start < count
            ? Option.Create(Tuple.Create(x, x + 1))
            : Option.Empty);
}

Not as efficient as the framework version of Range but a good mental exercise to get your head around using Unfold. Implementing this method in C# is fairly straight forward.

public static IEnumerable<TResult> Unfold<TSource, TResult>(
    TSource state, 
    Func<TSource, Option<Tuple<TResult, TSource>>> func)
{
    if (func == null)
    {
        throw new ArgumentNullException("func");
    }

    return UnfoldHelper(state, func);
}

private static IEnumerable<TResult> UnfoldHelper<TSource, TResult>(
    TSource state, 
    Func<TSource, Option<Tuple<TResult, TSource>>> func)
{
    do
    {
        var result = func(state);
        if (!result.HasValue)
        {
            break;
        }

        yield return result.Value.First;
        state = result.Value.Second;
    } while (true);
}

Functional C#: Providing an Option

Jared Parsons — Mon, 06 Oct 2008 15:00:16 GMT

Sorry for the terrible pun in the title. I wanted to blog about developing an F# style Option class for C# and I couldn't resist.

The basics of an Option class are very straight forward. It's a class that either has a value or doesn't. It's almost like nullable but for every type and allows for nulls to be a valid value. Here's a straight forward Option class I coded up.

public sealed class Option<T> {
    private readonly T m_value;
    private readonly bool m_hasValue;
    public static Option<T> Empty {
        get { return new Option<T>(); }
    }
    public bool HasValue {
        get { return m_hasValue; }
    }
    public T Value {
        get {
            if (!HasValue) {
                throw new InvalidOperationException("Option does not have a value");
            }
            return m_value;
        }
    }
    public Option(T value) {
        m_hasValue = true;
        m_value = value;
    }
    private Option() {
        m_hasValue = false;
        m_value = default(T);
    }
}

public sealed class Option {
    public static Option<T> Create<T>(T value) {
        return new Option<T>(value);
    }
}

I modified a bit of terminology to be more consistent with other frameworks I use (Some/None -> Value,HasValue). It's succinct, generic and has type inference friendly create functions. Or does it?

Lets consider a function which has a return type of Option<int>. Case 1 is Option with a value. There is a type inference friendly Option.Create method which makes for a simple return expression. No types needed.

Option<int> SomeMethod() {
    return Option.Create(42);
}

Now lets consider Case #2, None. Here there is no handy inference method because what would we use for inference. There is no variable with a Type to use so we are forced to be explicit about the type.

Option<int> SomeMethod2() {
    return Option<int>.Empty;
}

In this case we're not so bad off because we're dealing with a simple type. But what about more complex types? Consider for example a hypothetical Unfold method. The termination expression would be Option<Tuple<int,string>>.Empty. Anonymous types are even worse since they are unnamable and can not ever be the source of an option with this design. This really pales in the usage category when compared with F#.

Lets see if we can do better.

First we could consider a design where we have a static creation method Empty which takes variables that aren't ever used. This will give us the benefit of type inference but at the expense of an API which is faulty to the core. It forces the user to create parameters that aren't ever used. Definitely not a good design.

This leaves us with using a solution that doesn't involve variables of the necessary type. This essentially forces us into a non-generic solution since we need variables for type inference. This non-generic Option won't be compatible with our generic return type. But wait, what will the compiler do if two expressions have conflicting types? Eventually it will attempt to perform a conversion. So if we make our non-generic empty Option convertible to any generic empty Option we can use the compilers type safety to our advantage.

Definition a non-generic empty Option is straight forward.

public sealed class Option {
    private static Option s_empty = new Option();
    private Option() {
    }
    public static Option Empty {
        get { return s_empty; }
    }
    public static Option<T> Create<T>(T value) {
        return new Option<T>(value);
    }
}

Using a private constructor allows us a high degree of confidence that any Option instance hanging around came from our Empty property and hence represents an empty option. Now all we need to do is define a conversion on Option<T>. Essentially we want to say that any non-generic Option is convertible to this instance. Add the following to Option<T>

public static implicit operator Option<T>(Option option) {
    return Option<T>.Empty;
}

Now, we can use an empty option in any generic scenario without having to specify ugly type parameters.

Option<int> SomeMethod3() {
    return Option.Empty;
}

RantPack Update 2.0.0.2

Jared Parsons — Wed, 23 Jul 2008 15:00:13 GMT

Version 2.0.0.2 released.

Summary: RantPack is a utility library I maintain and actively use. The main themes of this library are functional programming, patterns, immutable/pressitent collections, future and other threading primitives. I've placed the code and binaries on http://code.msdn.microsoft.com/RantPack for educational and sharing purposes.

Release Link: https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=RantPack&ReleaseId=1306

Release Notes:

Renamed Tuple properties to be more consistent

Item0, Item1 instead of A,B

Added a Match operator
Made Enumerable more compatible
Bug fixes

Yet another rule for Equality

Jared Parsons — Fri, 11 Jul 2008 15:00:24 GMT

"If you implement equality in a child class, including operators, you must implement the equality operators in the base class."

Unfortunately this is another case of learn the hard way but makes sense when you think about it. The below code snippet is an example of the problem that I hit. Even though I have equality properly defined in Child, the equality check goes through Parent. As such the C# compiler will perform the default comparison which is reference equality.

The simple fix is to add the operator ==/!= definitions to Parent which call through EqualityComparer<Parent>.Default. This will end up calling obj.Equals and equality will function correctly.

While this is intuitive when you think about it, it's an easy trap to fall into. It would be nice if there was a Compiler/FXCop warning here.

    class Parent {
    }
    class Child : Parent{
        public readonly int Field1;
        public Child(int value) {
            Field1 = value;
        }

        public override int GetHashCode() {
            return Field1;
        }
        public override bool Equals(object obj) {
            var other = obj as Child;
            if (other == null) {
                return false;
            }
            return other.Field1 == Field1;
        }
        public static bool operator ==(Child left, Child right) {
            return EqualityComparer<Child>.Default.Equals(left, right);
        }

        public static bool operator !=(Child left, Child right) {
            return !EqualityComparer<Child>.Default.Equals(left, right);
        }
    }

    class Program {
        static void Main(string[] args) {
            Child child1 = new Child(42);
            Child child2 = new Child(42);
            Parent parent1 = child1;
            Parent parent2 = child2;
            bool isChildEqual = child2 == child1;       // True
            bool isParentEqual = parent1 == parent2;    // False
        }
    }

Enums vs. Adapters

Jared Parsons — Wed, 18 Jun 2008 15:00:21 GMT

I like Enums and use them frequently for options and behavior. To an extent I use Enum's to control behavior. For example

enum Kind {
    Kind1,
    Kind2,
    Kind3
}

class Example {
    private Kind m_kind;

    public int SomeAction() {
        switch (m_kind1) {
            case Kind.Kind1:
                return ActionForKind1();
            case Kind.Kind2:
                return ActionForKind2();
            case Kind.Kind3:
                return ActionForKind3();
            default:
                throw new InvalidOperationException("Invalid Kind");
        }
    }
}

This is an acceptable pattern and use for enums. However if you take a step back, what I've actually done here is use an enum to implement an adapter pattern. I've just been a bit lazy about it and not actually coded up the classes.

To an extent though this violates the principle of single use as Example now performs N different behaviors based upon the enum. But lets face it, if ActionForKindN() is just a simple 2 line function then is it really worth it to create and maintain an adapter pattern? A purest would likely say yes but I'm more pragmatic and don't believe so.

Once the functions reach a certain level of complexity though an adapter pattern is much more suitable. Over time I find that many of my similar patterns evolve to level.

Yet I struggle to define the point at which an adapter is suitable. After several recent experiences I started adapting the following rules. If any of them is violated then I switch from an enum based behavior to adapter based behavior.

The Action* method contains state
There are more than 2 functions which change their behavior based on the enum value
All methods in the class change their behavior based on the enum

Anyone have a better set?

Making Equality easier

Jared Parsons — Tue, 03 Jun 2008 15:00:10 GMT

Recently I've done a bit of posting about the difficulties of properly implementing equality in VB (and DotNet in general). While most of the problems can be fixed with a standard snippet the one really hard to implement issue is GetHashCode(). The rules for GetHashCode() are both simple and seemingly contradictory

If two objects are equal (via Equals) their GetHashCode() should be equal
GetHashCode() shouldn't ever change

These rules imply that GetHashCode() is related to Equality. At a fundamental level though GetHashCode has nothing to do with Equality. Instead it is linked to bucketing and ultimately any hashing sturcture such as Dictionary, Hashtable, etc ...

Unfortunately it is impossible to separate these two from an API perspective because it is ingrained into the BCL. There is a way to separate this out at a functionality level and still satisfy all of the rules of the GetHashCode() and Equals()

    Public Overrides Function GetHashCode() As Integer
        Return 1
    End Function

This absolutely maintains both of the rules for GetHashCode(). This allows you to completely separate Equality and GetHashCode() in your implementation while not breaking any BCL rules or assumptions.

Of course this does come with a trade off. As said before GetHashCode() is primarily used as a bucketing mechanism. It will cause the performance of bucketing collections such as Dictionary or Hashtable to drop from close to O(1) to O(N). But once again this is not a bug but a conscious trade off.

RantPack Update

Jared Parsons — Tue, 03 Jun 2008 03:26:08 GMT

I released a new version of RantPack today. Mostly this is a bug fix release with a couple of minor new features.

https://code.msdn.microsoft.com/Release/ProjectReleases.aspx?ProjectName=RantPack&ReleaseId=1119

Features

Added a way to shim Immutable collections to non-immutable interfaces to increase the level of interoperability. The collections are still immutable and throw an exception whenever one of the mutable APIs are called. However if the collection is used in an immutable fashion, such as data binding, CollectionUtility.Create* can be used to quickly create a wrapper

var q = ImmutableStack<int>.Empty;
CollectionUtility.GetRangeCount(1, 10).ForEach(x => q = q.Push(x));
ICollection<int> list = CollectionUtility.CreateICollection(q);

var m = ImmutableAvlTree<int, string>.Empty;
CollectionUtility.GetRangeCount(1, 10).ForEach(x => m = m.Add(x, x.ToString()));
IDictionary<int, string> map = CollectionUtility.CreateIDictionary(m);

Added an immutable queue named ImmutableQueue
Added more overloads to Immutable*.Create to allow more interoperability with BCL data structures.

Bugs

MutableTuple.GetHashCode() violated the contract for Object.GetHashCode() by allowing updates to mutate the hash code

do {} while(0) what?

Jared Parsons — Wed, 21 May 2008 15:00:00 GMT

A recent check in of mine raised a few eye brows during reviews. I checked in a few macros which ended with/contained a "do{}while(0)" and people were curious as to why.

In my experience there are two main uses for it.

Insert an empty statement with no runtime penalty
Group a set of statements into a single statement followable by a semi-colon

do { Func1(); Func2() } while(0)

Macros are mutating little constructs which jump back and forth depending on the compile time options. Many macros compile to different expressions based on the options and in some cases they compile to nothing. This is where #1 really comes in hand. Imagine you have the following code.

  if(someCondition)
    MY_MACRO();

Compiling MY_MACRO to nothing will cause at the least a compile time warning since you will have essentially if(someCondition);. Instead you can use the do{}while(0) trick.

#if CONST_1
#define MY_MACRO() Func1()
#else
#define MY_MACRO() do{}while(0)

Another us is for stylistic reasons. Some camps don't believe a ; should be used as a empty statement and use do{}while(0) instead. I tend to agree. Mainly because one of my early C professors had the same belief. The habit stuck around.

Update: Changed incorrect use of word expression -> single statement

Switching on Types

Jared Parsons — Fri, 16 May 2008 15:00:00 GMT

One action I find frustrating in C# is where a particular action needs to be taken based off of the type of a particular object. Ideally I would like to solve this with a switch statement but switch statements only support constant expressions in C# so no luck there. Previously I've had to resort to ugly looking code like the following.

Type t = sender.GetType();
if (t == typeof(Button)) {
    var realObj = (Button)sender;
    // Do Something
}
else if (t == typeof(CheckBox)) {
    var realObj = (CheckBox)sender;
    // Do something else
}
else {
    // Default action
}

Yes I realize this isn't the ugliest code but it seems less elegant to me over a standard switch statement and I find the casting tedious. Especially since it requires you to write every type twice.

What I want to say is "Given this type, execute this block of code." So I decided to run with that this afternoon. Lambdas will serve nicely for the block of code and using type inference will allow us to avoid writing every type out twice. What I ended up with was a class called TypeSwitch with 3 main methods (see bottom of post for full code).

Do - Entry point where switching begins
Case - Several overloads which take a generic type argument and an Action<T> to run for the object
Default - Optional default action.

I wrote a quick winforms app to test out the solution. I dropped some random controls on a from and bound the MouseHover event for all of them to a single method. I can now use the following code to print out different messages based on the type.

TypeSwitch.Do(
    sender,
    TypeSwitch.Case<Button>(() => textBox1.Text = "Hit a Button"),
    TypeSwitch.Case<CheckBox>(x => textBox1.Text = "Checkbox is " + x.Checked),
    TypeSwitch.Default(() => textBox1.Text = "Not sure what is hovered over"));

Notice that for check box I was able to access CheckBox properties in a strongly typed fashion. The underlying case code will optionally pass the first argument to the lambda expression strongly typed to the value specified as the generic argument.

There are a couple of faults with this approach including Default being anywhere in the list but it was a fun experiment and works well.

TypeSwitch code.

static class TypeSwitch {
    public class CaseInfo {
        public bool IsDefault { get; set; }
        public Type Target { get; set; }
        public Action<object> Action { get; set; }
    }

    public static void Do(object source, params CaseInfo[] cases) {
        var type = source.GetType();
        foreach (var entry in cases) {
            if (entry.IsDefault || type == entry.Target) {
                entry.Action(source);
                break;
            }
        }
    }

    public static CaseInfo Case<T>(Action action) {
        return new CaseInfo() {
            Action = x => action(),
            Target = typeof(T)
        };
    }

    public static CaseInfo Case<T>(Action<T> action) {
        return new CaseInfo() {
            Action = (x) => action((T)x),
            Target = typeof(T)
        };
    }

    public static CaseInfo Default(Action action) {
        return new CaseInfo() {
            Action = x => action(),
            IsDefault = true
        };
    }
}

IEquatable(Of T) and GetHashCode()

Jared Parsons — Fri, 09 May 2008 15:00:53 GMT

This is a bit of a follow up to a previous post we discussed how to properly implement equality in VB. Several users commented/asked that IEquatable(Of T) could be used in place of overriding Equals(). Since IEquatable(Of T) doesn't define a GetHashCode() method the user didn't need to define it and hence run into all of the problems associated with GetHashCode() usage.

Unfortunately this is not the case. Several parts of the framework link IEquatable(Of T).Equals and Object.GetHashCode() in the same way that Object.Equals() and Object.GetHashCode() are linked.

The prime example of this is EqualityComparer(Of T). This class is used to provide instances of IEqualityComparer(Of T) for any given type. Under the hood it tries to determine the best way checking for equality in types. If T implements IEquatable(Of T) it will eventually create an instance of GenericEqualityComparer(Of T) [1]. The methods of IEqualityComparer(Of T) are implemented as follows (boundary cases removed)

Equals(left, right): return left.Equals(right)

Equals in this case is IEquatable(Of T).Equals

GetHashCode(obj): return obj.GetHashCode()

This implicitly links IEquatable(Of T).Equals to Object.GetHashCode(). Therefore if you implement IEquatable(Of T) you should also override GetHashCode(). The best way to view this is "if you implement IEquatable(Of T) you should override Equals and GetHashCode."

What's even more unfortunate is there is no feedback to indicate this relationship exists. If you override Equals or GetHashCode both the C# and VB compilers will issue a warning/error. Implementing IEquatable(Of T) produces no such warning.

[1] Unfortunately this is a private type so you will need to use Reflector to view the type.

Properly Implementing Equality in VB

Jared Parsons — Mon, 28 Apr 2008 15:04:06 GMT

Many developers want to implement equality functions for their objects. DotNet made equality a deep part of the framework and added support all the way up to System.Object with Equals and GetHashCode. In addition to the strongly enforced method semantics of GetHashCode and Equals there are also several other hard to enforce patterns that developers must follow in order to properly integrate into the rest of the DotNet framework. We'll explore those rules today.

Before even talking about how to implement equality we need to define the types of equality.

Reference equality: Are these two objects really the exact same object.
Object/value equality: Depends on what the object author thinks equality means. Can be anything from reference equality up to, comparing fields, to were they created in the same app domain.

In VB these are two very separate types of equality. Reference equality is expressed through the "Is" operator. Object equality is done directly through operator=, operator<> and Equals. This is also indirectly exposed via GetHashCode, EqualityComparer(Of T) and other framework patterns.

When implementing object/value Equality there are four methods that are important to consider in order to fit expected patterns. What's even more important is understanding which ones must be implemented together. If an author overrides any of the functions in the following pairs they must override both.

Equals/GetHashCode
Operator=/Operator!=

To make it easier, my rule of thumb is to override all four or none.

Equals

This is the bread and butter of object/value equality. The author has free reign to decide what is and what is not equal. However there are a few rules authors must follow in order to fit into the rest of the framework.

Do not throw an exception from Equals. Many components call Equals in a loop and there is no way for them to handle or recover from an exception. If the object is not equal just return False
The object passed in is typed to object. It is perfectly valid for the framework to pass in an object that is completely unrelated to the type defining Equals. The type author must account for and handle this case.
The framework can pass in Nothing as a parameter to Equals and this is valid.

#2 and #3 may seem a bit off at first but it is implemented with a standard pattern as seen below.

Class C1
    Public Overrides Function Equals(ByVal obj As Object) As Boolean
        Dim other = TryCast(obj, C1)
        If other Is Nothing Then
            Return False
        End If
        ...
    End Function
End Class

It's very important that you use "Is" to compare other in the above example. Imagine if you slip up and type "=" instead. You're about to override Operator= and this will cause "other=Nothing" to call operator=. If this is a valid C1 instance operator= will almost certainly call Equals and then you'd have a stack overflow. Our implementation of Operator= below will avoid this problem.

GetHashCode

This is both the easiest and trickiest function to override because it has very subtle semantics which cause very hard to find bugs in code. The simple rule is "If two objects are equal in the sense of value equality they must return the same value in GetHashCode()".

Why? Many classes use the hash code to classify an object. In particular hash tables and dictionaries tend to place objects in buckets based on their hash code. When checking if an object is already in the hash table it will first look for it in a bucket. If two objects are equal but have different hash codes they may be put into different buckets and the dictionary would fail to lookup the object.

The better version of the GetHashCode rule has a small suffix on the simple rule. "Only calculate the hash code based off of primitive fields which are ReadOnly". This is not an absolute requirement as long as you are careful when you are code. But as previously stated, when coding it's best not to trust yourself to do the right thing. Not doing this will get you into trouble when dealing with Hashtables and dictionaries.

For instance take this not so small example. In this case value equality is based solely off of Field1 which is a modifiable field. Once Field1 is changed you may or may not be able to access the value in the dictionary because GetHashCode() will change. This example is contrived but it does happen in the real world and it can be incredibly difficult to track down.

Class C2
    Public Field1 As Integer

    Public Sub New(ByVal f1 As Integer)
        Field1 = f1
    End Sub
    Public Overrides Function GetHashCode() As Integer
        Return Field1.GetHashCode()
    End Function
    Public Overrides Function Equals(ByVal obj As Object) As Boolean
        Dim other = TryCast(obj, C2)
        If other Is Nothing Then
            Return False
        End If
        Return other.Field1 = Field1
    End Function
End Class

Module Module1

    Sub Main()
        Dim map = New Dictionary(Of C2, String)
        Dim v1 = New C2(44)
        map.Add(v1, "avalue")
        Console.WriteLine(map(v1))
        v1.Field1 = 2
        Console.WriteLine(map(v1))  ' Potentially throws
    End Sub

End Module

If Field1 were ReadOnly there would be no way to hit this problem. Then again we'd also not be able to change Field1.

Operator=

When implementing equality overriding operator= allows you to use the more pleasant and reliable version of syntax comparison: a=b vs. a.Equals(b). I say more reliable because using a.Equals(b) has an inherent dependency on "a" being a non-Nothing object. "Operator=" makes no assumption and should operate correctly in the presence of Nothing.

Operator= has virtually the same rules as Equals. Mainly don't throw from operator=. Operator= is usually just defined in terms of Equals() and since it also has to respect the no throw rule once we get there we are in good shape. Getting to Equals() can be tricky though because one or both of the arguments can be Nothing. In addition make sure not to use "=" to check for Nothing because you're back to the stack overflow problem.

What's great here is there is a simple solution that you should use every time you define Operator=. EqualityComparer(Of T) knows all of these rules and in the face of both parameters being non-Nothing will call Equals() just like we want. This makes the definition of Operator= boiler plate (I define very Operator= the exact same way)

Public Shared Operator =(ByVal left As C2, ByVal right As C2) As Boolean
    Return EqualityComparer(Of C2).Default.Equals(left, right)
End Operator

What's even better is that EqualityComparer(Of T) understands the stack overflow problem which can occur in equality comparison and avoids it.

Operator <>

Operator<> has the same rules as Operator= and luckily the same easy type of answer.

Public Shared Operator <>(ByVal left As C2, ByVal right As C2) As Boolean
    Return Not EqualityComparer(Of C2).Default.Equals(left, right)
End Operator

Wrapping Up

I started this article thinking it would be a few paragraphs of simple rules. But as I kept going I kept remembering the subtleties and problems I encountered in the past.

For my own projects I avoid implementing equality unless it's truly needed because of the problems with properly implementing GetHashCode(). The one exception is when I define immutable objects. Immutable objects have no problems with GetHashCode() since they are unchangable so Equality is straight forward.