Merge pull request JuliaLang#10859 from mbauman/mb/linearindexing

Document and improve consistency of linearindexing
jiahao · Apr 17, 2015 · 3e72801 · 3e72801
2 parents ec8f5d9 + 809cc82
commit 3e72801
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 7 deletions.
diff --git a/base/abstractarray.jl b/base/abstractarray.jl
@@ -106,12 +106,10 @@ abstract LinearIndexing
 immutable LinearFast <: LinearIndexing end
 immutable LinearSlow <: LinearIndexing end
 
-linearindexing(::AbstractArray) = LinearSlow()
-linearindexing(::Array) = LinearFast()
-linearindexing(::Range) = LinearFast()
-linearindexing{A<:AbstractArray}(::Type{A}) = LinearSlow()
-linearindexing{A<:Array}(::Type{A}) = LinearFast()
-linearindexing{A<:Range}(::Type{A}) = LinearFast()
+linearindexing(A::AbstractArray) = linearindexing(typeof(A))
+linearindexing{T<:AbstractArray}(::Type{T}) = LinearSlow()
+linearindexing{T<:Array}(::Type{T}) = LinearFast()
+linearindexing{T<:Range}(::Type{T}) = LinearFast()
 
 ## Bounds checking ##
 checkbounds(sz::Int, ::Colon) = nothing

diff --git a/base/multidimensional.jl b/base/multidimensional.jl
@@ -8,7 +8,6 @@ import Base: @nref, @ncall, @nif, @nexprs, LinearFast, LinearSlow, to_index
 export CartesianIndex, CartesianRange
 
 # Traits for linear indexing
-linearindexing(::BitArray) = LinearFast()
 linearindexing{A<:BitArray}(::Type{A}) = LinearFast()
 
 # CartesianIndex

diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst
@@ -59,6 +59,14 @@ Basic functions
  (iter.I_1,iter.I_2) = (2,3)
  A[iter] = 0.8090413606455655
 
+.. function:: Base.linearindexing(A)
+
+ ``linearindexing`` defines how an AbstractArray most efficiently accesses its elements. If ``Base.linearindexing(A)`` returns ``Base.LinearFast()``, this means that linear indexing with only one index is an efficient operation. If it instead returns ``Base.LinearSlow()`` (by default), this means that the array intrinsically accesses its elements with indices specified for every dimension. Since converting a linear index to multiple indexing subscripts is typically very expensive, this provides a traits-based mechanism to enable efficient generic code for all array types.
+
+ An abstract array subtype ``MyArray`` that wishes to opt into fast linear indexing behaviors should define ``linearindexing`` in the type-domain::
+
+ Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()
+
 .. function:: countnz(A)
 
  Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values.