Add docs

JuliaLang · May 9, 2016 · 44bb49c · 44bb49c
1 parent 9d8fd12
commit 44bb49c
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 20 deletions.
diff --git 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
@@ -50,7 +50,9 @@ Function                          Description
 :func:`length(A) <length>`        the number of elements in ``A``
 :func:`ndims(A) <ndims>`          the number of dimensions of ``A``
 :func:`size(A) <size>`            a tuple containing the dimensions of ``A``
-:func:`size(A,n) <size>`          the size of ``A`` in a particular dimension
+:func:`size(A,n) <size>`          the size of ``A`` along a particular dimension
+:func:`indices(A) <indices>`      a tuple containing the valid indices of ``A``
+:func:`indices(A,n) <indices>`    a range expressing the valid indices along dimension ``n``
 :func:`eachindex(A) <eachindex>`  an efficient iterator for visiting each position in ``A``
 :func:`stride(A,k) <stride>`      the stride (linear index distance between adjacent elements) along dimension ``k``
 :func:`strides(A) <strides>`      a tuple of the strides in each dimension

diff --git 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) <size>`                                                                                  Returns a tuple containing the dimensions of A
-:func:`Base.linearindexing(Type) <Base.linearindexing>`                                                 Returns either ``Base.LinearFast()`` or ``Base.LinearSlow()``. See the description below.
-:func:`getindex(A, i::Int) <getindex>`                                                                  (if ``LinearFast``) Linear scalar indexing
-:func:`getindex(A, i1::Int, ..., iN::Int) <getindex>`                                                   (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexing
-:func:`setindex!(A, v, i::Int) <getindex>`                                                              (if ``LinearFast``) Scalar indexed assignment
-:func:`setindex!(A, v, i1::Int, ..., iN::Int) <getindex>`                                               (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexed assignment
-**Optional methods**                                       **Default definition**                       **Brief description**
-:func:`getindex(A, I...) <getindex>`                       defined in terms of scalar :func:`getindex`  :ref:`Multidimensional and nonscalar indexing <man-array-indexing>`
-:func:`setindex!(A, I...) <setindex!>`                     defined in terms of scalar :func:`setindex!` :ref:`Multidimensional and nonscalar indexed assignment <man-array-indexing>`
-:func:`start`/:func:`next`/:func:`done`                    defined in terms of scalar :func:`getindex`  Iteration
-:func:`length(A) <length>`                                 ``prod(size(A))``                            Number of elements
-:func:`similar(A) <similar>`                               ``similar(A, eltype(A), size(A))``           Return a mutable array with the same shape and element type
-:func:`similar(A, ::Type{S}) <similar>`                    ``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>`            ``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}) <similar>` ``Array(S, dims)``                           Return a mutable array with the specified element type and dimensions
-========================================================== ============================================ =======================================================================================
+===================================================================== ============================================ =======================================================================================
+Methods to implement                                                                                               Brief description
+===================================================================== ============================================ =======================================================================================
+:func:`size(A) <size>`                                                                                             Returns a tuple containing the dimensions of ``A``
+:func:`getindex(A, i::Int) <getindex>`                                                                             (if ``LinearFast``) Linear scalar indexing
+:func:`getindex(A, i1::Int, ..., iN::Int) <getindex>`                                                              (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexing
+:func:`setindex!(A, v, i::Int) <getindex>`                                                                         (if ``LinearFast``) Scalar indexed assignment
+:func:`setindex!(A, v, i1::Int, ..., iN::Int) <getindex>`                                                          (if ``LinearSlow``, where ``N = ndims(A)``) N-dimensional scalar indexed assignment
+**Optional methods**                                                  **Default definition**                       **Brief description**
+:func:`Base.linearindexing(Type) <Base.linearindexing>`               ``Base.LinearSlow()``                        Returns either ``Base.LinearFast()`` or ``Base.LinearSlow()``. See the description below.
+:func:`indices(A, d) <indices>`                                       ``1:size(A, d)``                             Returns the range of valid indices along dimension ``d``
+:func:`getindex(A, I...) <getindex>`                                  defined in terms of scalar :func:`getindex`  :ref:`Multidimensional and nonscalar indexing <man-array-indexing>`
+:func:`setindex!(A, I...) <setindex!>`                                defined in terms of scalar :func:`setindex!` :ref:`Multidimensional and nonscalar indexed assignment <man-array-indexing>`
+:func:`start`/:func:`next`/:func:`done`                               defined in terms of scalar :func:`getindex`  Iteration
+:func:`length(A) <length>`                                            ``prod(size(A))``                            Number of elements
+:func:`similar(A) <similar>`                                          ``similar(A, eltype(A), indices(A))``        Return a mutable array with the same shape and element type
+:func:`similar(A, ::Type{S}) <similar>`                               ``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>`            ``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>`                       ``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}}) <similar>` ``Array(S, map(length, inds))``              Return a mutable array with the specified element type and indices
+:func:`similar(A, ::Type{S}, dims::NTuple{Int}) <similar>`            ``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 <man-arrays>` and :ref:`standard library section <stdlib-arrays>` for more supported methods.
 

diff --git 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