Immutable array with boxed elements.

Since: 0.3.0

Compare pointers for two immutable arrays and see if they refer to the exact same one.

Since: 0.3.0

O(1) - Get the number of elements in an immutable array

Documentation for utilized primop: sizeofArray#.

Since: 0.3.0

O(1) - Index an element in the immutable boxed array.

Documentation for utilized primop: indexArray#.

Unsafe

Bounds are not checked. When a precondition for ix argument is violated the result is either unpredictable output or failure with a segfault.

Examples

>>> import Data.Prim.Array
>>> let a = fromListBArray [[0 .. i] | i <- [0 .. 10 :: Int]]
>>> indexBArray a 1
[0,1]
>>> indexBArray a 5
[0,1,2,3,4,5]

Since: 0.3.0

O(sz) - Copy a subsection of an immutable array into a subsection of a mutable array. Source and destination arrays must not be the same array in different states.

Documentation for utilized primop: copyArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault.

Since: 0.3.0

O(sz) - Make an exact copy of a subsection of a pure immutable array.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also possibility when the @sz is too large.

Documentation for utilized primop: cloneArray#.

Examples

>>> let a = fromListBArray ['a'..'z']
>>> a
BArray "abcdefghijklmnopqrstuvwxyz"
>>> cloneBArray a 23 3
BArray "xyz"

Since: 0.3.0

O(1) - Convert a pure immutable boxed array into a mutable boxed array. Use freezeBMArray in order to go in the opposite direction.

Documentation for utilized primop: unsafeThawArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the mutable boxed array will also be reflected in the source immutable array as well. See thawCopyBArray that avoids this problem with a fresh allocation and data copy.

Examples

>>> ma <- thawBArray $ fromListBArray [1 .. 5 :: Integer]
>>> writeBMArray ma 1 10
>>> freezeBMArray ma
BArray [1,10,3,4,5]

>>> let a = fromListBArray [1 .. 5 :: Integer]
>>> ma' <- thawBArray a
>>> writeBMArray ma' 0 100000
>>> a
BArray [100000,2,3,4,5]

Since: 0.3.0

O(sz) - Create a new mutable array with size sz and copy that number of elements from source immutable srcArray starting at an offset startIx into the newly created dstMutArray. This function can help avoid an issue with referential transparency that is inherent to thawBArray.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also a possibility when the @sz is too large.

Documentation for utilized primop: thawArray#.

Examples

>>> let a = fromListBArray [1 .. 5 :: Int]
>>> ma <- thawCopyBArray a 1 3
>>> writeBMArray ma 1 10
>>> freezeBMArray ma
BArray [2,10,4]
>>> a
BArray [1,2,3,4,5]

Since: 0.3.0

Convert a pure boxed array into a list. It should work fine with GHC built-in list fusion.

Since: 0.1.0

O(length list) - Convert a list into an immutable boxed array. It is more efficient to use fromListBArrayN when the number of elements is known ahead of time. The reason for this is that it is necessary to iterate the whole list twice: once to count how many elements there is in order to create large enough array that can fit them; and the second time to load the actual elements. Naturally, infinite lists will grind the program to a halt.

Example

>>> fromListBArray "Hello Haskell"
BArray "Hello Haskell"

Since: 0.3.0

O(min(length list, sz)) - Same as fromListBArray, except that it will allocate an array exactly of n size, as such it will not convert any portion of the list that doesn't fit into the newly created array.

Partial

When length of supplied list is in fact smaller then the expected size sz, thunks with UndefinedElement exception throwing function will be placed in the tail portion of the array.

Unsafe

When a precondition sz is violated this function can result in critical failure with out of memory or HeapOverflow async exception.

Examples

>>> fromListBArrayN 3 [1 :: Int, 2, 3]
BArray [1,2,3]
>>> fromListBArrayN 3 [1 :: Int ..]
BArray [1,2,3]

Since: 0.1.0

O(1) - cast a boxed immutable Array that is wired with GHC to BArray from primal.

