Create Iterators.first and Iterators.last

Instead of creating a version of Base.first and Base.last accepting a
predicate, create functions in the Iterators module. This allows easy
composition with Iterators.filter without having to accept a predicate
argument.

Author: non-Jedi

base/abstractarray.jl

@@ -343,38 +343,6 @@ function first(itr)
     x[1]
 end
 
-"""
-    first(predicate, coll)
-
-Get the first element of `coll` satisfying `predicate` wrapped in [`Some`](@ref).
-
-If no element of `coll` satisfies `predicate`, return `nothing`.
-
-!!! compat "Julia 1.6"
-    This method was added in Julia 1.6.
-
-# Examples
-```jldoctest
-julia> first(>(5), 1:10)
-Some(6)
-
-julia> isnothing(first(isodd, 2:2:10))
-true
-
-julia> something(first(iseven, [5, 3, 4, 2, 6, 8]))
-4
-
-julia> something(first(>(10), 1:10), 0)
-0
-```
-"""
-function first(predicate, itr)
-    for x in itr
-        predicate(x) && return Some(x)
-    end
-    return nothing
-end
-
 """
     first(itr, n::Integer)
 
@@ -420,47 +388,6 @@ julia> last([1; 2; 3; 4])
 """
 last(a) = a[end]
 
