Feedback Edit

Reference Cells

  • Article
  • 2 minutes to read

Reference cells are storage locations that enable you to create mutable values with reference semantics.

Syntax

ref expression

Remarks

You use the ref operator before a value to create a new reference cell that encapsulates the value. You can then change the underlying value because it is mutable.

A reference cell holds an actual value; it is not just an address. When you create a reference cell by using the ref operator, you create a copy of the underlying value as an encapsulated mutable value.

You can dereference a reference cell by using the ! (bang) operator.

The following code example illustrates the declaration and use of reference cells.

// Declare a reference.
let refVar = ref 6

// Change the value referred to by the reference.
refVar := 50

// Dereference by using the ! operator.
printfn "%d" !refVar

The output is 50.

Reference cells are instances of the Ref generic record type, which is declared as follows.

type Ref<'a> =
{ mutable contents: 'a }

The type 'a ref is a synonym for Ref<'a>. The compiler and IntelliSense in the IDE display the former for this type, but the underlying definition is the latter.

The ref operator creates a new reference cell. The following code is the declaration of the ref operator.

let ref x = { contents = x }

The following table shows the features that are available on the reference cell.

Operator, member, or field Description Type Definition
! (dereference operator) Returns the underlying value. 'a ref -> 'a let (!) r = r.contents
:= (assignment operator) Changes the underlying value. 'a ref -> 'a -> unit let (:=) r x = r.contents <- x
ref (operator) Encapsulates a value into a new reference cell. 'a -> 'a ref let ref x = { contents = x }
Value (property) Gets or sets the underlying value. unit -> 'a member x.Value = x.contents
contents (record field) Gets or sets the underlying value. 'a let ref x = { contents = x }

There are several ways to access the underlying value. The value returned by the dereference operator (!) is not an assignable value. Therefore, if you are modifying the underlying value, you must use the assignment operator (:=) instead.

Both the Value property and the contents field are assignable values. Therefore, you can use these to either access or change the underlying value, as shown in the following code.

let xRef : int ref = ref 10

printfn "%d" (xRef.Value)
printfn "%d" (xRef.contents)

xRef.Value <- 11
printfn "%d" (xRef.Value)
xRef.contents <- 12
printfn "%d" (xRef.contents)

The output is as follows.

10
10
11
12

The field contents is provided for compatibility with other versions of ML and will produce a warning during compilation. To disable the warning, use the --mlcompatibility compiler option. For more information, see Compiler Options.

C# programmers should know that ref in C# is not the same thing as ref in F#. The equivalent constructs in F# are byrefs, which are a different concept from reference cells.

Values marked as mutablemay be automatically promoted to 'a ref if captured by a closure; see Values.

See also