Add the append, prepend and zip operators

Ports Enumerable.Append, Prepend and Zip. append and zip shadow their Base
counterparts.

append and prepend convert the extra element to the source's element type, so
appending an Int to a sequence of Float64 works rather than erroring.

zip stops at the shorter of its two sources, matching both Base.zip and .NET.
Nothing is padded, so zip manufactures no null values — a test asserts the
result contains neither missing nor DataValue. Without a result selector it
yields Tuples, as Base.zip and Enumerable.Zip both do.

All three are lazy, and zip pulls at most one element past the end of the
shorter source.

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

Author: davidanthoff

src/QueryOperators.jl

@@ -38,6 +38,9 @@ include("enumerable/enumerable_intersect.jl")
 include("enumerable/enumerable_reverse.jl")
 include("enumerable/enumerable_shuffle.jl")
 include("enumerable/enumerable_index.jl")
+include("enumerable/enumerable_append.jl")
+include("enumerable/enumerable_prepend.jl")
+include("enumerable/enumerable_zip.jl")
 include("enumerable/enumerable_pivot.jl")
 include("enumerable/enumerable_summarize.jl")
 include("enumerable/enumerable_countby.jl")

src/enumerable/enumerable_append.jl

@@ -0,0 +1,32 @@
+struct EnumerableAppend{T,S} <: Enumerable
+    source::S
+    element::T
+end
+
+# Enumerable.Append: the source followed by one more element. The element is
+# converted to the source's element type, so appending an Int to a sequence of
+# Float64 works.
+function append(source::Enumerable, element)
+    T = eltype(source)
+    return EnumerableAppend{T,typeof(source)}(source, convert(T, element))
+end
+
+Base.IteratorSize(::Type{EnumerableAppend{T,S}}) where {T,S} = haslength(S)
+
+Base.eltype(::Type{EnumerableAppend{T,S}}) where {T,S} = T
+
+Base.length(iter::EnumerableAppend) = length(iter.source) + 1
+
+Base.iterate(iter::EnumerableAppend) = _append_next(iter, _NotStarted())
+
+function Base.iterate(iter::EnumerableAppend, state)
+    # `state.done` marks the appended element as already handed out.
+    state.done && return nothing
+    return _append_next(iter, state.state)
+end
+
+function _append_next(iter::EnumerableAppend, source_state)
+    ret = _iterate_from(iter.source, source_state)
+    ret === nothing && return iter.element, (done=true, state=source_state)
+    return ret[1], (done=false, state=ret[2])
+end

src/enumerable/enumerable_prepend.jl

@@ -0,0 +1,25 @@
+struct EnumerablePrepend{T,S} <: Enumerable
+    source::S
+    element::T
+end
+
+# Enumerable.Prepend: one element followed by the source. As with `append`, the
+# element is converted to the source's element type.
+function prepend(source::Enumerable, element)
+    T = eltype(source)
+    return EnumerablePrepend{T,typeof(source)}(source, convert(T, element))
+end
+
+Base.IteratorSize(::Type{EnumerablePrepend{T,S}}) where {T,S} = haslength(S)
+
+Base.eltype(::Type{EnumerablePrepend{T,S}}) where {T,S} = T
+
+Base.length(iter::EnumerablePrepend) = length(iter.source) + 1
+
+Base.iterate(iter::EnumerablePrepend) = (iter.element, (state=_NotStarted(),))
+
+function Base.iterate(iter::EnumerablePrepend, state)
+    ret = _iterate_from(iter.source, state.state)
+    ret === nothing && return nothing
+    return ret[1], (state=ret[2],)
+end

src/enumerable/enumerable_zip.jl

