As already demonstrated, a pattern-match can match against constant values in a manner entirely similar to that of the switch/case construct from any C-family language:

let x = (new System.Random()).Next(5)
let message = match x with
               | 0 -> "zero"
               | 1 -> "one"
               | 2 -> "two"
               | 3 -> "three"
               | 4 -> "four"
               | 5 -> "five"
               | _ -> "Unknown: " + x.ToString()
                                                          

As might well be expected, the match only works if the value stored in x is equal to the value in an individual match clause, such that if x holds the value 3, the corresponding result for message will be "three". Officially, this evaluation of equality is done using the F# method FSharp.Core .Operators.(=) (defining operator methods is described in more detail in Chapter 8).

Note that null is an acceptable constant value to match against, though F# code in general frowns on the use of null, preferring to use Option types (see Chapter 5) instead, using None to represent no value.

Unlike the switch/case, multiple constants can be matched, allowing easy construction of state machines or truth tables:

let x = (new System.Random()).Next(2)
let y = (new System.Random()).Next(2)
let quadrant = match x, y with
                | 0, 0 -> "(0,0)"
                | 0, 1 -> "(0,1)"
                | 0, 2 -> "(0,2)"
                | 1, 0 -> "(1,0)"
                | 1, 1 -> "(1,1)"
                | 1, 2 -> "(1,2)"
                | 2, 0 -> "(2,0)"
                | 2, 1 -> "(2,1)"
                | 2, 2 -> "(2,2)"
System.Console.WriteLine("We got {0}", quadrant)
                                                     

In the preceding code, the F# compiler will emit a warning about possible unmatched cases, because it cannot determine that the ranges of x and y are limited to 0 and 2. This is F# trying to help avoid a runtime exception, because it can't determine that the values of x and y will be limited to the range 0 to 2 (as defined by the Random.Next() method call).

If the match clause consists of a name beginning with a lowercase letter, then it is a variable-binding pattern, and it introduces a new local variable into which the value is bound for use in the expression to the right of the arrow:

let p = new Person("Rachel", "Reese", 25)
let message = match p.FirstName with
               | fn -> "Hello, " + fn
System.Console.WriteLine("We got {0}", message)

Admittedly, this particular example is a bit contrived, because we could just as easily have obtained said value by simply using the FirstName property on the Person object, but this will become much more useful when combined with some of the other patterns, such as tuple or list patterns. When combined with constant patterns, it allows for a useful "default" case:

let p = new Person("Rachel", "Appel", 25)
let message = match p.FirstName with
                | "Rachel" -> "It's one of the Rachii!!"
                | fn -> "Alas, you are not a Rachii, " + fn
System.Console.WriteLine("We got {0}", message)

Variables bound this way are scoped to the match construct itself.

Patterns can combine using the Boolean operator "|" (for "or"), so that the right expression will be evaluated if either of the two clauses is a match:

let p = new Person("Rachel", "Reese", 25)
let message = match p.FirstName with
                | ("Rachel" | "Scott") ->
                    "Hello, " + p.FirstName
                | _ ->
                    "Who are you, again?"
System.Console.WriteLine("We got {0}", message)

Patterns can also use the & to connect two clauses that must both match for the right expression to fire, but for the most part, this will be limited to the use of active patterns discussed next.

Given what's been said already about F#'s binding of values to names and the pattern-matching rules, it would seem reasonable to expect the following to work:

let rachel = "Rachel"
let p = new Person("Rachel", "Reese", 25)
let message = match p.FirstName with
                | rachel -> "Howdy, Rachel!"
System.Console.WriteLine("We got {0}", message)

And, it will — it will work too well as the compiler will tell us when we try to add any additional clauses to the pattern-match:

let Rachel = "Rachel"
let p = new Person("Rachel", "Reese", 25)
let message = match p.FirstName with
                | Rachel -> "Howdy, Rachel!"
                | _ -> "Howdy, whoever you are!"
System.Console.WriteLine("We got {0}", message)

The F# compiler will emit a warning that the wildcard clause will never be matched, which seems strange. However, a little bit further investigation reveals that despite the direct literal assignment, F# doesn't consider rachel to be a constant to compare against. Instead, it introduces a new binding; to be precise, F# binds the value of the match (p.FirstName) into a new name, rachel, for the duration of the pattern-match.

To tell F# that the binding "rachel" should be treated as a literal value in the pattern match, the .NET attribute "Literal" (introduced in Chapter 3) should be put on the let expression that introduces it:

