boustrophedonic

Implementing Tic-Tac-Toe using state classes

2012-10-25T12:00:00+01:00

This post follows on from the previous one on union types, by showing how to use state classes to implement a Tic-Tac-Toe game (a.k.a. Noughts and Crosses here in the UK).

Background

I ran across two mentions of the game of Tic-Tac-Toe recently. First, in the excellent book “Professional Enterprise .NET” by Jon Arking and Scott Millett, chapter 4 describes using TDD for Tic-Tac-Toe.

Secondly, Tony Morris wrote a post a while back that he almost called “What to Solve Before Expecting Me to Take Your Opinions of Static Typing Seriously” in which he describes his disappointment that most programmers couldn’t implement a robust API for a trivial game like Tic-Tac-Toe.

An extremely robust API for a relatively trivial problem … was achieved by exploiting techniques available from static typing and functional programming.
[This] appears to be difficult for many programmers to reproduce.
Tony Morris Understanding Practical API Design

Here is a paraphase of some of his requirements for the API:

If you write a function, I must be able to call it with the same arguments and always get the same results.
If I, as a client of your API, call one of your functions, I should always get a sensible result. Not null or an exception, etc.
If I call Move on a tic-tac-toe board, but the game has finished, I should get a compile-time error. In other words, calling move on inappropriate game states is disallowed by the types themselves.
If I call WhoWonOrDraw on a tic-tac-toe board, but the game hasn’t yet finished, I get a compile-time error.
It is not possible to play out of turn.

So, before reading on, think about how you might do this in C# – can you meet the challenge!

Tests vs static typing

Unit tests were championed by users of dynamic languages such as Smalltalk and Ruby, but C# is statically typed, so surely we can take advantage of this to write fewer tests?

The answer is yes! With a bit of work, you can use the type system to provide you with “compile time unit tests” as it were.

Unfortunately, a typical C# implementation does not take full advantage of the power of static types and therefore does not meet the requirements above. A typical C# (or Java) implementation will have just a single class to represent all the states of the game, with various internal flags, and lots of branching logic. So then of course you need tests to ensure that the code is robust.

_{[Note: I’m not talking about TDD as a process to drive design, but unit tests as a robustness and code coverage tool.]}

For example, in the Professional Enterprise .NET book, the code for a move looks something like:

public void PlaceMarkerAt(Row row, Column column)
{
    if (CanPlaceMarkerAt(row, column))
    {
        // check that slot is not occupied
        ChangeCurrentPlayer();
    }
    else
    {
        throw new ApplicationException(...)
    }
}

And the code for checking the status looks something like this:

public GameStatus Status()
{
    GameStatus gameStatus;

    if (IsAWinner(Player.O))
        gameStatus = GameStatus.PlayerOWins;
    else if (IsAWinner(Player.X))
        gameStatus = GameStatus.PlayerXWins;
    else if (GameIsADraw())
        gameStatus = GameStatus.GameDrawn;
    else if (WhoseTurn() == Player.X)
        gameStatus = GameStatus.AwaitingPlayerXToPlaceMarker;
    else
        gameStatus = GameStatus.AwaitingPlayerOToPlaceMarker;

    return gameStatus;
}

I’m not picking on this book at all – as I said, it is a great book – but it does demonstrate that even best-practice C# code is not maximally benefiting from the type system. Almost every method has (potentially buggy) conditionals and switches which would be unneeded if states were used.

The Tic-Tac-Toe implementation

So, enough talk, how can you create an API for Tic-Tac-Toe that makes Tony Morris happy?

The trick is to create distinct classes for each state in the game, as discussed in the previous post. We’re going to use the template class demonstrated in that post, but you could always create the code by hand.

First, create an IGameState.tt file to generate the interface and the states. In this implementation, we’ll only create three states: GameStateXToMove, GameStateOToMove, and GameStateGameOver.

Here’s the file:

<#
var states = new [] {"GameStateXToMove", "GameStateOToMove","GameStateGameOver"};
#>
<#@ include file="..\FoldStates.ttinclude" #>

And here’s the generated code:

partial interface IGameState
{
    IGameState Transition(
        Func<GameStateXToMove, IGameState> gameStateXToMove,
        Func<GameStateOToMove, IGameState> gameStateOToMove,
        Func<GameStateGameOver, IGameState> gameStateGameOver
        );

    void Action(
        Action<GameStateXToMove> gameStateXToMove,
        Action<GameStateOToMove> gameStateOToMove,
        Action<GameStateGameOver> gameStateGameOver
        );

    TObject Func<TObject>(
        Func<GameStateXToMove, TObject> gameStateXToMove,
        Func<GameStateOToMove, TObject> gameStateOToMove,
        Func<GameStateGameOver, TObject> gameStateGameOver
        );
}

partial class GameStateXToMove : IGameState
{
    IGameState IGameState.Transition(Func<GameStateXToMove, IGameState> gameStateXToMove, Func<GameStateOToMove, IGameState> gameStateOToMove, Func<GameStateGameOver, IGameState> gameStateGameOver)
    {
        return gameStateXToMove(this);
    }

    void IGameState.Action(Action<GameStateXToMove> gameStateXToMove, Action<GameStateOToMove> gameStateOToMove, Action<GameStateGameOver> gameStateGameOver)
    {
        gameStateXToMove(this);
    }

    TObject IGameState.Func<TObject>(Func<GameStateXToMove, TObject> gameStateXToMove, Func<GameStateOToMove, TObject> gameStateOToMove, Func<GameStateGameOver, TObject> gameStateGameOver)
    {
        return gameStateXToMove(this);
    }
}

partial class GameStateOToMove : IGameState
{
    IGameState IGameState.Transition(Func<GameStateXToMove, IGameState> gameStateXToMove, Func<GameStateOToMove, IGameState> gameStateOToMove, Func<GameStateGameOver, IGameState> gameStateGameOver)
    {
        return gameStateOToMove(this);
    }

    void IGameState.Action(Action<GameStateXToMove> gameStateXToMove, Action<GameStateOToMove> gameStateOToMove, Action<GameStateGameOver> gameStateGameOver)
    {
        gameStateOToMove(this);
    }

    TObject IGameState.Func<TObject>(Func<GameStateXToMove, TObject> gameStateXToMove, Func<GameStateOToMove, TObject> gameStateOToMove, Func<GameStateGameOver, TObject> gameStateGameOver)
    {
        return gameStateOToMove(this);
    }
}

partial class GameStateGameOver : IGameState
{
    IGameState IGameState.Transition(Func<GameStateXToMove, IGameState> gameStateXToMove, Func<GameStateOToMove, IGameState> gameStateOToMove, Func<GameStateGameOver, IGameState> gameStateGameOver)
    {
        return gameStateGameOver(this);
    }

    void IGameState.Action(Action<GameStateXToMove> gameStateXToMove, Action<GameStateOToMove> gameStateOToMove, Action<GameStateGameOver> gameStateGameOver)
    {
        gameStateGameOver(this);
    }

    TObject IGameState.Func<TObject>(Func<GameStateXToMove, TObject> gameStateXToMove, Func<GameStateOToMove, TObject> gameStateOToMove, Func<GameStateGameOver, TObject> gameStateGameOver)
    {
        return gameStateGameOver(this);
    }
}

Extending the IGameState interface

Next, we’ll add to the partial interface in a separate file (IGameState.cs):

public partial interface IGameState
{
    bool IsValidMove(Row row, Col col);
}

We’ll add one method (IsValidMove) that is common to all states. Note what is missing though. There is is no Move method or WhoWonOrDraw method. These will be reserved for the state classes.

The GameStateXToMove class

Now let’s look at the code needed for the first state: GameStateXToMove:

public partial class GameStateXToMove : GameStateBase
{
    internal GameStateXToMove()
        : base(new MoveSequence())
    {
    }