@@ -0,0 +1,46 @@
+struct EnumerableZip{T,S1,S2,RS<:Function} <: Enumerable
+    first::S1
+    second::S2
+    resultSelector::RS
+end
+
+Base.eltype(::Type{EnumerableZip{T,S1,S2,RS}}) where {T,S1,S2,RS} = T
+
+# Enumerable.Zip. Like Base.zip and .NET, the result stops at the shorter of
+# the two sources — nothing is padded, so no null values are manufactured.
+function zip(first::Enumerable, second::Enumerable)
+    return _zip(first, second, tuple)
+end
+
+function zip(first::Enumerable, second::Enumerable, f_resultSelector::Function, resultSelector::Expr)
+    return _zip(first, second, f_resultSelector)
+end
+
+function _zip(first::Enumerable, second::Enumerable, f_resultSelector::Function)
+    T1 = eltype(first)
+    T2 = eltype(second)
+    T = Base._return_type(f_resultSelector, Tuple{T1,T2})
+
+    return EnumerableZip{T,typeof(first),typeof(second),typeof(f_resultSelector)}(first, second, f_resultSelector)
+end
+
+function Base.IteratorSize(::Type{EnumerableZip{T,S1,S2,RS}}) where {T,S1,S2,RS}
+    return haslength(S1) isa Base.HasLength && haslength(S2) isa Base.HasLength ?
+        Base.HasLength() : Base.SizeUnknown()
+end
+
+Base.length(iter::EnumerableZip) = min(length(iter.first), length(iter.second))
+
+Base.iterate(iter::EnumerableZip) = _zip_next(iter, _NotStarted(), _NotStarted())
+
+Base.iterate(iter::EnumerableZip, state) = _zip_next(iter, state.s1, state.s2)
+
+function _zip_next(iter::EnumerableZip, s1, s2)
+    r1 = _iterate_from(iter.first, s1)
+    r1 === nothing && return nothing
+
+    r2 = _iterate_from(iter.second, s2)
+    r2 === nothing && return nothing
+
+    return iter.resultSelector(r1[1], r2[1]), (s1=r1[2], s2=r2[2])
+end

src/operators.jl

@@ -191,3 +191,11 @@ function drop_while end
 function take_last end
 
 function drop_last end
+
+# Combining sequences. `append` and `zip` shadow their Base counterparts.
+
+function append end
+
+function prepend end
+
+function zip end

test/runtests.jl

@@ -6,6 +6,7 @@ include("test_enumerable_setops.jl")
 include("test_enumerable_ordering.jl")
 include("test_enumerable_keyed_aggregation.jl")
 include("test_enumerable_partitioning.jl")
+include("test_enumerable_combining.jl")
 include("test_enumerable_unique.jl")
 include("test_enumerable_summarize.jl")
 include("test_namedtupleutilities.jl")

test/test_enumerable_combining.jl

