Add the concat, union, except and intersect set operators

Ports Enumerable.Concat/Union/UnionBy/Except/ExceptBy/Intersect/IntersectBy.
union, except and intersect shadow their Base counterparts, as map, filter,
count, take, unique and join already do here.

concat is fully lazy and reports a length when both sources have one. union
is lazy over both sources behind a growing set of seen keys; except and
intersect materialise the second source's keys on first iterate and then walk
the first source lazily. All three de-duplicate their output, matching .NET.

One deliberate deviation: Enumerable.ExceptBy and IntersectBy take a bare
sequence of keys as their second argument, while UnionBy takes a sequence of
elements. Here the key selector is applied to both sequences in all three
cases. That keeps the operators consistent with each other, matches the shape
of the equivalent SQL, and is what a table-shaped second argument makes
natural.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: davidanthoff

src/QueryOperators.jl

@@ -26,6 +26,10 @@ include("enumerable/enumerable_count.jl")
 include("enumerable/enumerable_take.jl")
 include("enumerable/enumerable_drop.jl")
 include("enumerable/enumerable_unique.jl")
+include("enumerable/enumerable_concat.jl")
+include("enumerable/enumerable_union.jl")
+include("enumerable/enumerable_except.jl")
+include("enumerable/enumerable_intersect.jl")
 include("enumerable/enumerable_pivot.jl")
 include("enumerable/enumerable_summarize.jl")
 include("enumerable/show.jl")

src/enumerable/enumerable.jl

@@ -4,3 +4,26 @@ Base.IteratorSize(::Type{T}) where {T <: Enumerable} = Base.SizeUnknown()
 IteratorInterfaceExtensions.isiterable(x::Enumerable) = true
 
 haslength(S) = Base.IteratorSize(S) isa Union{Base.HasLength, Base.HasShape} ? Base.HasLength() : Base.IteratorSize(S)
+
+# Operators that walk more than one source keep "which source, how far into it"
+# in their iteration state. `_NotStarted` marks a source that has not been
+# iterated yet, so that `_iterate_from` can pick the right `iterate` method
+# without conflating it with a source whose own state happens to be `nothing`.
+struct _NotStarted end
+
+_iterate_from(source, ::_NotStarted) = iterate(source)
+_iterate_from(source, state) = iterate(source, state)
+
+# Element types of two sources that will be emitted into a single stream have
+# to agree, the same requirement `default_if_empty` places on its default value.
+function _check_same_eltype(op, ::Type{T1}, ::Type{T2}) where {T1,T2}
+    if T1 != T2
+        error("The two sequences passed to $op have different element types, $T1 and $T2.")
+    end
+end
+
+function _check_same_keytype(op, ::Type{TKey1}, ::Type{TKey2}) where {TKey1,TKey2}
+    if TKey1 != TKey2
+        error("The keys of the two sequences passed to $op have different types, $TKey1 and $TKey2.")
+    end
+end

src/enumerable/enumerable_concat.jl

@@ -0,0 +1,44 @@
+struct EnumerableConcat{T,S1,S2} <: Enumerable
+    first::S1
+    second::S2
+end
+
+function concat(first::Enumerable, second::Enumerable)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    _check_same_eltype("concat", T1, T2)
+
+    return EnumerableConcat{T1,typeof(first),typeof(second)}(first, second)
+end
+
+Base.eltype(::Type{EnumerableConcat{T,S1,S2}}) where {T,S1,S2} = T
+
+function Base.IteratorSize(::Type{EnumerableConcat{T,S1,S2}}) where {T,S1,S2}
+    return haslength(S1) isa Base.HasLength && haslength(S2) isa Base.HasLength ?
+        Base.HasLength() : Base.SizeUnknown()
+end
+
+Base.length(iter::EnumerableConcat) = length(iter.first) + length(iter.second)
+
+Base.iterate(iter::EnumerableConcat) = _concat_next(iter, 1, _NotStarted())
+
+function Base.iterate(iter::EnumerableConcat, state)
+    return _concat_next(iter, state.side, state.state)
+end
+
+function _concat_next(iter::EnumerableConcat, side, source_state)
+    if side == 1
+        ret = _iterate_from(iter.first, source_state)
+        if ret !== nothing
+            return ret[1], (side=1, state=ret[2])
+        end
+        # First source exhausted — fall through to the second.
+        side = 2
+        source_state = _NotStarted()
+    end
+
+    ret = _iterate_from(iter.second, source_state)
+    ret === nothing && return nothing
+    return ret[1], (side=2, state=ret[2])
+end

