implement Base.mod (#114)

* implement Base.mod

* docstring

Co-authored-by: Yuto Horikawa <[email protected]>

* mod() for open and half-open intervals

Co-authored-by: Yuto Horikawa <[email protected]>

Author: aplavin

src/IntervalSets.jl

@@ -2,7 +2,7 @@ module IntervalSets
 
 using Base: @pure
 import Base: eltype, convert, show, in, length, isempty, isequal, issubset, ==, hash,
-             union, intersect, minimum, maximum, extrema, range, clamp, float, ⊇, ⊊, ⊋
+             union, intersect, minimum, maximum, extrema, range, clamp, mod, float, ⊇, ⊊, ⊋
 
 using Statistics
 import Statistics: mean
@@ -229,6 +229,46 @@ Clamp the scalar `t` such that the result is in the interval `i`.
 clamp(t, i::TypedEndpointsInterval{:closed,:closed}) =
     clamp(t, leftendpoint(i), rightendpoint(i))
 
+"""
+    mod(x, i::AbstractInterval)
+
+Find `y` in the `i` interval such that ``x ≡ y (mod w)``, where `w = width(i)`.
+
+# Examples
+
+```jldoctest
+julia> I = 2.5..4.5;
+
+julia> mod(3.0, I)
+3.0
+
+julia> mod(5.0, I)
+3.0
+
+julia> mod(2.5, I)
+2.5
+
+julia> mod(4.5, I)  # (a in I) does not imply (a == mod(a, I)) for closed intervals
+2.5
+
+julia> mod(4.5, Interval{:open, :closed}(2.5, 4.5))
+4.5
+```
+"""
+mod(x, i::TypedEndpointsInterval{:closed,:closed}) = mod(x - leftendpoint(i), width(i)) + leftendpoint(i)
+
+function mod(x, i::AbstractInterval)
+    res = mod(x - leftendpoint(i), width(i)) + leftendpoint(i)
+    if res == rightendpoint(i) && isrightopen(i)
+        isleftclosed(i) && return oftype(res, leftendpoint(i))
+    elseif res == leftendpoint(i) && isleftopen(i)
+        isrightclosed(i) && return oftype(res, rightendpoint(i))
+    else
+        return res
+    end
+    throw(DomainError(x, "mod() result is an endpoint of the open interval $i"))
+end
+
 include("interval.jl")
 include("findall.jl")
 

test/runtests.jl

@@ -728,6 +728,21 @@ struct IncompleteInterval <: AbstractInterval{Int} end
         @test clamp.([pi, 1.0, big(10.)], Ref(2..9.)) == [big(pi), 2, 9]
     end
 
+    @testset "mod" begin
+        @test mod(10, 0..3) === 1
+        @test mod(-10, 0..3) === 2
+        @test mod(10.5, 0..3) == 1.5
+        @test mod(10.5, 1..1) |> isnan
+        @test mod(10.5, Interval{:open, :open}(0, 3)) == 1.5
+        @test mod(10.5, Interval{:open, :open}(1, 1)) |> isnan
+
+        @test_throws DomainError mod(0, Interval{:open, :open}(0, 3))
+        for x in (0, 3, 0.0, -0.0, 3.0, -eps())
+            @test mod(x, Interval{:closed, :open}(0, 3))::typeof(x) == 0
+            @test mod(x, Interval{:open, :closed}(0, 3))::typeof(x) == 3
+        end
+    end
+
     @testset "rand" begin
         @test rand(1..2) isa Float64
         @test rand(1..2.) isa Float64