[<Literal>]
let Rachel = "Rachel"
let p = new Person("Rachel", "Reese", 25)

let message = match p.FirstName with
                | Rachel -> "Howdy, Rachel!"
                | _ -> "Howdy, whoever you are!"
System.Console.WriteLine("We got {0}", message)

Now the warning goes away, and the pattern-match behaves as expected.

Technically, we've already seen tuple matching; in the constant patterns section, we showed the following:

let x = (new System.Random()).Next(2)
let y = (new System.Random()).Next(2)
let quadrant = match x, y with
                | 0, 0 -> "(0,0)"
                | 0, 1 -> "(0,1)"
                | 0, 2 -> "(0,2)"
                | 1, 0 -> "(1,0)"
                | 1, 1 -> "(1,1)"
                | 1, 2 -> "(1,2)"
                | 2, 0 -> "(2,0)"
                | 2, 1 -> "(2,1)"
                | 2, 2 -> "(2,2)"
System.Console.WriteLine("We got {0}", message)
                                                           

What we didn't say at the time is that the F# language considers the x, y pair to be a tuple. F# allows tuples to be used both in the match value and the criteria, as the preceding code demonstrates. Tuple-based pattern-matching combined with named patterns is one of the most common ways to extract the values out of a tuple:

let t = ("Aaron", "Erickson", 35)
let message = match t with
                | (first, last, age) ->
                    "Howdy " + first + " " + last +
                    ", I'm glad to hear you're " +
                    age.ToString() + "!"
System.Console.WriteLine("We got {0}", message)

Tuples and pattern-matching go well together, so much so that it should be assumed that wherever tuples are used, pattern-matching will be used to extract and manipulate the data from inside the tuple.

The as keyword allows us to do both extraction from a tuple and bind a new name to the original tuple at the same time:

let message = match t1 with
                | (x,y) as t2 ->
                     x.ToString() + " " +
                     y.ToString() + " " +
                     t2.ToString()
System.Console.WriteLine("We got {0}", message)

In this case, the original tuple value (t1) is not only extracted into the individual values x1 and y1, but also into the tuple value t2. This pattern-match type isn't common, at least not in this form; see the section "Beyond the Match" for details.

Pattern-matching can also be used to match and extract values from lists, usually by extracting the head and the tail of the list into local values:

let numbers = [1; 2; 3; 4; 5]
let rec sumList ns = match ns with
                        | [] -> 0
                        | head :: tail -> head + sumList tail
let sum = sumList numbers
System.Console.WriteLine("Sum of numbers = {0}", sum)

Here the list is matched either against the empty list, or the head of the list is extracted into the local value "head" and the tail (which may be empty, if the incoming list is exactly one element long) is extracted into the local value "tail." This is an extremely common idiom in F#, particularly because of its thread-safe nature (because all state is held on the stack, rather than in a temporary variable; see Chapter 14 for more on F# and immutable state).

Note, however, that other forms of matching against the list are possible; for example the following is a more verbose way of extracting the first few values of a list:

let message = match numbers with
                | [] -> "List is empty!"
                | [one] ->
                    "List has one item: " + one.ToString()
                | [one; two] ->
                    "List has two items: " +
                    one.ToString() + " " + two.ToString()
                | _ -> "List has more than two items"
System.Console.WriteLine(message)

Again, because the pattern-match happens in a top-down fashion, the wildcard only matches if the list has three or more items in it. In general, however, because this style of list-matching has no convenient way to match against a list of arbitrary length, the preferred manner is to use the head :: tail pattern recursively.

Just as pattern-matching can match against lists, pattern-matching can also match against arrays:

let numbers = [|1; 2; 3; 4; 5|]
let message = match numbers with
                | [| |] -> "Array is empty!"
                | [| one |] ->
                    "Array has one item: " + one.ToString()
                | [| one; two |] ->
                    "Array has two items: " +
                     one.ToString() + " " + two.ToString()
                | _ -> "Array has more than two items"
System.Console.WriteLine(message)

However, because arrays lack an easy way to "tear off" a piece of the array and recursively process the remainder, as lists do, arrays are rarely used as a source or target of pattern-matching.

Pattern-matching against discriminated unions (described in Chapter 7) is not much different than pattern-matching against other types, with the exception that the compiler sanity-checks to ensure that a match against a discriminated union value only has match clauses that could be remotely possible.

type Color =
    | Black
    | Blue
    | Cyan
    | Gray
    | Green
    | Magenta
    | DarkBlue
    | Red
    | White
    | Yellow