src/enumerable/enumerable_except.jl

@@ -0,0 +1,62 @@
+struct EnumerableExcept{T,TKEY,S1,S2,Q<:Function} <: Enumerable
+    first::S1
+    second::S2
+    f::Q
+end
+
+Base.eltype(::Type{EnumerableExcept{T,TKEY,S1,S2,Q}}) where {T,TKEY,S1,S2,Q} = T
+
+function except(first::Enumerable, second::Enumerable)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    _check_same_eltype("except", T1, T2)
+
+    return EnumerableExcept{T1,T1,typeof(first),typeof(second),typeof(identity)}(first, second, identity)
+end
+
+# Unlike Enumerable.ExceptBy, whose second argument is a sequence of keys, the
+# key selector here is applied to both sequences. That keeps `except_by`
+# consistent with `union_by`, matches the shape of the equivalent SQL
+# (`WHERE k NOT IN (SELECT k FROM b)`), and is what a table-shaped second
+# argument makes natural.
+function except_by(first::Enumerable, second::Enumerable, f::Function, f_expr::Expr)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    TKEY1 = Base._return_type(f, Tuple{T1,})
+    TKEY2 = Base._return_type(f, Tuple{T2,})
+
+    _check_same_keytype("except_by", TKEY1, TKEY2)
+
+    return EnumerableExcept{T1,TKEY1,typeof(first),typeof(second),typeof(f)}(first, second, f)
+end
+
+function Base.iterate(iter::EnumerableExcept{T,TKEY,S1,S2,Q}) where {T,TKEY,S1,S2,Q}
+    excluded = Set{TKEY}()
+    for i in iter.second
+        push!(excluded, iter.f(i))
+    end
+
+    return _except_next(iter, excluded, Set{TKEY}(), _NotStarted())
+end
+
+function Base.iterate(iter::EnumerableExcept, state)
+    return _except_next(iter, state.excluded, state.observed, state.state)
+end
+
+# Yields the distinct elements of the first source whose key does not occur in
+# the second, matching Enumerable.Except's de-duplicating behaviour.
+function _except_next(iter::EnumerableExcept, excluded, observed, source_state)
+    while true
+        ret = _iterate_from(iter.first, source_state)
+        ret === nothing && return nothing
+
+        element, source_state = ret
+        k = iter.f(element)
+        if !(k in excluded) && !(k in observed)
+            push!(observed, k)
+            return element, (excluded=excluded, observed=observed, state=source_state)
+        end
+    end
+end

src/enumerable/enumerable_intersect.jl

