Rename endof->endindex and introduce beginindex. Fixes #23354

Author: timholy

NEWS.md

@@ -43,6 +43,9 @@ New language features
   * Values for `Enum`s can now be specified inside of a `begin` block when using the
     `@enum` macro ([#25424]).
 
+  * `a[begin]` can now be used to address the first element of an integer-indexed collection `a`.
+    The index is computed by `beginindex(a)` ([#23554]).
+
 Language changes
 ----------------
 
@@ -918,6 +921,8 @@ Deprecated or removed
 
   * `findin(a, b)` has been deprecated in favor of `find(occursin(b), a)` ([#24673]).
 
+  * `endof(a)` has been renamed `endindex(a)` ([#23554]).
+
 Command-line option changes
 ---------------------------
 
@@ -1074,6 +1079,7 @@ Command-line option changes
 [#23323]: https://github.com/JuliaLang/julia/issues/23323
 [#23341]: https://github.com/JuliaLang/julia/issues/23341
 [#23342]: https://github.com/JuliaLang/julia/issues/23342
+[#23354]: https://github.com/JuliaLang/julia/issues/23354
 [#23366]: https://github.com/JuliaLang/julia/issues/23366
 [#23373]: https://github.com/JuliaLang/julia/issues/23373
 [#23404]: https://github.com/JuliaLang/julia/issues/23404

base/abstractarray.jl

@@ -146,7 +146,7 @@ ndims(::Type{T}) where {T<:AbstractArray} = ndims(supertype(T))
 
 Return the number of elements in the collection.
 
-Use [`endof`](@ref) to get the last valid index of an indexable collection.
+Use [`endindex`](@ref) to get the last valid index of an indexable collection.
 
 # Examples
 ```jldoctest
@@ -165,17 +165,30 @@ _length(A::AbstractArray) = (@_inline_meta; prod(map(unsafe_length, axes(A)))) #
 _length(A) = (@_inline_meta; length(A))
 
 """
-    endof(collection) -> Integer
+    endindex(collection) -> Integer
 
 Return the last index of the collection.
 
 # Examples
 ```jldoctest
-julia> endof([1,2,4])
+julia> endindex([1,2,4])
 3
 ```
 """
-endof(a::AbstractArray) = (@_inline_meta; last(linearindices(a)))
+endindex(a::AbstractArray) = (@_inline_meta; last(linearindices(a)))
+
+"""
+    beginindex(collection) -> Integer
+
+Return the first index of the collection.
+
+# Examples
+```jldoctest
+julia> beginindex([1,2,4])
+1
+```
+"""
+beginindex(a::AbstractArray) = (@_inline_meta; first(linearindices(a)))
 
 first(a::AbstractArray) = a[first(eachindex(a))]
 
@@ -204,7 +217,7 @@ end
     last(coll)
 
 Get the last element of an ordered collection, if it can be computed in O(1) time. This is
-accomplished by calling [`endof`](@ref) to get the last index. Return the end
+accomplished by calling [`endindex`](@ref) to get the last index. Return the end
 point of an `AbstractRange` even if it is empty.
 
 # Examples

base/array.jl

@@ -1512,7 +1512,7 @@ julia> findnext(A, 3)
 ```
 """
 function findnext(A, start::Integer)
-    l = endof(A)
+    l = endindex(A)
     i = start
     warned = false
     while i <= l
@@ -1572,7 +1572,7 @@ julia> findnext(isodd, A, 2)
 ```
 """
 function findnext(testf::Function, A, start::Integer)
-    l = endof(A)
+    l = endindex(A)
     i = start
     while i <= l
         if testf(A[i])
@@ -1664,7 +1664,7 @@ julia> findlast(A)
 0
 ```
 """
-findlast(A) = findprev(A, endof(A))
+findlast(A) = findprev(A, endindex(A))
 
 """
     findprev(predicate::Function, A, i::Integer)
@@ -1715,7 +1715,7 @@ julia> findlast(x -> x > 5, A)
 0
 ```
 """
-findlast(testf::Function, A) = findprev(testf, A, endof(A))
+findlast(testf::Function, A) = findprev(testf, A, endindex(A))
 
 """
     find(f::Function, A)

base/char.jl

@@ -70,7 +70,8 @@ size(c::Char,d) = convert(Int, d) < 1 ? throw(BoundsError()) : 1
 ndims(c::Char) = 0
 ndims(::Type{Char}) = 0
 length(c::Char) = 1
-endof(c::Char) = 1
+beginindex(c::Char) = 1
+endindex(c::Char) = 1
 getindex(c::Char) = c
 getindex(c::Char, i::Integer) = i == 1 ? c : throw(BoundsError())
 getindex(c::Char, I::Integer...) = all(x -> x == 1, I) ? c : throw(BoundsError())

base/deprecated.jl

@@ -3871,9 +3871,9 @@ end
 @deprecate rsearch(s::AbstractString, r::Regex) findlast(r, s)
 @deprecate rsearch(s::AbstractString, c::Char, i::Integer) findprev(equalto(c), s, i)
 @deprecate rsearch(s::AbstractString, c::Char) findlast(equalto(c), s)
-@deprecate rsearch(a::Union{String,ByteArray}, b::Union{Int8,UInt8}, i::Integer = endof(a)) findprev(equalto(b), a, i)
-@deprecate rsearch(a::String, b::Union{Int8,UInt8}, i::Integer = endof(a)) findprev(equalto(Char(b)), a, i)
-@deprecate rsearch(a::ByteArray, b::Char, i::Integer = endof(a)) findprev(equalto(UInt8(b)), a, i)
+@deprecate rsearch(a::Union{String,ByteArray}, b::Union{Int8,UInt8}, i::Integer = endindex(a)) findprev(equalto(b), a, i)
+@deprecate rsearch(a::String, b::Union{Int8,UInt8}, i::Integer = endindex(a)) findprev(equalto(Char(b)), a, i)
+@deprecate rsearch(a::ByteArray, b::Char, i::Integer = endindex(a)) findprev(equalto(UInt8(b)), a, i)
 
 @deprecate searchindex(s::AbstractString, t::AbstractString) first(findfirst(t, s))
 @deprecate searchindex(s::AbstractString, t::AbstractString, i::Integer) first(findnext(t, s, i))
@@ -3889,6 +3889,11 @@ end
 
 @deprecate findin(a, b) find(occursin(b), a)
 
+@deprecate endof(a) endindex(a)
+function beginindex(a)
+    depwarn("if appropriate you should implement `beginindex` for type $(typeof(a)), which might just return 1", :beginof)
+    1
+end
 
 # END 0.7 deprecations
 # BEGIN 1.0 deprecations

base/dict.jl

@@ -16,7 +16,7 @@ function _truncate_at_width_or_chars(str, width, chars="", truncmark="…")
 
     lastidx != 0 && str[lastidx] in chars && (lastidx = prevind(str, lastidx))
     truncidx == 0 && (truncidx = lastidx)
-    if lastidx < endof(str)
+    if lastidx < endindex(str)
         return String(SubString(str, 1, truncidx) * truncmark)
     else
         return String(str)

base/essentials.jl

@@ -546,7 +546,8 @@ function length(v::SimpleVector)
     @_gc_preserve_end t
     return l
 end
-endof(v::SimpleVector) = length(v)
+beginindex(v::SimpleVector) = 1
+endindex(v::SimpleVector) = length(v)
 start(v::SimpleVector) = 1
 next(v::SimpleVector,i) = (v[i],i+1)
 done(v::SimpleVector,i) = (length(v) < i)

base/exports.jl

@@ -619,14 +619,15 @@ export
     allunique,
     any!,
     any,
+    beginindex,
     collect,
     count,
     delete!,
     deleteat!,
     eltype,
     empty!,
     empty,
-    endof,
+    endindex,
     filter!,
     filter,
     foldl,

base/gmp.jl

@@ -238,9 +238,9 @@ hastypemax(::Type{BigInt}) = false
 
 function tryparse_internal(::Type{BigInt}, s::AbstractString, startpos::Int, endpos::Int, base_::Integer, raise::Bool)
     # don't make a copy in the common case where we are parsing a whole String
-    bstr = startpos == start(s) && endpos == endof(s) ? String(s) : String(SubString(s,startpos,endpos))
+    bstr = startpos == start(s) && endpos == endindex(s) ? String(s) : String(SubString(s,startpos,endpos))
 
-    sgn, base, i = Base.parseint_preamble(true,Int(base_),bstr,start(bstr),endof(bstr))
+    sgn, base, i = Base.parseint_preamble(true,Int(base_),bstr,start(bstr),endindex(bstr))
     if !(2 <= base <= 62)
         raise && throw(ArgumentError("invalid base: base must be 2 ≤ base ≤ 62, got $base"))
         return nothing

base/int.jl

@@ -539,9 +539,9 @@ end
 macro big_str(s)
     if '_' in s
         # remove _ in s[2:end-1]
-        bf = IOBuffer(endof(s))
+        bf = IOBuffer(endindex(s))
         print(bf, s[1])
-        for c in SubString(s, 2, endof(s)-1)
+        for c in SubString(s, 2, endindex(s)-1)
             c != '_' && print(bf, c)
         end
         print(bf, s[end])

base/io.jl

@@ -648,14 +648,14 @@ function readuntil(s::IO, delim::T) where T
     return out
 end
 
-# requires that indices for target are small ordered integers bounded by start and endof
+# requires that indices for target are small ordered integers bounded by start and endindex
 function readuntil_indexable(io::IO, target#=::Indexable{T}=#, out)
     T = eltype(target)
     first = start(target)
     if done(target, first)
         return
     end
-    len = endof(target)
+    len = endindex(target)
     local cache # will be lazy initialized when needed
     second = next(target, first)[2]
     max_pos = second

base/markdown/parse/parse.jl

@@ -23,7 +23,8 @@ config(md::MD) = md.meta[:config]::Config
 Base.push!(md::MD, x) = push!(md.content, x)
 Base.getindex(md::MD, args...) = md.content[args...]
 Base.setindex!(md::MD, args...) = setindex!(md.content, args...)
-Base.endof(md::MD) = endof(md.content)
+Base.endindex(md::MD) = endindex(md.content)
+Base.beginindex(md::MD) = beginindex(md.content)
 Base.length(md::MD) = length(md.content)
 Base.isempty(md::MD) = isempty(md.content)
 

base/namedtuple.jl

@@ -48,7 +48,8 @@ length(t::NamedTuple) = nfields(t)
 start(t::NamedTuple) = 1
 done(t::NamedTuple, iter) = iter > nfields(t)
 next(t::NamedTuple, iter) = (getfield(t, iter), iter + 1)
-endof(t::NamedTuple) = nfields(t)
+beginindex(t::NamedTuple) = 1
+endindex(t::NamedTuple) = nfields(t)
 getindex(t::NamedTuple, i::Int) = getfield(t, i)
 getindex(t::NamedTuple, i::Symbol) = getfield(t, i)
 indexed_next(t::NamedTuple, i::Int, state) = (getfield(t, i), i+1)

base/number.jl

@@ -52,7 +52,8 @@ eltype(::Type{T}) where {T<:Number} = T
 ndims(x::Number) = 0
 ndims(::Type{<:Number}) = 0
 length(x::Number) = 1
-endof(x::Number) = 1
+beginindex(x::Number) = 1
+endindex(x::Number) = 1
 IteratorSize(::Type{<:Number}) = HasShape()
 keys(::Number) = OneTo(1)
 

base/pair.jl

@@ -52,7 +52,8 @@ getindex(p::Pair,i::Int) = getfield(p,i)
 getindex(p::Pair,i::Real) = getfield(p, convert(Int, i))
 reverse(p::Pair{A,B}) where {A,B} = Pair{B,A}(p.second, p.first)
 
-endof(p::Pair) = 2
+beginindex(p::Pair) = 1
+endindex(p::Pair) = 2
 length(p::Pair) = 2
 first(p::Pair) = p.first
 last(p::Pair) = p.second

base/parse.jl

@@ -208,16 +208,16 @@ Like [`parse`](@ref), but returns either a value of the requested type,
 or [`nothing`](@ref) if the string does not contain a valid number.
 """
 tryparse(::Type{T}, s::AbstractString, base::Integer) where {T<:Integer} =
-    tryparse_internal(T, s, start(s), endof(s), check_valid_base(base), false)
+    tryparse_internal(T, s, start(s), endindex(s), check_valid_base(base), false)
 tryparse(::Type{T}, s::AbstractString) where {T<:Integer} =
-    tryparse_internal(T, s, start(s), endof(s), 0, false)
+    tryparse_internal(T, s, start(s), endindex(s), 0, false)
 
 function parse(::Type{T}, s::AbstractString, base::Integer) where T<:Integer
-    tryparse_internal(T, s, start(s), endof(s), check_valid_base(base), true)
+    tryparse_internal(T, s, start(s), endindex(s), check_valid_base(base), true)
 end
 
 function parse(::Type{T}, s::AbstractString) where T<:Integer
-    tryparse_internal(T, s, start(s), endof(s), 0, true) # Zero means, "figure it out"
+    tryparse_internal(T, s, start(s), endindex(s), 0, true) # Zero means, "figure it out"
 end
 
 ## string to float functions ##
@@ -331,7 +331,7 @@ tryparse_internal(T::Type{<:Complex}, s::AbstractString, i::Int, e::Int, raise::
 
 # fallback methods for tryparse_internal
 tryparse_internal(::Type{T}, s::AbstractString, startpos::Int, endpos::Int) where T<:Real =
-    startpos == start(s) && endpos == endof(s) ? tryparse(T, s) : tryparse(T, SubString(s, startpos, endpos))
+    startpos == start(s) && endpos == endindex(s) ? tryparse(T, s) : tryparse(T, SubString(s, startpos, endpos))
 function tryparse_internal(::Type{T}, s::AbstractString, startpos::Int, endpos::Int, raise::Bool) where T<:Real
     result = tryparse_internal(T, s, startpos, endpos)
     if raise && result === nothing
@@ -343,4 +343,4 @@ tryparse_internal(::Type{T}, s::AbstractString, startpos::Int, endpos::Int, rais
     tryparse_internal(T, s, startpos, endpos, 10, raise)
 
 parse(::Type{T}, s::AbstractString) where T<:Union{Real,Complex} =
-    tryparse_internal(T, s, start(s), endof(s), true)
+    tryparse_internal(T, s, start(s), endindex(s), true)

base/precompile.jl

@@ -774,11 +774,11 @@ precompile(Tuple{Type{BoundsError}, Array{Expr, 1}, Base.UnitRange{Int64}})
 precompile(Tuple{getfield(Base.Cartesian, Symbol("#@ncall")), Int64, Symbol, Symbol})
 precompile(Tuple{typeof(Base.getindex), Tuple{Symbol}, Base.UnitRange{Int64}})
 precompile(Tuple{getfield(Base.Cartesian, Symbol("#@ncall")), Int64, Symbol, Symbol, Expr})
-precompile(Tuple{typeof(Base.endof), Tuple{Symbol, Expr}})
+precompile(Tuple{typeof(Base.endindex), Tuple{Symbol, Expr}})
 precompile(Tuple{typeof(Base.getindex), Tuple{Symbol, Expr}, Base.UnitRange{Int64}})
 precompile(Tuple{getfield(Base.Cartesian, Symbol("#@nloops")), Int64, Symbol, Expr, Expr})
-precompile(Tuple{typeof(Base.endof), Tuple{Expr}})
-precompile(Tuple{typeof(Base.endof), Tuple{Symbol, Symbol, Symbol}})
+precompile(Tuple{typeof(Base.endindex), Tuple{Expr}})
+precompile(Tuple{typeof(Base.endindex), Tuple{Symbol, Symbol, Symbol}})
 precompile(Tuple{typeof(Base.getindex), Tuple{Symbol, Symbol, Symbol}, Base.UnitRange{Int64}})
 precompile(Tuple{Type{Expr}, Symbol, Symbol, Symbol, Symbol, Symbol, Symbol})
 precompile(Tuple{typeof(Base.join), Base.GenericIOBuffer{Array{UInt8, 1}}, Tuple{String, String}, Char})
@@ -991,7 +991,7 @@ precompile(Tuple{typeof(Base.Markdown.terminline), Base.GenericIOBuffer{Array{UI
 precompile(Tuple{typeof(Base._search), Base.SubString{String}, String, Int64})
 precompile(Tuple{typeof(Base._split), Base.SubString{String}, String, Int64, Bool, Array{Base.SubString{String}, 1}})
 precompile(Tuple{getfield(Base.Markdown, Symbol("#kw##wrapped_lines")), Array{Any, 1}, typeof(Base.Markdown.wrapped_lines), Base.SubString{String}})
-precompile(Tuple{typeof(Base.endof), Array{AbstractString, 1}})
+precompile(Tuple{typeof(Base.endindex), Array{AbstractString, 1}})
 precompile(Tuple{typeof(Base.getindex), Array{AbstractString, 1}, Base.UnitRange{Int64}})
 precompile(Tuple{typeof(Base.throw_boundserror), Array{AbstractString, 1}, Tuple{Base.UnitRange{Int64}}})
 precompile(Tuple{typeof(Base.unsafe_copyto!), Array{AbstractString, 1}, Int64, Array{AbstractString, 1}, Int64, Int64})

base/printf.jl

@@ -54,7 +54,7 @@ function parse(s::AbstractString)
         j1 = j
         j = k
     end
-    i > endof(s) || push!(list, s[i:end])
+    i > endindex(s) || push!(list, s[i:end])
     # coalesce adjacent strings
     i = 1
     while i < length(list)

base/process.jl

@@ -829,7 +829,7 @@ wait(x::ProcessChain) = for p in x.processes; wait(p); end
 show(io::IO, p::Process) = print(io, "Process(", p.cmd, ", ", process_status(p), ")")
 
 # allow the elements of the Cmd to be accessed as an array or iterator
-for f in (:length, :endof, :start, :keys, :eltype, :first, :last)
+for f in (:length, :beginindex, :endindex, :start, :keys, :eltype, :first, :last)
     @eval $f(cmd::Cmd) = $f(cmd.exec)
 end
 for f in (:next, :done, :getindex)

base/random/generation.jl

@@ -416,12 +416,12 @@ Sampler(rng::AbstractRNG, str::AbstractString, n::Val{Inf}) = Sampler(rng, colle
 # when generating only one char from a string, the specialized method below
 # is usually more efficient
 Sampler(rng::AbstractRNG, str::AbstractString, ::Val{1}) =
-    SamplerSimple(str, Sampler(rng, 1:_endof(str), Val(Inf)))
+    SamplerSimple(str, Sampler(rng, 1:_endindex(str), Val(Inf)))
 
 isvalid_unsafe(s::String, i) = !Base.is_valid_continuation(Base.@gc_preserve s unsafe_load(pointer(s), i))
 isvalid_unsafe(s::AbstractString, i) = isvalid(s, i)
-_endof(s::String) = sizeof(s)
-_endof(s::AbstractString) = endof(s)
+_endindex(s::String) = sizeof(s)
+_endindex(s::AbstractString) = endindex(s)
 
 function rand(rng::AbstractRNG, sp::SamplerSimple{<:AbstractString,<:Sampler})::Char
     str = sp[]

base/reduce.jl

@@ -126,7 +126,7 @@ end
 Like [`mapreduce`](@ref), but with guaranteed right associativity, as in [`foldr`](@ref).
 `v0` will be used exactly once.
 """
-mapfoldr(f, op, v0, itr) = mapfoldr_impl(f, op, v0, itr, endof(itr))
+mapfoldr(f, op, v0, itr) = mapfoldr_impl(f, op, v0, itr, endindex(itr))
 
 """
     mapfoldr(f, op, itr)
@@ -137,7 +137,7 @@ Specifically, `mapfoldr(f, op, itr)` produces the same result as
 In general, this cannot be used with empty collections (see [`reduce(op, itr)`](@ref)).
 """
 function mapfoldr(f, op, itr)
-    i = endof(itr)
+    i = endindex(itr)
     if isempty(itr)
         return Base.mapreduce_empty_iter(f, op, itr, IteratorEltype(itr))
     end