let color = Black
let message = match color with
                | Black -> "Black!"
                | Blue -> "Blue!"
                | _ -> "Something other than black or blue"
System.Console.WriteLine(message)

Discriminated unions are a powerful companion to pattern-matching, just as tuples are.

Record types, described more in Chapter 7, can also be pattern-matched (and values extracted) in much the same way that tuples are. In fact, since a record type is, in many ways, "just" a tuple, pattern matching with a record type is just an extension of doing it against a tuple type:

type Author =
    | Author of string * string * int

let ted = Author("Ted", "Neward", 38)

match ted with
    | Author(first, last, age) ->
        System.Console.WriteLine("Hello, {0}", first)

Record types are covered in more detail in Chapter 7, and more examples of pattern-matching with records are given there.

The single-case active pattern is conceptually the easiest to understand: It allows the F# developer to specify a function that is called from inside the pattern-match — rather than before the match — so as to allow for processing or conversion of the data.

For example, when a developer starts to get used to using pattern-matching, it's fairly common to want to use it to handle all sorts of multi-case logic, such as situations where we want to determine if text matches a particular input pattern. It's not too difficult to imagine validation cases in a web application where a developer wants to determine if a text string contains "dangerous" input, such as embedded HTML tags of some form:

let inputData = "This is some <script>alert()</script> data"
let contains (inStr : string) =
    inStr.Contains "<script>"
System.Console.WriteLine("Does the text contain bad data? " +
    (contains inputData).ToString())

Obviously a real implementation would be screening for much more beyond <script> tags, so a refinement is necessary:

let inputData = "This is some <script>alert()</script> data"
let contains (srchStr : string) (inStr : string) =
    inStr.Contains srchStr
System.Console.WriteLine("Does the text contain bad data? " +
    (contains "<script>" inputData).ToString())

But using this requires us to list out all the possible "bad tags" that might appear in this user-input string, which can get tedious:

let inputData = "This is some <script>alert()</script> data"
let contains (srchStr : string) (inStr : string) =
    inStr.Contains srchStr
let goodInput inStr =
    contains "<script>" inStr ||
    contains "<object>" inStr ||
    contains "<embed>" inStr ||
    contains "<applet>" inStr
System.Console.WriteLine("Does the text contain bad data? " +
    (goodInput inputData).ToString())

Frankly, this is precisely the kind of thing that pattern-matching was originally intended to model, to avoid having to write this kind of code. Unfortunately, attempting to use contains() inside the pattern-match causes the pattern-match to match on the results of the contains() call, which isn't quite what's needed here, particularly because we need to call contains() over and over again (once for each potentially "bad" input).

Enter the single-case active pattern. By defining an active pattern — a function defined with "banana clips" around it — the function can be called as part of the pattern-match, as in:

let (|Contains|) srchStr (inStr : string) =
    inStr.Contains srchStr
let isSafeHtml inputData =
    match inputData with
    | Contains "<script>" true -> false
    | Contains "<object>" true -> false
    | Contains "<embed>" true -> false
    | Contains "<applet>" true -> false
    | _ -> true

Viewed this way, it may not seem like the active pattern is saving much time or space, but the logical equivalent, when written out, would be a series of nested "if" or pattern-match statements, testing each possibility one-by-one before finally resolving to some result.

The parameters to the Contains pattern function don't seem to match precisely against the use inside the pattern-match itself. This is because the first parameter (srchStr in the Contains() example) is coming from the match clause (<script>), and the second parameter (inStr) from the value being matched against (inputData). Regardless of the number of parameters to the active recognizer (the term the F# language uses for the Contains() function), the last parameter in the function definition is always the value being matched. The true at the end of the match clause is the actual test — if the Contains() call returns true, it matches against the value in the test (the literal "true"), and thus the match clause succeeds.

The partial-case active pattern is, in many ways, a variant of the single-case active pattern, in that it allows for matches that may or may not always match successfully; in other words, it enables a "partitioning" of the input space into one or more possible variations. To understand what that means, let's return to the previous input-validation scenario. Much of the input validation itself would be made easier if we could incorporate a regular expression into the mix — in other words, if we could "partition out" the input into either something that matched a given regex or not. To do so, we can write a partial-case active pattern — again using the "banana clips" notation — to define it:

let inputData = "This is some <script>alert()</script> data"

let (|Contains|_|) pat inStr =
    let results =
        (System.Text.RegularExpressions.Regex.Matches(inStr, pat))
    if results.Count > 0
       then Some [ for m in results -> m.Value ]
       else None

