Implementing order functions where missings is the smallest value

README.md

@@ -28,6 +28,8 @@ This package provides additional functionality for working with `missing` values
 - `Missings.replace` to wrap a collection in a (possibly indexable) iterator replacing `missing` with another value
 - `Missings.fail` to wrap a collection in a (possibly indexable) iterator throwing an error if `missing` is encountered
 - `skipmissings` to loop through a collection of iterators excluding indices where any iterators are `missing`
+- `missingsmallest(f)` to create a partial order function that treats `missing` as the smallest value and otherwise behaves like `f`
+- `missingsmallest` the standard `isless` function modified to treat `missing` as the smallest value rather than the largest one
 
 ## Contributing and Questions
 

src/Missings.jl

@@ -2,7 +2,7 @@ module Missings
 
 export allowmissing, disallowmissing, ismissing, missing, missings,
        Missing, MissingException, levels, coalesce, passmissing, nonmissingtype,
-       skipmissings, emptymissing
+       skipmissings, emptymissing, missingsmallest
 
 using Base: ismissing, missing, Missing, MissingException
 
@@ -514,4 +514,77 @@ julia> emptymissing(first)([1], 2)
 """
 emptymissing(f) = (x, args...; kwargs...) -> isempty(x) ? missing : f(x, args...; kwargs...)
 
+# Only for internal use. Allows dispatch over anonymous functions.
+struct MissingSmallest{T}
+    lt::T
+end
+
+"""
+    missingsmallest(f)
+
+Creates a function of two arguments `x` and `y` that tests whether `x` is less
+than `y` such that `missing` is always less than the other argument. In other 
+words, returns a modified version of the partial order function `f` such that
+`missing` is the smallest possible value, and all other non-`missing` values are
+compared according to `f`.
+
+# Examples
+```
+julia> missingsmallest((x, y) -> isless(x, 10*y))(missing, Inf)
+true
+
+julia> missingsless(-Inf, missing)
+false
+```
+"""
+missingsmallest(f) = MissingSmallest(f)
+
+
+" The standard partial order `isless` modified so that `missing` is always the
+smallest possible value."
+
+"""
+    missingsmallest(x, y)
+
+The standard partial order `isless` modified so that `missing` is always the
+smallest possible value. The expected behaviour is the following:
+- If neither argument is `missing`, the function behaves exactly as `isless`.
+- If `x` is `missing` the result will be `true` regardless of the value of `y`.
+- If `y` is `missing` the result will be `false` regardless of the value of `x`.
+
+See also [`missingsmallest`](@ref), which modifies a partial order function and
+yields a function that behaves as the expected behaviour outlined above.
+
+# Examples
+```
+julia> missingsmallest(missing, Inf)
+true
+
+julia> missingsmallest(-Inf, missing)
+false
+
+julia> missingsmallest(missing, missing)
+true
+```
+"""
+missingsmallest(x, y) = missingsmallest(isless)(x, y)
+
+(ms::MissingSmallest)(x, y) = ismissing(y) ? false : ismissing(x) ? true : ms.lt(x, y)
+
+# Some optimizations
+const _MissingSmallest = Union{MissingSmallest, typeof(missingsmallest)}
+
+@static if isdefined(Base.Sort, :MissingOptimization) && isdefined(Base.Sort, :_sort!)
+    function Base.Sort._sort!(v::AbstractVector, a::Base.Sort.MissingOptimization,
+        o::Base.Order.Lt{<:_MissingSmallest}, kw)
+        # put missing at beginning
+        Base.Sort._sort!(v, a.next, withoutmissingordering(o), kw...;hi=new_hi)
+    end
+    function Base.Sort._sort!(v::AbstractVector, a::Base.Sort.MissingOptimization,
+        o::Base.Order.ReverseOrdering{Base.Order.Lt{<:_MissingSmallest}}, kw)
+        # put missing at end
+        Base.Sort._sort!(v, a.next, ReverseOrdering(withoutmissingordering(o.fwd)), kw...; lo=new_lo)
+    end
+end
+
 end # module

test/runtests.jl

@@ -257,4 +257,22 @@ struct CubeRooter end
     @test emptymissing(fun)(3, 1, c=2) == (1, 2)
 end
 
+@testset "missingsmallest" begin
+    @test missingsmallest(missing, Inf) == true
+    @test missingsmallest(-Inf, missing) == false
+    @test missingsmallest(missing, missing) == false
+    @test missingsmallest(3, 4) == true
+    @test missingsmallest(-Inf, Inf) == true 
+
+    ≪(x, y) = isless(10*x, y) # "Much greater than" function
+    missings_ll = missingsmallest(≪)
+    @test missings_ll(missing, Inf) == true
+    @test missings_ll(-Inf, missing) == false
+    @test missings_ll(1, 2) == false
+    @test missings_ll(1, 200) == true
+
+    @test_throws MethodError missingsmallest(isless)(isless)
+    @test missingsmallest !== missingsmallest(isless)
+end
+
 end