diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 1b245fb8a0dd0c..dca4d96a561450 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -21,7 +21,17 @@ end size{T,n}(t::AbstractArray{T,n}, d) = d <= n ? size(t)[d] : 1 size(x, d1::Integer, d2::Integer, dx::Integer...) = tuple(size(x, d1), size(x, d2, dx...)...) +""" + indices(A, d) + +Returns the valid range of indices for array `A` along dimension `d`. +""" indices(A::AbstractArray, d) = 1:size(A,d) +""" + indices(A) + +Returns the tuple of valid indices for array `A`. +""" indices{T,N}(A::AbstractArray{T,N}) = ntuple(d->indices(A, d), Val{N}) eltype{T}(::Type{AbstractArray{T}}) = T eltype{T,n}(::Type{AbstractArray{T,n}}) = T diff --git a/doc/manual/arrays.rst b/doc/manual/arrays.rst index 974636fa865570..70362101fa3c5f 100644 --- a/doc/manual/arrays.rst +++ b/doc/manual/arrays.rst @@ -50,7 +50,9 @@ Function Description :func:`length(A) ` the number of elements in ``A`` :func:`ndims(A) ` the number of dimensions of ``A`` :func:`size(A) ` a tuple containing the dimensions of ``A`` -:func:`size(A,n) ` the size of ``A`` in a particular dimension +:func:`size(A,n) ` the size of ``A`` along a particular dimension +:func:`indices(A) ` a tuple containing the valid indices of ``A`` +:func:`indices(A,n) ` a range expressing the valid indices along dimension ``n`` :func:`eachindex(A) ` an efficient iterator for visiting each position in ``A`` :func:`stride(A,k) ` the stride (linear index distance between adjacent elements) along dimension ``k`` :func:`strides(A) ` a tuple of the strides in each dimension diff --git a/doc/manual/interfaces.rst b/doc/manual/interfaces.rst index 58c9f318fdc891..b327a67faddb17 100644 --- a/doc/manual/interfaces.rst +++ b/doc/manual/interfaces.rst @@ -147,25 +147,28 @@ While this is starting to support more of the :ref:`indexing operations supporte Abstract Arrays --------------- -========================================================== ============================================ ======================================================================================= -Methods to implement Brief description -========================================================== ============================================ ======================================================================================= -:func:`size(A) ` Returns a tuple containing the dimensions of A -:func:`Base.linearindexing(Type) ` Returns either ``Base.LinearFast()`` or ``Base.LinearSlow()``. See the description below. -:func:`getindex(A, i::Int) ` (if ``LinearFast``) Linear scalar indexing -:func:`getindex(A, i1::Int, ..., iN::Int) ` (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexing -:func:`setindex!(A, v, i::Int) ` (if ``LinearFast``) Scalar indexed assignment -:func:`setindex!(A, v, i1::Int, ..., iN::Int) ` (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexed assignment -**Optional methods** **Default definition** **Brief description** -:func:`getindex(A, I...) ` defined in terms of scalar :func:`getindex` :ref:`Multidimensional and nonscalar indexing ` -:func:`setindex!(A, I...) ` defined in terms of scalar :func:`setindex!` :ref:`Multidimensional and nonscalar indexed assignment ` -:func:`start`/:func:`next`/:func:`done` defined in terms of scalar :func:`getindex` Iteration -:func:`length(A) ` ``prod(size(A))`` Number of elements -:func:`similar(A) ` ``similar(A, eltype(A), size(A))`` Return a mutable array with the same shape and element type -:func:`similar(A, ::Type{S}) ` ``similar(A, S, size(A))`` Return a mutable array with the same shape and the specified element type -:func:`similar(A, dims::NTuple{Int}) ` ``similar(A, eltype(A), dims)`` Return a mutable array with the same element type and the specified dimensions -:func:`similar(A, ::Type{S}, dims::NTuple{Int}) ` ``Array(S, dims)`` Return a mutable array with the specified element type and dimensions -========================================================== ============================================ ======================================================================================= +===================================================================== ============================================ ======================================================================================= +Methods to implement Brief description +===================================================================== ============================================ ======================================================================================= +:func:`size(A) ` Returns a tuple containing the dimensions of ``A`` +:func:`getindex(A, i::Int) ` (if ``LinearFast``) Linear scalar indexing +:func:`getindex(A, i1::Int, ..., iN::Int) ` (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexing +:func:`setindex!(A, v, i::Int) ` (if ``LinearFast``) Scalar indexed assignment +:func:`setindex!(A, v, i1::Int, ..., iN::Int) ` (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexed assignment +**Optional methods** **Default definition** **Brief description** +:func:`Base.linearindexing(Type) ` ``Base.LinearSlow()`` Returns either ``Base.LinearFast()`` or ``Base.LinearSlow()``. See the description below. +:func:`indices(A, d) ` ``1:size(A, d)`` Returns the range of valid indices along dimension ``d`` +:func:`getindex(A, I...) ` defined in terms of scalar :func:`getindex` :ref:`Multidimensional and nonscalar indexing ` +:func:`setindex!(A, I...) ` defined in terms of scalar :func:`setindex!` :ref:`Multidimensional and nonscalar indexed assignment ` +:func:`start`/:func:`next`/:func:`done` defined in terms of scalar :func:`getindex` Iteration +:func:`length(A) ` ``prod(size(A))`` Number of elements +:func:`similar(A) ` ``similar(A, eltype(A), indices(A))`` Return a mutable array with the same shape and element type +:func:`similar(A, ::Type{S}) ` ``similar(A, S, indices(A))`` Return a mutable array with the same shape and the specified element type +:func:`similar(A, inds::NTuple{UnitRange{Int}}) ` ``similar(A, eltype(A), inds)`` Return a mutable array with the same element type and the specified indices +:func:`similar(A, dims::NTuple{Int}) ` ``similar(A, eltype(A), dims)`` Return a mutable array with the same element type and size `dims` +:func:`similar(A, ::Type{S}, inds::NTuple{UnitRange{Int}}) ` ``Array(S, map(length, inds))`` Return a mutable array with the specified element type and indices +:func:`similar(A, ::Type{S}, dims::NTuple{Int}) ` ``Array(S, dims)`` Return a mutable array with the specified element type and size +===================================================================== ============================================ ======================================================================================= If a type is defined as a subtype of ``AbstractArray``, it inherits a very large set of rich behaviors including iteration and multidimensional indexing built on top of single-element access. See the :ref:`arrays manual page ` and :ref:`standard library section ` for more supported methods. diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 436c88282f0027..d196a79296c76c 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -31,6 +31,18 @@ Basic functions julia> size(A,3,2) (4,3) +.. function:: indices(A) + + .. Docstring generated from Julia source + + Returns the tuple of valid indices for array ``A``\ . + +.. function:: indices(A, d) + + .. Docstring generated from Julia source + + Returns the valid range of indices for array ``A`` along dimension ``d``\ . + .. function:: iseltype(A,T) .. Docstring generated from Julia source