Data.Massiv.Core.Index

1-dimensional type synonym for size.

2-dimensional size type synonym.

3-dimensional size type synonym.

4-dimensional size type synonym.

5-dimensional size type synonym.

Sz is the size of the array. It describes total number of elements along each dimension in the array. It is a wrapper around an index of the same dimension, however it provides type safety preventing mixup with index. Moreover the Sz constructor and others such as Sz1, Sz2, ... that are specialized to specific dimensions, prevent creation of invalid sizes with negative values by clamping them to zero.

Examples

>>> import Data.Massiv.Array>>> Sz (1 :> 2 :. 3)Sz (1 :> 2 :. 3)

Sz has a Num instance, which is very convenient:

>>> Sz (1 :> 2 :. 3) + 5Sz (6 :> 7 :. 8)

However subtraction can sometimes lead to surprising behavior, because size is not allowed to take negative values it will be clamped at 0.

>>> Sz (1 :> 2 :. 3) - 2Sz (0 :> 0 :. 1)

Warning: It is always wrong to negate a size, thus it will result in an error. For that reason also watch out for partially applied (- sz), which is deugared into negate sz. See more info about it in #114.

A safe bidirectional pattern synonym for Sz construction that will make sure that none of the size elements are negative.

1-dimensional size constructor. Especially useful with literals: (Sz1 5) == Sz (5 :: Int).

2-dimensional size constructor. (Sz2 i j) == Sz (i :. j)

3-dimensional size constructor. (Sz3 i j k) == Sz (i :> j :. k)

4-dimensional size constructor. (Sz4 i j k l) == Sz (i :> j :> k :. l)

5-dimensional size constructor. (Sz5 i j k l m) == Sz (i :> j :> k :> l :. m)

Function for unwrapping Sz.

Example

>>> import Data.Massiv.Core.Index>>> unSz $ Sz3 1 2 31 :> 2 :. 3

An empty size with all elements in size equal to 0.

Example

>>> import Data.Massiv.Core.Index>>> zeroSz :: Sz5Sz (0 :> 0 :> 0 :> 0 :. 0)

A singleton size with all elements in size equal to 1.

Example

>>> import Data.Massiv.Core.Index>>> oneSz :: Sz3Sz (1 :> 1 :. 1)

Same as liftIndex, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> liftSz succ (Sz2 2 3)Sz (3 :. 4)

Same as liftIndex2, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> liftSz2 (-) (Sz2 2 3) (Sz2 3 1)Sz (0 :. 2)

Same as consDim, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> consSz (Sz1 1) (Sz2 2 3) :: Sz3Sz (1 :> 2 :. 3)

Same as unconsDim, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> unconsSz $ Sz3 1 2 3(Sz1 1,Sz (2 :. 3))

Same as snocDim, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> snocSz (Sz2 2 3) (Sz1 1) :: Sz3Sz (2 :> 3 :. 1)

Same as unsnocDim, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> unsnocSz $ Sz3 1 2 3(Sz (1 :. 2),Sz1 3)

Same as setDimM, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> setSzM (Sz2 2 3) 2 (Sz1 1) :: IO Sz2Sz (1 :. 3)>>> setSzM (Sz2 2 3) 3 (Sz1 1) :: IO Sz2*** Exception: IndexDimensionException: (Dim 3) for (2 :. 3)

Same as insertDimM, but for Sz

Example

>>> import Data.Massiv.Core.Index>>> insertSzM (Sz2 2 3) 3 (Sz1 1) :: IO Sz3Sz (1 :> 2 :. 3)>>> insertSzM (Sz2 2 3) 4 (Sz1 1) :: IO Sz3*** Exception: IndexDimensionException: (Dim 4) for (2 :. 3)

Same as pullOutDim, but for Sz

>>> import Data.Massiv.Core.Index>>> pullOutSzM (Sz3 1 2 3) 3(Sz1 1,Sz (2 :. 3))>>> pullOutSzM (Sz3 1 2 3) 0*** Exception: IndexDimensionException: (Dim 0) for (1 :> 2 :. 3)

Convert a size to a linear size.

Construct size from index while checking its correctness. Throws SizeNegativeException and SizeOverflowException.

A way to select Array dimension at a value level.

A way to select Array dimension at a type level.

Construct 1st dimension

Construct 2nd dimension

Construct 3rd dimension

Construct 4th dimension

Construct 5th dimension

A type level constraint that ensures index is indeed valid and that supplied dimension can be safely used with it.

Stride provides a way to ignore elements of an array if an index is divisible by a corresponding value in a stride. So, for a Stride (i :. j) only elements with indices will be kept around:

( 0 :. 0) ( 0 :. j) ( 0 :. 2j) ( 0 :. 3j) ...
( i :. 0) ( i :. j) ( i :. 2j) ( i :. 3j) ...
(2i :. 0) (2i :. j) (2i :. 2j) (2i :. 3j) ...
...

Only positive strides make sense, so Stride pattern synonym constructor will prevent a user from creating a stride with negative or zero values, thus promoting safety of the library.

Examples:

• Default and minimal stride of Stride (pureIndex 1) will have no affect and all elements will kept.

• If stride is Stride 2, then every 2nd element (i.e. with index 1, 3, 5, ..) will be skipped and only elemnts with indices divisible by 2 will be kept around.

• In case of two dimensions, if what you want is to keep all rows divisible by 5, but keep every column intact then you'd use Stride (5 :. 1).

