Skip to content

Commit

Permalink
Remove left over mentions of the deprecated indices function (JuliaLa…
Browse files Browse the repository at this point in the history
  • Loading branch information
nalimilan authored Apr 1, 2018
1 parent e94484c commit daadf4a
Show file tree
Hide file tree
Showing 4 changed files with 12 additions and 12 deletions.
4 changes: 2 additions & 2 deletions base/abstractarray.jl
Original file line number Diff line number Diff line change
Expand Up @@ -570,10 +570,10 @@ to_shape(r::OneTo) = Int(last(r))
to_shape(r::AbstractUnitRange) = r

"""
similar(storagetype, indices)
similar(storagetype, axes)
Create an uninitialized mutable array analogous to that specified by
`storagetype`, but with `indices` specified by the last
`storagetype`, but with `axes` specified by the last
argument. `storagetype` might be a type or a function.
**Examples**:
Expand Down
4 changes: 2 additions & 2 deletions doc/src/devdocs/boundscheck.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ of "permitted" indices of `A`.

`checkbounds(A, I...)` throws an error if the indices are invalid, whereas `checkbounds(Bool, A, I...)`
returns `false` in that circumstance. `checkbounds_indices` discards any information about the
array other than its `indices` tuple, and performs a pure indices-vs-indices comparison: this
array other than its `axes` tuple, and performs a pure indices-vs-indices comparison: this
allows relatively few compiled methods to serve a huge variety of array types. Indices are specified
as tuples, and are usually compared in a 1-1 fashion with individual dimensions handled by calling
another important function, `checkindex`: typically,
Expand All @@ -78,7 +78,7 @@ so `checkindex` checks a single dimension. All of these functions, including th

If you have to customize bounds checking for a specific array type, you should specialize `checkbounds(Bool, A, I...)`.
However, in most cases you should be able to rely on `checkbounds_indices` as long as you supply
useful `indices` for your array type.
useful `axes` for your array type.

If you have novel index types, first consider specializing `checkindex`, which handles a single
index for a particular dimension of an array. If you have a custom multidimensional index type
Expand Down
14 changes: 7 additions & 7 deletions doc/src/devdocs/offset-arrays.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ the exported interfaces of Julia.

As an overview, the steps are:

* replace many uses of `size` with `indices`
* replace many uses of `size` with `axes`
* replace `1:length(A)` with `eachindex(A)`, or in some cases `linearindices(A)`
* replace `length(A)` with `length(linearindices(A))`
* replace explicit allocations like `Array{Int}(size(B))` with `similar(Array{Int}, axes(B))`
Expand Down Expand Up @@ -52,7 +52,7 @@ To ensure that such errors are caught, in Julia 0.5 both `length` and `size`**sh
error when passed an array with non-1 indexing. This is designed to force users of such arrays
to check the code, and inspect it for whether it needs to be generalized.

### Using `indices` for bounds checks and loop iteration
### Using `axes` for bounds checks and loop iteration

`axes(A)` (reminiscent of `size(A)`) returns a tuple of `AbstractUnitRange` objects, specifying
the range of valid indices along each dimension of `A`. When `A` has unconventional indexing,
Expand All @@ -61,7 +61,7 @@ is `axes(A, d)`.

Base implements a custom range type, `OneTo`, where `OneTo(n)` means the same thing as `1:n` but
in a form that guarantees (via the type system) that the lower index is 1. For any new [`AbstractArray`](@ref)
type, this is the default returned by `indices`, and it indicates that this array type uses "conventional"
type, this is the default returned by `axes`, and it indicates that this array type uses "conventional"
1-based indexing. Note that if you don't want to be bothered supporting arrays with non-1 indexing,
you can add the following line:

Expand All @@ -83,7 +83,7 @@ For this reason, your best option may be to iterate over the array with `eachind

By this definition, 1-dimensional arrays always use Cartesian indexing with the array's native indices. To help enforce this, it's worth noting that the index conversion functions will throw an error if shape indicates a 1-dimensional array with unconventional indexing (i.e., is a `Tuple{UnitRange}` rather than a tuple of `OneTo`). For arrays with conventional indexing, these functions continue to work the same as always.

Using `indices` and `linearindices`, here is one way you could rewrite `mycopy!`:
Using `axes` and `linearindices`, here is one way you could rewrite `mycopy!`:

```julia
function mycopy!(dest::AbstractVector, src::AbstractVector)
Expand Down Expand Up @@ -151,7 +151,7 @@ omit the `@boundscheck` annotation so the check always runs).

### Custom `AbstractUnitRange` types

If you're writing a non-1 indexed array type, you will want to specialize `indices` so it returns
If you're writing a non-1 indexed array type, you will want to specialize `axes` so it returns
a `UnitRange`, or (perhaps better) a custom `AbstractUnitRange`. The advantage of a custom type
is that it "signals" the allocation type for functions like `similar`. If we're writing an array
type for which indexing will start at 0, we likely want to begin by creating a new `AbstractUnitRange`,
Expand All @@ -166,9 +166,9 @@ create a `ModuleA.ZeroArray`, whereas `ModuleB.ZeroRange` indicates a `ModuleB.Z
Note that the Julia package [CustomUnitRanges.jl](https://github.com/JuliaArrays/CustomUnitRanges.jl)
can sometimes be used to avoid the need to write your own `ZeroRange` type.

### Specializing `indices`
### Specializing `axes`

Once you have your `AbstractUnitRange` type, then specialize `indices`:
Once you have your `AbstractUnitRange` type, then specialize `axes`:

```julia
Base.axes(A::ZeroArray) = map(n->ZeroRange(n), A.size)
Expand Down
2 changes: 1 addition & 1 deletion doc/src/manual/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -399,7 +399,7 @@ julia> mean(A)
```

If you are defining an array type that allows non-traditional indexing (indices that start at
something other than 1), you should specialize `indices`. You should also specialize [`similar`](@ref)
something other than 1), you should specialize `axes`. You should also specialize [`similar`](@ref)
so that the `dims` argument (ordinarily a `Dims` size-tuple) can accept `AbstractUnitRange` objects,
perhaps range-types `Ind` of your own design. For more information, see
[Arrays with custom indices](@ref man-custom-indices).
Expand Down

0 comments on commit daadf4a

Please sign in to comment.