@@ -0,0 +1,59 @@
+struct EnumerableIntersect{T,TKEY,S1,S2,Q<:Function} <: Enumerable
+    first::S1
+    second::S2
+    f::Q
+end
+
+Base.eltype(::Type{EnumerableIntersect{T,TKEY,S1,S2,Q}}) where {T,TKEY,S1,S2,Q} = T
+
+function intersect(first::Enumerable, second::Enumerable)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    _check_same_eltype("intersect", T1, T2)
+
+    return EnumerableIntersect{T1,T1,typeof(first),typeof(second),typeof(identity)}(first, second, identity)
+end
+
+# As with `except_by`, the key selector is applied to both sequences rather than
+# the second being a bare sequence of keys as in Enumerable.IntersectBy.
+function intersect_by(first::Enumerable, second::Enumerable, f::Function, f_expr::Expr)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    TKEY1 = Base._return_type(f, Tuple{T1,})
+    TKEY2 = Base._return_type(f, Tuple{T2,})
+
+    _check_same_keytype("intersect_by", TKEY1, TKEY2)
+
+    return EnumerableIntersect{T1,TKEY1,typeof(first),typeof(second),typeof(f)}(first, second, f)
+end
+
+function Base.iterate(iter::EnumerableIntersect{T,TKEY,S1,S2,Q}) where {T,TKEY,S1,S2,Q}
+    required = Set{TKEY}()
+    for i in iter.second
+        push!(required, iter.f(i))
+    end
+
+    return _intersect_next(iter, required, Set{TKEY}(), _NotStarted())
+end
+
+function Base.iterate(iter::EnumerableIntersect, state)
+    return _intersect_next(iter, state.required, state.observed, state.state)
+end
+
+# Yields the distinct elements of the first source whose key also occurs in the
+# second, matching Enumerable.Intersect's de-duplicating behaviour.
+function _intersect_next(iter::EnumerableIntersect, required, observed, source_state)
+    while true
+        ret = _iterate_from(iter.first, source_state)
+        ret === nothing && return nothing
+
+        element, source_state = ret
+        k = iter.f(element)
+        if k in required && !(k in observed)
+            push!(observed, k)
+            return element, (required=required, observed=observed, state=source_state)
+        end
+    end
+end

src/enumerable/enumerable_union.jl

@@ -0,0 +1,58 @@
+struct EnumerableUnion{T,TKEY,S1,S2,Q<:Function} <: Enumerable
+    first::S1
+    second::S2
+    f::Q
+end
+
+Base.eltype(::Type{EnumerableUnion{T,TKEY,S1,S2,Q}}) where {T,TKEY,S1,S2,Q} = T
+
+function union(first::Enumerable, second::Enumerable)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    _check_same_eltype("union", T1, T2)
+
+    return EnumerableUnion{T1,T1,typeof(first),typeof(second),typeof(identity)}(first, second, identity)
+end
+
+function union_by(first::Enumerable, second::Enumerable, f::Function, f_expr::Expr)
+    T1 = eltype(first)
+    T2 = eltype(second)
+
+    _check_same_eltype("union_by", T1, T2)
+
+    TKEY = Base._return_type(f, Tuple{T1,})
+
+    return EnumerableUnion{T1,TKEY,typeof(first),typeof(second),typeof(f)}(first, second, f)
+end
+
+function Base.iterate(iter::EnumerableUnion{T,TKEY,S1,S2,Q}) where {T,TKEY,S1,S2,Q}
+    return _union_next(iter, Set{TKEY}(), 1, _NotStarted())
+end
+
+function Base.iterate(iter::EnumerableUnion, state)
+    return _union_next(iter, state.observed, state.side, state.state)
+end
+
+# Walks the first source and then the second, yielding each element whose key
+# has not been seen before, so that the result is distinct across both sources.
+function _union_next(iter::EnumerableUnion{T,TKEY,S1,S2,Q}, observed, side, source_state) where {T,TKEY,S1,S2,Q}
+    while true
+        source = side == 1 ? iter.first : iter.second
+        ret = _iterate_from(source, source_state)
+
+        if ret === nothing
+            side == 2 && return nothing
+            side = 2
+            source_state = _NotStarted()
+            continue
+        end
+
+        element, source_state = ret
+        k = iter.f(element)
+        if !(k in observed)
+            push!(observed, k)
+            return element, (observed=observed, side=side, state=source_state)
+        end
+    end
+end

src/operators.jl

@@ -138,3 +138,21 @@ function left_join end
 function right_join end
 
 function full_join end
+
+# Set operations. `union`, `except` and `intersect` shadow their Base
+# counterparts, as `map`, `filter`, `count`, `take`, `unique` and `join`
+# already do in this module.
+
+function concat end
+
+function union end
+
+function union_by end
+
+function except end
+
+function except_by end
+
+function intersect end
+
+function intersect_by end

test/runtests.jl

@@ -2,6 +2,7 @@ using TestItemRunner
 
 include("test_core.jl")
 include("test_enumerable_outerjoins.jl")
+include("test_enumerable_setops.jl")
 include("test_enumerable_unique.jl")
 include("test_enumerable_summarize.jl")
 include("test_namedtupleutilities.jl")