Value.NullableEquals
ValueCompares two values for equality, returning null if either value is null (three-valued logic).
Syntax
Value.NullableEquals(value1 as any, value2 as any, optional comparer as nullable function) as nullable 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 for custom equality semantics. |
Return Value
logical — True if equal, false if not equal, null if either value is null.
Remarks
Value.NullableEquals implements three-valued equality (also called SQL-style equality): when either operand is null, the result is null — not true or false. This matches the behavior of the M = operator when applied to nullable values and mirrors SQL's IS DISTINCT FROM / = null semantics.
The three possible results are:
| value1 | value2 | Result |
|--------|--------|--------|
| non-null | non-null (equal) | true |
| non-null | non-null (different) | false |
| null | any | null |
| any | null | null |
This contrasts with Value.Equals(null, null) which always returns true — Value.Equals never returns null. Choose between the two based on whether you need null-propagating semantics:
- Use Value.NullableEquals when you want comparisons involving null to return null (propagate unknown), as in SQL WHERE clauses
- Use Value.Equals when you want null = null to be definitively true, as in deduplication or record matching
The optional comparer parameter allows custom equality logic (e.g., Comparer.OrdinalIgnoreCase) just like Value.Equals.
Examples
Example 3: Both null — returns null (unlike Value.Equals)
Value.NullableEquals(null, null)Result | |
|---|---|
| 1 | null |
Example 4: Both non-null and unequal — returns false
Value.NullableEquals("hello", "world")Result | |
|---|---|
| 1 | FALSE |