let matchStuff inData =
    match inData with
    | Contains "http://S+" _ -> "Contains urls"
    | Contains "[^@]@[^.]+.W+" _ -> "Contains emails"
    | Contains "<script>" _ -> "Found <script>"
    | Contains "<object>" _ -> "Found <object>"
    | _ -> "Didn't find what we were looking for"

System.Console.WriteLine(matchStuff inputData)

The defining characteristic of a partial-case pattern match is twofold; first, the "wildcard" character defined as part of the function's name (such as (|Contains|_|) in the preceding code), intended to convey the idea that this is not always necessarily going to yield a successful result; and second, the return of the function being an Option type, with Some returning the results (which we ignore in our example), and None implying that the match didn't work.

Note that we can have numerous partial-case pattern matches; in fact, we can have as many as might be necessary to help complete the match. So, to use a different example (drawing from the Person class defined in Chapter 8), we can write several partial-case pattern match constructs to make it easier to use Reflection to find a particular part of a type:

let AllBindingFlags =
    BindingFlags.NonPublic ||| BindingFlags.Public |||
    BindingFlags.Instance ||| BindingFlags.Static
let (|Field|_|) name (t : System.Type) =
    let fi = t.GetField(name, AllBindingFlags)
    if fi <> null then Some(fi) else None
let (|Method|_|) name (t : System.Type) =
    let fi = t.GetMethod(name, AllBindingFlags)
    if fi <> null then Some(fi) else None
let (|Property|_|) name (t : System.Type) =
    let fi = t.GetProperty(name, AllBindingFlags)
    if fi <> null then Some(fi) else None
let pt = (new Person("", "", 0)).GetType()
let message =
    match pt with
    | Property "FirstName" pi ->
        "Found property " + pi.ToString()
    | Property "LastName" pi ->
        "Found property " + pi.ToString()
    | _ -> "There's other stuff, but who cares?"
System.Console.WriteLine(message)

Contrary to what a Reflection-based example might imply, and what the preceding syntax seems to reinforce, this code won't find all the different properties, fields, and methods on the type passed in; instead, as is always the case with pattern-matching, it finds the first match that succeeds and returns that as the result of the pattern-match expression. This means that the partial-case pattern is good for finding a particular element (such as the FirstName property on any passed-in object) before extracting its value from that object:

let AllBindingFlags =
    BindingFlags.NonPublic ||| BindingFlags.Public |||
    BindingFlags.Instance ||| BindingFlags.Static
let (|Field|_|) name (inst : obj) =
    let fi = inst.GetType().GetField(name, AllBindingFlags)
    if fi <> null

then Some(fi.GetValue(inst))
    else None
let (|Method|_|) name (inst : obj) =
    let fi = inst.GetType().GetMethod(name, AllBindingFlags)
    if fi <> null
    then Some(fi)
    else None
let (|Property|_|) name (inst : obj) =
    let fi = inst.GetType().GetProperty(name, AllBindingFlags)
    if fi <> null
    then Some(fi.GetValue(inst, null))
    else None

let rm = new Person("Rick", "Minerich", 29)
// Does it have a first name? Get the value if it does
let message = match rm with
                | Property "FirstName" value ->
                    "FirstName = " + value.ToString()
                | _ -> "No FirstName to be found"
System.Console.WriteLine(message)

This is sometimes known as duck typing ("If it walks like a duck and talks like a duck, treat it as a duck") in dynamic languages such as Python and Ruby.

This is also where AND patterns, briefly mentioned in the section "AND, OR Patterns" can be useful; if the object in question needs both a FirstName property and a LastName property before it can be considered a good object to work with, then the AND in the pattern-match will require both properties to be there before evaluating the action after the arrow:

let rm = new Person("Rick", "Minerich", 29)
// Does it have a first name AND a last name?
let message = match rm with
                | Property "FirstName" fnval &
                  Property "LastName" lnval ->
                     "Full name = " + fnval.ToString() +
                     " " + lnval.ToString()
                | Property "FirstName" value ->
                    "Name = " + value.ToString()
                | Property "LastName" value ->
                    "Name = " + value.ToString()
                | _ ->
                    "No name to be found"
System.Console.WriteLine(message)