>>> import Data.Array.IArray as IA
>>> let arr = IA.listArray (10, 15) [30 .. 35] :: IA.Array Int Integer
>>> arr
array (10,15) [(10,30),(11,31),(12,32),(13,33),(14,34),(15,35)]
>>> fromBaseBArray arr
BArray [30,31,32,33,34,35]

Since: 0.3.0

O(1) - cast a boxed BArray from primal into Array, which is wired with GHC. Resulting array range starts at 0, like any sane array would.

>>> let arr = fromListBArray [1, 2, 3 :: Integer]
>>> arr
BArray [1,2,3]
>>> toBaseBArray arr
array (0,2) [(0,1),(1,2),(2,3)]

Since: 0.3.0

Mutable array with boxed elements.

Since: 0.3.0

O(1) - Get the size of a mutable boxed array

Documentation for utilized primop: sizeofMutableArray#.

Example

>>> ma <- newBMArray 1024 "Element of each cell"
>>> getSizeOfBMArray ma
Size {unSize = 1024}

Since: 0.3.0

O(1) - Read an element from a mutable boxed array at the supplied index.

Documentation for utilized primop: readArray#.

Unsafe

Violation of ix preconditions can result in undefined behavior or a failure with a segfault

Example

>>> ma <- makeBMArray 10 (pure . ("Element ix: " ++) . show)
>>> readBMArray ma 5
"Element ix: 5"

Since: 0.1.0

O(1) - Write an element elt into the mutable boxed array dstMutArray at the supplied index ix. The actual element will be evaluated to WHNF prior to mutation.

Unsafe

Violation of ix preconditions can result in heap corruption or a failure with a segfault

Examples

>>> ma <- newBMArray 4 (Nothing :: Maybe Integer)
>>> writeBMArray ma 2 (Just 2)
>>> freezeBMArray ma
BArray [Nothing,Nothing,Just 2,Nothing]

>>> import Control.Prim.Exception
>>> writeBMArray ma 2 (impureThrow DivideByZero)
*** Exception: divide by zero
>>> freezeBMArray ma
BArray [Nothing,Nothing,Just 2,Nothing]

