Merge pull request #90 from JuliaArrays/teh/redesign

Redesign around IdOffsetRange

Project.toml

@@ -1,6 +1,6 @@
 name = "OffsetArrays"
 uuid = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
-version = "0.11.4"
+version = "1.0.0"
 
 [compat]
 julia = "0.7, 1"

README.md

@@ -1,10 +1,55 @@
 # OffsetArrays.jl
 
+[![Build Status](https://travis-ci.org/JuliaArrays/OffsetArrays.jl.svg?branch=master)](https://travis-ci.org/JuliaArrays/OffsetArrays.jl)
+[![codecov.io](http://codecov.io/github/JuliaArrays/OffsetArrays.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaArrays/OffsetArrays.jl?branch=master)
+[![PkgEval][pkgeval-img]][pkgeval-url]
+
 
 OffsetArrays provides Julia users with arrays that have arbitrary
 indices, similar to those found in some other programming languages
 like Fortran.
 
+## Usage
+
+You can construct such arrays as follows:
+
+```julia
+OA = OffsetArray(A, axis1, axis2, ...)
+```
+
+where you want `OA` to have axes `(axis1, axis2, ...)` and be indexed by values that
+fall within these axis ranges. Example:
+
+```julia
+using OffsetArrays
+A = reshape(1:15, 3, 5)
+println("here is A:")
+display(A)
+OA = OffsetArray(A, -1:1, 0:4)    # OA will have axes (-1:1, 0:4)
+println("here is OA:")
+display(OA)
+@show OA[-1,0] OA[1,4]
+```
+
+which prints out
+
+```
+here is A:
+3×5 reshape(::UnitRange{Int64}, 3, 5) with eltype Int64:
+ 1  4  7  10  13
+ 2  5  8  11  14
+ 3  6  9  12  15
+here is OA:
+OffsetArray(reshape(::UnitRange{Int64}, 3, 5), -1:1, 0:4) with eltype Int64 with indices -1:1×0:4:
+ 1  4  7  10  13
+ 2  5  8  11  14
+ 3  6  9  12  15
+OA[-1, 0] = 1
+OA[1, 4] = 15
+```
+
+OffsetArrays works for arbitrary dimensionality:
+
 ```julia
 julia> using OffsetArrays
 
@@ -21,7 +66,8 @@ julia> y[-1,-7,-128,-5,-1,-3,-2,-1] += 5
 ```
 
 ## Example: Relativistic Notation
-Suppose we have a position vector `r = [:x, :y, :z]` which is naturally one-based, ie. `r[1] == :x`, `r[2] == :y`,  `r[3] == :z` and we also want to construct a relativistic position vector which includes time as the 0th component. This can be done with OffsetArrays like 
+Suppose we have a position vector `r = [:x, :y, :z]` which is naturally one-based, ie. `r[1] == :x`, `r[2] == :y`,  `r[3] == :z` and we also want to construct a relativistic position vector which includes time as the 0th component. This can be done with OffsetArrays like
+
 ```julia
 julia> using OffsetArrays
 
@@ -49,7 +95,7 @@ Suppose one wants to represent the Laurent polynomial
 ```
 6/x + 5 - 2*x + 3*x^2 + x^3
 ```
-in julia. The coefficients of this polynomial are a naturally `-1` based list, since the `n`th element of the list 
+in julia. The coefficients of this polynomial are a naturally `-1` based list, since the `n`th element of the list
 (counting from `-1`) `6, 5, -2, 3, 1` is the coefficient corresponding to the `n`th power of `x`. This Laurent polynomial can be evaluated at say `x = 2` as follows.
 ```julia
 julia> using OffsetArrays
@@ -72,4 +118,8 @@ Notice our use of the `eachindex` function which does not assume that the given
 
 ## Notes on supporting OffsetArrays
 
-Julia supports generic programming with arrays that doesn't require you to assume that indices start with 1, see the [documentation](http://docs.julialang.org/en/latest/devdocs/offset-arrays/).
+There are several "tricks" that make it easier to support arrays with general indexes, see the [documentation](http://docs.julialang.org/en/latest/devdocs/offset-arrays/).
+
+
+[pkgeval-img]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/O/OffsetArrays.svg
+[pkgeval-url]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/report.html