    internal GameStateXToMove(MoveSequence moveSequence)
        : base(moveSequence)
    {
    }

    public IGameState Move(Row row, Col col, Action<Move> invalidMoveCallback)
    {
        var move = new Move(row, col, Player.X);
        var newMoveSequence = MoveSequence.WithNewMove(move, invalidMoveCallback);
        return newMoveSequence.IsGameOver()
            ? new GameStateGameOver(newMoveSequence)
            : new GameStateOToMove(newMoveSequence) as IGameState;
    }

    bool IGameState.IsValidMove(Row row, Col col)
    {
        return MoveSequence.IsValidMove(row, col);
    }
}

This class inherits from GameStateBase, which stores a MoveSequence that is common to all three states. The MoveSequence has the intelligence to know which moves are valid and when the game is over. The two constructors initialize the class with either an empty MoveSequence, or a non-empty one.

The Move method exists only in the GameStateXToMove and GameStateOToMove classes. It creates a new move, then appends that it the current MoveSequence, and then creates a new state depending on whether the game is over. If the game is over, the new state is GameStateGameOver, otherwise it is Player O’s turn (GameStateOToMove). Because two different states could be returned, the overall return type must be IGameState, not any particular state.

What happens if the move is invalid? Should we ignore it, throw an exception, or what? This code can’t (and shouldn’t) decide, so the action has been delegated back to the called. In this case, the move sequence is left unchanged – MoveSequence.WithNewMove returns the same list. Again, this is one of the requirements – no unexpected exceptions!

Finally, the IsValidMove method delegates to the MoveSequence. I have deliberately made this an explicit interface implementation so that the methods common to all game states are separate from the state-specific methods.

The GameStateOToMove class

The code for the GameStateOToMove is almost identical, except that in the Move method, the next state is GameStateXToMove, if the game is not over.

public partial class GameStateOToMove : GameStateBase
{
    internal GameStateOToMove()
        : base(new MoveSequence())
    {
    }

    internal GameStateOToMove(MoveSequence moveSequence)
        : base(moveSequence)
    {
    }

    public IGameState Move(Row row, Col col, Action<Move> invalidMoveCallback)
    {
        var move = new Move(row, col, Player.O);
        var newMoveSequence = MoveSequence.WithNewMove(move, invalidMoveCallback);
        return newMoveSequence.IsGameOver()
            ? new GameStateGameOver(newMoveSequence)
            : new GameStateXToMove(newMoveSequence) as IGameState;
    }

    bool IGameState.IsValidMove(Row row, Col col)
    {
        return MoveSequence.IsValidMove(row, col);
    }
}

The GameStateGameOver class

The code for the GameStateGameOver is quite different. It does not implement Move and it does implement WhoWonOrDraw.

public enum GameOverState
{
    XWon, YWon, Draw
}

public partial class GameStateGameOver : GameStateBase
{
    internal GameStateGameOver(MoveSequence moveSequence)
        : base(moveSequence)
    {
    }

    public GameOverState WhoWonOrDraw()
    {
        return MoveSequence.WhoWonOrDraw();
    }

    bool IGameState.IsValidMove(Row row, Col col)
    {
        return false;
    }
}

It can also return false for IsValidMove without even looking at the MoveSequence.

This code is a good example of how the number of conditionals is greatly reduced. Because this class only deals with one state, there are no conditionals at all!

If you think about trying to get 100% code coverage for tests, every conditional doubles the number of code paths to test! So avoiding them has multiple benefits – it makes the code more compact, more readable, less buggy and easier to test thoroughly.

Testing the code

Let’s look at how this code might be tested.

Test: “Player X is the first Player to place a marker.”

The TicTacToeGame wrapper class simply returns a new GameStateXToMove when a new game is started. Then to test which state we are in, we use the Func method, with a lambda for each case.

[Test]
public void PlayerXIsTheFirstPlayerToPlaceAMarker()
{
    var initialState = TicTacToeGame.StartNewGame();
    var isXToPlay = initialState.Func(
        xToMove => true,
        oToMove => false,
        gameOver => false);
    Assert.That(isXToPlay, Is.True);
}

Here’s another test:

Test: “Player O Will Be Next To Take A Turn After Player X Has Placed A Marker”

[Test]
public void PlayerOWillBeNextToTakeATurnAfterPlayerXHasPlacedAMarker()
{
    var initialState = TicTacToeGame.StartNewGame();
    Action<Move> invalidMoveAction = move => Console.WriteLine("The move {0} is not allowed", move);

    // X plays
    var afterFirstMove = initialState.Transition(
        xToMove => xToMove.Move(Row.Row1, Col.Col1, invalidMoveAction),
        oToMove => oToMove,
        gameOver => gameOver);

    var isOToPlay = afterFirstMove.Func(xToMove => false, oToMove => true, gameOver => false);
    Assert.That(isOToPlay, Is.True);
}

Again, a similar technique is used to find out which state we are in.

We can go on like this in a similar vein. Let’s skip to what happens when the game is over:

Test: “If Player X gets three Xs in a row, then the game is won by Player X.”

[Test]
public void IfPlayerXGetsThreeXsInARowThenTheGameIsWonByPlayerX()
{
    var initialState = TicTacToeGame.StartNewGame();
    Action<Move> invalidMoveAction = move => Console.WriteLine("The move {0} is not allowed", move);

    // X plays
    var move1 = initialState.Transition(
        xToMove => xToMove.Move(Row.Row1, Col.Col1, invalidMoveAction),
        oToMove => oToMove,
        gameOver => gameOver);

    // O plays
    var move2 = move1.Transition(
        xToMove => xToMove,
        oToMove => oToMove.Move(Row.Row2, Col.Col1, invalidMoveAction),
        gameOver => gameOver);

    // X plays
    var move3 = move2.Transition(
        xToMove => xToMove.Move(Row.Row1, Col.Col2, invalidMoveAction),
        oToMove => oToMove,
        gameOver => gameOver);

    // O plays
    var move4 = move3.Transition(
        xToMove => xToMove,
        oToMove => oToMove.Move(Row.Row2, Col.Col2, invalidMoveAction),
        gameOver => gameOver);

    // X plays and wins
    var move5 = move4.Transition(
        xToMove => xToMove.Move(Row.Row1, Col.Col3, invalidMoveAction),
        oToMove => oToMove,
        gameOver => gameOver);

    var isGameOver = move5.Func(xToMove => false, oToMove => false, gameOver => true);
    Assert.IsTrue(isGameOver);

    GameOverState? whoWon = null;
    move5.Action(
        xToMove => { },
        oToMove => { },
        gameOver => whoWon = gameOver.WhoWonOrDraw());
    Assert.That(whoWon, Is.EqualTo(GameOverState.XWon));

}

Summary

Looking back at the requirements, did we meet them?

Call a function with the same arguments and always get the same results. Check! The states are immutable.
A client of your API, calling one of your functions, should always get a sensible result. Check! No nulls or exceptions anywhere in the code.
If I call Move but the game has finished, I should get a compile-time error. Check! Try it:

var move5 = move4.Transition(
    xToMove => xToMove.Move(Row.Row1, Col.Col3, invalidMoveAction),
    oToMove => oToMove,
    gameOver => gameOver.Move(Row.Row1, Col.Col3, invalidMoveAction));  // compile time error!

If I call WhoWonOrDraw on a tic-tac-toe board, but the game hasn’t yet finished, I get a compile-time error. Check again! Try it:

move5.Action(
    xToMove => whoWon = xToMove.WhoWonOrDraw(), // compile time error
    oToMove => { },
    gameOver => whoWon = gameOver.WhoWonOrDraw());

It is not possible to play out of turn. Check! If the state is GameStateXToMove then only X can move. The types will not allow player O to move.

