Weaving Software with Patterns

I have many “favorite” F# features, but my favorite favorite is pattern matching! Perhaps this is because it’s the feature that takes us furthest away from Object-Oriented coding, letting us truly differentiate from legacy coding patterns. Another nice aspect is how unexpectedly pervasive it can be in well-factored code bases. Prepare to be surprised at the places where you can use pattern matching to simplify and beautify your code. But also be prepared to exercise some restraint in using your newfound superpower. Pattern matching can be overdone.

Because pattern matching tends to be completely new, conceptually, to many developers, I’m going to be more gradual in my explanations than I have been in other chapters of this intermediate book. I’ll start with the very basics.

Pattern Matching Basics

This is explicit pattern matching – that is, we are using the match keyword – and it’s super clear what is going on.

Using pattern matching to match on integer literals like this is a bit like using an expensive torque wrench as a hammer, but even here there are some surprising goodies to be had. Try commenting out the bottom line in Listing 6-2. You’ll get a compiler warning saying “Incomplete pattern matches on this expression. For example, the value '0' may indicate a case not covered by the pattern(s).” The F# compiler checks, at the type level, whether a value that isn’t covered by the listed cases could conceivably be passed in. And just in case you don’t believe it, it gives you an example! I can’t tell you how many times that feature alone has saved my bacon. Incidentally, it’s a good habit to have no warnings in your F# code or even to turn on the “warnings as errors” setting in your development/build environment. F# warnings are almost always pointing you to a genuine weakness in your code, and “Incomplete pattern matches” warnings are the best example of this.

I love how layout and syntax work together here so that you can run your eye down the code and spot anomalies and special cases at a glance. The code is almost a diagram of what you want to happen.

Using the as x construct means that an identifier of the appropriate type, called x (or whatever you want to label it), is bound with the value that matched. The scope of this identifier is limited to the code that’s executed as a result of the match. In the code of other cases, and outside the match expression, it has no meaning.¹

I like to think of a match expression as a kind of time travel, allowing you to go back and get the value that must have been assigned for this case to have matched.

When Guards

Pattern Matching on Arrays and Lists

This process of recovering the constituents of a structured type is often called decomposition .

Here, the first two cases are pretty much as Listing 6-6, except we use list brackets [] instead of “array clamps” [||]. The next case uses a cons operator ::. When constructing a list, you can use the cons operator to join a single element onto the beginning of a list (e.g., "One fish" :: [ "Two fish"; "Red fish" ]). But here we are using it in the opposite direction – to recover the first element and all subsequent elements (if any) from an existing list. (You can see now why I referred to pattern matching as a form of time travel: the :: operator works both forwards in time to compose and backwards in time to decompose. You can also think of this as the :: operator being “inverted.”)

In Listing 6-7, I’ve used the identifiers head and tail in the cons case, that is, head::tail. I normally use the names head and tail in cons matching, regardless of the business meanings of the particular values in question. (The alternative in this case might have been something like firstFish::otherFishes.) This is one of those conventions, like using acc and elem in fold functions, which helps your mind recognize common idioms with as little cognitive overhead as possible and saves you from some unnecessary decision-making.

You might want to experiment a bit to prove what I said about the possibility of the tail containing zero elements. Comment out the | [ fish ] -> case from Listing 6-7 and its following printf line. What do you expect to happen when you send list1 into the match expression? Were you right?

Finally, you might have noticed that although the individual “ponds” in Listing 6-7 are of type List<string>, the demonstration in the last two lines makes an array of those lists and uses Array.map to process them. I could just as well have used a list of lists, but it’s also absolutely fine to mix collections as I have done here.

Pattern Matching on Tuples

Pattern Matching on Records

In Listing 6-10, we pull Title out of the record and ignore Artist. (You aren’t obliged to use Artist = _ to do this; you can just omit the fields you aren’t interested in.). The syntax is a little confusing at first because Title = title looks almost like an assignment but written backward, given that it is title (on the right) that receives the value.

There are more concise ways to achieve what we did in Listing 6-10 (e.g., Seq.map (fun song -> song.Title)) – but it’s worth getting used to record matching in the context of a match expression, as it’ll make things easier to understand when we start to discover record matching in other constructs. In fact, let’s jump ahead a bit and look at one example of pattern matching on records without a match expression.

