From 8d4fe7314bb627db9991934c73fcf7e8001410f0 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Fri, 29 May 2020 13:57:30 +0200 Subject: [PATCH 1/2] Add docstring for keys(::AbstractArray) This is helpful for users, and it matters because some Base functions rely on `keys(::AbstractArray)` returning a collection of integer ranges (e.g. `hash`). --- base/abstractarray.jl | 10 ++++++++++ doc/src/base/arrays.md | 1 + 2 files changed, 11 insertions(+) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 703895a96ba26..c4925d9906c6c 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -98,6 +98,16 @@ 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 the tuple of valid indices for array `a`. This is equivalent to +[`LinearIndices(a)`](@ref) for vectors, and to [`CartesianIndices(axes(a))`](@ref) +for higher-dimensional arrays. + +This may not return the most efficient indices type to iterate over `a`: +use [`eachindex`](@ref) instead for maximum performance. +""" 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 index 50c2c09caae9c..37875b5d208de 100644 --- a/doc/src/base/arrays.md +++ b/doc/src/base/arrays.md @@ -51,6 +51,7 @@ Base.size Base.axes(::Any) Base.axes(::AbstractArray, ::Any) Base.length(::AbstractArray) +Base.keys(::AbstractArray) Base.eachindex Base.IndexStyle Base.IndexLinear From 8c9c491d3aa043b72c7e30591c48c932f621e08a Mon Sep 17 00:00:00 2001 From: Jameson Nash Date: Tue, 20 Apr 2021 14:55:37 -0400 Subject: [PATCH 2/2] Update base/abstractarray.jl Co-authored-by: Matt Bauman --- base/abstractarray.jl | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index c4925d9906c6c..5e54ad4576a6e 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -101,12 +101,15 @@ unsafe_indices(r::AbstractRange) = (OneTo(unsafe_length(r)),) # Ranges use check """ keys(a::AbstractArray) -Return the tuple of valid indices for array `a`. This is equivalent to -[`LinearIndices(a)`](@ref) for vectors, and to [`CartesianIndices(axes(a))`](@ref) -for higher-dimensional arrays. +Return an efficient array describing all valid indices for `a` arranged in the shape of `a` itself. -This may not return the most efficient indices type to iterate over `a`: -use [`eachindex`](@ref) instead for maximum performance. +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)