So all in all, a nice solution to a thorny problem.

Getting the code

You can get the code from the git repository for this blog (see the about page). This has a full set of examples and unit tests.

Union types in C#

2012-10-21T12:00:00+01:00

This post shows how to easily implement states in C# using a T4 template.

Background

I often run into situations where I need an object that has a number of alternate “states” or “choices”. The set of states must be treated as “one thing” for general manipulation, but on the other hand, each state will often have slightly different behavior from the other states.

Some examples:

A shopping cart might have states Empty, Active and Paid.
- You can call “AddItem” but not “RemoveItem” on the Empty state
- You can call “AddItem” and “RemoveItem” and also “Pay” on the Active state
- You can’t do anything with the Paid state. Once paid, the cart is immutable.
A domain object such as Product might have states Valid and Invalid.
- Only Valid objects can be saved to disk.
A game such as chess might have states WhiteToPlay, BlackToPlay and GameOver.
- Only the GameOver state has a “Winner” method.
- Only the other states have a “Play” method.

So given this common situation, what kinds of ways are there to implement these kinds of cases?

The inheritance based approach

The standard approach in a object-oriented language is to use inheritance. There is a class for each state, and each state inherits from a common base class or interface.

But where should the custom behavior live?

For example, in the shopping cart example, should the “RemoveItem” method be available at the interface level?

Approach 1: Define all possible actions at the interface level

Let’s say the “RemoveItem” method is available at the interface level, then the interface would look like this:

interface ICartState
{
    ICartState AddItem(Product product);
    ICartState RemoveItem(Product product);
    ICartState Pay(decimal amount);
}

But what should the empty state implementation do with the methods that are not relevant? It can either throw an exception or ignore them, as shown below.

class CartStateEmpty : ICartState
{
    public ICartState AddItem(Product product)
    {
        // implementation
    }

    public ICartState RemoveItem(Product product)
    {
        // throw not implemented exception or ignore
    }

    public ICartState Pay(decimal amount)
    {
        // throw not implemented exception or ignore
    }
}

Throwing an exception seems a bit drastic, and ignoring the call seems even worse. Is there another approach?

Approach 2: Define actions only at the appropriate level

The next approach is that the base interface should only have genuinely common code, and each subclass implements its own special behavior.

So the code for the shopping cart would look something like this:

interface ICartState
{
    // nothing in common between the states
}

class CartStateEmpty : ICartState
{
    public ICartState AddItem(Product product)
    {
        // implementation
    }
}

class CartStateActive : ICartState
{
    public ICartState AddItem(Product product) {} // implementation

    public ICartState RemoveItem(Product product) {} // implementation

    public ICartState  Pay(decimal amount) {} // implementation 
}

class CartStatePaid : ICartState
{
    public decimal GetAmountPaid() {} // implementation 
}

This is much cleaner, but now the question is: how does the client know which state the cart is in?

Typically, the caller would have to try downcasting the object to each state in turn. The client code would look something like this:

private class CientWithDowncasting
{
    public ICartState AddProduct(ICartState currentState, Product product)
    {
        var cartStateEmpty = currentState as CartStateEmpty; //CAST!
        if (cartStateEmpty != null)
        {
            return cartStateEmpty.AddItem(Product.ProductY);
        }

        var cartStateActive = currentState as CartStateActive; //CAST!
        if (cartStateActive != null)
        {
            return cartStateActive.AddItem(Product.ProductY);
        }

        // paid state -- do nothing    
        return currentState;
    }
}

But this approach is not only ugly, it’s all error prone, as the client has to do all the work.

For example, what happens if the client forgets to cast properly? And what happens if the requirements change and there are now four states to handle? These kinds of errors will be hard to catch.

Approach 3: The double dispatch or visitor pattern

In OO design, a reliance on this kind of branching and casting for control flow is always a sign that polymorphism is not being used properly. And indeed there is a way to avoid downcasting by using so-called “double dispatch” or its big brother, the visitor pattern.

The idea behind it is that the caller does not know the type of the state, but the state knows its own type, and can call back a type-specific method on the caller. For example, the empty state can call a “VisitEmpty” method, while the active state can call a “VisitActive” method, and so on. In this way, no casting is used. Furthermore, if the number of states increase, the code will break until a handler for the new state is implemented.

To use this approach, first we implement a visitor interface as follows:

interface ICartStateVisitor
{
    ICartState VisitEmpty(CartStateEmpty empty);
    ICartState VisitActive(CartStateActive active);
    ICartState VisitPaid(CartStatePaid paid);
}

Next we change the base interface to allow the visitor to call on the state:

interface ICartState
{
    ICartState Accept(ICartStateVisitor visitor);
}

Finally, for each state, we implement the appropriate VisitXXX method:

class CartStateEmpty : ICartState
{
    public ICartState Accept(ICartStateVisitor visitor)
    {
        return visitor.VisitEmpty(this);
    }
}

class CartStateActive : ICartState
{
    public ICartState Accept(ICartStateVisitor visitor)
    {
        return visitor.VisitActive(this);
    }

class CartStatePaid : ICartState
{
    public ICartState Accept(ICartStateVisitor visitor)
    {
        return visitor.VisitPaid(this);
    }
}

Now we are ready to use it – and here is where our problems start! Because, for each different set of visitor behavior, we have to implement a custom class.

For example, when we want to add an item, we have to create an instance of AddProductVisitor and when we want to pay for something, we need to create a PayForCartVisitor.

Here’s some code to show what I mean:

class CientWithVisitor
{
    class AddProductVisitor: ICartStateVisitor
    {
        public Product productToAdd;
        public ICartState VisitEmpty(CartStateEmpty empty) { empty.AddItem(productToAdd); return empty; }
        public ICartState VisitActive(CartStateActive active) { active.AddItem(productToAdd); return active; }
        public ICartState VisitPaid(CartStatePaid paid) { return paid; }
    }

    class PayForCartVisitor : ICartStateVisitor
    {
        public decimal amountToPay;
        public ICartState VisitEmpty(CartStateEmpty empty) { return empty; }
        public ICartState VisitActive(CartStateActive active) { active.Pay(amountToPay); return active; }
        public ICartState VisitPaid(CartStatePaid paid) { return paid; }
    }

    public ICartState AddProduct(ICartState currentState, Product product)
    {
        var visitor = new AddProductVisitor() { productToAdd = product };
        return currentState.Accept(visitor);
    }

