diff --git a/docs/Intro.md b/docs/Intro.md index bcc6e0e..9673732 100644 --- a/docs/Intro.md +++ b/docs/Intro.md @@ -7,7 +7,7 @@ If you're familiar with the Python library [NumPy](https://numpy.org/) or anythi #### Tutorial 1. [Fundamental Data Types](DataTypes.md) -2. Basic Operations +2. [Basic Operations on Arrays](Operations.md) 3. Working with Vectors and Matrices 4. Transforms diff --git a/docs/Operations.md b/docs/Operations.md index 66a6fca..90d7129 100644 --- a/docs/Operations.md +++ b/docs/Operations.md @@ -1,2 +1,81 @@ -# Basic Operations +# Basic Operations on Arrays +## Constructing Arrays + +The most important array constructor is `array`, which returns an array of the specified values: + +```idris +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. + +```idris +-- 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. + +```idris +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: + +```idris +matrix [[2, 0], [1, 2]] !!.. [All, One 0] + == vector [2, 1] +``` + +[Previous](DataTypes.md) | [Contents](Intro.md) | [Next](VectorsMatrices.md) diff --git a/docs/Transforms.md b/docs/Transforms.md index 8d482ae..d2e5e37 100644 --- a/docs/Transforms.md +++ b/docs/Transforms.md @@ -1,2 +1,4 @@ # Transforms + +[Previous](VectorsMatrices.md) | [Contents](Intro.md) diff --git a/docs/VectorsMatrices.md b/docs/VectorsMatrices.md index b0c97bb..c49de2f 100644 --- a/docs/VectorsMatrices.md +++ b/docs/VectorsMatrices.md @@ -1,2 +1,4 @@ # Working with Vectors and Matrices + +[Previous](Operations.md) | [Contents](Intro.md) | [Next](Transforms.md)