Value.Compare
ValueCompares two values and returns -1, 0, or 1 indicating their relative order.
Syntax
Value.Compare(value1 as any, value2 as any, optional comparer as nullable function) as numberParameters
| Name | Type | Required | Description |
|---|---|---|---|
value1 | any | Yes | The first value. |
value2 | any | Yes | The second value. |
comparer | function | No | An optional comparer function. When omitted, the default ordering semantics are used. |
Return Value
number — -1 if value1 < value2, 0 if equal, 1 if value1 > value2.
Remarks
Value.Compare returns a signed integer indicating the ordering relationship between two values:
- -1 — value1 is less than value2
- 0 — the values are equal
- 1 — value1 is greater than value2
This three-way comparison result is the standard convention for comparer functions in M, compatible with the comparer parameter of List.Sort, Table.Sort, and similar functions. You can wrap Value.Compare in a lambda to build a custom comparer and pass it to these functions.
The optional third parameter accepts a comparer function (such as Comparer.OrdinalIgnoreCase or Comparer.FromCulture("fr-FR")) for locale-aware or case-insensitive comparisons. Without this parameter, the default ordinal ordering is used.
Note that Value.Compare expects values of comparable types — comparing a number to text will raise an error. For null-safe comparison, be aware that null sorts as the lowest value under the default ordering. To check equality specifically, consider Value.Equals or Value.NullableEquals instead.
Examples
Example 3: Use as a custom comparer in List.Sort for case-insensitive ordering
List.Sort({"banana", "Apple", "cherry"}, (a, b) => Value.Compare(a, b, Comparer.OrdinalIgnoreCase))Result | |
|---|---|
| 1 | Apple,banana,cherry |