    public ICartState Pay(ICartState currentState, decimal amountToPay)
    {
        var visitor = new PayForCartVisitor() { amountToPay = amountToPay };
        return currentState.Accept(visitor);
    }
}

Phew! It does work, and it is polymorphic and type safe. But it seems like an awful lot of scaffolding is needed just to do something straightforward. An interface, two new classes, and nine new methods!

Here’s are all the players visualized as a diagram:

Compared with the second approach, you can see that it is a lot more complicated. And this is a simple example! It reminds me of the ”Kingdom of Nouns”.

Surely there must be another way – combining the simplicity of the second approach with the safeness of the visitor approach?

Algebraic data types and “Sum” types

Let’s step back and see how other languages do it. In some languages, especially functional languages such as Haskell and F#, the type system is not based around classes, but instead is based around mathematics.

The idea is that given a number of smaller types, you can combine them in various ways to make larger, composite types. There are two ways of creating these combinations, “addition” and “multiplication”, and the kinds of types built this way are called “algebraic data types”.

Multiplication of types means taking every possible value of one type and combining it with every possible value of another type. You might already be familiar with this from SQL, because it is similar to a CROSS JOIN. The resulting composite types are called “product” types.

For example a Date type might be created by combining every possible Day value with every possible Month value with every possible Year value . So the type is written Date type = Day type x Month type x Year type.

On the other hand, addition of types means having a set of types and choosing only one value at a time from the union of all of possible values.

For example, we could define a new Temperature type as EITHER one value from the set of temperatures in DegreesF OR one value from the set of temperatures in DegreesC. The resulting composite types are called “sum” or “union” types. So the temperature type is written Temperature type = DegreesF type + DegreesC type.

What does that mean in practice? It means that “sum” types are perfect for modelling situations where there are mutually exclusive states or choices.

In F#, for example, we can create types for each shopping cart state, and then combine (“sum”) them into a composite type. Here’s the F# code:

// three different types, each representing a state
type CartStateEmpty = NoItems
type CartStateActive = { UnpaidItems:Product list; }
type CartStatePaid = { PaidItems:Product list; AmountPaid:decimal}

// then create a new type that combines them all as distinct choices 
type CartState =
    | Empty of CartStateEmpty
    | Active of CartStateActive
    | Paid of CartStatePaid

In F#, a CartState must be one of the possible choices. That is, it can be Empty or Active or Paid, but only one at any one time.

And because of this, it is simple to write code that depends on the particular choice. For example, to add a product to the cart, the client code would look something like this:

let addProductFromCart cart product =
   match cart with
   | Empty state -> state.AddItem product
   | Active state -> state.AddItem product
   | Paid state -> cart // do nothing

You can think of match cart with code as a kind of switch statement that has a different case for each state. Each case is a sort of lambda expression, which in C# would look something like:

(CartStateEmpty state) => state.AddItem(product)
(CartStateActive state) => state.AddItem(product)
(CartStatePaid state) => // do nothing

The particular state that the object is in determines which lambda expression to execute.

Here is the similar code for removing a product from the cart:

let removeProductFromCart cart item =
   match cart with
   | Empty state ->
      printfn "ERROR: The cart is empty"
      cart   // return the cart 
   | Active state ->
      state.Remove item
   | Paid state ->
      printfn "ERROR: The cart is paid for"
      cart   // return the cart

and so on.

For more details on how F# does this, see my post on the F# implementation of a shopping cart.

Implementing choices in C#

The F# code gives us a clue on how we might solve the problem in C#.

The idea is that for each possible state, we pass in a lambda specifically designed for that state. We do this through a single method call. In other words we provide a list of functions but we don’t know which one will actually get evaluated – we let the cart decide, based on its state.

Here is some example code:

partial interface ICartState
{
  ICartState Transition(
        Func<CartStateEmpty, ICartState> cartStateEmpty,
        Func<CartStateActive, ICartState> cartStateActive,
        Func<CartStatePaid, ICartState> cartStatePaid
        );
}
  
class CartStateEmpty : ICartState
{
  ICartState ICartState.Transition(
        Func<CartStateEmpty, ICartState> cartStateEmpty,
        Func<CartStateActive, ICartState> cartStateActive,
        Func<CartStatePaid, ICartState> cartStatePaid
        )
  {
        // I'm the empty state, so invoke cartStateEmpty 
      return cartStateEmpty(this);
  }
}
  
class CartStateActive : ICartState
{
  ICartState ICartState.Transition(
        Func<CartStateEmpty, ICartState> cartStateEmpty,
        Func<CartStateActive, ICartState> cartStateActive,
        Func<CartStatePaid, ICartState> cartStatePaid
        )
  {
        // I'm the active state, so invoke cartStateActive
      return cartStateActive(this);
  }
}
  
class CartStatePaid : ICartState
{
  ICartState ICartState.Transition(
        Func<CartStateEmpty, ICartState> cartStateEmpty,
        Func<CartStateActive, ICartState> cartStateActive,
        Func<CartStatePaid, ICartState> cartStatePaid
        )
  {
        // I'm the paid state, so invoke cartStatePaid
      return cartStatePaid(this);
  }
}

And here is an example of how a client might call it in practice:

public ICartState AddProduct(ICartState currentState, Product product)
{
    return currentState.Transition(
        cartStateEmpty => cartStateEmpty.AddItem(product),
        cartStateActive => cartStateActive.AddItem(product),
        cartStatePaid => cartStatePaid
        );

}

public void Example()
{
    var currentState = new CartStateEmpty() as ICartState;

    //add some products 
    currentState = AddProduct(currentState, Product.ProductX);
    currentState = AddProduct(currentState, Product.ProductY);

    //pay 
    const decimal paidAmount = 12.34m;
    currentState = currentState.Transition(
        cartStateEmpty => cartStateEmpty,
        cartStateActive => cartStateActive.Pay(paidAmount),
        cartStatePaid => cartStatePaid
        );
}

As you can see, this approach solves all the problems discussed earlier:

It is completely idiot proof. A client of the interface always gets a valid value back. The client cannot mess things up by forgetting to cast or forgetting to check for null.
Illegal states are not even representable. A client cannot call the “wrong” method, such as calling “Pay” on an empty cart. The compiler will not allow it. Because of this, there is no need for runtime errors or “not implemented” exceptions.
If the number of states ever changes to four say, just add a new parameter to the Transition method. The Transition method will now take four lambdas, so all your existing code will fail to compile. This a good thing! You cannot accidentally forget to handle a state.
The code is simple and low complexity. Just as in the second approach above, each state only implements the methods it needs to, and there are no if statements or special case handlers anywhere.

In a way, this is what the visitor pattern was trying to get at in its complicated way, but the use of inline lambdas rather than whole visitor classes reduces the complexity immensely.

Introducing the T4 template

Now that we understand how the states work in conjunction with the top level interface, we can create them in C#.

But there is a lot of boilerplate – so I have created a T4 template that generate the states for you automatically.

Creating new types using the T4 template

To setup, first download the FoldStates.ttinclude and add it to your project somewhere.

Then to create a new type:

Create a template file and give the filename the name of the interface type, such as “ICartState.tt”
Include the code below, and define each state that you want in the array, as shown.

<#
var states = new [] {"CartStateEmpty", "CartStateActive","CartStatePaid"};
#>
<#@ include file="..\FoldStates.ttinclude" #>

Visual Studio will then generate you a file with code like this:

partial interface ICartState
{
    ICartState Transition(Func<CartStateEmpty, ICartState> cartStateEmpty, Func<CartStateActive, ICartState> cartStateActive, Func<CartStatePaid, ICartState> cartStatePaid);
    void Action(Action<CartStateEmpty> cartStateEmpty, Action<CartStateActive> cartStateActive, Action<CartStatePaid> cartStatePaid);
    TObject Func<TObject>(Func<CartStateEmpty, TObject> cartStateEmpty, Func<CartStateActive, TObject> cartStateActive, Func<CartStatePaid, TObject> cartStatePaid);
}

partial class CartStateEmpty : ICartState
{
    ICartState ICartState.Transition(Func<CartStateEmpty, ICartState> cartStateEmpty, Func<CartStateActive, ICartState> cartStateActive, Func<CartStatePaid, ICartState> cartStatePaid)
    {
        return cartStateEmpty(this);
    }

    void ICartState.Action(Action<CartStateEmpty> cartStateEmpty, Action<CartStateActive> cartStateActive, Action<CartStatePaid> cartStatePaid)
    {
        cartStateEmpty(this);
    }

    TObject ICartState.Func<TObject>(Func<CartStateEmpty, TObject> cartStateEmpty, Func<CartStateActive, TObject> cartStateActive, Func<CartStatePaid, TObject> cartStatePaid)
    {
        return cartStateEmpty(this);
    }
}

partial class CartStateActive : ICartState
{
    ICartState ICartState.Transition(Func<CartStateEmpty, ICartState> cartStateEmpty, Func<CartStateActive, ICartState> cartStateActive, Func<CartStatePaid, ICartState> cartStatePaid)
    {
        return cartStateActive(this);
    }

