# Reference

`OffsetArrays.OffsetArray`

— Type`OffsetArray(A, indices...)`

Return an `AbstractArray`

that shares element type and size with the first argument but uses the supplied `indices`

to infer its axes. If all the indices are `AbstractUnitRange`

s then these are directly used as the axis span along each dimension. Refer to the examples below for other permissible types.

Alternatively it's possible to specify the coordinates of one corner of the array and have the axes be computed automatically from the size of `A`

. This constructor makes it convenient to shift to an arbitrary starting index along each axis, for example to a zero-based indexing scheme followed by arrays in languages such as C and Python. See `Origin`

and the examples below for this usage.

**Example: offsets**

There are two types of `indices`

: integers and ranges-like types.

Integers are recognized as offsets, where `0`

means no offsets are applied:

```
julia> A = OffsetArray(reshape(1:6, 2, 3), -1, -2)
2×3 OffsetArray(reshape(::UnitRange{Int64}, 2, 3), 0:1, -1:1) with eltype Int64 with indices 0:1×-1:1:
1 3 5
2 4 6
julia> A[0, 1]
5
```

Examples of range-like types are: `UnitRange`

(e.g, `-1:2`

), `CartesianIndices`

, and `Colon()`

(or concisely `:`

). A `UnitRange`

specifies the axis span along one particular dimension, `CartesianIndices`

specify the axis spans along multiple dimensions, and a `Colon`

is a placeholder that specifies that the `OffsetArray`

shares its axis with its parent along that dimension.

```
julia> OffsetArray(reshape(1:6, 2, 3), 0:1, -1:1)
2×3 OffsetArray(reshape(::UnitRange{Int64}, 2, 3), 0:1, -1:1) with eltype Int64 with indices 0:1×-1:1:
1 3 5
2 4 6
julia> OffsetArray(reshape(1:6, 2, 3), :, -1:1) # : as a placeholder to indicate that no offset is to be applied to the first dimension
2×3 OffsetArray(reshape(::UnitRange{Int64}, 2, 3), 1:2, -1:1) with eltype Int64 with indices 1:2×-1:1:
1 3 5
2 4 6
```

Use `CartesianIndices`

to specify the coordinates of two diagonally opposite corners:

```
julia> OffsetArray(reshape(1:6, 2, 3), CartesianIndex(0, -1):CartesianIndex(1, 1))
2×3 OffsetArray(reshape(::UnitRange{Int64}, 2, 3), 0:1, -1:1) with eltype Int64 with indices 0:1×-1:1:
1 3 5
2 4 6
```

Integers and range-like types may not be combined in the same call:

```
julia> OffsetArray(reshape(1:6, 2, 3), 0, -1:1)
ERROR: [...]
```

**Example: origin**

`OffsetArrays.Origin`

may be used to specify the origin of the OffsetArray. The term origin here refers to the corner with the lowest values of coordinates, such as the left edge for an `AbstractVector`

, the bottom left corner for an `AbstractMatrix`

and so on. The coordinates of the origin sets the starting index of the array along each dimension.

```
julia> a = [1 2; 3 4];
julia> OffsetArray(a, OffsetArrays.Origin(0, 1))
2×2 OffsetArray(::Matrix{Int64}, 0:1, 1:2) with eltype Int64 with indices 0:1×1:2:
1 2
3 4
julia> OffsetArray(a, OffsetArrays.Origin(0)) # set the origin to zero along each dimension
2×2 OffsetArray(::Matrix{Int64}, 0:1, 0:1) with eltype Int64 with indices 0:1×0:1:
1 2
3 4
```

`OffsetArrays.OffsetVector`

— Type`OffsetVector(v, index)`

Type alias and convenience constructor for one-dimensional `OffsetArray`

s.

`OffsetArrays.OffsetMatrix`

— Type`OffsetMatrix(A, index1, index2)`

Type alias and convenience constructor for two-dimensional `OffsetArray`

s.

`OffsetArrays.Origin`

— Type```
Origin(indices...)
Origin(origin::Tuple)
Origin(origin::CartesianIndex)
```

A helper type to construct OffsetArray with a given origin. This is not exported.

The `origin`

of an array is defined as the tuple of the first index along each axis, i.e., `first.(axes(A))`

.

**Example**

```
julia> a = [1 2; 3 4];
julia> using OffsetArrays: Origin
julia> OffsetArray(a, Origin(0, 1))
2×2 OffsetArray(::Matrix{Int64}, 0:1, 1:2) with eltype Int64 with indices 0:1×1:2:
1 2
3 4
julia> OffsetArray(a, Origin(0)) # short notation for `Origin(0, 0)`
2×2 OffsetArray(::Matrix{Int64}, 0:1, 0:1) with eltype Int64 with indices 0:1×0:1:
1 2
3 4
```

An `Origin`

object is callable, and it may shift the origin of an array to the specified point.

```
julia> b = Origin(0)(a) # shift the origin of the array to (0,0)
2×2 OffsetArray(::Matrix{Int64}, 0:1, 0:1) with eltype Int64 with indices 0:1×0:1:
1 2
3 4
```