Partial-case active patterns can obviously be used in a variety of other scenarios beyond Reflection; one such area is in processing XML documents, where judicious use of active patterns can act as a structured and type-safe form of XPath query. (More on using XML with F# can be found in Chapter 20.)

The previous Reflection-oriented example suffers from the fact that the match types a Type and uses that to try and find a match in top-down order, which succeeds the first time and then quits the rest of the match expression. This is fine if we want to test to see if a particular type supports a particular operation, but if the goal is to break down a given type into its constituent parts (such as what we see with tools such as ILDasm or Reflector), then the multi-case active pattern comes into play:

let (|Property|Method|Field|Constructor|) (mi : MemberInfo) =
    if (mi :? FieldInfo) then
        Field(mi.Name, (mi :?> FieldInfo).FieldType)
    elif (mi :? MethodInfo) then
        Method(mi.Name, (mi :?> MethodInfo).ReturnType)
    elif (mi :? PropertyInfo) then
        Property(mi.Name, (mi :?> PropertyInfo).PropertyType)
    elif (mi :? ConstructorInfo) then
        Constructor("", mi.DeclaringType)
    else
        failwith "Unrecognized Reflection type"

In this case, we use dynamic type tests (see Chapter 9 for details on downcasting) to determine what subtype the MemberInfo instance is and extract values from that subtype for use.

Syntactically, notice that the multi-case active pattern includes all the possible result values within the banana clips, and the lack of the wildcard character implies that when this function is invoked, the results must, somehow, match into one of those values (Property, Method, Field, or Constructor in the previous example). The data that should be returned for use in the pattern-match is gathered into a tuple under the pattern-match name (Property, Method, and so on) and handed back.

When used, the multi-case active pattern (like all pattern-matching constructs) can bind values into a local value binding, which in this case, using the preceding definition, makes it relatively easy to extract the name and type of the reflective element in question:

for p in typeof<Person>.GetMembers(AllBindingFlags) do
    match p with
    | Property(nm, ty) ->
        System.Console.WriteLine(
            "Found prop {1} {0}", nm, ty)
    | Field(nm, ty) ->
        System.Console.WriteLine(
            "Found fld {1} {0}", nm, ty)
    | Method(nm, rt) ->
        System.Console.WriteLine(
            "Found mth {1} {0}(...)", nm, rt)
    | Constructor(_, _) ->
        System.Console.WriteLine("Found ctor")

Having done that, however, something jarring appears: Under the current definition of the multi-case pattern match, we lose the parameters from the method, and the constructor doesn't actually have a name or a return type, per se. This is because as written, the multi-case pattern match assumes that in each case, we want to return a string and a System.Type tuple.

Fortunately, the multi-case active pattern doesn't require that each possibility return the same type; it returns a Choice<> type, essentially creating a large tagged union type out of each of the potential types returned by the individual matches. So we can have the Constructor tuple return just the parameters to the constructor, and the Method tuple return the name, the return type, and the parameters to the method:

let (|Property|Method|Field|Constructor|) (mi : MemberInfo) =
    if (mi :? FieldInfo) then
        Field(mi.Name, (mi :?> FieldInfo).FieldType)
    elif (mi :? MethodInfo) then
        let mthi = (mi :?> MethodInfo)
        Method(mi.Name, mthi.ReturnType, mthi.GetParameters())
    elif (mi :? PropertyInfo) then
        let pi = (mi :?> PropertyInfo)
        Property(pi.Name, pi.PropertyType)
    elif (mi :? ConstructorInfo) then
        let ci = (mi :?> ConstructorInfo)
        Constructor(ci.GetParameters())
    else
        failwith "Unrecognized Reflection type"

This now gives us better data-extraction capabilities when displaying the individual parts of the type:

let pt = (new Person("", "", 0)).GetType()
let AllBindingFlags =
    BindingFlags.NonPublic ||| BindingFlags.Public |||
    BindingFlags.Instance ||| BindingFlags.Static
for p in pt.GetMembers(AllBindingFlags) do
    match p with
    | Property(nm, ty) ->
        System.Console.WriteLine(
            "Found prop {1} {0}", nm, ty)
    | Field(nm, ty) ->
        System.Console.WriteLine(
            "Found fld {1} {0}", nm, ty)
    | Method(nm, rt, parms) ->
         System.Console.WriteLine(
             "Found mth {1} {0}(...)", nm, rt)
    | Constructor(parms) ->
        System.Console.WriteLine("Found ctor")

The huge advantage to this approach, of course, is that as this code seeks to support additional Reflection types (events, delegates, generics, and so on), the active-pattern can simply be extended to add those additional types, and using them simply follows the traditional pattern-match style.

The multi-case active pattern is sometimes called data decomposition because it essentially allows an object (in this case, System.Type instance) to be broken down (decomposed) into its constituent parts and processed.