Multi-interval set operators

.JuliaFormatter.toml

@@ -0,0 +1,2 @@
+style = "blue"
+margin = 92

.gitignore

@@ -5,3 +5,4 @@
 /docs/build/
 /docs/site/
 /Manifest.toml
+/test/Manifest.toml

Project.toml

@@ -22,9 +22,10 @@ julia = "1.6"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 Infinity = "a303e19e-6eb4-11e9-3b09-cd9505f79100"
+InvertedIndices = "41ab1584-1d38-5bbf-9106-f11c6c58b48f"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 VisualRegressionTests = "34922c18-7c2a-561c-bac1-01e79b2c4c92"
-
-[targets]
-test = ["Documenter", "ImageMagick", "Infinity", "Plots", "Test", "VisualRegressionTests"]

docs/src/index.md

@@ -26,21 +26,38 @@ This package defines:
   * [`Open`](@ref), indicating the endpoint value of the interval is not included
   * [`Unbounded`](@ref), indicating the endpoint value is effectively infinite
 
-## Example Usage
+## Sets
 
-### Intersection
+A single interval can be used to represent a contiguous set within a domain but cannot be
+used to represent a disjoint set. Due to this restriction all set-based operations that
+return an interval will always return a vector of intervals. These operations will combine
+any intervals which are overlapping or touching into a single continuous interval and never
+return an interval instance which itself is empty.
 
-```jldoctest
-julia> a = 1..10
-Interval{Int64, Closed, Closed}(1, 10)
+```julia
+julia> union([1..10], [5..15])
+1-element Vector{Interval{Int64, Closed, Closed}}:
+ Interval{Int64, Closed, Closed}(1, 15)
 
-julia> b = 5..15
-Interval{Int64, Closed, Closed}(5, 15)
+julia> intersect([1..10], [5..15])
+1-element Vector{Interval{Int64, Closed, Closed}}:
+ Interval{Int64, Closed, Closed}(5, 10)
 
-julia> intersect(a, b)
-Interval{Int64, Closed, Closed}(5, 10)
+julia> setdiff([1..10], [5..15])
+1-element Vector{Interval{Int64, Closed, Open}}:
+ Interval{Int64, Closed, Open}(1, 5)
+
+julia> symdiff([1..10], [5..15])
+2-element Vector{Interval{Int64}}:
+ Interval{Int64, Closed, Open}(1, 5)
+ Interval{Int64, Open, Closed}(10, 15)
+
+julia> intersect([1..5], [10..15])
+Interval[]
 ```
 
+## Example Usage
+
 ### Bounds
 
 ```jldoctest
@@ -135,31 +152,6 @@ julia> anchor(he)
 2013-02-13T01:00:00-06:00
 ```
 
-### Plotting
-`AbstractInterval` subtypes can be plotted with [Plots.jl](https://github.com/JuliaPlots/Plots.jl).
-
-
-```julia
-julia> using Plots
-
-julia> start_dt = DateTime(2017,1,1,0,0,0);
-
-julia> end_dt = DateTime(2017,1,1,10,30,0);
-
-julia> datetimes = start_dt:Hour(1):end_dt
-DateTime("2017-01-01T00:00:00"):Hour(1):DateTime("2017-01-01T10:00:00")
-
-julia> intervals = HE.(datetimes);
-
-julia> plot(intervals, 1:11)
-```
-
-![Example Plot](assets/HE.png)
-
-In the plot, inclusive boundaries are marked with a vertical bar, whereas exclusive boundaries just end.
-
-
-
 ### Comparisons
 
 #### Equality
@@ -247,6 +239,30 @@ julia> round(AnchoredInterval{+0.5}(0.5), on=:right)
 AnchoredInterval{0.5, Float64, Closed, Open}(0.5)
 ```
 
+### Plotting
+
+`AbstractInterval` subtypes can be plotted with [Plots.jl](https://github.com/JuliaPlots/Plots.jl).
+
+```julia
+julia> using Plots
+
+julia> start_dt = DateTime(2017,1,1,0,0,0);
+
+julia> end_dt = DateTime(2017,1,1,10,30,0);
+
+julia> datetimes = start_dt:Hour(1):end_dt
+DateTime("2017-01-01T00:00:00"):Hour(1):DateTime("2017-01-01T10:00:00")
+
+julia> intervals = HE.(datetimes);
+
+julia> plot(intervals, 1:11)
+```
+
+![Example Plot](assets/HE.png)
+
+In the plot, inclusive boundaries are marked with a vertical bar, whereas exclusive boundaries just end.
+
+
 ## API
 
 ```@docs

src/Intervals.jl

@@ -27,6 +27,7 @@ bounds_types(x::AbstractInterval{T,L,R}) where {T,L,R} = (L, R)
 include("isfinite.jl")
 include("endpoint.jl")
 include("interval.jl")
+include("interval_sets.jl")
 include("anchoredinterval.jl")
 include("parse.jl")
 include("description.jl")

src/endpoint.jl

@@ -6,7 +6,8 @@ const Right = Direction{:Right}()
 const Beginning = Left
 const Ending = Right
 
-struct Endpoint{T, D, B <: Bound}
+abstract type AbstractEndpoint end
+struct Endpoint{T, D, B <: Bound} <: AbstractEndpoint
     endpoint::T
 
     function Endpoint{T,D,B}(ep::T) where {T, D, B <: Bounded}

src/interval.jl

@@ -405,60 +405,6 @@ function Base.intersect(a::AbstractInterval{S}, b::AbstractInterval{T}) where {S
     return Interval(left, right)
 end
 
-# There is power in a union.
-"""
-    union(intervals::AbstractVector{<:AbstractInterval})
-
-Flattens a vector of overlapping intervals into a new, smaller vector containing only
-non-overlapping intervals.
-"""
-function Base.union(intervals::AbstractVector{<:AbstractInterval})
-    return union!(convert(Vector{AbstractInterval}, intervals))
-end
-
-"""
-    union!(intervals::AbstractVector{<:Union{Interval, AbstractInterval}})
-
-Flattens a vector of overlapping intervals in-place to be a smaller vector containing only
-non-overlapping intervals.
-"""
-function Base.union!(intervals::Union{AbstractVector{<:Interval}, AbstractVector{AbstractInterval}})
-    sort!(intervals)
-
-    i = 2
-    n = length(intervals)
-    while i <= n
-        prev = intervals[i - 1]
-        curr = intervals[i]
-
-        # If the current and previous intervals don't meet then move along
-        if !overlaps(prev, curr) && !contiguous(prev, curr)
-            i = i + 1
-
-        # If the two intervals meet then we absorb the current interval into
-        # the previous one.
-        else
-            intervals[i - 1] = merge(prev, curr)
-            deleteat!(intervals, i)
-            n -= 1
-        end
-    end
-
-    return intervals
-end
-
-"""
-    superset(intervals::AbstractArray{<:AbstractInterval}) -> Interval
-
-Create the smallest single interval which encompasses all of the provided intervals.
-"""
-function superset(intervals::AbstractArray{<:AbstractInterval})
-    left = minimum(LeftEndpoint.(intervals))
-    right = maximum(RightEndpoint.(intervals))
-
-    return Interval(left, right)
-end
-
 function Base.merge(a::AbstractInterval, b::AbstractInterval)
     if !overlaps(a, b) && !contiguous(a, b)
         throw(ArgumentError("$a and $b are neither overlapping or contiguous."))