Relational Operations

===(x,y) -> Bool
≡(x,y) -> Bool

Determine whether x and y are identical, in the sense that no program could distinguish them. First the types of x and y are compared. If those are identical, mutable objects are compared by address in memory and immutable objects (such as numbers) are compared by contents at the bit level. This function is sometimes called "egal". It always returns a Bool value.

Examples

julia> a = [1, 2]; b = [1, 2];

julia> a == b
true

julia> a === b
false

julia> a === a
true

==(x, y)

Generic equality operator. Falls back to ===. Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Collections of the same type generally compare their key sets, and if those are ==, then compare the values for each of those keys, returning true if all such pairs are ==. Other properties are typically not taken into account (such as the exact type).

This operator follows IEEE semantics for floating-point numbers: 0.0 == -0.0 and NaN != NaN.

The result is of type Bool, except when one of the operands is missing, in which case missing is returned (three-valued logic). Collections generally implement three-valued logic akin to all, returning missing if any operands contain missing values and all other pairs are equal. Use isequal or === to always get a Bool result.

Implementation

New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible.

Equality and hashing are intimately related; two values that are considered isequal must have the same hash and by default isequal falls back to ==. If a type customizes the behavior of == and/or isequal, then hash must be similarly implemented to ensure isequal and hash agree. Sets, Dicts, and many other internal implementations assume that this invariant holds.

If some type defines ==, isequal, and isless then it should also implement < to ensure consistency of comparisons.

>=(x)

Create a function that compares its argument to x using >=, i.e. a function equivalent to y -> y >= x. The returned function is of type Base.Fix2{typeof(>=)}, which can be used to implement specialized methods.

>=(x, y)
≥(x,y)

Greater-than-or-equals comparison operator. Falls back to y <= x.

Examples

julia> 'a' >= 'b'
false

julia> 7 ≥ 7 ≥ 3
true

julia> "abc" ≥ "abc"
true

julia> 5 >= 3
true

>(x)

Create a function that compares its argument to x using >, i.e. a function equivalent to y -> y > x. The returned function is of type Base.Fix2{typeof(>)}, which can be used to implement specialized methods.

>(x, y)

Greater-than comparison operator. Falls back to y < x.

Implementation

Generally, new types should implement < instead of this function, and rely on the fallback definition >(x, y) = y < x.

Examples

julia> 'a' > 'b'
false

julia> 7 > 3 > 1
true

julia> "abc" > "abd"
false

julia> 5 > 3
true

<=(x)

Create a function that compares its argument to x using <=, i.e. a function equivalent to y -> y <= x. The returned function is of type Base.Fix2{typeof(<=)}, which can be used to implement specialized methods.

<=(x, y)
≤(x,y)

Less-than-or-equals comparison operator. Falls back to (x < y) | (x == y).

Examples

julia> 'a' <= 'b'
true

julia> 7 ≤ 7 ≤ 9
true

julia> "abc" ≤ "abc"
true

julia> 5 <= 3
false

<(x)

Create a function that compares its argument to x using <, i.e. a function equivalent to y -> y < x. The returned function is of type Base.Fix2{typeof(<)}, which can be used to implement specialized methods.

<(x, y)

Less-than comparison operator. Falls back to isless. Because of the behavior of floating-point NaN values, this operator implements a partial order.

Implementation

New types with a canonical partial order should implement this function for two arguments of the new type. Types with a canonical total order should implement isless instead.

See also isunordered.

Examples

julia> 'a' < 'b'
true

julia> "abc" < "abd"
true

julia> 5 < 3
false

!=(x)

Create a function that compares its argument to x using !=, i.e. a function equivalent to y -> y != x. The returned function is of type Base.Fix2{typeof(!=)}, which can be used to implement specialized methods.

!=(x, y)
≠(x,y)

Not-equals comparison operator. Always gives the opposite answer as ==.

Implementation

New types should generally not implement this, and rely on the fallback definition !=(x,y) = !(x==y) instead.

Examples

julia> 3 != 2
true

julia> "foo" ≠ "foo"
false

!==(x, y)
≢(x,y)

Always gives the opposite answer as ===.

Examples

julia> a = [1, 2]; b = [1, 2];

julia> a ≢ b
true

julia> a ≢ a
false

isequal(x)

Create a function that compares its argument to x using isequal, i.e. a function equivalent to y -> isequal(y, x).

The returned function is of type Base.Fix2{typeof(isequal)}, which can be used to implement specialized methods.

isequal(x, y) -> Bool

Similar to ==, except for the treatment of floating point numbers and of missing values. isequal treats all floating-point NaN values as equal to each other, treats -0.0 as unequal to 0.0, and missing as equal to missing. Always returns a Bool value.

isequal is an equivalence relation - it is reflexive (=== implies isequal), symmetric (isequal(a, b) implies isequal(b, a)) and transitive (isequal(a, b) and isequal(b, c) implies isequal(a, c)).

Implementation

The default implementation of isequal calls ==, so a type that does not involve floating-point values generally only needs to define ==.

isequal is the comparison function used by hash tables (Dict). isequal(x,y) must imply that hash(x) == hash(y).

This typically means that types for which a custom == or isequal method exists must implement a corresponding hash method (and vice versa). Collections typically implement isequal by calling isequal recursively on all contents.

Furthermore, isequal is linked with isless, and they work together to define a fixed total ordering, where exactly one of isequal(x, y), isless(x, y), or isless(y, x) must be true (and the other two false).

Scalar types generally do not need to implement isequal separate from ==, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on isnan, signbit, and ==).

Examples

julia> isequal([1., NaN], [1., NaN])
true

julia> [1., NaN] == [1., NaN]
false

julia> 0.0 == -0.0
true

julia> isequal(0.0, -0.0)
false

julia> missing == missing
missing

julia> isequal(missing, missing)
true

isless(x, y)

Test whether x is less than y, according to a fixed total order (defined together with isequal). isless is not defined for pairs (x, y) of all types. However, if it is defined, it is expected to satisfy the following:

• If isless(x, y) is defined, then so is isless(y, x) and isequal(x, y), and exactly one of those three yields true.
• The relation defined by isless is transitive, i.e., isless(x, y) && isless(y, z) implies isless(x, z).

Values that are normally unordered, such as NaN, are ordered after regular values. missing values are ordered last.

This is the default comparison used by sort!.

Implementation

Non-numeric types with a total order should implement this function. Numeric types only need to implement it if they have special values such as NaN. Types with a partial order should implement <. See the documentation on Alternate Orderings for how to define alternate ordering methods that can be used in sorting and related functions.

Examples

julia> isless(1, 3)
true

julia> isless("Red", "Blue")
false

isunordered(x)

Return true if x is a value that is not orderable according to <, such as NaN or missing.

The values that evaluate to true with this predicate may be orderable with respect to other orderings such as isless.

max(x, y, ...)

Return the maximum of the arguments, with respect to isless. If any of the arguments is missing, return missing. See also the maximum function to take the maximum element from a collection.

Examples

julia> max(2, 5, 1)
5

julia> max(5, missing, 6)
missing

min(x, y, ...)

Return the minimum of the arguments, with respect to isless. If any of the arguments is missing, return missing. See also the minimum function to take the minimum element from a collection.

Examples

julia> min(2, 5, 1)
1

julia> min(4, missing, 6)
missing

minmax(x, y)

Return (min(x,y), max(x,y)).

See also extrema that returns (minimum(x), maximum(x)).

Examples

julia> minmax('c','b')
('b', 'c')