diff --git a/dev/reference/index.html b/dev/reference/index.html index c70e7ce..fc3de5a 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -27,7 +27,7 @@ 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 4source
OffsetArrays.OffsetVector — Type
OffsetVector(v, index)

Type alias and convenience constructor for one-dimensional OffsetArrays.

source
OffsetArrays.OffsetMatrix — Type
OffsetMatrix(A, index1, index2)

Type alias and convenience constructor for two-dimensional OffsetArrays.

source
OffsetArrays.Origin — Type
Origin(indices...)
+ 3  4
source
OffsetArrays.OffsetVector — Type
OffsetVector(v, index)

Type alias and convenience constructor for one-dimensional OffsetArrays.

source
OffsetArrays.OffsetMatrix — Type
OffsetMatrix(A, index1, index2)

Type alias and convenience constructor for two-dimensional OffsetArrays.

source
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];
 
@@ -71,7 +71,7 @@
 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
source
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
+true
source
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)
@@ -94,7 +94,7 @@
 
 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.

Warning

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.

source
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];
+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.

source
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:
@@ -107,7 +107,7 @@
 julia> A
 2×3 Matrix{Int64}:
  -9  3  5
-  2  4  6
source
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}
+  2  4  6
source
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
 
@@ -127,7 +127,7 @@
 true
 
 julia> axes(oa, 2) == 2:4
-true
source
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.

OffsetArrays 1.9

This method requires at least OffsetArrays 1.9.

Examples

julia> A = reshape(collect(1:9), 3, 3)
+true
source
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.

OffsetArrays 1.9

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
@@ -145,7 +145,7 @@
 (0, 0)
 
 julia> Ao[c...]
-5

To shift the center coordinate of the given array to (0, 0, ...), you can use centered.

source
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).

OffsetArrays 1.9

This method requires at least OffsetArrays 1.9.

Examples

julia> A = reshape(collect(1:9), 3, 3)
+5

To shift the center coordinate of the given array to (0, 0, ...), you can use centered.

source
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).

OffsetArrays 1.9

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
@@ -174,4 +174,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.

source
+ 2 4

See also center.

source