Add docstring for keys(::AbstractArray) (#36073)

This is helpful for users, and it matters because some Base functions may rely on these guarantees for their correct behavior (e.g. `hash`). Co-authored-by: Matt Bauman <[email protected]>
JuliaLang · Apr 21, 2021 · 9418acc · 9418acc
1 parent 6492751
commit 9418acc
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/base/abstractarray.jl b/base/abstractarray.jl
@@ -119,6 +119,19 @@ axes1(iter) = oneto(length(iter))
 unsafe_indices(A) = axes(A)
 unsafe_indices(r::AbstractRange) = (oneto(unsafe_length(r)),) # Ranges use checked_sub for size
 
+"""
+    keys(a::AbstractArray)
+
+Return an efficient array describing all valid indices for `a` arranged in the shape of `a` itself.
+
+They keys of 1-dimensional arrays (vectors) are integers, whereas all other N-dimensional
+arrays use [`CartesianIndex`](@ref) to describe their locations.  Often the special array
+types [`LinearIndices`](@ref) and [`CartesianIndices`](@ref) are used to efficiently
+represent these arrays of integers and `CartesianIndex`es, respectively.
+
+Note that the `keys` of an array might not be the most efficient index type; for maximum
+performance use  [`eachindex`](@ref) instead.
+"""
 keys(a::AbstractArray) = CartesianIndices(axes(a))
 keys(a::AbstractVector) = LinearIndices(a)
 

diff --git a/doc/src/base/arrays.md b/doc/src/base/arrays.md
@@ -52,6 +52,7 @@ Base.size
 Base.axes(::Any)
 Base.axes(::AbstractArray, ::Any)
 Base.length(::AbstractArray)
+Base.keys(::AbstractArray)
 Base.eachindex
 Base.IndexStyle
 Base.IndexLinear