    void ICartState.Action(Action<CartStateEmpty> cartStateEmpty, Action<CartStateActive> cartStateActive, Action<CartStatePaid> cartStatePaid)
    {
        cartStateActive(this);
    }

    TObject ICartState.Func<TObject>(Func<CartStateEmpty, TObject> cartStateEmpty, Func<CartStateActive, TObject> cartStateActive, Func<CartStatePaid, TObject> cartStatePaid)
    {
        return cartStateActive(this);
    }
}

partial class CartStatePaid : ICartState
{
    ICartState ICartState.Transition(Func<CartStateEmpty, ICartState> cartStateEmpty, Func<CartStateActive, ICartState> cartStateActive, Func<CartStatePaid, ICartState> cartStatePaid)
    {
        return cartStatePaid(this);
    }

    void ICartState.Action(Action<CartStateEmpty> cartStateEmpty, Action<CartStateActive> cartStateActive, Action<CartStatePaid> cartStatePaid)
    {
        cartStatePaid(this);
    }

    TObject ICartState.Func<TObject>(Func<CartStateEmpty, TObject> cartStateEmpty, Func<CartStateActive, TObject> cartStateActive, Func<CartStatePaid, TObject> cartStatePaid)
    {
        return cartStatePaid(this);
    }
}

Using the new type

A few things to note about the generated code:

There are three generated methods: Transition, Action and Func. I’ll explain the purpose of each one shortly.
All the classes are partial. After creating the states, you should then create separate files for the partial classes so you can write some real code!

For the shopping cart example, let’s look at each state in turn.

The CartStateEmpty state

As described above, you should create a separate file CartStateEmpty.cs and create code like the following:

public partial class CartStateEmpty
{
    internal CartStateEmpty()
    {
    }

    public ICartState Add(Product item)
    {
        var newItems = new[] { item };
        var newState = new CartStateActive(newItems);
        return newState;
    }
}

This state has no items. The only thing you can do with this state is add a product.

To add a product, create a new list of products and pass it into the constructor of the CartStateActive class.

Note that the Add method returns an ICartState not a CartStateActive. This is critical! The caller should not know the exact state of the cart, just that it is some kind of cart. You’ll see why this is so important shortly.

The CartStateActive state

Again, you should create a separate file CartStateActive.cs and create code like the following:

public partial class CartStateActive
{
    public CartStateActive(IEnumerable<Product> items)
    {
        Items = items;
    }

    public IEnumerable<Product> Items { get; private set; }

    public ICartState Add(Product item)
    {
        var newItems = new List<Product>(Items) { item };
        return new CartStateActive(newItems);
    }

    public ICartState Remove(Product item)
    {
        var newItems = new List<Product>(Items);
        newItems.Remove(item);
        return newItems.Count > 0
            ? (ICartState)new CartStateActive(newItems)
            : new CartStateEmpty();
    }

    public ICartState Pay(decimal amount)
    {
        return new CartStatePaid(Items, amount);
    }
}

This state does have a list of items, and supports three methods: Add, Remove, and Pay.

To add a product, create a new list of products and pass it into the constructor of the CartStateActive class. Again note that the Add method returns an ICartState not a CartStateActive.

To remove a product, remove it from the existing list of products and pass either into the constructor of the CartStateActive class, or if the list is empty, return a new CartStateEmpty.
Again note that this method returns an ICartState. The (ICartState) cast is needed to make the ternary expression happy, unfortunately.

Finally, the Pay method creates a CartStatePaid and returns it. Once again, the return type is ICartState.

The CartStatePaid state

Finally, implement CartStatePaid.cs with code like this:

public partial class CartStatePaid
{
    public CartStatePaid(IEnumerable<Product> items, decimal amount)
    {
        Items = items.ToList();
        Amount = amount;
    }

    public IEnumerable<Product> Items { get; private set; }
    public decimal Amount { get; private set; }
}

CartStatePaid is immutable – you can get the list of items and payment amount, but you can’t change them.

Now that you have seen all the implementations, it is worth pointing out another great benefit of this approach. In the implementation for each state, there are hardly any conditionals or branches! You’ll find that this state-based approach really reduces code complexity because each method only has to deal with one state.

Putting it together with some tests.

Lets see how this code can be used in practice.

First, lets start with a simple test case: “If you add a item to an empty cart you get an active cart with one item”.

Here’s the code for this test:

[Test]
public void WhenEmptyCartAndAddItemExpectActiveCartWithOneItem()
{
    var emptyCart = new CartStateEmpty();

    var newState = emptyCart.Add(Product.ProductX);

    var isActiveState = newState.Func(
        cartStateEmpty => false,
        cartStateActive => true,
        cartStatePaid => false
        );
    Assert.IsTrue(isActiveState);

    var itemCount = newState.Func(
        cartStateEmpty => -1,
        cartStateActive => cartStateActive.Items.Count(),
        cartStatePaid => -1
        );
    Assert.That(itemCount, Is.EqualTo(1));
}

You can see here that we are using the Func method and passing in three lambdas. To test what state the cart is in, we return true or false for each lambda. And to count the items, we return a int.

Note that if we had the following code, we would get an compiler error:

var itemCount = newState.Func(
   cartStateEmpty => cartStateEmpty.Items.Count(),
   cartStateActive => cartStateActive.Items.Count(),
   cartStatePaid => cartStatePaid.Items.Count()
   );

The reason is that cartStateEmpty does not have an Items property. This is a key concept – you cannot call a method accidentally using this approach. The caller cannot forget to cast, or forget to handle a state. The interface enforces this.

Let’s look at another test: “If you pay for an active cart you get an paid cart with the same number of items and the same amount paid”.

[Test]
public void WhenActiveCartWithTwoItemsAndPayExpectPaidCart()
{
    var activeCart = new CartStateActive(new[] { Product.ProductX, Product.ProductY });

    const decimal paidAmount = 12.34m;
    var newState = activeCart.Pay(paidAmount);

    var isPaidState = newState.Func(
        cartStateEmpty => false,
        cartStateActive => false,
        cartStatePaid => true
        );
    Assert.IsTrue(isPaidState);

    var itemCount = newState.Func(
        cartStateEmpty => -1,
        cartStateActive => -1,
        cartStatePaid => cartStatePaid.Items.Count()
        );
    Assert.That(itemCount, Is.EqualTo(2));

    var actualPaidAmount = newState.Func(
        cartStateEmpty => -1,
        cartStateActive => -1,
        cartStatePaid => cartStatePaid.Amount
        );
    Assert.That(actualPaidAmount, Is.EqualTo(paidAmount));
}

Note that in the last assertion, we are getting the cartStatePaid.Amount. This property does not exist for the other two states, and as above, if we accidentally try to call it, we will get a compiler error.

So you have seen how the Func method works. The Action method is exactly the same, but returns void instead.

The Transition method

Now let’s look at the Transition method and see how it is used.

Here is the code that adds a product to a cart.

public ICartState AddProduct(ICartState currentState, Product product)
{
    return currentState.Transition(
        cartStateEmpty => cartStateEmpty.Add(product),
        cartStateActive => cartStateActive.Add(product),
        cartStatePaid => cartStatePaid
        );
}

Some things to note:

The input (currentState) is a ICartState because we don’t know what state it will be.
The return type is also a ICartState because we don’t know what the state will be after adding the item. Well, actually we do in this particular case, but generally we won’t. So for example RemoveItem could return either an empty state or an active state.
The input value is not ‘edited in place’ but transformed into a new value. In the state implementations above, you’ll have seen that all the states are immutable. It’s not just a ‘nice-to-have’, but is critical for these kinds of state based transitions.

A particular important point is that all three lambdas return something. In this case, we can call Add for the empty and active states. But what about the paid state? It doesn’t have an Add method!

This is where we are forced to make a choice: we could throw an exception or log an error. But in this case, we will ignore it. We have to return a valid cart, so we can’t return null. Instead, we’ll just return the cart that was passed in.

Now earlier I talked about a similar decision for the empty state – should it throw an exception or silently ignore the problem. There is a big difference however between that case and this one. however. In that case, the decision was inside the empty state’s implementation. The decision would be applicable to all callers.

But in this approach, the decision is up to the caller, not the implementor. It is up to the caller to decide what to do, and it can provide different behavior in different circumstances.

Finally, I hope you can now see why the Add method returned an ICartState rather than a CartStateActive . It is because all the the lambdas must return the same type, and in the case of transition from one state to another, that type will always be ICartState.

Ok, let’s see how Remove and Pay would be implemented:

public ICartState RemoveProduct(ICartState currentState, Product product)
{
    return currentState.Transition(
        cartStateEmpty => cartStateEmpty,
        cartStateActive => cartStateActive.Remove(product),
        cartStatePaid => cartStatePaid
        );
}

public ICartState Pay(ICartState currentState, decimal amount)
{
    return currentState.Transition(
        cartStateEmpty => cartStateEmpty,
        cartStateActive => cartStateActive.Pay(paidAmount),
        cartStatePaid => cartStatePaid
        );
}

Very similar to the AddProduct method, except that in these cases, we can only call methods on the active state.

To see how these methods might be combined together, we might have a set of transitions that looks like this:

[Test]
public void TransitionExample()
{
    var currentState = new CartStateEmpty() as ICartState;

    //add some products from the UI, say
    currentState = AddProduct(currentState, Product.ProductX);
    currentState = AddProduct(currentState, Product.ProductY);
    currentState = RemoveProduct(currentState, Product.ProductY);

    //pay from the UI, say
    const decimal paidAmount = 12.34m;
    currentState = Pay(currentState, Product.ProductY);
}

Another example: Email Addresses

We’ll quickly look at another way these states can be used, namely for handling a domain object that might have distinct ‘valid’ and ‘invalid’ states that mustn’t be mixed up.

Consider an email address. It can valid (conforming to the RFC spec) or invalid. We might want to allow both states in our domain, but on the other hand, only allow valid emails to be sent to.

The IEmailAddress template

We’ll call the common state IEmailAddress. We will use the EmailAddress state to represent any email address, including invalid ones, and the ValidEmailAddress state to mean only valid emails.

So here is the template:

<#
var states = new [] {"EmailAddress", "ValidEmailAddress"};
#>
<#@ include file="..\FoldStates.ttinclude" #>

This generates the same kind of code as we saw for the shopping cart states:

partial interface IEmailAddress
{
    IEmailAddress Transition(Func<EmailAddress, IEmailAddress> emailAddress, Func<ValidEmailAddress, IEmailAddress> validEmailAddress);
    void Action(Action<EmailAddress> emailAddress, Action<ValidEmailAddress> validEmailAddress);
    TObject Func<TObject>(Func<EmailAddress, TObject> emailAddress, Func<ValidEmailAddress, TObject> validEmailAddress);
}

partial class EmailAddress : IEmailAddress
{
    IEmailAddress IEmailAddress.Transition(Func<EmailAddress, IEmailAddress> emailAddress, Func<ValidEmailAddress, IEmailAddress> validEmailAddress)
    {
        return emailAddress(this);
    }