>>> writeBMArray ma 3 (Just (7 `div` 0 ))
>>> freezeBMArray ma
BArray [Nothing,Nothing,Just 2,Just *** Exception: divide by zero
>>> readBMArray ma 3
Just *** Exception: divide by zero

Since: 0.3.0

O(1) - Same as writeBMArray but allows to write a thunk into an array instead of an evaluated element. Careful with memory leaks and thunks that evaluate to exceptions.

Documentation for utilized primop: writeArray#.

Unsafe

Same reasons as writeBMArray

Since: 0.3.0

O(1) - Same as writeBMArray, except it ensures that the value being written is fully evaluated, i.e. to Normal Form (NF).

Unsafe

Same reasons as writeBMArray

Since: 0.3.0

Compare pointers for two mutable arrays and see if they refer to the exact same one.

Documentation for utilized primop: sameMutableArray#.

Since: 0.3.0

Create a mutable boxed array where each element is set to the supplied initial value elt, which is evaluated before array allocation happens. See newLazyBMArray for an ability to initialize with a thunk.

Unsafe size

Violation of precondition for the sz argument can result in the current thread being killed with HeapOverflow asynchronous exception or death of the whole process with some unchecked exception from RTS.

Examples

>>> newBMArray 10 'A' >>= freezeBMArray
BArray "AAAAAAAAAA"

Since: 0.3.0

Same as newBMArray, except initial element is allowed to be a thunk.

Documentation for utilized primop: newArray#.

Unsafe

Same reasons as newBMArray

Since: 0.3.0

Create new mutable array, where each element is initilized to a thunk that throws an error when evaluated. This is useful when there is a plan to later iterate over the whole array and write values into each cell in some index aware fashion. Consider makeBMArray as an alternative.

Partial

All array cells are initialized with thunks that throw UndefinedElement exception when evaluated

Unsafe

Same reasons as newBMArray

Examples

>>> import Data.Prim
>>> let xs = "Hello Haskell"
>>> ma <- newRawBMArray (Size (length xs)) :: IO (BMArray Char RW)
>>> mapM_ (\(i, x) -> writeBMArray ma i x) (zip [0..] xs)
>>> freezeBMArray ma
BArray "Hello Haskell"

Since: 0.3.0

Create new mutable boxed array of the supplied size and fill it with a monadic action that is applied to indices of each array cell.

Unsafe

Same reasons as newBMArray

Examples

>>> ma <- makeBMArray 5 $ \i -> (toEnum (i + 97) :: Char) <$ putStrLn ("Handling index: " ++ show i)
Handling index: 0
Handling index: 1
Handling index: 2
Handling index: 3
Handling index: 4
>>> freezeBMArray ma
BArray "abcde"

Since: 0.3.0

O(sz) - Copy a subsection of a mutable array into a subsection of another or the same mutable array. Therefore, unlike copyBArray, memory ia allowed to overlap between source and destination.

Documentation for utilized primop: copyMutableArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault.

Since: 0.3.0

O(sz) - Allocate a new mutable array of size sz and copy that number of the elements over from the srcArray starting at index ix. Similar to cloneBArray, except it works on mutable arrays.

Documentation for utilized primop: cloneMutableArray#.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also a possibility when the @sz is too large.

Since: 0.3.0

O(1) - Reduce the size of a mutable boxed array.

Documentation for utilized primop: shrinkMutableArray#.

Unsafe

- Violation of preconditions for sz leads to undefined behavior

1. 3.0

O(1) - Either grow or shrink the size of a mutable unboxed array. Shrinking happens in-place without new array creation and data copy, while growing the array is implemented with creating new array and copy of the data over from the source array srcMutArray. This has a consequence that produced array dstMutArray might refer to the same srcMutArray or to a totally new array, which can be checked with isSameBMArray.

Documentation on the utilized primop: resizeMutableArray#.

Unsafe

- Same reasons as in newRawBMArray.

1. 3.0

O(1) - Same as resizeBMArray, except when growing the array empty space at the end is filled with bottom.

Partial

- When size sz is larger then the size of srcMutArray then dstMutArray will have cells at the end initialized with thunks that throw UndefinedElement exception.

Unsafe

- Same reasons as in newBMArray.

1. 3.0

O(1) - Convert a mutable boxed array into an immutable one. Use thawBArray in order to go in the opposite direction.

Documentation for utilized primop: unsafeFreezeArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the source mutable boxed array will also be reflected in the resulting immutable array. See freezeCopyBMArray that avoids this problem with fresh allocation.

Since: 0.3.0

O(sz) - Similar to freezeBMArray, except it creates a new array with the copy of a subsection of a mutable array before converting it into an immutable.

Documentation for utilized primop: freezeArray#.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault or out of memory exception.

Since: 0.3.0

Small boxed immutable array

Compare pointers for two immutable arrays and see if they refer to the exact same one.

Since: 0.3.0

O(1) - Get the number of elements in an immutable array

Documentation for utilized primop: sizeofSmallArray#.

Since: 0.3.0

O(1) - Index an element in the immutable small boxed array.

Documentation for utilized primop: indexSmallArray#.

Unsafe

Bounds are not checked. When a precondition for ix argument is violated the result is either unpredictable output or failure with a segfault.

Examples

>>> import Data.Prim.Array
>>> let a = fromListSBArray [[0 .. i] | i <- [0 .. 10 :: Int]]
>>> indexSBArray a 1
[0,1]
>>> indexSBArray a 5
[0,1,2,3,4,5]

Since: 0.3.0

O(sz) - Copy a subsection of an immutable array into a subsection of a mutable array. Source and destination arrays must not be the same array in different states.

Documentation for utilized primop: copySmallArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault.

Since: 0.3.0

O(sz) - Make an exact copy of a subsection of a pure immutable array.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also a possibility when the @sz is too large.

Documentation for utilized primop: cloneSmallArray#.

Examples

>>> let a = fromListSBArray ['a'..'z']
>>> a
SBArray "abcdefghijklmnopqrstuvwxyz"
>>> cloneSBArray a 23 3
SBArray "xyz"

Since: 0.3.0

O(1) - Convert a pure immutable boxed array into a mutable boxed array. Use freezeSBMArray in order to go in the opposite direction.

Documentation for utilized primop: unsafeThawSmallArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the mutable boxed array will also be reflected in the source immutable array as well. See thawCopySBArray that avoids this problem with a fresh allocation and data copy.

Examples

>>> ma <- thawSBArray $ fromListSBArray [1 .. 5 :: Integer]
>>> writeSBMArray ma 1 10
>>> freezeSBMArray ma
SBArray [1,10,3,4,5]

>>> let a = fromListSBArray [1 .. 5 :: Integer]
>>> ma' <- thawSBArray a
>>> writeSBMArray ma' 0 100000
>>> a
SBArray [100000,2,3,4,5]

Since: 0.3.0

O(sz) - Create a new mutable array with size sz and copy that number of elements from source immutable srcArray starting at an offset startIx into the newly created dstMutArray. This function can help avoid an issue with referential transparency that is inherent to thawSBArray.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also a possibility when the @sz is too large.

Documentation for utilized primop: thawSmallArray#.

Examples

>>> let a = fromListSBArray [1 .. 5 :: Int]
>>> ma <- thawCopySBArray a 1 3
>>> writeSBMArray ma 1 10
>>> freezeSBMArray ma
SBArray [2,10,4]
>>> a
SBArray [1,2,3,4,5]

Since: 0.3.0

Convert a pure boxed array into a list. It should work fine with GHC built-in list fusion.

Since: 0.1.0

O(length list) - Convert a list into an immutable boxed array. It is more efficient to use fromListSBArrayN when the number of elements is known ahead of time. The reason for this is that it is necessary to iterate the whole list twice: once to count how many elements there is in order to create large enough array that can fit them; and the second time to load the actual elements. Naturally, infinite lists will grind the program to a halt.

Example

>>> fromListSBArray "Hello Haskell"
SBArray "Hello Haskell"

Since: 0.3.0

O(min(length list, sz)) - Same as fromListSBArray, except that it will allocate an array exactly of n size, as such it will not convert any portion of the list that doesn't fit into the newly created array.

Partial

When length of supplied list is in fact smaller then the expected size sz, thunks with UndefinedElement exception throwing function will be placed in the tail portion of the array.

Unsafe

When a precondition sz is violated this function can result in critical failure with out of memory or HeapOverflow async exception.

Examples

>>> fromListSBArrayN 3 [1 :: Int, 2, 3]
SBArray [1,2,3]
>>> fromListSBArrayN 3 [1 :: Int ..]
SBArray [1,2,3]

Since: 0.1.0

Small boxed mutable array

Compare pointers for two mutable arrays and see if they refer to the exact same one.

Documentation for utilized primop: sameSmallMutableArray#.

Since: 0.3.0

O(1) - Get the size of a mutable boxed array

Documentation for utilized primop: getSizeofSmallMutableArray# for ghc-8.10 and newer and fallback to sizeofMutableArray# for older versions.

Example

>>> ma <- newSBMArray 1024 "Element of each cell"
>>> getSizeOfSBMArray ma
Size {unSize = 1024}

Since: 0.3.0

O(1) - Read an element from a mutable small boxed array at the supplied index.

Documentation for utilized primop: readSmallArray#.

Unsafe

Violation of ix preconditions can result in undefined behavior or a failure with a segfault

Example

>>> ma <- makeSBMArray 10 (pure . ("Element ix: " ++) . show)
>>> readSBMArray ma 5
"Element ix: 5"

Since: 0.1.0

O(1) - Write an element elt into the mutable small boxed array dstMutArray at the supplied index ix. The actual element will be evaluated to WHNF prior to mutation.

Unsafe

Violation of ix preconditions can result in heap corruption or a failure with a segfault

Examples

>>> ma <- newSBMArray 4 (Nothing :: Maybe Integer)
>>> writeSBMArray ma 2 (Just 2)
>>> freezeSBMArray ma
SBArray [Nothing,Nothing,Just 2,Nothing]

>>> import Control.Prim.Exception
>>> writeSBMArray ma 2 (impureThrow DivideByZero)
*** Exception: divide by zero
>>> freezeSBMArray ma
SBArray [Nothing,Nothing,Just 2,Nothing]

>>> writeSBMArray ma 3 (Just (7 `div` 0 ))
>>> freezeSBMArray ma
SBArray [Nothing,Nothing,Just 2,Just *** Exception: divide by zero

Since: 0.3.0

O(1) - Same as writeSBMArray but allows to write a thunk into an array instead of an evaluated element. Careful with memory leaks and thunks that evaluate to exceptions.

Documentation for utilized primop: writeSmallArray#.

Unsafe

Same reasons as writeSBMArray

Since: 0.3.0

O(1) - Same as writeSBMArray, except it ensures that the value being written is fully evaluated, i.e. to Normal Form (NF).

Unsafe

Same reasons as writeSBMArray

Since: 0.3.0

Create a mutable boxed array where each element is set to the supplied initial value elt, which is evaluated before array allocation happens. See newLazySBMArray for an ability to initialize with a thunk.

Unsafe size

Violation of precondition for the sz argument can result in the current thread being killed with HeapOverflow asynchronous exception or death of the whole process with some unchecked exception from RTS.

Examples

>>> newSBMArray 10 'A' >>= freezeSBMArray
SBArray "AAAAAAAAAA"

Since: 0.3.0

Same as newSBMArray, except initial element is allowed to be a thunk.

Documentation for utilized primop: newSmallArray#.

Unsafe

Same reasons as newSBMArray

Since: 0.3.0

Create new mutable array, where each element is initilized to a thunk that throws an error when evaluated. This is useful when there is a plan to later iterate over the whole array and write values into each cell in some index aware fashion. Consider makeSBMArray as an alternative.

Partial

All array cells are initialized with thunks that throw UndefinedElement exception.

Unsafe

Same reasons as newSBMArray

Examples

>>> import Data.Prim
>>> let xs = "Hello Haskell"
>>> ma <- newRawSBMArray (Size (length xs)) :: IO (SBMArray Char RW)
>>> mapM_ (\(i, x) -> writeSBMArray ma i x) (zip [0..] xs)
>>> freezeSBMArray ma
SBArray "Hello Haskell"

Since: 0.3.0

Create new mutable boxed array of the supplied size and fill it with a monadic action that is applied to indices of each array cell.

Unsafe

Same reasons as newSBMArray

Examples

>>> ma <- makeSBMArray 5 $ \i -> (toEnum (i + 97) :: Char) <$ putStrLn ("Handling index: " ++ show i)
Handling index: 0
Handling index: 1
Handling index: 2
Handling index: 3
Handling index: 4
>>> freezeSBMArray ma
SBArray "abcde"

Since: 0.3.0

O(sz) - Copy a subsection of a mutable array into a subsection of another or the same mutable array. Therefore, unlike copySBArray, memory ia allowed to overlap between source and destination.

Documentation for utilized primop: copySmallMutableArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault.

Since: 0.3.0

O(sz) - Allocate a new small boxed mutable array of size sz and copy that number of the elements over from the srcArray starting at index ix. Similar to cloneSBArray, except that it works on mutable arrays.

Documentation for utilized primop: cloneSmallMutableArray#.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault. Failure with out of memory is also a possibility when the @sz is too large.

Since: 0.3.0

O(1) - Reduce the size of a mutable small boxed array.

Documentation for utilized primop: shrinkSmallMutableArray#.

Unsafe

- Violation of preconditions for sz leads to undefined behavior

1. 3.0

O(1) - Either grow or shrink the size of a mutable unboxed array. Shrinking happens in-place without new array creation and data copy, while growing the array is implemented with creating new array and copy of the data over from the source array srcMutArray. This has a consequence that produced array dstMutArray might refer to the same srcMutArray or to a totally new array, which can be checked with isSameSBMArray.

Documentation on the utilized primop: resizeSmallMutableArray#.

Unsafe

- Same reasons as in newRawSBMArray.

1. 3.0

O(1) - Same as resizeSBMArray, except when growing the array empty space at the end is filled with bottom.

Partial

- When size sz is larger then the size of srcMutArray then dstMutArray will have cells at the end initialized with thunks that throw UndefinedElement exception.

Unsafe

- Same reasons as in newSBMArray.

1. 3.0

O(1) - Convert a mutable boxed array into an immutable one. Use thawSBArray in order to go in the opposite direction.

Documentation for utilized primop: unsafeFreezeSmallArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the source mutable boxed array will also be reflected in the resulting immutable array. See freezeCopySBMArray that avoids this problem with fresh allocation.

Since: 0.3.0

O(sz) - Similar to freezeSBMArray, except it creates a new array with the copy of a subsection of a mutable array before converting it into an immutable.

Documentation for utilized primop: freezeSmallArray#.

Unsafe

When any of the preconditions for startIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or more likely a failure with a segfault or out of memory exception.

Since: 0.3.0

O(1) - Compare pointers for two immutable arrays and see if they refer to the exact same one.

Documentation for utilized primop: isSameByteArray#.

Since: 0.3.0

O(1) - Check if memory for immutable unboxed array was allocated as pinned.

Documentation for utilized primop: isByteArrayPinned#.

Since: 0.3.0

O(1) - Get the size of an immutable array in number of elements.

Documentation for utilized primop: sizeofByteArray#.

Since: 0.3.0

O(1) - Index an element of a pure unboxed array.

Documentation for utilized primop: indexByteArray#.

Unsafe

Bounds are not checked. When a precondition for ix argument is violated the result is either unpredictable output or failure with a segfault.

Examples

>>> let a = fromListUArray ([Left pi, Right 123] :: [Either Double Int])
>>> indexUArray a 0
Left 3.141592653589793
>>> indexUArray a 1
Right 123

Since: 0.3.0

O(sz) - Copy a subsection of an immutable array into a subsection of another mutable array. Source and destination arrays must not be the same array in different states.

Documentation for utilized primop: copyByteArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or failure with a segfault.

Since: 0.3.0

O(1) - Convert a pure immutable unboxed array into a mutable unboxed array. Use freezeUMArray in order to go in the opposite direction.

Documentation for utilized primop: unsafeThawByteArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the mutable unboxed array will also be reflected in the source immutable array as well.

Examples

>>> ma <- thawUArray $ fromListUArray [1 .. 5 :: Int]
>>> writeUMArray ma 1 10
>>> freezeUMArray ma
UArray [1,10,3,4,5]

>>> let a = fromListUArray [1 .. 5 :: Int]
>>> ma' <- thawUArray a
>>> writeUMArray ma' 0 100000
>>> a
UArray [100000,2,3,4,5]

Since: 0.3.0

O(n) - Convert a pure boxed array into a list. It should work fine with GHC built-in list fusion.

Since: 0.1.0

O(length list) - Convert a list into an immutable boxed array. It is more efficient to use fromListUArrayN when the number of elements is known ahead of time. The reason for this is that it is necessary to iterate the whole list twice: once to count how many elements there is in order to create large enough array that can fit them; and the second time to load the actual elements. Naturally, infinite lists will grind the program to a halt.

Example

>>> fromListUArray "Hello Haskell"
UArray "Hello Haskell"

Since: 0.3.0

O(min(length list, sz)) - Same as fromListUArray, except it will allocate an array exactly of n size, as such it will not convert any portion of the list that doesn't fit into the newly created array.

Partial

When length of supplied list is in fact smaller then the expected size sz, thunks with UndefinedElement exception throwing function will be placed in the tail portion of the array.

Unsafe

When a precondition sz is violated this function can result in critical failure with out of memory or HeapOverflow async exception.

Examples

>>> fromListUArrayN 3 [1 :: Int, 2, 3]
UArray [1,2,3]
>>> fromListUArrayN 3 [1 :: Int ..]
UArray [1,2,3]

Since: 0.1.0

O(1) - cast an unboxed UArray that is wired with GHC to UArray from primal.

>>> import Data.Array.IArray as IA
>>> import Data.Array.Unboxed as UA
>>> let uarr = IA.listArray (10, 15) [30 .. 35] :: UA.UArray Int Word
>>> uarr
array (10,15) [(10,30),(11,31),(12,32),(13,33),(14,34),(15,35)]
>>> fromBaseUArray uarr
UArray [30,31,32,33,34,35]

Since: 0.3.0

O(1) - cast an unboxed UArray from primal into UArray, which is wired with GHC. Resulting array range starts at 0, like any sane array would.

>>> let uarr = fromListUArray [1, 2, 3 :: Int]
>>> uarr
UArray [1,2,3]
>>> toBaseUArray uarr
array (0,2) [(0,1),(1,2),(2,3)]

Since: 0.3.0

O(1) - Compare pointers for two mutable arrays and see if they refer to the exact same one.

Documentation for utilized primop: sameMutableByteArray#.

Since: 0.3.0

O(1) - Check if memory for mutable unboxed array was allocated as pinned.

Documentation for utilized primop: isMutableByteArrayPinned#.

Since: 0.3.0

O(1) - Get the size of a mutable unboxed array

Documentation for utilized primop: getSizeofMutableByteArray#.

Example

>>> ma <- thawUArray $ fromListUArray ['a' .. 'z']
>>> getSizeOfUMArray ma
Size {unSize = 26}

Since: 0.3.0

O(1) - Read an element from a mutable unboxed array at the supplied index.

Documentation for utilized primop: readMutableByteArray#.

Unsafe

Violation of ix preconditions can result in value that doesn't belong to srcMutArray or a failure with a segfault

Examples

>>> ma <- thawUArray $ fromListUArray "Hi!"
>>> readUMArray ma 2
'!'

Since: 0.3.0

O(1) - Write an element into an unboxed mutable array at a supplied index.

Documentation for utilized primop: writeMutableByteArray#.

Unsafe

Violation of ix preconditions can result in heap corruption or a failure with a segfault

Examples

>>> import Data.Prim
>>> ma <- newRawUMArray 4 :: IO (UMArray (Maybe Int) RW)
>>> mapM_ (\i -> writeUMArray ma i Nothing) [0, 1, 3]
>>> writeUMArray ma 2 (Just 2)
>>> freezeUMArray ma
UArray [Nothing,Nothing,Just 2,Nothing]

Since: 0.3.0

O(sz) - Allocate new mutable unboxed array. Similar to newRawUMArray, except all elements are initialized to the supplied initial value. This is equivalent to makeUMArray sz (const (pure a)) but often will be more efficient.

Unsafe

When any of preconditions for sz argument is violated the outcome is unpredictable. One possible outcome is termination with HeapOverflow async exception.

Examples

>>> import Data.Prim
>>> let xs = "Hello"
>>> ma <- newUMArray (Size (length xs) + 8) '!' :: IO (UMArray Char RW)
>>> mapM_ (\(i, x) -> writeUMArray ma i x) (zip [0..] xs)
>>> freezeUMArray ma
UArray "Hello!!!!!!!!"

Since: 0.3.0

O(1) - Allocate new mutable unboxed array. None of the elements are initialized so expect it to contain some random garbage.

Documentation for utilized primop: newByteArray#.

Unsafe

When any of preconditions for sz argument is violated the outcome is unpredictable. One possible outcome is termination with HeapOverflow async exception. In a pure setting, such as when executed within runST, if each cell in new array is not overwritten it can lead to violation of referential transparency, because contents of newly allocated unboxed array is non-determinstic.

Examples

>>> import Data.Prim
>>> let xs = "Hello Haskell"
>>> ma <- newRawUMArray (Size (length xs)) :: IO (UMArray Char RW)
>>> mapM_ (\(i, x) -> writeUMArray ma i x) (zip [0..] xs)
>>> freezeUMArray ma
UArray "Hello Haskell"

Since: 0.3.0

Create new mutable unboxed array of the supplied size and fill it with a monadic action that is applied to indices of each array cell.

Unsafe

Same reasons as newUMArray

Examples

>>> ma <- makeUMArray 5 $ \i -> (toEnum (i + 97) :: Char) <$ putStrLn ("Handling index: " ++ show i)
Handling index: 0
Handling index: 1
Handling index: 2
Handling index: 3
Handling index: 4
>>> freezeUMArray ma
UArray "abcde"

Since: 0.3.0

Same newUMArray, but allocate memory as pinned. See newRawPinnedUMArray for more info.

Unsafe

- Same reasons as newUMArray.

Since: 0.3.0

O(1) - Same as newRawUMArray except allocate new mutable unboxed array as pinned

Documentation for utilized primop: newPinnedByteArray#.

Unsafe

Same reasons as in newRawUMArray.

Since: 0.3.0

Same as makeUMArray, but allocate memory as pinned.

Unsafe

Same reasons as newUMArray

Since: 0.3.0

Same newUMArray, but allocate memory as pinned and aligned. See newRawAlignedPinnedUMArray for more info.

Unsafe

- Same reasons as newUMArray.

Since: 0.3.0

O(1) - Same as newRawPinnedUMArray except allocate new mutable unboxed array as pinned and aligned according to the Prim instance for the type of element e

Documentation for utilized primop: newAlignedPinnedByteArray#.

Unsafe

Same reasons as in newRawUMArray.

Since: 0.3.0

Same as makeUMArray, but allocate memory as pinned and aligned.

Unsafe

Same reasons as newUMArray

Since: 0.3.0

O(sz) - Copy a subsection of a mutable array into a subsection of another or the same mutable array. Therefore, unlike copyBArray, memory ia allowed to overlap between source and destination.

Documentation for utilized primop: copyMutableByteArray#.

Unsafe

When any of the preconditions for srcStartIx, dstStartIx or sz is violated this function can result in a copy of some data that doesn't belong to srcArray or failure with a segfault.

Since: 0.3.0

O(n) - Write the same element into the dstMutArray mutable array n times starting at dstStartIx offset.

Unsafe

Since: 0.3.0

O(1) - Reduce the size of a mutable unboxed array.

Documentation for utilized primop: shrinkMutableByteArray#.

Unsafe

- Violation of preconditions for sz leads to undefined behavior

1. 3.0

O(1) - Either grow or shrink the size of a mutable unboxed array. Shrinking happens without new allocation and data copy, while growing the array is implemented with allocation of new unpinned array and copy of the data over from the source array srcMutArray. This has a consequence that produced array dstMutArray might refer to the same srcMutArray or to a totally new array, which can be checked with isSameUMArray.

Documentation on the utilized primop: resizeMutableByteArray#.

Unsafe

- Same reasons as in newRawUMArray. When size sz is larger then the size of srcMutArray then dstMutArray will contain uninitialized memory at its end, hence a potential problem for referential transparency.

1. 3.0

O(1) - Convert a mutable unboxed array into an immutable one. Use thawUArray in order to go in the opposite direction.

Documentation on the utilized primop: unsafeFreezeByteArray#.

Unsafe

This function makes it possible to break referential transparency, because any subsequent destructive operation to the source mutable boxed array will also be reflected in the resulting immutable array. See freezeCopyBMArray that avoids this problem with fresh allocation.

Since: 0.3.0

Default "raw" element for boxed arrays.

Helper for generating mutable arrays

Since: 0.3.0

Convert a list to a mutable array

Right fold that is strict on the element. The key feature of this function is that it can be used to convert an array to a list by integrating with list fusion using build.

Since: 0.3.0

Check for equality of two arrays

Since: 0.3.0

Compare two arrays using supplied functions

Since: 0.3.0

Append two arrays together using supplied functions

Since: 0.3.0

Concat many arrays together using supplied functions

Since: 0.3.0