The magic happens in the parameter list of formatMenuItem, where we say ( { Title = title; Artist = artist } ). This will cause values called title and artist to be bound with the relevant fields’ values from a Track instance, and they will be available within the function body. Other fields from the record are ignored. See how the Seq.map near the bottom of the listing can send in whole Track instances.

You could argue that this technique offers a whole new paradigm of parameter declaration: an alternative to both the curried style, where you just list the parameters with spaces, meaning the caller can populate as many as it feels like; and the tupled style, where the caller must supply values for all parameters. In this new paradigm, the caller must supply a whole record instance, but the callee only sees some of the values. It can be very useful, but it’s a trick to use sparingly. I’ve come across it in my own code and been confused by it!

Pattern Matching on Discriminated Unions

It’s time for the yin of pattern matching to meet its yang, in the form of Discriminated Unions. A Discriminated Union (DU) is a type that has several labeled cases, each of which may have an associated payload of any type. The payload type associated with each case can be different. Multiple types can be put into the payload of a DU case simply by tupling them together or using another complex type such as a class or record.

I suspect there is a reason for this: here, the decomposition isn’t quite the “opposite” of the composition because in the decomposition, you can legitimately omit some of the items from the payload. For example, if you just wanted to pull out the day reading, you could use the match case | Economy7(Day=day) -> ....

You will see code like Listing 6-13 much more often, but I prefer the style of Listing 6-12 if there is any possibility of confusion between the elements of a DU payload, or if the nature of the payload isn’t immediately obvious from context. Remember: motivational transparency !

Another alternative to labeling the payload elements is to have the payload as a whole be a type with some structure, for example, a record type. Thus, the field labels or member names make the code self-documenting, taking the place of the payload element labels. Using a “proper” type is obviously a less minimalist approach than simply having labels in the DU payload (and generally I like minimalism), but obviously, it has benefits if you have broader uses for the type anyway.

Pattern Matching on DUs in Function Parameters

Note how, as in Listing 6-12, I’ve opted to label the two components of the payload tuple, as it is rather critical we don’t mix up the real and imaginary components! The key new concept here is the add function , where I’ve done pattern matching in the parameter declaration to pull out the actual values we need for the computation. In the body of the add function, we simply construct a new Complex instance , doing the necessary computation at the same time. Once again, we use the slightly odd semicolon-based syntax at the decomposition stage, even though we compose the instances using commas.

Exactly as with records, this technique can be useful in certain circumstances. But it is a double-edged sword in terms of readability, particularly for nonadvanced maintainers of your code. I would say I’ve regretted using single-case DUs in the manner outlined in Listing 6-14 about as often as I’ve been pleased with the results.

This immediately causes a compiler warning where the add function is declared because the function only handles one of the two DU cases that could be sent to it. Never ignore this kind of warning: if the DU truly needs to have multiple cases, you will have to refactor any code that uses it to handle all the cases. Failing to do so will undermine the whole edifice of type safety that using F# lets you construct.

Leaving aside whether this is a mathematically valid operation, this really isn’t terribly readable, and I struggle to think of a good reason to do it, except perhaps in rather specialized code.

Pattern Matching in Let Bindings

Note that when using labels like this, you must use a semicolon separator rather than a comma, as we saw earlier.

As I said in the previous section, the times where it is useful and advisable to do this are fairly rare.

Pattern matching in let bindings is a really useful trick once you get used to it. But do bear in mind the readability implications based on the skill level of your collaborators. Don’t do it just to look clever!

Revisiting Single-Case Discriminated Unions

Parts of Listing 6-19 will already be familiar to you: we use a Single-Case DU to carry a payload value, we place the type inside a module named after the DU, and we make its case (also called Heading) private – which makes it impossible to bypass validation by creating an instance directly. For a (potential) performance gain, we mark the DU with the [<Struct>] attribute. Finally, we provide a create function to do instantiation. In Chapter 2, we used a create function to both validate and instantiate, but here we clean and instantiate: values outside the range 0.0…359.99… are automatically wrapped around. Wrapping values above 360.0 is easy – we can use the modulus operator %. Wrapping values below 0.0 requires recursively adding 360.0 until the value is brought into range. There are probably more mathematical ways to achieve this, but I quite like the elegance of the recursion. We have to mark the create function as recursive by saying let rec instead of just let.

