Discriminated Unions (F#)
Learn how to use F# discriminated unions.
Discriminated unions provide support for values that can be one of a number of named cases, possibly each with different values and types. Discriminated unions are useful for heterogeneous data; data that can have special cases, including valid and error cases; data that varies in type from one instance to another; and as an alternative for small object hierarchies. In addition, recursive discriminated unions are used to represent tree data structures.
[ attributes ] type [accessibility-modifier] type-name = | case-identifier1 [of [ fieldname1 : ] type1 [ * [ fieldname2 : ] type2 ...] | case-identifier2 [of [fieldname3 : ]type3 [ * [ fieldname4 : ]type4 ...] ...
Discriminated unions are similar to union types in other languages, but there are differences. As with a union type in C++ or a variant type in Visual Basic, the data stored in the value is not fixed; it can be one of several distinct options. Unlike unions in these other languages, however, each of the possible options is given a case identifier. The case identifiers are names for the various possible types of values that objects of this type could be; the values are optional. If values are not present, the case is equivalent to an enumeration case. If values are present, each value can either be a single value of a specified type, or a tuple that aggregates multiple fields of the same or different types. You can give an individual field a name, but the name is optional, even if other fields in the same case are named.
Accessibility for discriminated unions defaults to
For example, consider the following declaration of a Shape type.
type Shape = | Rectangle of width : float * length : float | Circle of radius : float | Prism of width : float * float * height : float
The preceding code declares a discriminated union Shape, which can have values of any of three cases: Rectangle, Circle, and Prism. Each case has a different set of fields. The Rectangle case has two named fields, both of type
float, that have the names width and length. The Circle case has just one named field, radius. The Prism case has three fields, two of which (width and height) are named fields. Unnamed fields are referred to as anonymous fields.
You construct objects by providing values for the named and anonymous fields according to the following examples.
let rect = Rectangle(length = 1.3, width = 10.0) let circ = Circle (1.0) let prism = Prism(5., 2.0, height = 3.0)
This code shows that you can either use the named fields in the initialization, or you can rely on the ordering of the fields in the declaration and just provide the values for each field in turn. The constructor call for
rect in the previous code uses the named fields, but the constructor call for
circ uses the ordering. You can mix the ordered fields and named fields, as in the construction of
option type is a simple discriminated union in the F# core library. The
option type is declared as follows.
// The option type is a discriminated union. type Option<'a> = | Some of 'a | None
The previous code specifies that the type
Option is a discriminated union that has two cases,
Some case has an associated value that consists of one anonymous field whose type is represented by the type parameter
None case has no associated value. Thus the
option type specifies a generic type that either has a value of some type or no value. The type
Option also has a lowercase type alias,
option, that is more commonly used.
The case identifiers can be used as constructors for the discriminated union type. For example, the following code is used to create values of the
The case identifiers are also used in pattern matching expressions. In a pattern matching expression, identifiers are provided for the values associated with the individual cases. For example, in the following code,
x is the identifier given the value that is associated with the
Some case of the
In pattern matching expressions, you can use named fields to specify discriminated union matches. For the Shape type that was declared previously, you can use the named fields as the following code shows to extract the values of the fields.
let getShapeHeight shape = match shape with | Rectangle(height = h) -> h | Circle(radius = r) -> 2. * r | Prism(height = h) -> h
Normally, the case identifiers can be used without qualifying them with the name of the union. If you want the name to always be qualified with the name of the union, you can apply the RequireQualifiedAccess attribute to the union type definition.
Unwrapping Discriminated Unions
In F# Discriminated Unions are often used in domain-modeling for wrapping a single type. It's easy to extract the underlying value via pattern matching as well. You don't need to use a match expression for a single case:
let ([UnionCaseName] [values]) = [UnionValue]
The following example demonstrates this:
type ShaderProgram = | ShaderProgram of id:int let someMethodUsingShaderProgram shaderProgram = let (ShaderProgram id) = shaderProgram // Use the unwrapped value ..
Struct Discriminated Unions
Starting with F# 4.1, you can also represent Discriminated Unions as structs. This is done with the
[<Struct>] type SingleCase = Case of string [<Struct>] type Multicase = | Case1 of Case1 : string | Case2 of Case2 : int | Case3 of Case3 : double
Because these are value types and not reference types, there are extra considerations compared with reference discriminated unions:
- They are copied as value types and have value type semantics.
- You cannot use a recursive type definition with a multicase struct Discriminated Union.
- You must provide unique case names for a multicase struct Discriminated Union.
Using Discriminated Unions Instead of Object Hierarchies
You can often use a discriminated union as a simpler alternative to a small object hierarchy. For example, the following discriminated union could be used instead of a
Shape base class that has derived types for circle, square, and so on.
Instead of a virtual method to compute an area or perimeter, as you would use in an object-oriented implementation, you can use pattern matching to branch to appropriate formulas to compute these quantities. In the following example, different formulas are used to compute the area, depending on the shape.
The output is as follows:
Area of circle that has radius 15.000000: 706.858347 Area of square that has side 10.000000: 100.000000 Area of rectangle that has height 5.000000 and width 10.000000 is 50.000000
Using Discriminated Unions for Tree Data Structures
Discriminated unions can be recursive, meaning that the union itself can be included in the type of one or more cases. Recursive discriminated unions can be used to create tree structures, which are used to model expressions in programming languages. In the following code, a recursive discriminated union is used to create a binary tree data structure. The union consists of two cases,
Node, which is a node with an integer value and left and right subtrees, and
Tip, which terminates the tree.
In the previous code,
resultSumTree has the value 10. The following illustration shows the tree structure for
Discriminated unions work well if the nodes in the tree are heterogeneous. In the following code, the type
Expression represents the abstract syntax tree of an expression in a simple programming language that supports addition and multiplication of numbers and variables. Some of the union cases are not recursive and represent either numbers (
Number) or variables (
Variable). Other cases are recursive, and represent operations (
Multiply), where the operands are also expressions. The
Evaluate function uses a match expression to recursively process the syntax tree.
When this code is executed, the value of
result is 5.
The following attributes are commonly seen in discriminated unions:
[Struct](F# 4.1 and higher)