    void IEmailAddress.Action(Action<EmailAddress> emailAddress, Action<ValidEmailAddress> validEmailAddress)
    {
        emailAddress(this);
    }

    TObject IEmailAddress.Func<TObject>(Func<EmailAddress, TObject> emailAddress, Func<ValidEmailAddress, TObject> validEmailAddress)
    {
        return emailAddress(this);
    }
}

partial class ValidEmailAddress : IEmailAddress
{
    IEmailAddress IEmailAddress.Transition(Func<EmailAddress, IEmailAddress> emailAddress, Func<ValidEmailAddress, IEmailAddress> validEmailAddress)
    {
        return validEmailAddress(this);
    }

    void IEmailAddress.Action(Action<EmailAddress> emailAddress, Action<ValidEmailAddress> validEmailAddress)
    {
        validEmailAddress(this);
    }

    TObject IEmailAddress.Func<TObject>(Func<EmailAddress, TObject> emailAddress, Func<ValidEmailAddress, TObject> validEmailAddress)
    {
        return validEmailAddress(this);
    }
}

Implementing the states

We’ll start by adding a property to the interface that both states will have to implement:

public partial interface IEmailAddress
{
    string Address { get; }
}

Next, we’ll implement the general email address.

public partial class EmailAddress
{
    public EmailAddress(string emailAddress)
    {
        Address = emailAddress;
    }

    public string Address { get; protected set; }

    /// 
    /// Create a new email address
    /// 
    static public IEmailAddress New(string emailAddress)
    {
        try
        {
            // do the validation in the ValidEmailAddress itself so that it is impossible to create an invalid one
            return new ValidEmailAddress(emailAddress);
        }
        catch (ArgumentException)
        {
            return new EmailAddress(emailAddress);
        }
    }
}

Note that it implements a static New method that returns either a ValidEmailAddress or a invalid EmailAddress.

Finally, the ValidEmailAddress implementation is:

public partial class ValidEmailAddress
{
    public ValidEmailAddress(string emailAddress)
    {
        // do validation here
        if (string.IsNullOrEmpty(emailAddress) || !emailAddress.Contains("@"))
        {
            throw new ArgumentException("emailAddress");
        }

        Address = emailAddress;
    }

    public string Address { get; protected set; }

    /// 
    /// This method is only available for the ValidEmailAddress
    /// 
    public void SendMessage(string subject)
    {
        var from = "me@example.com";
        Console.WriteLine("To: {0} From: {1} Re: {2}", Address, from, subject);
    }
}

As you can see, only the ValidEmailAddress implements the SendMessage method.

Using the email address

Let’s look at two test cases to see how this works in practice.

Test: If the address does not contain “@”, the address is not valid

[Test]
public void OnCreationWithNoAtSignExpectInvalidAddress()
{
    var email = EmailAddress.New("no at sign");

    var isValid = email.Func(invalid => false, valid => true);
    Assert.IsFalse(isValid);
}

Test: If the address does contain “@”, the address is valid

Yes, the validation is a bit crude!

[Test]
public void OnCreationWithAtSignExpectValidAddress()
{
    var email = EmailAddress.New("x@example.com");

    var isValid = email.Func(invalid => false, valid => true);
    Assert.IsTrue(isValid);
}

Test: You cannot send email to an invalid address

[Test]
public void CannotSendEmailToInvalidAddress()
{
    var email = EmailAddress.New("x@example.com");

    email.Action(
        invalid => { },
        valid => valid.SendMessage("hello")
        );
}

Again, note that you cannot bypass the type safety. What would happen if you attempted to send an email to an invalid address like this:

[Test]
public void CannotSendEmailToInvalidAddress()
{
    var email = EmailAddress.New("x@example.com");

    email.Action(
        invalid => invalid.SendMessage("hello"),
        valid => valid.SendMessage("hello")
        );
}

Try it and see!

Summary

Well, I hope you found this interesting and useful. It’s definitely a different way of thinking if you are not familiar with functional programming.

BTW, you might be wondering why the template is called “FoldStates”. The answer is that this technique of having a different function for each case is more generally called a ”fold” (or catamorphism if you want to get fancy).

In this example, we have only just touched on the power of folds. In a language like F# that supports recursive data structures, they are a key part of a functional programmers toolbelt.

Getting the code

You can get the code two ways:

Download the template only: FoldStates.ttinclude.
or, from the git repository for this blog (see the about page). This has a full set of examples and unit tests.

Semantic strings in C#

2012-10-20T12:00:00+01:00

This post shows how to easily implement simple types that wrap strings. This approach has a number of benefits:

The types have domain-specific meaning, so Email and ProductCode (say) are distinct value objects in a domain driven design).
The types cannot be mixed, and if they are, you get type errors at compile time, so Email values cannot be accidentally used where a ProductCode is expected.
The code itself can reveal whether absent values are allowed or not. So for example, a Product ProductCode property can never be null (and if you get it wrong you get errors at compile time), but a ProductCode? parameter could be null in the context of a database query .

