See also axes from eachindex's docstring, etc. (JuliaLang#45356)

mcabbott · web-flow · commit baa85f4f39c3 · 2022-08-22T11:49:12.000-04:00
* mention pairs and axes in eachindex's docstring
diff --git a/base/abstractarray.jl b/base/abstractarray.jl
@@ -55,6 +55,9 @@ julia> A = fill(1, (5,6,7));
 
 julia> axes(A, 2)
 Base.OneTo(6)
+
+julia> axes(A, 4) == 1:1  # all dimensions d > ndims(A) have size 1
+true
 ```
 
 # Usage note
@@ -322,17 +325,21 @@ if all inputs have fast linear indexing, a [`CartesianIndices`](@ref)
 otherwise).
 If the arrays have different sizes and/or dimensionalities, a `DimensionMismatch` exception
 will be thrown.
+
+See also [`pairs`](@ref)`(A)` to iterate over indices and values together,
+and [`axes`](@ref)`(A, 2)` for valid indices along one dimension.
+
 # Examples
 ```jldoctest
-julia> A = [1 2; 3 4];
+julia> A = [10 20; 30 40];
 
 julia> for i in eachindex(A) # linear indexing
-           println(i)
+           println("A[", i, "] == ", A[i])
        end
-1
-2
-3
-4
+A[1] == 10
+A[2] == 30
+A[3] == 20
+A[4] == 40
 
 julia> for i in eachindex(view(A, 1:2, 1:1)) # Cartesian indexing
            println(i)
diff --git a/base/iterators.jl b/base/iterators.jl
@@ -162,10 +162,12 @@ end
 An iterator that yields `(i, x)` where `i` is a counter starting at 1,
 and `x` is the `i`th value from the given iterator. It's useful when
 you need not only the values `x` over which you are iterating, but
-also the number of iterations so far. Note that `i` may not be valid
-for indexing `iter`; it's also possible that `x != iter[i]`, if `iter`
-has indices that do not start at 1. See the `pairs(IndexLinear(),
-iter)` method if you want to ensure that `i` is an index.
+also the number of iterations so far.
+
+Note that `i` may not be valid for indexing `iter`, or may index a
+different element. This will happen if `iter` has indices that do not
+start at 1, and may happen for strings, dictionaries, etc.
+See the `pairs(IndexLinear(), iter)` method if you want to ensure that `i` is an index.
 
 # Examples
 ```jldoctest
@@ -177,6 +179,18 @@ julia> for (index, value) in enumerate(a)
 1 a
 2 b
 3 c
+
+julia> str = "na&iuml;ve";
+
+julia> for (i, val) in enumerate(str)
+           print("i = ", i, ", val = ", val, ", ")
+           try @show(str[i]) catch e println(e) end
+       end
+i = 1, val = n, str[i] = 'n'
+i = 2, val = a, str[i] = 'a'
+i = 3, val = &iuml;, str[i] = '&iuml;'
+i = 4, val = v, StringIndexError("na&iuml;ve", 4)
+i = 5, val = e, str[i] = 'v'
 ```
 """
 enumerate(iter) = Enumerate(iter)