The type `Origin`

, when called with an `AbstractArray`

as the argument, will return an instance corresponding ot the origin of the array.

```
julia> origin_b = Origin(b) # retrieve the origin of the array as an Origin instance
Origin(0, 0)
julia> origin_b(ones(2,2)) # shift the origin of another array to that of b, in this case to (0,0)
2×2 OffsetArray(::Matrix{Float64}, 0:1, 0:1) with eltype Float64 with indices 0:1×0:1:
1.0 1.0
1.0 1.0
```

One may broadcast an `Origin`

instance over multiple arrays to shift them all to the same origin.

```
julia> using OffsetArrays: Origin
julia> a = [1 2; 3 4]; # origin at (1,1)
julia> b = Origin(2,3)(a); # origin at (2,3)
julia> c = Origin(4)(a); # origin at (4,4)
julia> ao, bo, co = Origin(0).((a, b, c)); # shift all origins to (0,0)
julia> first.(axes(ao)) == first.(axes(bo)) == first.(axes(co)) == (0,0)
true
julia> ao, bo, co = Origin(b).((a, b, c)); # shift all origins to that of b
julia> first.(axes(ao)) == first.(axes(bo)) == first.(axes(co)) == (2,3)
true
julia> ao, bo, co = OffsetArray.((a, b, c), Origin(b)); # another way to do the same
julia> first.(axes(ao)) == first.(axes(bo)) == first.(axes(co)) == (2,3)
true
```

`OffsetArrays.IdOffsetRange`

— Type`ro = IdOffsetRange(r::AbstractUnitRange, offset=0)`

Construct an "identity offset range". Numerically, `collect(ro) == collect(r) .+ offset`

, with the additional property that `axes(ro, 1) = axes(r, 1) .+ offset`

. When `r`

starts at 1, then `ro[i] == i`

and even `ro[ro] == ro`

, i.e., it's the "identity," which is the origin of the "Id" in `IdOffsetRange`

.

**Examples**

The most common case is shifting a range that starts at 1 (either `1:n`

or `Base.OneTo(n)`

):

```
julia> using OffsetArrays: IdOffsetRange
julia> ro = IdOffsetRange(1:3, -2)
IdOffsetRange(values=-1:1, indices=-1:1)
julia> axes(ro, 1)
IdOffsetRange(values=-1:1, indices=-1:1)
julia> ro[-1]
-1
julia> ro[3]
ERROR: BoundsError: attempt to access 3-element OffsetArrays.IdOffsetRange{Int64, UnitRange{Int64}} with indices -1:1 at index [3]
```

If the range doesn't start at 1, the values may be different from the indices:

```
julia> ro = IdOffsetRange(11:13, -2)
IdOffsetRange(values=9:11, indices=-1:1)
julia> axes(ro, 1) # 11:13 is indexed by 1:3, and the offset is also applied to the axes
IdOffsetRange(values=-1:1, indices=-1:1)
julia> ro[-1]
9
julia> ro[3]
ERROR: BoundsError: attempt to access 3-element OffsetArrays.IdOffsetRange{Int64, UnitRange{Int64}} with indices -1:1 at index [3]
```

**Extended help**

Construction/coercion preserves the (shifted) values of the input range, but may modify the indices if required by the specified types. For example,

`r = OffsetArrays.IdOffsetRange{Int,UnitRange{Int}}(3:4)`

has `r[1] == 3`

and `r[2] == 4`

, whereas

`r = OffsetArrays.IdOffsetRange{Int,Base.OneTo{Int}}(3:4)`

has `r[3] == 3`

and `r[4] == 4`

, and `r[1]`

would throw a `BoundsError`

. In this latter case, a shift in the axes was needed because `Base.OneTo`

ranges must start with value 1.

In the future, *conversion* will preserve both the values and the indices, throwing an error when this is not achievable. For instance,

`r = convert(OffsetArrays.IdOffsetRange{Int,UnitRange{Int}}, 3:4)`

has `r[1] == 3`

and `r[2] == 4`

and would satisfy `r == 3:4`

, whereas

```
julia> convert(OffsetArrays.IdOffsetRange{Int,Base.OneTo{Int}}, 3:4) # future behavior, not present behavior
ERROR: ArgumentError: first element must be 1, got 3
```

where the error will arise because the result could not have the same axes as the input.

An important corollary is that `typeof(r1)(r2)`

and `oftype(r1, r2)`

will behave differently: the first coerces `r2`

to be of the type of `r1`

, whereas the second converts. Developers are urged to future-proof their code by choosing the behavior appropriate for each usage.

`OffsetArrays.no_offset_view`

— Function`no_offset_view(A)`

Return an `AbstractArray`

that shares structure and underlying data with the argument, but uses 1-based indexing. May just return the argument when applicable. Not exported.

The default implementation uses `OffsetArrays`

, but other types should use something more specific to remove a level of indirection when applicable.