A safe bidirectional pattern synonym for Stride construction that will make sure stride elements are always positive.

Just a helper function for unwrapping Stride.

Compute linear index with stride using the original size and index

Adjust starting index according to the stride

Adjust size according to the stride.

A default stride of 1, where all elements are kept

Approach to be used near the borders during various transformations. Whenever a function needs information not only about an element of interest, but also about it's neighbors, it will go out of bounds near the array edges, hence is this set of approaches that specify how to handle such situation.

Apply a border resolution technique to an index

Examples

>>> handleBorderIndex (Fill 100) (Sz (2 :. 3)) id (2 :. 3)100 :. 100>>> handleBorderIndex Wrap (Sz (2 :. 3)) id (2 :. 3)0 :. 0>>> handleBorderIndex Edge (Sz (2 :. 3)) id (2 :. 3)1 :. 2

This type family will always point to a type for a dimension that is one lower than the type argument.

This is bread and butter of multi-dimensional array indexing. It is unlikely that any of the functions in this class will be useful to a regular user, unless general algorithms are being implemented that do span multiple dimensions.

Index with all zeros

Examples

>>> zeroIndex :: Ix40 :> 0 :> 0 :. 0

Index with all ones

Checks whether size can hold at least one element.

Examples

>>> isZeroSz (Sz3 1 0 2)True

Checks whether size can hold at least one element.

Examples

>>> isNotZeroSz (Sz3 1 0 2)False

Get the outmost dimension of the index.

Examples

>>> headDim (2 :> 3 :> 4 :. 5)2

Drop the outmost dimension from the index

Examples

>>> tailDim (2 :> 3 :> 4 :. 5)3 :> 4 :. 5

Get the innermost dimension from the index

Examples

>>> lastDim (2 :> 3 :> 4 :. 5)5

Drop the innermost dimension from the index

Examples

>>> initDim (2 :> 3 :> 4 :. 5)2 :> 3 :. 4

Change the value from a specific dimension within the index. See getDimM for a safer version and getDimension for a type safe version.

Examples

>>> getDim' (2 :> 3 :> 4 :. 5) 33

Change the value of a specific dimension within the index. See setDimM for a safer version and setDimension for a type safe version.

Examples

>>> setDim' (2 :> 3 :> 4 :. 5) 3 102 :> 10 :> 4 :. 5

Update the value of a specific dimension within the index. See modifyDimM for a safer version and modifyDimension for a type safe version.

Examples

>>> modifyDim' (2 :> 3 :> 4 :. 5) 2 (+ 10)(4,2 :> 3 :> 14 :. 5)

Remove a dimension from the index.

Examples

>>> dropDimM (2 :> 3 :> 4 :. 5) 3 :: Maybe Ix3Just (2 :> 4 :. 5)>>> dropDimM (2 :> 3 :> 4 :. 5) 6 :: Maybe Ix3Nothing

Remove a dimension from the index.

Examples

>>> dropDim' (2 :> 3 :> 4 :. 5) 32 :> 4 :. 5

Lower the dimension of the index by pulling the specified dimension. See pullOutDimM for a safer version and pullOutDimension for a type safe version.

Examples

>>> pullOutDim' (2 :> 3 :> 4 :. 5) 3(3,2 :> 4 :. 5)

Raise the dimension of the index by inserting one in the specified dimension. See insertDimM for a safer version and insertDimension for a type safe version.

Examples

>>> insertDim' (2 :> 3 :> 4 :. 5) 3 10 :: Ix52 :> 3 :> 10 :> 4 :. 5

Get the value level Dim from the type level equivalent.

Examples

>>> fromDimension Dim4(Dim 4)>>> :set -XDataKinds>>> fromDimension (DimN :: Dimension 10)(Dim 10)

Type safe way to extract value of index at a particular dimension.

Examples

>>> getDimension (2 :> 3 :> 4 :. 5) Dim24

Type safe way to set value of index at a particular dimension.

Examples

>>> setDimension (2 :> 3 :> 4 :. 5) Dim4 1010 :> 3 :> 4 :. 5

Type safe way to set value of index at a particular dimension.

Examples

>>> modifyDimension (2 :> 3 :> 4 :. 5) Dim3 (+ 2)(3,2 :> 5 :> 4 :. 5)

Type safe way of dropping a particular dimension, thus lowering index dimensionality.

Examples

>>> dropDimension (2 :> 3 :> 4 :. 5) Dim22 :> 3 :. 5

Type safe way of pulling out a particular dimension, thus lowering index dimensionality and returning the value at specified dimension.

Examples

>>> pullOutDimension (2 :> 3 :> 4 :. 5) Dim2(4,2 :> 3 :. 5)

Type safe way of inserting a particular dimension, thus raising index dimensionality.

Examples

>>> insertDimension (2 :> 3 :> 4 :. 5) Dim5 10 :: Ix510 :> 2 :> 3 :> 4 :. 5>>> insertDimension (2 :> 3 :> 4 :. 5) Dim4 10 :: Ix52 :> 10 :> 3 :> 4 :. 5>>> insertDimension (2 :> 3 :> 4 :. 5) Dim3 10 :: Ix52 :> 3 :> 10 :> 4 :. 5>>> insertDimension (2 :> 3 :> 4 :. 5) Dim2 10 :: Ix52 :> 3 :> 4 :> 10 :. 5>>> insertDimension (2 :> 3 :> 4 :. 5) Dim1 10 :: Ix52 :> 3 :> 4 :> 5 :. 10