-"""
-    last(predicate, coll)
-
-Get the last element of `coll` satisfying `predicate` wrapped in [`Some`](@ref).
-
-If no element of `coll` satisfies `predicate`, return `nothing`.
-
-!!! compat "Julia 1.6"
-    This method was added in Julia 1.6.
-    
-# Examples
-```jldoctest
-julia> last(<(5), 1:10)
-Some(4)
-
-julia> isnothing(last(isodd, 2:2:10))
-true
-
-julia> something(last(iseven, [5; 3; 4; 2; 6; 9]))
-6
-
-julia> something(last(>(10), 1:10), 0)
-0
-```
-"""
-function last(predicate, itr)
-    out = nothing
-    for x in itr
-        out = ifelse(predicate(x), Some(x), out)
-    end
-    return out
-end
-
-# faster version for arrays
-function last(predicate, a::AbstractArray)
-    @inbounds for i in reverse(eachindex(a))
-        predicate(a[i]) && return Some(a[i])
-    end
-    return nothing
-end
-
 """
     last(itr, n::Integer)
 

base/iterators.jl

@@ -15,7 +15,6 @@ using .Base:
     LinearIndices, (:), |, +, -, !==, !, <=, <, missing, any, _counttuple
 
 import .Base:
-    first, last,
     isempty, length, size, axes, ndims,
     eltype, IteratorSize, IteratorEltype,
     haskey, keys, values, pairs,
@@ -102,8 +101,8 @@ length(r::Reverse) = length(r.itr)
 size(r::Reverse) = size(r.itr)
 IteratorSize(::Type{Reverse{T}}) where {T} = IteratorSize(T)
 IteratorEltype(::Type{Reverse{T}}) where {T} = IteratorEltype(T)
-last(r::Reverse) = first(r.itr) # the first shall be last
-first(r::Reverse) = last(r.itr) # and the last shall be first
+Base.last(r::Reverse) = Base.first(r.itr) # the first shall be last
+Base.first(r::Reverse) = Base.last(r.itr) # and the last shall be first
 
 # reverse-order array iterators: assumes more-specialized Reverse for eachindex
 @propagate_inbounds function iterate(A::Reverse{<:AbstractArray}, state=(reverse(eachindex(A.itr)),))
@@ -986,8 +985,8 @@ iterate(::ProductIterator{Tuple{}}, state) = nothing
 
 @inline isdone(P::ProductIterator) = any(isdone, P.iterators)
 @inline function _pisdone(iters, states)
-    iter1 = first(iters)
-    done1 = isdone(iter1, first(states)[2]) # check step
+    iter1 = Base.first(iters)
+    done1 = isdone(iter1, Base.first(states)[2]) # check step
     done1 === true || return done1 # false or missing
     done1 = isdone(iter1) # check restart
     done1 === true || return done1 # false or missing
@@ -1012,8 +1011,8 @@ end
 
 @inline _piterate1(::Tuple{}, ::Tuple{}) = nothing
 @inline function _piterate1(iters, states)
-    iter1 = first(iters)
-    next = iterate(iter1, first(states)[2])
+    iter1 = Base.first(iters)
+    next = iterate(iter1, Base.first(states)[2])
     restnext = tail(states)
     if next === nothing
         isdone(iter1) === true && return nothing
@@ -1335,9 +1334,89 @@ only(x::Tuple) = throw(
     ArgumentError("Tuple contains $(length(x)) elements, must contain exactly 1 element")
 )
 only(a::AbstractArray{<:Any, 0}) = @inbounds return a[]
-only(x::NamedTuple{<:Any, <:Tuple{Any}}) = first(x)
+only(x::NamedTuple{<:Any, <:Tuple{Any}}) = Base.first(x)
 only(x::NamedTuple) = throw(
     ArgumentError("NamedTuple contains $(length(x)) elements, must contain exactly 1 element")
 )
 
+"""
+    Iterators.first(coll)
+
+Return the first element of iterable `coll` wrapped in [`Some`](@ref).
+
+If `coll` is empty, return `nothing`.
+
+See also [`something`](@ref), [`Iterators.last`](@ref).
+
+!!! compat "Julia 1.6"
+    This function was added in Julia 1.6.
+
+# Extended help
+
+This differs from [`first`](@ref) by not throwing an error for empty
+iterables. It can be used with [`Iterators.filter`](@ref) to safely
+get the first element of an iterable which matches a condition. With
+[`first`](@ref), this use requires handling collections with no
+elements matching the condition by catching the thrown
+[`BoundsError`](@ref).
+
+# Examples
+```jldoctest
+julia> Iterators.first(Iterators.filter(>(5), 1:10))
+Some(6)
+
+julia> isnothing(Iterators.first(Iterators.filter(isodd, 2:2:10)))
+true
+
+julia> something(Iterators.first(Iterators.filter(iseven, [5, 3, 4, 2, 6, 8])))
+4
+
+julia> something(Iterators.first(Iterators.filter(>(10), 1:10)), 0)
+0
+```
+"""
+function first(itr)
+    x = iterate(itr)
+    x === nothing && return
+    return Some(x[1])
+end
+
+"""
+    Iterators.last(coll)
+
+Return the last element of iterable `coll` wrapped in [`Some`](@ref).
+
+If `coll` is empty, return `nothing`.
+
+See also [`something`](@ref), [`Iterators.first`](@ref).
+
+!!! compat "Julia 1.6"
+    This function was added in Julia 1.6.
+
+# Extended help
+
+This differs from [`last`](@ref) by not throwing an error for empty
+iterables. It can be used with [`Iterators.filter`](@ref) to safely
+get the last element of an iterable which matches a condition. With
+[`last`](@ref), this use requires handling collections with no
+elements matching the condition by catching the thrown
+[`BoundsError`](@ref).
+
+# Examples
+```jldoctest
+julia> Iterators.last(Iterators.filter(<(5), 1:10))
+Some(4)
+
+julia> isnothing(Iterators.last(Iterators.filter(isodd, 2:2:10)))
+true
+
+julia> something(Iterators.last(Iterators.filter(iseven, [5, 3, 4, 2, 6, 9])))
+6
+
+julia> something(Iterators.last(Iterators.filter(>(10), 1:10)), 0)
+0
+```
+"""
+last(itr) = first(reverse(itr))
+
 end

doc/src/base/iterators.md

@@ -19,6 +19,8 @@ Base.Iterators.map
 Base.Iterators.filter
 Base.Iterators.accumulate
 Base.Iterators.reverse
+Base.Iterators.first
+Base.Iterators.last
 Base.Iterators.only
 Base.Iterators.peel
 ```

test/abstractarray.jl

@@ -1126,28 +1126,3 @@ end
         end
     end
 end
-
-@testset "first/last n elements of $(typeof(itr))" for itr in (collect(1:9),
-                                                               [1 4 7; 2 5 8; 3 6 9],
-                                                               ntuple(identity, 9))
-    @test first(itr, 6) == [itr[1:6]...]
-    @test first(itr, 25) == [itr[:]...]
-    @test first(itr, 25) !== itr
-    @test first(itr, 1) == [itr[1]]
-    @test_throws ArgumentError first(itr, -6)
-    @test last(itr, 6) == [itr[end-5:end]...]
-    @test last(itr, 25) == [itr[:]...]
-    @test last(itr, 25) !== itr
-    @test last(itr, 1) == [itr[end]]
-    @test_throws ArgumentError last(itr, -6)
-end
-
-@testset "first/last element satisfying predicate of $(typeof(itr))" for itr in (1:9,
-                                                                                 collect(1:9),
-                                                                                 reshape(1:9, (3, 3)),
-                                                                                 ntuple(identity, 9))
-    @test first(>(5), itr) |> something == 6
-    @test last(<(5), itr) |> something == 4
-    @test first(>(9), itr) == nothing
-    @test last(>(9), itr) == nothing
-end

test/iterators.jl

@@ -848,3 +848,15 @@ end
     @test cumprod(x + 1 for x in 1:3) == [2, 6, 24]
     @test accumulate(+, (x^2 for x in 1:3); init=100) == [101, 105, 114]
 end
+
+@testset "Iterators.first and Iterators.last" for itr in (1:9,
+                                                          collect(1:9),
+                                                          reshape(1:9, (3, 3)),
+                                                          ntuple(identity, 9))
+    @test @inferred(Nothing, Iterators.first(itr)) == Some(1)
+    @test @inferred(Nothing, Iterators.last(itr)) == Some(9)
+    @test @inferred(Nothing, Iterators.first(Iterators.filter(>(5), itr))) == Some(6)
+    @test @inferred(Nothing, Iterators.last(Iterators.filter(<(5), itr))) == Some(4)
+    @test @inferred(Nothing, Iterators.first(Iterators.filter(>(9), itr))) === nothing
+    @test @inferred(Nothing, Iterators.last(Iterators.filter(>(9), itr))) === nothing
+end