numidr/docs/Operations.md

Basic Operations on Arrays

Constructing Arrays

The most important array constructor is array, which returns an array of the specified values:

array [[1, 2, 3], [4, 5, 6]]

Scalars, vectors and matrices have their own constructors, used in exactly the same way (scalar, vector, and matrix). These should be used instead of array whenever possible, as they provide more information to the type-checker.

There are also a few other, more basic constructors for convenience.

-- A 2x2x3 array filled with zeros
repeat 0 [2, 2, 3]

-- Same as previous
zeros [2, 2, 3]

-- A 2x2x3 array filled with ones
ones [2, 2, 3]

Indexing Arrays

NumIdr provides multiple different indexing functions for different purposes. These functions can be grouped based on these categories:

Operation

• Access - Accesses and returns elements from the array.
• Update - Returns a new array with the specified element or range updated by a function. These are indicated by an Update suffix.
• Set - Returns a new array with the specified element or range set to new values. These are indicated by a Set suffix.

Range

• Default - Operates on a single array element.
• Range - Operates on multiple elements at once. These are indicated by a Range suffix.

Safety

• Safe - Guarantees through its type that the index is within range by requiring each index to be a Fin value.
• Non-Bounded - Does not guarantee through its type that the index is within range, and returns Nothing if the provided index is out of bounds. These are indicated by an NB suffix.
• Unsafe - Does not perform any bounds checks at all. These are indicated by an Unsafe suffix. Only use these if you really know what you are doing!

Not all combinations of these categories are defined by the library. Here are the currently provided indexing functions:

	Safe	Ranged Safe	Non-Bounded	Ranged Non-Bounded	Unsafe	Ranged Unsafe
Access	index, (!!)	indexRange, (!!..)	indexNB, (!?)	indexRangeNB, (!?..)	indexUnsafe, (!#)	indexRangeUnsafe, (!#..)
Update	indexUpdate	indexUpdateRange	indexUpdateNB
Set	indexSet	indexSetRange	indexSetNB

The accessor functions also have operator forms.

Specifying Coordinates

When indexing a single element, a coordinate is specified as a list of numbers, where each number is either a Fin value for safe indexing or a Nat value for non-bounded and unsafe indexing.

index [1, 0] arr

-- Equivalent operator form
arr !! [1, 0]

With ranged indexing, a sub-array of the original array is accessed or modified. This sub-array is given by a list of range specifiers, one for each axis, which can be one of the following:

• Bounds x y - Every index from x to y
• StartBound x - Every index from x to the end of the axis
• EndBound y - Every index from the start of the axis to y
• All - Every index in the axis
• Indices xs - A list of indices in the axis
• Filter p - A predicate specifying which indices to access or modify

There is also an extra specifier, One i, that selects exactly one index of the axis. It is only usable in safe indexing, and it is notable for being the only range specifier that decreases the rank of the sub-array. For example, the following matrix access returns the first column as a vector due to One being used:

matrix [[2, 0], [1, 2]] !!.. [All, One 0]
  == vector [2, 1]

Previous | Contents | Next