Records (F#)

Records represent simple aggregates of named values, optionally with members. They can either be structs or reference types. They are reference types by default.

Syntax

[ attributes ]
type [accessibility-modifier] typename =
    [accessibility-modifier] { 
        [ mutable ] label1 : type1;
        [ mutable ] label2 : type2;
        ... 
    }
    [ member-list ]

The accessibility modifier before the typename affects the visibility of the entire type, and is public by default. The second accessibility modifier only affects the constructor and fields.

Remarks

In the previous syntax, typename is the name of the record type, label1 and label2 are names of values, referred to as labels, and type1 and type2 are the types of these values. member-list is the optional list of members for the type. You can use the [<Struct>] attribute to create a struct record rather than a record which is a reference type.

Following are some examples.

// Labels are separated by semicolons when defined on the same line.
type Point = { X: float; Y: float; Z: float }

// You can define labels on their own line with or without a semicolon.
type Customer =
    { First: string
      Last: string
      SSN: uint32
      AccountNumber: uint32 }

// A struct record.
[<Struct>]
type StructPoint = { X: float; Y: float; Z: float }

When each label is on a separate line, the semicolon is optional.

You can set values in expressions known as record expressions. The compiler infers the type from the labels used (if the labels are sufficiently distinct from those of other record types). Braces ({ }) enclose the record expression. The following code shows a record expression that initializes a record with three float elements with labels x, y and z.

let mypoint = { X = 1.0; Y = 1.0; Z = -1.0 }

Do not use the shortened form if there could be another type that also has the same labels.

type Point = { X: float; Y: float; Z: float }
type Point3D = { X: float; Y: float; Z: float }
// Ambiguity: Point or Point3D?
let mypoint3D = { X = 1.0; Y = 1.0; Z = 0.0 }

The labels of the most recently declared type take precedence over those of the previously declared type, so in the preceding example, mypoint3D is inferred to be Point3D. You can explicitly specify the record type, as in the following code.

let myPoint1 = { Point.X = 1.0; Y = 1.0; Z = 0.0 }

Methods can be defined for record types just as for class types.

Creating Records by Using Record Expressions

You can initialize records by using the labels that are defined in the record. An expression that does this is referred to as a record expression. Use braces to enclose the record expression and use the semicolon as a delimiter.

The following example shows how to create a record.

type MyRecord = { X: int; Y: int; Z: int }

let myRecord1 = { X = 1; Y = 2; Z = 3 }

The semicolons after the last field in the record expression and in the type definition are optional, regardless of whether the fields are all in one line.

When you create a record, you must supply values for each field. You cannot refer to the values of other fields in the initialization expression for any field.

In the following code, the type of myRecord2 is inferred from the names of the fields. Optionally, you can specify the type name explicitly.

let myRecord2 =
    { MyRecord.X = 1
      MyRecord.Y = 2
      MyRecord.Z = 3 }

Another form of record construction can be useful when you have to copy an existing record, and possibly change some of the field values. The following line of code illustrates this.

let myRecord3 = { myRecord2 with Y = 100; Z = 2 }

This form of the record expression is called the copy and update record expression.

Records are immutable by default; however, you can easily create modified records by using a copy and update expression. You can also explicitly specify a mutable field.

type Car =
    { Make: string
      Model: string
      mutable Odometer: int }

let myCar =
    { Make = "Fabrikam"
      Model = "Coupe"
      Odometer = 108112 }

myCar.Odometer <- myCar.Odometer + 21

Don't use the DefaultValue attribute with record fields. A better approach is to define default instances of records with fields that are initialized to default values and then use a copy and update record expression to set any fields that differ from the default values.

// Rather than use [<DefaultValue>], define a default record.
type MyRecord =
    { Field1 : int
      Field2 : int }

let defaultRecord1 = { Field1 = 0; Field2 = 0 }
let defaultRecord2 = { Field1 = 1; Field2 = 25 }

// Use the with keyword to populate only a few chosen fields
// and leave the rest with default values.
let rr3 = { defaultRecord1 with Field2 = 42 }

Compose records with spreads

To reuse fields across different models, F# 11 provides type spreads (...SourceType) and expression spreads (...sourceValue). They copy declarations or values without inheritance. See Record spread operators for examples; for a same-type update, use copy-and-update.

Record constructors

To identify a record type directly at its construction site, use its all-fields constructor:

type Person = { Name: string; Age: int }
let person = Person(Name = "Ada", Age = 36)

Positional arguments follow field order; named arguments avoid that dependency. Representation accessibility still applies, and a same-named value takes precedence. Constructor patterns aren't supported.

Creating Mutually Recursive Records

Sometime when creating a record, you may want to have it depend on another type that you would like to define afterwards. This is a compile error unless you define the record types to be mutually recursive.

Defining mutually recursive records is done with the and keyword. This lets you link 2 or more record types together.

For example, the following code defines a Person and Address type as mutually recursive:

// Create a Person type and use the Address type that is not defined
type Person =
    { Name: string
      Age: int
      Address: Address }
// Define the Address type which is used in the Person record
and Address =
    { Line1: string
      Line2: string
      PostCode: string
      Occupant: Person }

To create instances of both, you do the following:

// Create a Person type and use the Address type that is not defined
let rec person =
    {
        Name = "Person name"
        Age = 12
        Address =
            {
                Line1 = "line 1"
                Line2 = "line 2"
                PostCode = "abc123"
                Occupant = person
            }
    }

If you were to define the previous example without the and keyword, then it would not compile. The and keyword is required for mutually recursive definitions.

Pattern Matching with Records

Records can be used with pattern matching. You can specify some fields explicitly and provide variables for other fields that will be assigned when a match occurs. The following code example illustrates this.

type Point3D = { X: float; Y: float; Z: float }
let evaluatePoint (point: Point3D) =
    match point with
    | { X = 0.0; Y = 0.0; Z = 0.0 } -> printfn "Point is at the origin."
    | { X = xVal; Y = 0.0; Z = 0.0 } -> printfn "Point is on the x-axis. Value is %f." xVal
    | { X = 0.0; Y = yVal; Z = 0.0 } -> printfn "Point is on the y-axis. Value is %f." yVal
    | { X = 0.0; Y = 0.0; Z = zVal } -> printfn "Point is on the z-axis. Value is %f." zVal
    | { X = xVal; Y = yVal; Z = zVal } -> printfn "Point is at (%f, %f, %f)." xVal yVal zVal

evaluatePoint { X = 0.0; Y = 0.0; Z = 0.0 }
evaluatePoint { X = 100.0; Y = 0.0; Z = 0.0 }
evaluatePoint { X = 10.0; Y = 0.0; Z = -1.0 }

The output of this code is as follows.

Point is at the origin.
Point is on the x-axis. Value is 100.000000.
Point is at (10.000000, 0.000000, -1.000000).

Records and members

You can specify members on records much like you can with classes. There is no support for fields. A common approach is to define a Default static member for easy record construction:

type Person =
    { Name: string
      Age: int
      Address: string }

    static member Default =
        { Name = "Phillip"
          Age = 12
          Address = "123 happy fun street" }

let defaultPerson = Person.Default

If you use a self identifier, that identifier refers to the instance of the record whose member is called:

type Person =
    { Name: string
      Age: int
      Address: string }

    member this.WeirdToString() =
        this.Name + this.Address + string this.Age

let p = { Name = "a"; Age = 12; Address = "abc123" }
let weirdString = p.WeirdToString()

Accessibility Modifiers on Records

The following code illustrates the use of accessibility modifiers. There are three files in the project: Module1.fs, Test1.fs, and Test2.fs. An internal record type and a record type with a private constructor are defined in Module1.

// Module1.fs

module Module1

type internal internalRecd = { X: int }

type recdWithInternalCtor = private { Y: int }

In the Test1.fs file, the internal record must be initialized with the internal access modifier, that's because the protection level of the value and the record must match, and both must belong to the same assembly.

// Test1.fs

module Test1

open Module1

let myInternalRecd1 = { X = 2 } // This line will cause a compiler error.

let internal myInternalRecd2 = { X = 4 } // This is OK

In the Test2.fs file, the record with the private constructor cannot be initialized directly due the protection level of the constructor.

// Test2.fs

module Test2

open Module1

let myRecdWithInternalCtor = { Y = 6 } // This line will cause a compiler error.

For more information about accessibility modifiers, see the Access Control article.

Differences Between Records and Classes

Record fields differ from class fields in that they are automatically exposed as properties, and they are used in the creation and copying of records. Record construction also differs from class construction. In a record type, you cannot define a constructor. Instead, the construction syntax described in this topic applies. Classes have no direct relationship between constructor parameters, fields, and properties.

Like union and structure types, records have structural equality semantics. Classes have reference equality semantics. The following code example demonstrates this.

type RecordTest = { X: int; Y: int }

let record1 = { X = 1; Y = 2 }
let record2 = { X = 1; Y = 2 }

if (record1 = record2) then
    printfn "The records are equal."
else
    printfn "The records are unequal."

The output of this code is as follows:

The records are equal.

If you write the same code with classes, the two class objects would be unequal because the two values would represent two objects on the heap and only the addresses would be compared (unless the class type overrides the System.Object.Equals method).

If you need reference equality for records, add the attribute [<ReferenceEquality>] above the record.

See also

• F# Types
• Classes
• F# Language Reference
• Reference-Equality
• Pattern Matching