Value.Equals
ValueReturns true if two values are equal, with an optional custom comparer function.
Syntax
Value.Equals(value1 as any, value2 as any, optional comparer as nullable function) as logicalParameters
| Name | Type | Required | Description |
|---|---|---|---|
value1 | any | Yes | The first value to compare. |
value2 | any | Yes | The second value to compare. |
comparer | function | No | An optional comparer function that accepts two values and returns -1, 0, or 1. When omitted, the default equality semantics are used. |
Return Value
logical — True if value1 and value2 are equal, false otherwise.
Remarks
Value.Equals tests whether two values are equal, returning true or false. For most primitive types it is equivalent to the = operator, but with two important differences:
1. Null handling: null = null in M evaluates to null (three-valued logic), but Value.Equals(null, null) returns true. Value.Equals always returns a logical, never null. Use Value.NullableEquals when you specifically need SQL-style three-valued logic.
2. Custom comparers: the optional comparer parameter accepts a comparer function (e.g., Comparer.OrdinalIgnoreCase) for case-insensitive or locale-aware equality. The = operator has no equivalent capability.
Value.Equals works on any M value type — numbers, text, dates, lists, records — using M's built-in structural equality. For structural types (lists, records, tables), equality is defined recursively over their contents.
When building custom equality predicates or comparer functions for use with List.Sort, Table.Distinct, or similar functions, Value.Equals provides a clean, explicit equality check that is safe for null inputs.
Examples
Example 3: Null equals null returns true — unlike the = operator
Value.Equals(null, null)Result | |
|---|---|
| 1 | TRUE |
Example 4: Case-insensitive text comparison with a comparer
Value.Equals("Hello", "hello", Comparer.OrdinalIgnoreCase)Result | |
|---|---|
| 1 | TRUE |