Add a contract for Ordered and additional traits

base/traits.jl

@@ -1,17 +1,49 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 ## numeric/object traits
-# trait for objects that have an ordering
+
+"""
+    OrderedStyle()
+
+An abstract type of a trait that signals if some type `T` guarantees
+that a call `isless(::T, ::T)` will return `true` or `false`.
+
+It has two concrete subtypes [`Ordered`](@ref) and
+[`Unordered`](@ref), which is the default.
+
+Types guaranteeing the support [`isless`](@ref) are recommend to support
+[`Ordered`](@ref) trait to enable optimizations.
+"""
 abstract type OrderStyle end
+
+"""
+    Ordered()
+
+Indicate that a type `T` guarantees that a call `isless(::T, ::T)` will return `true` or `false`.
+It is recommended that custom types defining `isless` implement this
+trait as this information can be used to enable optimizations.
+"""
 struct Ordered <: OrderStyle end
+
+"""
+    Unordered()
+
+A default `OrderStyle` for any type `T` indicating that optimizations
+cannot rely on the fact that it is guaranteed that a call `isless(::T, ::T)`
+will return `true` or `false`.
+"""
 struct Unordered <: OrderStyle end
 
 OrderStyle(instance) = OrderStyle(typeof(instance))
-OrderStyle(::Type{<:Real}) = Ordered()
-OrderStyle(::Type{<:AbstractString}) = Ordered()
+OrderStyle(::Type{Union{}}) = Ordered()
+OrderStyle(::Type{<:Union{Missing,Real}}) = Ordered()
+OrderStyle(::Type{<:Union{Missing,AbstractString}}) = Ordered()
+OrderStyle(::Type{<:Union{Missing,AbstractChar}}) = Ordered()
+OrderStyle(::Type{<:Union{Missing,Symbol}}) = Ordered()
+OrderStyle(::Type{<:Union{Missing,CartesianIndex}}) = Ordered()
 OrderStyle(::Type{Symbol}) = Ordered()
+OrderStyle(::Type{Missing}) = Ordered()
 OrderStyle(::Type{<:Any}) = Unordered()
-OrderStyle(::Type{Union{}}) = Ordered()
 
 # trait for objects that support arithmetic
 abstract type ArithmeticStyle end

stdlib/Dates/src/periods.jl

@@ -72,6 +72,7 @@ default(p::Union{T,Type{T}}) where {T<:TimePeriod} = T(0)
 ==(x::Period, y::Period) = (==)(promote(x, y)...)
 Base.isless(x::P, y::P) where {P<:Period} = isless(value(x), value(y))
 Base.isless(x::Period, y::Period) = isless(promote(x, y)...)
+Base.OrderStyle(::Type{<:Union{Missing,Period}}) = Base.Ordered()
 
 # Period Arithmetic, grouped by dimensionality:
 for op in (:+, :-, :lcm, :gcd)

stdlib/Dates/src/types.jl

@@ -433,6 +433,7 @@ Base.typemin(::Union{Time, Type{Time}}) = Time(0)
 Base.promote_rule(::Type{Date}, x::Type{DateTime}) = DateTime
 Base.isless(x::T, y::T) where {T<:TimeType} = isless(value(x), value(y))
 Base.isless(x::TimeType, y::TimeType) = isless(promote(x, y)...)
+Base.OrderStyle(::Type{<:Union{Missing,TimeType}}) = Base.Ordered()
 (==)(x::T, y::T) where {T<:TimeType} = (==)(value(x), value(y))
 (==)(x::TimeType, y::TimeType) = (===)(promote(x, y)...)
 Base.min(x::AbstractTime) = x

stdlib/Test/src/Test.jl

@@ -1647,6 +1647,7 @@ struct GenericOrder{T}
     val::T
 end
 Base.isless(x::GenericOrder, y::GenericOrder) = isless(x.val,y.val)
+Base.OrderStyle(::Type{<:Union{Missing,GenericOrder}}) = Base.Ordered()
 
 Base.keys(a::GenericArray) = keys(a.a)
 Base.axes(a::GenericArray) = axes(a.a)