@@ -0,0 +1,154 @@
+@testitem "append" begin
+    source = QueryOperators.query([1, 2, 3])
+
+    res = QueryOperators.append(source, 4)
+
+    @test collect(res) == [1, 2, 3, 4]
+    @test eltype(res) == Int
+    @test Base.IteratorSize(typeof(res)) == Base.HasLength()
+    @test length(res) == 4
+end
+
+@testitem "append to an empty source" begin
+    source = QueryOperators.query(Int[])
+
+    @test collect(QueryOperators.append(source, 1)) == [1]
+end
+
+@testitem "append converts the element to the source element type" begin
+    source = QueryOperators.query([1.0, 2.0])
+
+    res = QueryOperators.append(source, 3)
+
+    @test collect(res) == [1.0, 2.0, 3.0]
+    @test eltype(res) == Float64
+end
+
+@testitem "append rejects an element that cannot be converted" begin
+    source = QueryOperators.query([1, 2])
+
+    @test_throws MethodError QueryOperators.append(source, "three")
+end
+
+@testitem "append of NamedTuple rows" begin
+    source = QueryOperators.query([(a=1, b="x")])
+
+    res = QueryOperators.append(source, (a=2, b="y"))
+
+    @test collect(res) == [(a=1, b="x"), (a=2, b="y")]
+end
+
+@testitem "prepend" begin
+    source = QueryOperators.query([2, 3])
+
+    res = QueryOperators.prepend(source, 1)
+
+    @test collect(res) == [1, 2, 3]
+    @test eltype(res) == Int
+    @test Base.IteratorSize(typeof(res)) == Base.HasLength()
+    @test length(res) == 3
+end
+
+@testitem "prepend to an empty source" begin
+    source = QueryOperators.query(Int[])
+
+    @test collect(QueryOperators.prepend(source, 1)) == [1]
+end
+
+@testitem "append and prepend compose" begin
+    source = QueryOperators.query([2, 3])
+
+    res = QueryOperators.append(QueryOperators.prepend(source, 1), 4)
+
+    @test collect(res) == [1, 2, 3, 4]
+    @test length(res) == 4
+end
+
+@testitem "zip" begin
+    a = QueryOperators.query([1, 2, 3])
+    b = QueryOperators.query(["a", "b", "c"])
+
+    res = QueryOperators.zip(a, b)
+
+    @test collect(res) == [(1, "a"), (2, "b"), (3, "c")]
+    @test eltype(res) == Tuple{Int,String}
+    @test Base.IteratorSize(typeof(res)) == Base.HasLength()
+    @test length(res) == 3
+end
+
+@testitem "zip truncates to the shorter source" begin
+    a = QueryOperators.query([1, 2, 3, 4])
+    b = QueryOperators.query(["a", "b"])
+
+    @test collect(QueryOperators.zip(a, b)) == [(1, "a"), (2, "b")]
+    @test length(QueryOperators.zip(a, b)) == 2
+    @test collect(QueryOperators.zip(b, a)) == [("a", 1), ("b", 2)]
+end
+
+@testitem "zip with an empty source" begin
+    a = QueryOperators.query([1, 2])
+    empty = QueryOperators.query(String[])
+
+    @test collect(QueryOperators.zip(a, empty)) == Tuple{Int,String}[]
+    @test collect(QueryOperators.zip(empty, a)) == Tuple{String,Int}[]
+end
+
+@testitem "zip with a result selector" begin
+    a = QueryOperators.query([1, 2, 3])
+    b = QueryOperators.query([10, 20, 30])
+
+    res = QueryOperators.zip(a, b, (x, y) -> (sum=x + y,), :((x, y) -> (sum=x + y,)))
+
+    @test collect(res) == [(sum=11,), (sum=22,), (sum=33,)]
+    @test eltype(res) == NamedTuple{(:sum,),Tuple{Int}}
+end
+
+@testitem "zip pads nothing, so it manufactures no null values" begin
+    using DataValues
+
+    a = QueryOperators.query([1, 2, 3])
+    b = QueryOperators.query([10])
+
+    res = collect(QueryOperators.zip(a, b))
+
+    @test length(res) == 1
+    @test !any(r -> any(ismissing, r), res)
+    @test !any(r -> any(x -> x isa DataValue, r), res)
+end
+
+@testitem "zip does not over-read the longer source" begin
+    import IteratorInterfaceExtensions
+
+    mutable struct CountedZipSource
+        data::Vector{Int}
+        pulled::Int
+    end
+    Base.eltype(::Type{CountedZipSource}) = Int
+    Base.IteratorSize(::Type{CountedZipSource}) = Base.HasLength()
+    Base.length(c::CountedZipSource) = length(c.data)
+    function Base.iterate(c::CountedZipSource, i=1)
+        i > length(c.data) && return nothing
+        c.pulled += 1
+        return c.data[i], i + 1
+    end
+    IteratorInterfaceExtensions.isiterable(::CountedZipSource) = true
+    IteratorInterfaceExtensions.getiterator(c::CountedZipSource) = c
+
+    long = CountedZipSource(collect(1:100), 0)
+    res = QueryOperators.zip(QueryOperators.query(long), QueryOperators.query([1, 2]))
+
+    @test length(collect(res)) == 2
+    # Three pulls: two matched, plus the one that had no partner.
+    @test long.pulled == 3
+end
+
+@testitem "combining operators work downstream of groupby" begin
+    source = QueryOperators.query([(k=1, v=1), (k=2, v=2)])
+    grouped = QueryOperators.@groupby_simple(source, i -> i.k)
+
+    zipped = collect(QueryOperators.zip(grouped, QueryOperators.query(["first", "second"])))
+
+    @test length(zipped) == 2
+    @test [QueryOperators.key(g) for (g, _) in zipped] == [1, 2]
+    @test [s for (_, s) in zipped] == ["first", "second"]
+end