Pattern Matching in Loops and Lambdas

In Listing 6-21, we make a list of tuples and then iterate over it in both a for-loop and a higher-order function style. In both cases, a pattern match in the form of (name, count) lets us recover the values from the tuple, for use in the body code.

You can also do this with Record Types, and there’s an exercise showing that at the end of the chapter. And you can do it with Discriminated Unions, though normally only when they are single case.

Pattern Matching and Enums

Here, the DU FileMode can take one of four explicit values, each of which is associated with a bit pattern (000, 001, 010, and 100). We can use the HasFlag property (which is added for us because we used the Flags attribute) to check whether an instance has a particular bit set, regardless of the other bits. We can also bitwise-OR two instances together, using the ^^^ operator.

Because it makes a hole in type safety, I always avoid using enum DUs except in very specific scenarios, typically those involving language interop.

Active Patterns

Pattern matching and Discriminated Unions are exciting enough, but there’s more! Active Patterns let you exploit the syntactical infrastructure that exists to support pattern matching, by building your own mapping between values and cases. Once again, because this is a somewhat advanced feature, I’m going to explain Active Patterns from the very beginning. Then we can discuss their stylistic implications.

Pattern Matching with “&”

In Listing 6-30, we have two Active Patterns, a PostCode one that validates UK postcodes and an OuterLondon one that checks whether a postcode has one of the defined prefixes (and also returns which prefix matched). In the promotionAvailable function, we use & to match on both PostCode and OuterLondon for the main switching logic.

Incidentally, it might look as though PostCode and OuterLondon would each be called twice for each input string, but this is not the case. The code is more efficient than it appears at first glance.

Pattern Matching on Types

Occasionally, even functional programmers have to deal with type hierarchies! Sometimes, it’s because we are interacting with external libraries like System.Windows.Forms, which make extensive use of inheritance. Sometimes, it’s because inheritance is genuinely the best way to model something, even in F#. Whatever the reason, this can place us in a position where we need to detect whether an instance is of a particular type or is of a descendent of that type. You won’t be surprised to learn that F# achieves this using pattern matching.

With this little hierarchy in place, we define a list called people and put both alice and bob into the list. Because collections require elements to all be the same type, we must shoehorn (upcast) bob back into a plain old Person. Then when we iterate over the list, we must use pattern matching to identify whether each element is “really” a Child, using the :? operator, or is just a Person. I use a wildcard pattern “_” to cover the Person case; otherwise, I will get a compiler warning. This is because the operation “:? Person” is redundant, since all the elements are of type Person.

Pattern matching on types is indispensable when dealing with type hierarchies in F#, and I use it unhesitatingly when hierarchies crop up.

Pattern Matching on Null

How do you choose between these alternatives? On stylistic grounds, I prefer the original version (Listing 6-32) because – at least for code that is going to be maintained by people with strong F# skills – sticking everywhere to functions from the Option module feels more consistent. But there’s no doubt that the new version (Listing 6-33) is slightly more concise and more likely to be readable to maintainers who are earlier in their F# journey. You might also want to experiment with performance in your use case, since it looks as though the null-matching version creates no intermediate values and may therefore allocate/deallocate less memory. In performance-critical code, this could make quite a difference.

Recommendations

Summary

If you aren’t pattern matching heavily, you aren’t writing good F# code. Remember that you can pattern match explicitly using the match keyword , but you can also pattern match in let bindings, loops, lambdas, and function declarations. Active Patterns add a whole new layer of power, letting you map from somewhat open-ended data like strings or floating-point values to much more strongly typed classifications.

But pattern matching can be overdone, leading to code that is unreadable to collaborators who may not be experienced in F#. Doing this violates the principle of motivational transparency.

In the next chapter, we’ll look more closely at F#’s primary mechanism for storing groups of labeled values: record types.

Exercises

Exercise Solutions

This section shows solutions for the exercises in this chapter.