Copy constructor that throws a ShapeError if region doesn't fit inside of bound_shape. (see IndexRegion#fits_in?)

src = IndexRegion.cover([3, 4]) # => IndexRegion[0..2, 0..3]
IndexRegion.new(src, [4, 4]) # => IndexRegion[0..2, 0..3]
IndexRegion.new(src, [2, 2]) # => ShapeError

Creates an IndexRegion from a region_literal, using bound_shape for relative index handling. This is the most commonly used IndexRegion constructor. If the region literal has fewer dimensions than bound_shape, then the latter axes will be inferred as ...

# Normal usage
IndexRegion.new([1...5, ..-3], [5, 5]) # => IndexRegion[1..4, 0..2]

# If the region literal is shorter than the bound shape, it
# is filled with trailing ".."s
IndexRegion.new([1], [2, 3])     # => IndexRegion[1, 0..2]
IndexRegion.new([1, ..], [2, 3]) # => IndexRegion[1, 0..2]

# If the region literal is longer than the bound shape, a
# DimensionError is raised
IndexRegion.new([.., 3], [3]) # => DimensionError

# If the region literal is out of bounds, an IndexError
# is raised
IndexRegion.new([5..10], [2]) # => IndexError
IndexRegion.new([5..10], [-2]) # => IndexError

Creates an IndexRegion from an absolute (positive, bounded) region_literal. This allows you to bypass the usual requirement of passing a bound_shape, which is usually needed in order to process negative or nil indexes.

IndexRegion.new([1, 2...5]) # => IndexRegion[1, 2..4]
IndexRegion.new([..]) # => Exception (TODO: pick a better exception)
IndexRegion.new([-1]) # => Exception (TODO: pick a better exception)

Creates an IndexRegion by clipping the region_literal to fit inside of the shape trim_to. By default, only absolute (positive) ordinates can be used in the region literal - however, if a bound_shape is passed, relative (negative / unbounded) indexing can be used, and will refer to it.

# Using *trim_to* allows you to clip a region to a shape
IndexRegion.new([0..5, 1..2], trim_to: [2, 2]) # => IndexRegion[0..1, 1..1]

# A *bound_shape* lets you use relative indexes
IndexRegion.new([.., 2..-2], bound_shape: [3, 5], trim_to: [2, 3]) # => IndexRegion[0..1, 2..2]

# This method won't throw, but it *will* return an empty
# IndexRegion if the *region_literal* doesn't fit in *trim_to*.
IndexRegion.new([5..8], trim_to: [3]) # => IndexRegion[0..0..0]

Creates an IndexRegion whose coordinates fully cover the given bound_shape.

IndexRegion.cover([2, 3]).to_narr # => 2x3 Phase::NArray(Array(Int32))
                                  #    [[[0, 0], [0, 1], [0, 2]],
                                  #     [[1, 0], [1, 1], [1, 2]]]

Returns true if both the shape and elements of self and other are equal.

NArray.new([1, 2]) == NArray.new([1, 2]) # => true
NArray.new([[1], [2]]) == NArray.new([1, 2]) # => false
NArray.new([8, 2]) == NArray.new([1, 2]) # => false

Maps an absolute (output) coordinate to its corresponding local (input) coordinate.

idx_r = IndexRegion(Int32).new([3..5, 2..1])
idx_r.absolute_to_local([3, 2]) # => [0, 0]
idx_r.absolute_to_local([4, 2]) # => [1, 0]
idx_r.absolute_to_local([5, 1]) # => [2, 1]

Unsafe version of #absolute_to_local that does not check if coord is in bounds for this IndexRegion.

Returns a copy of self with all instance variables cloned.

