Structural Equality vs Reference Equality
F#'s = operator performs structural equality by default for records, tuples, discriminated unions, and lists -- two values are equal if they have the same shape and every corresponding field or element is equal, regardless of whether they're literally the same object in memory. This is the opposite default from plain .NET reference types in C#, where == on a class typically checks reference identity unless the class explicitly overrides Equals; F# record types automatically get a compiler-generated structural Equals, GetHashCode, and CompareTo implementation, so { Name = "Ann"; Age = 30 } = { Name = "Ann"; Age = 30 } is true even though they're two separate heap allocations.
Cricket analogy: Structural equality is like two separately printed scorecards from the same match being considered 'the same result' because every run, wicket, and over matches exactly, even though they're two different physical pieces of paper -- F# compares the content of { Name = "Ann"; Age = 30 } the same way, not which specific memory allocation it lives in.
How F# Derives Equality for Records and DUs
The compiler generates structural equality automatically at compile time by walking each field in declaration order and comparing them with = recursively, so a DU like type Shape = Circle of float | Rectangle of float * float gets equality that first checks the case tag matches, then structurally compares the payload -- Circle 5.0 = Circle 5.0 is true, but Circle 5.0 = Rectangle (5.0, 5.0) is false even though 5.0 appears in both, because the case tags differ. This generated code also produces a consistent GetHashCode implementation derived the same way, which matters because structural equality and hashing must agree for records to work correctly as Dictionary or HashSet keys.
Cricket analogy: Comparing a DU's case tag before its payload, so Circle 5.0 = Rectangle(5.0, 5.0) is false despite sharing the number 5.0, mirrors how a scorecard entry tagged 'boundary: 4' is never considered equal to one tagged 'wide: 4' even though both record the number 4 -- the dismissal-type tag is checked first.
type Person = { Name: string; Age: int }
let p1 = { Name = "Ann"; Age = 30 }
let p2 = { Name = "Ann"; Age = 30 }
printfn "%b" (p1 = p2) // true: structural equality
printfn "%b" (obj.ReferenceEquals(p1, p2)) // false: different allocations
type Shape =
| Circle of float
| Rectangle of float * float
printfn "%b" (Circle 5.0 = Circle 5.0) // true
printfn "%b" (Circle 5.0 = Rectangle(5.0, 5.0)) // falseStructural equality extends to collections: two list, array, Set, or Map values are compared element-by-element (in order, for lists and arrays), so [1; 2; 3] = [1; 2; 3] is true even though they're separately allocated, and this is exactly why F# collections work correctly as Set elements or Dictionary keys without any extra configuration.
Comparison and Structural Ordering
Alongside equality, F# derives a structural CompareTo for records, tuples, and DUs whenever every field's type itself supports comparison, which lets you sort a list of records directly with List.sort without writing a custom comparer. Tuples compare lexicographically -- (1, "b") < (1, "c") is true, (1, "z") < (2, "a") is also true because the first element dominates when it differs -- and DU cases are ordered by their declaration order first, so type Priority = Low | Medium | High gives Low < Medium < High automatically, which is exactly why the order you write DU cases in matters even when you don't use them for equality.
Cricket analogy: Structural ordering giving type Priority = Low | Medium | High the ordering Low < Medium < High by declaration order mirrors how ICC tournament seeding tiers -- Group Stage, Super Six, Final -- are inherently ordered by their position in the competition structure, not by any number you have to assign manually.
type Priority = Low | Medium | High
let tasks = [ ("Deploy", High); ("Docs", Low); ("Review", Medium) ]
let sorted = tasks |> List.sortBy snd
// sorted by Priority's declaration order: Low, Medium, High
let tuples = [ (1, "z"); (2, "a"); (1, "b") ]
let sortedTuples = List.sort tuples
// [(1, "b"); (1, "z"); (2, "a")] -- lexicographicOpting Out: CustomEquality and ReferenceEquality
Sometimes structural equality is wrong for a type -- a type wrapping a System.Random instance or a database connection shouldn't be compared field-by-field -- so F# lets you opt out with the [<CustomEquality; NoComparison>] attributes and implement Equals/GetHashCode yourself, or opt into plain reference equality with [<ReferenceEquality>], which makes = behave like C#'s default == for classes. Attempting structural equality on a type that contains a function value (like a record with a field of type int -> int) is a compile error, since function values have no meaningful notion of structural equality -- there's no way to compare two closures for 'being the same computation' short of inspecting their compiled IL, which F# deliberately doesn't attempt.
Cricket analogy: Opting into [<ReferenceEquality>] for a type wrapping mutable state, like a live match's ball-by-ball connection object, mirrors why two separate radio commentary booths covering the same match aren't considered 'the same broadcast' just because they're describing identical events -- identity matters more than momentary content for a live feed.
Structural equality on float inherits IEEE 754's rule that nan = nan is false, so a record containing a float field set to nan is never structurally equal to itself, which can silently break Dictionary lookups, Set membership checks, and List.distinct. Also remember: comparing two records that both contain a field of function type is a compile error, since F# has no meaningful way to structurally compare closures.
- F#'s = performs structural equality by default for records, tuples, DUs, and lists.
- Two structurally equal values can be two entirely separate heap allocations.
- DU equality checks the case tag first, then compares the payload.
- The compiler auto-generates Equals, GetHashCode, and CompareTo consistently for records and DUs.
- Tuples compare lexicographically; DU cases compare by declaration order.
- [<ReferenceEquality>] opts a type into identity-based equality, like C#'s default ==.
- [<CustomEquality; NoComparison>] lets you implement equality yourself for types where structural comparison doesn't make sense.
Practice what you learned
1. Given type Person = { Name: string; Age: int }, what does { Name = "Ann"; Age = 30 } = { Name = "Ann"; Age = 30 } evaluate to?
2. For type Shape = Circle of float | Rectangle of float * float, why is Circle 5.0 = Rectangle(5.0, 5.0) false?
3. Given type Priority = Low | Medium | High, what determines that Low < Medium < High?
4. Which attribute makes a type's = operator behave like C#'s default reference equality?
5. Why can't two records containing fields of function type (e.g., int -> int) be compared with structural equality?
Was this page helpful?
You May Also Like
Discriminated Unions
Learn how F#'s discriminated unions model a closed set of named cases, each optionally carrying data, with compiler-enforced exhaustive pattern matching.
Option Types in F#
Understand F#'s option type as a safe, explicit alternative to null, and how to combine option values with map, bind, and defaultValue.
Units of Measure
See how F#'s units of measure attach compile-time-only physical units to numeric types, catching dimensional-analysis bugs before runtime.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics