@@ -93,6 +93,10 @@ and of missing values. `isequal` treats all floating-point `NaN` values as equal
93
93
to each other, treats `-0.0` as unequal to `0.0`, and [`missing`](@ref) as equal
94
94
to `missing`. Always returns a `Bool` value.
95
95
96
+ `isequal` is an equivalence relation - it is reflexive (`===` implies `isequal`), symmetric
97
+ (`isequal(a, b)` implies `isequal(b, a)`) and transitive (`isequal(a, b)` and
98
+ `isequal(b, c)` implies `isequal(a, c)`).
99
+
96
100
# Implementation
97
101
The default implementation of `isequal` calls `==`, so a type that does not involve
98
102
floating-point values generally only needs to define `==`.
@@ -101,8 +105,12 @@ floating-point values generally only needs to define `==`.
101
105
that `hash(x) == hash(y)`.
102
106
103
107
This typically means that types for which a custom `==` or `isequal` method exists must
104
- implement a corresponding `hash` method (and vice versa). Collections typically implement
105
- `isequal` by calling `isequal` recursively on all contents.
108
+ implement a corresponding [`hash`](@ref) method (and vice versa). Collections typically
109
+ implement `isequal` by calling `isequal` recursively on all contents.
110
+
111
+ Furthermore, `isequal` is linked with [`isless`](@ref), and they work together to
112
+ define a fixed total ordering, where exactly one of `isequal(x, y)`, `isless(x, y)`, or
113
+ `isless(y, x)` must be `true` (and the other two `false`).
106
114
107
115
Scalar types generally do not need to implement `isequal` separate from `==`, unless they
108
116
represent floating-point numbers amenable to a more efficient implementation than that
@@ -121,6 +129,12 @@ true
121
129
122
130
julia> isequal(0.0, -0.0)
123
131
false
132
+
133
+ julia> missing == missing
134
+ missing
135
+
136
+ julia> isequal(missing, missing)
137
+ true
124
138
```
125
139
"""
126
140
isequal (x, y) = x == y
@@ -135,8 +149,8 @@ isequal(x::AbstractFloat, y::Real ) = (isnan(x) & isnan(y)) | signequal(
135
149
"""
136
150
isless(x, y)
137
151
138
- Test whether `x` is less than `y`, according to a fixed total order.
139
- `isless` is not defined on all pairs of values `(x, y)`. However, if it
152
+ Test whether `x` is less than `y`, according to a fixed total order (defined together with
153
+ [`isequal`](@ref)). `isless` is not defined on all pairs of values `(x, y)`. However, if it
140
154
is defined, it is expected to satisfy the following:
141
155
- If `isless(x, y)` is defined, then so is `isless(y, x)` and `isequal(x, y)`,
142
156
and exactly one of those three yields `true`.
0 commit comments