Stores the user-hinted dimension dropping information from the region literal. For example: IndexRegion(Int32).new(1, 1..1, 1..2) has @degeneracy == [true, false, false] because axis 0 was an integer (droppable) whereas axis 1 and 2 were both ranges (and thus aren't reliably droppable). This array will be populated regardless of if dimension dropping is enabled. If this IndexRegion does not correspond to a region literal (e.g. IndexRegion.cover(shape)), @degeneracy should be populated with false.

Stores the user-hinted dimension dropping information from the region literal. For example: IndexRegion(Int32).new(1, 1..1, 1..2) has @degeneracy == [true, false, false] because axis 0 was an integer (droppable) whereas axis 1 and 2 were both ranges (and thus aren't reliably droppable). This array will be populated regardless of if dimension dropping is enabled. If this IndexRegion does not correspond to a region literal (e.g. IndexRegion.cover(shape)), @degeneracy should be populated with false.

Whether or not dimensions should be dropped.

Unsafe version of #absolute_to_local that does not check if coord is in bounds for this IndexRegion.

Returns a copy of the coordinate of the first "corner" in this IndexRegion. For example, if the region literal is [1..3, 5..-2..1], the "first corner" is [1, 5] - the first ordinate on the axis 0 range is 1, and the first ordinate on axis 1 is 5. Similarly, the #last coordinate is [3, 1]. Note that if and only if @step[i] == 0, then @first[i] and @last[i] will be meaningless, as an empty set of coordinates has no corners. See @step.

Returns true if this IndexRegion contains coordinates that all fit inside of the given bound_shape. For example:

idx_r = IndexRegion.new(region_literal: [1..2..], bound_shape: [5])
idx_r.to_narr # => [[1], [3]]

idx_r.fits_in?([3]) # => false
idx_r.fits_in?([4]) # => true
idx_r.fits_in?([4, 4]) # => DimensionError

See Object#hash(hasher)

Returns true if this IndexRegion points to the provided coord. For example:

idx_r = IndexRegion(Int32).new([0..3, 5..7])

# This IndexRegion maps the input coordinate [0, 0] to [0, 5]
idx_r.get(0, 0) # => [0, 5]

# And thus it includes [0, 5]
idx_r.includes? [0, 5] # => true

# On the other hand, no input coordinate will map to [10, 10]
idx_r.includes? [10, 10] # => false

# Don't confuse input and output coordinates, here! Like all
# `MultiIndexable`s, idx_r implements `#has_coord?`. `#includes?`
# refers to the values (output coordinates) of the `IndexRegion`,
# whereas `#has_coord?` refers to the input coordinates.
idx_r.includes? [0, 0] # => false
idx_r.has_coord? [0, 0] # => true

Similar to IndexRegion#first. For example, if the region literal is [1..3, 5..-2..1], the "last corner" is [3, 1] - the last ordinate on the axis 0 range is 3, and the last ordinate on axis 1 is 1.

Maps a local (input) coordinate to its corresponding absolute (output) coordinate. This is equivalent to using IndexRegion#[](coord), but it is aliased here in order to make IndexRegion code easier to reason about. For example:

idx_r = IndexRegion(Int32).new([3..5, 2..1])
idx_r.local_to_absolute([0, 0]) # => [3, 2]
idx_r[0, 0] # => [3, 2]

Unsafe version of #local_to_absolute that does not check if coord is in bounds for this IndexRegion.

Returns the number of dimensions of the space that this IndexRegion maps into. For example:

#                          region   proper shape
idx_r = IndexRegion.new([1, .., ..], [5, 5, 5])

# The IndexRegion above describes a 2D region (a matrix)
puts idx_r.dimensions # => 2

# But the matrix draws out of a 3D MultiIndexable:
puts idx_r.proper_dimensions # => 3

Returns a reversed copy of this IndexRegion. See #reverse!.

Reverses the ordering of an IndexRegion in place. For example:

idx_r = IndexRegion(Int32).new([0..2..2])
narr = NArray['a', 'b', 'c']

idx_r.each { |coord| puts coord } # => [0], [2]
narr[idx_r] # => NArray['a', 'c']

idx_r.reverse!
idx_r.each { |coord| puts coord } # => [2], [0]
narr[idx_r] # => NArray['c', 'a']

============= Methods required by MultiIndexable ===========================

TODO drop isn't being used here, why is it included?

Returns the spacing between elements along each axis. For example, if the region literal is [1..3, 5..-2..1], the stride on axis 0 is 1 (by default), and the stride on axis 1 is -2 (as written in the region literal). Thus, calling #stride on the corresponding IndexRegion would yield [1, -2].

idx_r = IndexRegion(Int32).new([1..3, 5..-2..1])
puts idx_r.stride # => [1, -2]

Returns a translated copy of this IndexRegion. See #translate!.

Returns a translated copy of this IndexRegion. See #translate!.

Translates this IndexRegion in place by adding an offset to each output coordinate. For example:

idx_r = IndexRegion(Int32).new([0, 5..-2..0])
puts idx_r # => IndexRegion[0, 5..-2..1]

idx_r.translate!([1, -1])
puts idx_r # => IndexRegion[1, 4..-2..0]

IndexRegions only output canonical coordinates. This
translation would produce negative ordinates in the output coords,
which is illegal.
idx_r.translate!([-10, -10]) # => IndexError

Returns a trimmed copy of this IndexRegion. See #trim!.

Clips this IndexRegion in-place to fit the bound_shape provided.

a = IndexRegion(Int32).new([1..3, 10..-2..0])
puts a # => IndexRegion[1..3, 10..-2..0]

# Trimming to a shape that `a` fits in has no effect:
a.trim!([100, 100])
puts a # => IndexRegion[1..3, 10..-2..0]

a.trim!([2, 3])
puts a # => IndexRegion[1..1, 2..-2..0]

# It's possible to recieve an empty result after trimming
b = IndexRegion(Int32).new([5..6])
b.trim!([0])
puts b # => IndexRegion[0..0..0] (no elements)

# When using the wrong number of dimensions, a DimensionError is raised
c = IndexRegion(Int32).new([5..4])
c.trim!([4, 3]) # => DimensionError

Returns the number of dimensions of the space that this IndexRegion maps into. For example:

#                          region   proper shape
idx_r = IndexRegion.new([1, .., ..], [5, 5, 5])

# The IndexRegion above describes a 2D region (a matrix)
puts idx_r.dimensions # => 2

# But the matrix draws out of a 3D MultiIndexable:
puts idx_r.proper_dimensions # => 3

Returns the number of dimensions of the space that this IndexRegion maps into. For example:

#                          region   proper shape
idx_r = IndexRegion.new([1, .., ..], [5, 5, 5])

# The IndexRegion above describes a 2D region (a matrix)
puts idx_r.dimensions # => 2

# But the matrix draws out of a 3D MultiIndexable:
puts idx_r.proper_dimensions # => 3

Translates an IndexRegion in place, without checking that the result is valid. See #translate!.

WARNING this allows for the creation of IndexRegions with negative ordinates, which may cause undocumented behaviour elsewhere in the code. The burden is on the user to ensure that negative ordinates are not created, or that they are appropriately handled.