```
julia> A = [1 3 5; 2 4 6];
julia> O = OffsetArray(A, 0:1, -1:1)
2×3 OffsetArray(::Matrix{Int64}, 0:1, -1:1) with eltype Int64 with indices 0:1×-1:1:
1 3 5
2 4 6
julia> OffsetArrays.no_offset_view(O)[1,1] = -9
-9
julia> A
2×3 Matrix{Int64}:
-9 3 5
2 4 6
```

`OffsetArrays.AxisConversionStyle`

— Type`OffsetArrays.AxisConversionStyle(typeof(indices))`

`AxisConversionStyle`

declares if `indices`

should be converted to a single `AbstractUnitRange{Int}`

or to a `Tuple{Vararg{AbstractUnitRange{Int}}}`

while flattening custom types into indices. This method is called after `to_indices(A::Array, axes(A), indices)`

to provide further information in case `to_indices`

does not return a `Tuple`

of `AbstractUnitRange{Int}`

.

Custom index types should extend `AxisConversionStyle`

and return either `OffsetArray.SingleRange()`

, which is the default, or `OffsetArray.TupleOfRanges()`

. In the former case, the type `T`

should define `Base.convert(::Type{AbstractUnitRange{Int}}, ::T)`

, whereas in the latter it should define `Base.convert(::Type{Tuple{Vararg{AbstractUnitRange{Int}}}}, ::T)`

.

An example of the latter is `CartesianIndices`

, which is converted to a `Tuple`

of `AbstractUnitRange{Int}`

while flattening the indices.

**Example**

```
julia> struct NTupleOfUnitRanges{N}
x ::NTuple{N, UnitRange{Int}}
end
julia> Base.to_indices(A, inds, t::Tuple{NTupleOfUnitRanges{N}}) where {N} = t;
julia> OffsetArrays.AxisConversionStyle(::Type{NTupleOfUnitRanges{N}}) where {N} = OffsetArrays.TupleOfRanges();
julia> Base.convert(::Type{Tuple{Vararg{AbstractUnitRange{Int}}}}, t::NTupleOfUnitRanges) = t.x;
julia> a = zeros(3, 3);
julia> inds = NTupleOfUnitRanges((3:5, 2:4));
julia> oa = OffsetArray(a, inds);
julia> axes(oa, 1) == 3:5
true
julia> axes(oa, 2) == 2:4
true
```

`OffsetArrays.center`

— Function`center(A, [r::RoundingMode=RoundDown])::Dims`

Return the center coordinate of given array `A`

. If `size(A, k)`

is even, a rounding procedure will be applied with mode `r`

.

This method requires at least OffsetArrays 1.9.

**Examples**

```
julia> A = reshape(collect(1:9), 3, 3)
3×3 Matrix{Int64}:
1 4 7
2 5 8
3 6 9
julia> c = OffsetArrays.center(A)
(2, 2)
julia> A[c...]
5
julia> Ao = OffsetArray(A, -2, -2); # axes (-1:1, -1:1)
julia> c = OffsetArrays.center(Ao)
(0, 0)
julia> Ao[c...]
5
```

To shift the center coordinate of the given array to `(0, 0, ...)`

, you can use `centered`

.

`OffsetArrays.centered`

— Function`centered(A, cp=center(A)) -> Ao`

Shift the center coordinate/point `cp`

of array `A`

to `(0, 0, ..., 0)`

. Internally, this is equivalent to `OffsetArray(A, .-cp)`

.

This method requires at least OffsetArrays 1.9.

**Examples**

```
julia> A = reshape(collect(1:9), 3, 3)
3×3 Matrix{Int64}:
1 4 7
2 5 8
3 6 9
julia> Ao = OffsetArrays.centered(A); # axes (-1:1, -1:1)
julia> Ao[0, 0]
5
julia> Ao = OffsetArray(A, OffsetArrays.Origin(0)); # axes (0:2, 0:2)
julia> Aoo = OffsetArrays.centered(Ao); # axes (-1:1, -1:1)
julia> Aoo[0, 0]
5
```

Users are allowed to pass `cp`

to change how "center point" is interpreted, but the meaning of the output array should be reinterpreted as well. For instance, if `cp = map(last, axes(A))`

then this function no longer shifts the center point but instead the bottom-right point to `(0, 0, ..., 0)`

. A commonly usage of `cp`

is to change the rounding behavior when the array is of even size at some dimension:

```
julia> A = reshape(collect(1:4), 2, 2) # Ideally the center should be (1.5, 1.5) but OffsetArrays only support integer offsets
2×2 Matrix{Int64}:
1 3
2 4
julia> OffsetArrays.centered(A, OffsetArrays.center(A, RoundUp)) # set (2, 2) as the center point
2×2 OffsetArray(::Matrix{Int64}, -1:0, -1:0) with eltype Int64 with indices -1:0×-1:0:
1 3
2 4
julia> OffsetArrays.centered(A, OffsetArrays.center(A, RoundDown)) # set (1, 1) as the center point
2×2 OffsetArray(::Matrix{Int64}, 0:1, 0:1) with eltype Int64 with indices 0:1×0:1:
1 3
2 4
```

See also `center`

.