Other posts:

• Part II - Making the class bet­ter{.}
• Part III - Using a struct{.}
• Part IV - A class with a spe­cial value{.}

Value ob­jects are ob­jects for which the iden­tity is based on their state in­stead of their pointer in mem­ory. For ex­am­ple, a nu­meric Complex class is, most of the time, a value ob­ject be­cause you can treat two in­stances as the same if their state (real and img fields in this case) is the same. An im­mutable value ob­ject is a value ob­ject that can­not be changed. You can­not mod­ify its state, you have to cre­ate new ones.

I’m us­ing these guys more and more in my code for a num­ber of rea­sons, both prac­ti­cal and philo­soph­i­cal. The prac­ti­cal ones re­volve around the greater ro­bust­ness of pro­gram­ming with­out side ef­fects and the greater sim­plic­ity of par­al­leliz­ing your code. The philo­soph­i­cal ones are more in­ter­est­ing (and sub­jec­tive). When in my de­sign process I spend the time to ag­gres­sively look­ing for these kinds of ob­jects, the re­sult­ing de­sign ends up cleaner. I es­pe­cially like when I can de­fine some sort of close al­ge­bra for these guys (i.e. a set of func­tions that op­er­ate over them and pro­duces new ones, not un­like ‘+’ and ‘-’ for num­bers).

This se­ries de­scribes how to cre­ate im­mutable value ob­jects in C# and the de­sign de­ci­sions in­volved. This is a sum­mary of an email thread I had with Mads and Luke.

The con­cept I will use for this se­ries is a DateSpan. As I de­fine it, a DateSpan has a Start and an End date. You can ask for the DataS­pan that rep­re­sents the Union and Intersection of two DateSpans. The tests in the at­tached code bet­ter de­fine the be­hav­ior of these op­er­a­tions.

Given that I never use structs in my code (I’m a min­i­mal­ist lan­guage user), I’ll start by us­ing a class to rep­re­sent it. We’ll make this class bet­ter in part II and use a struct in part III. A first stab at it is as fol­lows:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
public class DateSpan {
    public DateSpan(DateTime start, DateTime end) {
        if (end < start)
            throw new ArgumentException(start.ToString() + " doesn't come before " + end.ToString());
        Start = start;
        End = end;
    }
    public DateSpan Union(DateSpan other) {
        if (other == null)
            return new DateSpan(Start, End);
        if (IsOutside(other))
            return null;
        DateTime start = other.Start < Start ? other.Start : Start;
        DateTime end = other.End > End ? other.End : End;
        return new DateSpan(start, end);
    }
    public DateSpan Intersect(DateSpan other) {
        if (other == null)
            return null;
        if (IsOutside(other))
            return null;
        DateTime start = other.Start > Start ? other.Start : Start;
        DateTime end = other.End < End ? other.End : End;
        return new DateSpan(start, end);
    }
    private bool IsOutside(DateSpan other) {
        return other.Start > End || other.End < Start;
    }
    public DateTime Start { get; private set; }
    public DateTime End { get; private set; }
    #region Boilerplate Equals, ToString Implementation
    public override string ToString() {
        return string.Format("Start:{0} End:{1}", Start, End);
    }
    public override bool Equals(object obj) {
        if (obj == null) return false;
        if (this.GetType() != obj.GetType()) return false;
        DateSpan other = obj as DateSpan;
        return other.End == End && other.Start == Start;
    }
    public override int GetHashCode() {
        return Start.GetHashCode() | End.GetHashCode();
    }
    public static Boolean operator ==(DateSpan v1, DateSpan v2) {
        if ((object)v1 == null)
            if ((object)v2 == null)
                return true;
            else
                return false;
        return (v1.Equals(v2));
    }
    public static Boolean operator !=(DateSpan v1, DateSpan v2) {
        return !(v1 == v2);
    }
    #endregion
}

public static class TimeLineExtensions {
    public static bool IsSuperSet(this DateSpan span, DateSpan other) {
        if (span.Intersect(other) == other)
            return true;
        return false;
    }
}

Some things to no­tice in this code:

1. Defining a value ob­ject with a C# class in­volves over­rid­ing Equals, Hashcode, == and !=. It is tricky, but usu­ally boil­er­plate stuff, well de­scribed in Wagner (2004). I don’t have Bill’s book in my of­fice, so I kind of made it up on the fly. It could be very wrong (the ‘==’ one looks very sus­pi­cious). Don’t copy it, read Bill’s book in­stead

   • Defining an im­mutable ob­ject with a C# class in­volves dis­ci­pline in not chang­ing the pri­vate state (we’ll see in Part II that we can do bet­ter than ‘discipline’)

     • Notice the ex­ten­sion method IsSuperSet. This is some­thing I picked up from an old Coplien book, prob­a­bly this one. The con­cept is to keep meth­ods that don’t use in­ter­nal state of an ob­ject ex­ter­nal to the ob­ject it­self for the sake of fu­ture main­tain­abil­ity. The syn­tax for do­ing that was awk­ward be­fore, but ex­ten­sion meth­ods make it eas­ier

This works (it passes all the tests), but it has a num­ber of prob­lems. We’ll talk about these in Part II.

TimeLineAsClass - 1.zip