Creates an {{@type}} from a nested array with uniform dimensions. For example:

{{@type}}.new([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

Would create the 3x3 identity matrix of type {{@type}}(Int32).

This constructor will figure out the types of the scalars at the bottom of the nested array at compile time, which allows mixing datatypes effortlessly. For example, to create a matrix with 0.5 on the diagonals:

{{@type}}.new([[0.5, 0, 0], [0, 0.5, 0], [0, 0, 0.5]])

This may seem trivial, but note that the 0.5s are implicit Float32 literals, whereas the 0s are implicit Int32 literals. So, the type returned by that example will actually be an {{@type}}(Float32 | Int32). This also works for more disorganized examples:

{{@type}}.new([["We can mix types", 2, :do], ["C", 0.0, "l stuff."]])

The above line will create an {{@type}}(String | Int32 | Symbol | Float32).

When a nested array with non-uniform dimensions is passed, this method will raise a DimensionError. For example:

{{@type}}.new([[1], [1, 2]]) # => DimensionError

Adds a dimension at highest level, where each "row" is an input {{@type}}. If pad is false, then throw error if shapes of objects do not match; otherwise, pad subarrays along each axis to match whichever is largest in that axis

NArray[1, 2, 3] == NArray.new([1, 2, 3]) NArray[[1, 2, 3]] == NArray.new([[1, 2, 3]])

Constructs an {{@type}} using a user-provided shape (see shape) and a callback. The provided callback should map a multidimensional index, coord, (and an optional packed index) to the value you wish to store at that position. For example, to create the 2x2 identity matrix:

Phase::{{@type}}.build([2, 2]) do |coord|
  if coord[0] == coord[1]
    1
  else
    0
  end
end

Which will create:

[[1, 0, 0],
  0, 1, 0],
  0, 0, 1]]

The buffer index allows you to easily index elements in lexicographic order. For example:

{{@type}}.build([5, 1]) { |coord, index| index }

Will create:

[[0],
 [1],
 [2],
 [3],
 [4]]

Given a list of {{@type}}s, returns the smallest shape array in which any one of those {{@type}}s can be contained.

TODO Example

Checks that the shape of this and other match in every dimension (except axis, if it is specified)

Fills an {{@type}} of given shape with a specified value. For example, to create a zero vector:

{{@type}}.fill([3, 1], 0)

Will produce

[[0],
 [0],
 [0]]

Note that this method makes no effort to duplicate value, so this should only be used for Structs. If you want to populate an {{@type}} with Objects, see .new(shape, &block).

creates an {{@type}}-type vector from a tuple of scalars.

Checks for elementwise equality between self and other.

replaces all values in a boolean mask with a given value

Stores the elements of an {{@type}} in lexicographic (row-major) order.

Creates a deep copy of this {{@type}}; Allocates a new buffer of the same shape, and calls #clone on every item in the buffer.

Checks that the shape of this and other match in every dimension (except axis, if it is specified)

Creates a shallow copy of this {{@type}}; Allocates a new buffer of the same shape, and duplicates every item in the buffer.

The default "each" with no iterator type passed is lexicographic. For other orders, default to MultiIndexable's implementation.

Returns an iterator that will yield each coordinate of self in lexicographic (row-major) order.

narr = NArray[[1, 2, 3], [4, 5, 6]]
iter = narr.each_coord
iter.next # => [0, 0]
iter.next # => [0, 1]
iter.next # => [0, 2]
iter.next # => [1, 0]
iter.next # => [1, 1]
iter.next # => [1, 2]
iter.next # => Iterator::Stop

Iterates over the collection, yielding both the elements and their index.

["Alice", "Bob"].each_with_index do |user, i|
  puts "User ##{i}: #{user}"
end

Prints:

User # 0: Alice
User # 1: Bob

Accepts an optional offset parameter, which tells it to start counting from there. So, a more human friendly version of the previous snippet would be:

["Alice", "Bob"].each_with_index(1) do |user, i|
  puts "User ##{i}: #{user}"
end

Which would print:

User # 1: Alice
User # 2: Bob

Returns an Iterator over the elements in this MultiIndexable that will iterate in the fastest order possible. For most implementations, it is very likely that #each will be just as fast. However, certain implementations of MultiIndexable may have substantial performance differences. As a rule of thumb, this method is only worth using if the MultiIndexable you call it on explicitly mentions that you should.

NArray[1, 2, 3].fast_each.each do |el|
  # ...
end

This version requires you are only <= on each axis; cannot pad

Returns a MultiIndexable with the results of running the block against each element of self.

narr = NArray[[1, 2, 3], [4, 5, 6]]
res = narr.map { |el| el.to_s } # => NArray[["1", "2", "3"], ["4", "5", "6"]]

TODO docs, test

Returns a MultiIndexable with the results of running the block against each element and coordinate comprising self.

narr = NArray[[1, 2, 3], [4, 5, 6]]
narr.map_with_coord do |el, coord|
  el + coord.sum
end # => NArray[[1, 3, 5], [5, 7, 9]]

TODO docs DISCUSS is this good behaviour?

Like #map, but the block gets passed both the element and its index.

["Alice", "Bob"].map_with_index { |name, i| "User ##{i}: #{name}" }
# => ["User #0: Alice", "User #1: Bob"]

Accepts an optional offset parameter, which tells it to start counting from there.

core pad(0, {0 => {2, 2}, 1 => {3, 4}, -1 => {0, 5}})

optimization for pushing other NArrays on axis 0, in-place

TODO axis = 0 should not be a user modifiable parameter and never should have been

Returns the total number of elements in this MultiIndexable. This quantity is always equal to shape.product. However, this method is almost always more performant than computing the product directly.

NArray.new(['a', 'b', 'c']).size # => 3
NArray.new([[0, 1], [1, 0]]).size # => 4

Copies the elements in region to a new {{@type}}, assuming that region is in canonical form and in-bounds for this {{@type}}. For full specification of canonical form see IndexRegion documentation.

Retrieves the element specified by coord, assuming that coord is in canonical form and in-bounds for this {{@type}}. For full specification of canonical form see IndexRegion documentation.

Copies the elements from a MultiIndexable src into region, assuming that region is in canonical form and in-bounds for this {{type}} and the shape of region matches the shape of src.

Sets each element in region to value, assuming that region is in canonical form and in-bounds for this {{type}}