String wrappers in F#

Learning functional programming (mainly F#) will change the way you think about writing C# code. There are lot of techniques in F# that, once you understand them, can be back-ported to C#.

In F#, for example, it is trivial to create simple one-liner types that represent simple domain value objects. Here’s the F# code:

type EmailAddress = EmailAddress of string
type ProductCode = ProductCode of string
type PhoneNumber = PhoneNumber of string

and so on.

Once created, values of these types are distinct and will cause compile time errors if you accidentally mix them up.

let email = EmailAddress "abc"
let productCode = ProductCode "abc"

// comparison causes error at compile time
let areEqual = (email = productCode)

// assignment causes error at compile time
let anEmail : EmailAddress  = productCode

(By the way, if you have Visual Studio 2010 or higher, you can test this for yourself in the F# interactive window. Just paste the code in and add a double semicolon at the end of each group)

So we get fine grained domain objects, plus extra type safety at compile time. What’s not to like!

String wrappers in C#

This concept is not unique to functional languages. People have recommended the same approach for Java but it still seems controversial to many developers, perhaps because it seems like a lot of work with little obvious benefit.

So is there a way of doing this in C#, while keeping it very simple to use?

One obvious way might be to use the F# libraries from C#, and in fact there is a useful library for doing just that.

But for the special case of these simple string wrappers there is a much simpler way, namely using templates to generate the wrapper types as needed. I have created a T4 template to do just this, and this post will explain how to use it.

Creating new types using the T4 template

To setup, first download the StringWrapper.ttinclude file and add it to your project somewhere.

Then to create a new type:

Create a template file and give the filename the name of the type, such as “CurrencyCode.tt”
Include the code below (I’ll discuss the options shortly)

<#
var options = new { DefaultTransform = "TrimToUpper" };
#>
<#@ include file="..\StringWrapper.ttinclude" #>

Visual Studio will then generate you a file with code like this:

/// 
/// Struct to wrap strings for DDD, to avoid mixing up string types, and to avoid null strings.
/// 
/// 
/// structs cannot inherit, so the code is duplicated for each. 
/// 
[Serializable]
[System.Diagnostics.DebuggerDisplay(@"CurrencyCode[Value]")]
[System.CodeDom.Compiler.GeneratedCodeAttribute("T4Template:StringWrapper.ttinclude","1.0.0")]
public partial struct CurrencyCode : IEquatable<CurrencyCode>, IComparable<CurrencyCode>
{

    public string Value { get; private set; }

    /// 
    /// Create a new struct wrapping a string.
    /// 
    /// The string to wrap. It must not be null.
    /// A function to transform and/or validate the string. 
    /// The unwrapped string is passed into the transform function,  
    /// and the transform should throw an exception or return null if the string is not valid, 
    //  otherwise the transform should convert the string as needed (eg remove spaces, convert to uppercase, etc).
    /// A null transform is ignored.
    /// 
    /// Thrown if the str is null.
    static public CurrencyCode New(string str, Func<string, string> transform)
    {
        if (transform != null) { str = transform(str); }
        if (str == null) { throw new ArgumentException("Input to CurrencyCode is not valid","str"); }

        return new CurrencyCode { Value = str };
    }

    /// 
    /// Create a new struct wrapping a string.
    /// 
    /// The string to wrap. It must not be null.
    /// Thrown if the str is null.
    static public CurrencyCode New(string str)
    {
        Func<string, string> defaultTransform = s => { var trimmed = (s ?? "").Trim(); return trimmed.Length == 0 ? null : trimmed.ToUpper(); };
        return New(str, defaultTransform);
    }

    /// 
    /// Create a new nullable struct wrapping a string, or null if the string is null or invalid.
    /// 
    /// The string to wrap. If is is null or invalid, null is returned.
    /// A function to transform and/or validate the string. 
    /// The unwrapped string is passed into the transform function,  
    /// and the transform should throw an exception or return null if the string is not valid, 
    //  otherwise the transform should convert the string as needed (eg remove spaces, convert to uppercase, etc).
    /// A null transform is ignored.
    /// 
    static public CurrencyCode? NewOption(string str, Func<string,string> transform)
    {
        if (transform != null) { str = transform(str); }
        if (str == null) { return null; }
        return new CurrencyCode { Value = str };
    }

    /// 
    /// Create a new nullable struct wrapping a string, or null if the string is null.
    /// 
    /// The string to wrap. If is is null, null is returned.
    static public CurrencyCode? NewOption(string str)
    {
        Func<string, string> defaultTransform = s => { var trimmed = (s ?? "").Trim(); return trimmed.Length == 0 ? null : trimmed.ToUpper(); };
        return NewOption(str, defaultTransform);
    }

    public override string ToString()
    {
        return Value;
    }

    public override bool Equals(object other)
    {
        return other is CurrencyCode && Equals((CurrencyCode)other);
    }

    public bool Equals(CurrencyCode other)
    {
        return Value.Equals(other.Value, StringComparison.InvariantCulture);
    }

    public override int GetHashCode()
    {
        return Value.GetHashCode();
    }

    public static bool operator ==(CurrencyCode lhs, CurrencyCode rhs)
    {
        return lhs.Equals(rhs);
    }

    public static bool operator !=(CurrencyCode lhs, CurrencyCode rhs)
    {
        return !lhs.Equals(rhs);
    }

    public int CompareTo(CurrencyCode other)
    {
        return String.CompareOrdinal(Value, other.Value);
    }
}

/// 
/// Extensions to convert strings into CurrencyCodes.
/// 
public static class CurrencyCodeStringExtensions
{
    /// 
    /// Create a new struct wrapping a string.
    /// 
    /// The string to wrap. It must not be null.
    /// A function to transform and/or validate the string. 
    /// The unwrapped string is passed into the transform function,  
    /// and the transform should throw an exception or return null if the string is not valid, 
    //  otherwise the transform should convert the string as needed (eg remove spaces, convert to uppercase, etc).
    /// A null transform is ignored.
    /// 
    /// Thrown if the str is null.
    public static CurrencyCode ToCurrencyCode(this string str, Func<string, string> transform)
    {
        return CurrencyCode.New(str, transform);
    }

    /// 
    /// Create a new struct wrapping a string.
    /// 
    /// Thrown if the str is null.
    public static CurrencyCode ToCurrencyCode(this string str)
    {
        return CurrencyCode.New(str);
    }

    /// 
    /// Create a new nullable struct wrapping a string, or null if the string is null or invalid.
    /// 
    /// The string to wrap. If is is null or invalid, null is returned.
    /// A function to transform and/or validate the string. 
    /// The unwrapped string is passed into the transform function,  
    /// and the transform should throw an exception or return null if the string is not valid, 
    //  otherwise the transform should convert the string as needed (eg remove spaces, convert to uppercase, etc).
    /// A null transform is ignored.
    /// 
    public static CurrencyCode? ToCurrencyCodeOption(this string str, Func<string, string> transform)
    {
        return CurrencyCode.NewOption(str, transform);
    }

    /// 
    /// Create a new nullable struct wrapping a string, or null if the string is null.
    /// 
    public static CurrencyCode? ToCurrencyCodeOption(this string str)
    {
        return CurrencyCode.NewOption(str);
    }

}

Here’s a screenshot from Visual Studio:

Using the new type

You can now create instances of this type, either using the static New method, or the helper methods that have been defined.

For example, say that we have a method BuySomething:

void BuySomething(ProductCode productCode, decimal price, CurrencyCode currencyCode)
{
    if (productCode == null) { throw new ArgumentNullException("productCode"); }
    if (currencyCode == null) { throw new ArgumentNullException("currencyCode"); }

    Console.WriteLine("Bought {0} for {1}{2}", productCode, price, currencyCode);
}

We can use it like this:

// usage
var product1 = "product1".ToProductCode();
var usd = "usd".ToCurrencyCode();
BuySomething(product1, 12.34m, usd);

There are a few things to comment on here.

First, the new type is a struct not a class, which means that it cannot be null.
Which in turn means that the null checks that litter most C# code are not needed – you are not allowed to pass nulls as arguments, and you will get a compiler error if you try.

// try with null product
BuySomething(null, 12.34m, usd);

// Result is a compiler error:
// Argument 1: cannot convert from '' to 'ProductCode'    

So BuySomething can be rewritten to be cleaner:

void BuySomething(ProductCode productCode, decimal price, CurrencyCode currencyCode)
{
    Console.WriteLine("Bought {0} for {1}{2}", productCode, price, currencyCode);
}

Second, the compiler’s static type checking will stop you accidentally getting the parameters in the wrong order:

// try with product and currency swapped
BuySomething(usd, 12.34m, product1);

// Result is a compiler error:
// Argument 1: cannot convert from 'CurrencyCode' to 'ProductCode'    
// Argument 3: cannot convert from 'ProductCode' to 'CurrencyCode'    

In one fell swoop you have (a) eliminated code for runtime error-handling code and (b) guaranteed extra levels of correctness. Isn’t that nice.

Transformation and validation

Often, a domain type will have rules about what values are valid for that type. For example example.com would be a valid DomainName but not a valid EmailAddress.

And even if the string is valid, it might need to be transformed into a canonical form, such as being uppercased, or having spaces replaced with hyphens.

The template allows you to customize this transformation and validation by having variants that allow a function or lambda to be passed in. The simple rule is that if the function returns a null, the input is not valid.

So for example, here is a function for email addresses that validates against a regex and lowercases the input if successful:

public partial struct EmailAddress
{
    public static string TransformEmailAddress(string str)
    {
        if (string.IsNullOrWhiteSpace(str))
        {
            return null;
        }

        const string pattern = @"^[A-Z0-9._%-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$";
        if (Regex.IsMatch(str, pattern, RegexOptions.IgnoreCase))
        {
            return str.ToLower();
        }

        //add logging
        //Console.WriteLine("The string '{0}' is not a valid email address", str);
        return null;
    }
}

The generated code is created in a partial struct, so that you can easily add custom behavior like this in a separate file.

You can use this function explictly when creating values:

var e = "BOB@example.com".ToEmailAddress(EmailAddress.TransformEmailAddress);
Assert.AreEqual("bob@example.com", e.ToString());

Or you can use other transforms as well:

var e = "bob@example.com".ToEmailAddress(s => s.Substring(0, 3));
Assert.AreEqual("bob", e.Value);

To set the default transform to use when none is explicitly specified, you set the options in the template file:

<#
var options = new { DefaultTransform = "TransformEmailAddress" };
#>
<#@ include file="..\StringWrapper.ttinclude" #>

The template includes some built-in transforms as well such as “Trim” and “TrimToUpper” which you can set in the same way.

<#
var options = new { DefaultTransform = "TrimToUpper" };
#>
<#@ include file="..\StringWrapper.ttinclude" #>

Optional values

One of the advantages of this approach is that there is a clear distinction between when the value is optional and when it is not.

For example, for an interface to a product database, you might have something like this:

interface IProductRepository
{
    Product GetByCode(ProductCode productCode);

    /// 
    /// Find all matching. Note that productCode and supplierCode are optional but currencyCode is not.
    /// 
    IEnumerable<Product> FindMatchingProducts(ProductCode? productCode, SupplierCode? supplierCode, CurrencyCode currencyCode);
}

By using nullables, the interface itself makes it explicit when the product code is required (for GetByCode) and when it optional (for FindMatchingProducts). And this requirement is enforced by the compiler itself.

To see the importance of this, here is the same interface using strings:

interface IProductRepository
{
    Product GetByCode(string productCode);

    /// 
    /// Find all matching. Note that productCode and supplierCode are optional but currencyCode is not.
    /// 
    IEnumerable<Product> FindMatchingProducts(string productCode, string supplierCode, string currencyCode);
}

With this interface you must look at the comments to know what is required or not – the compiler will not enforce it for you. And if you get it wrong, you will not know immediately, but only at runtime (assuming you added null checking for the required parameters!)

Creating optional values

So how do you go about creating optional values? Simply use the NewOption static method on the struct or the ToXXXOption extension method.

var c = "".ToCurrencyCodeOption();
Assert.IsNull(c);

The same transform and validation functions can be used, but in this case, a failed validation will result in a null value for the type.

var e = "BADSTRING".ToEmailAddressOption();
Assert.IsNull(e);

Using this approach in conjunction with a validation boundary

By wrapping the strings and enforcing validation at creation time, we have shifted the work from the consumers of the type to the creators of the type.

In other words, without using this technique, the implementor has to do all the validation:

// caller code
var emailAddress = "BADSTRING";
EmailService.SendEmail(emailAddress)

// implementors code
class EmailService {
    public void SendEmail(string emailAddress)
    {
        if (emailAddress==null) {throw new ArgumentNullException(...); }
        if (!IsValid(emailAddress)) {throw new ArgumentException(...); }

        // do work
    }

But with this technique, the caller has to do the validation upfront, and the implementation is easier:

// client code
var e = "BADSTRING".ToEmailAddressOption();
if (e != null)
{
    EmailService.SendEmail(emailAddress.Value)
}

// implementors code
class EmailService {
    public void SendEmail(EmailAddress emailAddress)
    {
        // no validation needed

        // do work
    }

So in some sense, we haven’t really eliminated the work, but just moved it somewhere else. This is indeed true. But you might think of this technique as part of a general “validation boundary” approach around the core domain code. Inside the boundary, everything is valid and safe, and outside the boundary it is a wild jungle. When potentially dangerous data from the UI or database comes into the system, the boundary is where the validation occurs, rather than in the core.

So, for example, an MVC web app would create these kinds of wrapped strings in the controller before passing them to the domain model.

A database access or persistence layer would do the same thing, although if the persisted value was invalid on load, you might need to support two different domain types – such as ValidEmailAddress and InvalidEmailAddress. See the related post on union types for an example of how to deal with this.

Issues with this approach

There are a couple concerns that seem to arise when using this approach.

First, it’s not totally idiot proof. You can still create invalid objects if you want to. For example, the following code will create a CurrencyCode with a null string.

var c = new CurrencyCode();

There is not much we can do about this, unfortunately – it’s in the nature of structs. But hopefully this would not happen too often, and overall I prefer the usefulness of having non-null structs to having normal classes.

Second, you might also have performance concerns about using structs rather than classes, as they may need to be boxed and unboxed. In this particular case, I doubt that that much conversion will be happening in practice. But my general response to all concerns about performance is that you should rely on facts rather than assumptions.

For example, in my code that uses this approach, I haven’t seen any performance hits, but if your profiler tells you that the app is slow because of too much boxing and unboxing, then by all means, don’t use this approach. However, I think that in many (if not most) cases the benefits of correct code will outweigh any performance decrease.

Getting the code

You can get the code two ways:

Download the template only: StringWrapper.ttinclude.
or, from the git repository for this blog (see the about page). This has a full set of examples and unit tests.