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,73 @@ julia> emptymissing(first)([1], 2)
 """
 emptymissing(f) = (x, args...; kwargs...) -> isempty(x) ? missing : f(x, args...; kwargs...)
 
-end # module
+# 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`.
+
+The traditional `isless` function modified to treat `missing` as the smallest
+value can be accessed by using the 2-argument `missingsmallest(x, y)` function,
+see [`missingsmallest`](@ref).
+
+# Examples
+```
+julia> ismuchless = missingsmallest((x, y) -> isless(x, 10*y))
+julia> ismuchless(1, 100)
+true
+
+julia> ismuchless(-Inf, missing)
+false
+```
+"""
+missingsmallest(f) = MissingSmallest(f)
+
+"""
+    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), the 1-argument function which takes a
+partial ordering function (like `isless`) and modifies it to treat `missing` as
+explained above. These functions can be used together with sorting functions
+such that the first elements of the newly sorted Array are placed first.
+
+# Examples
+```
+julia> v = [missing, 10, missing, 1, 2]
+julia> sort(v, lt=missingsmallest)
+5-element Vector{Union{Missing, Int64}}:
+   missing
+   missing
+  1
+  2
+ 10
+
+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)
+
+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