Documentation

A boxed, unlifted datatype representing a region of raw memory in the garbage-collected heap, which is not scanned for pointers during garbage collection.

It is created by freezing a MutableByteArray# with unsafeFreezeByteArray#. Freezing is essentially a no-op, as MutableByteArray# and ByteArray# share the same heap structure under the hood.

The immutable and mutable variants are commonly used for scenarios requiring high-performance data structures, like Text, Primitive Vector, Unboxed Array, and ShortByteString.

Another application of fundamental importance is Integer, which is backed by ByteArray#.

The representation on the heap of a Byte Array is:

+------------+-----------------+-----------------------+
|            |                 |                       |
|   HEADER   | SIZE (in bytes) |       PAYLOAD         |
|            |                 |                       |
+------------+-----------------+-----------------------+

To obtain a pointer to actual payload (e.g., for FFI purposes) use byteArrayContents# or mutableByteArrayContents#.

Alternatively, enabling the UnliftedFFITypes extension allows to mention ByteArray# and MutableByteArray# in FFI type signatures directly.

A mutable ByteAray#. It can be created in three ways:

• newByteArray#: Create an unpinned array.
• newPinnedByteArray#: This will create a pinned array,
• newAlignedPinnedByteArray#: This will create a pinned array, with a custom alignment.

Unpinned arrays can be moved around during garbage collection, so you must not store or pass pointers to these values if there is a chance for the garbage collector to kick in. That said, even unpinned arrays can be passed to unsafe FFI calls, because no garbage collection happens during these unsafe calls (see Guaranteed Call Safety in the GHC Manual). For safe FFI calls, byte arrays must be not only pinned, but also kept alive by means of the keepAlive# function for the duration of a call (that's because garbage collection cannot move a pinned array, but is free to scrap it altogether).

Boxed arrays.

The empty Array.

Create a new mutable array of the specified size and initialise all elements with the given value.

Note: this function does not check if the input is non-negative.

Lifted wrapper for MutableByteArray#.

Since MutableByteArray# is an unlifted type and not a member of kind Type, things like [MutableByteArray#] or IO MutableByteArray# are ill-typed. To work around this inconvenience this module provides a standard lifted wrapper, inhabiting Type. Clients are expected to use MutableByteArray in higher-level APIs, but wrap and unwrap MutableByteArray internally as they please and use functions from GHC.Exts.

Since: base-4.17.0.0

Lifted wrapper for ByteArray#.

Since ByteArray# is an unlifted type and not a member of kind Type, things like [ByteArray#] or IO ByteArray# are ill-typed. To work around this inconvenience this module provides a standard lifted wrapper, inhabiting Type. Clients are expected to use ByteArray in higher-level APIs, but wrap and unwrap ByteArray internally as they please and use functions from GHC.Exts.

Since: base-4.17.0.0

Create a new mutable byte array of the specified size in bytes. The underlying memory is left uninitialized.

Note: this function does not check if the input is non-negative.

Convert a mutable byte array to an immutable one without copying. The array should not be modified after the conversion.

Size of the byte array in bytes.

Create a ByteArray from a list of a known length. If the length of the list does not match the given length, this throws an exception.

The empty ByteArray.

Check whether or not the byte array is pinned. Pinned byte arrays cannot be moved by the garbage collector. It is safe to use byteArrayContents on such byte arrays.

Caution: This function is only available when compiling with GHC 8.2 or newer.

Since: primitive-0.6.4.0

Right-fold over the elements of a ByteArray.

Copy from an unmanaged pointer address to a byte array. These must not overlap. The offset and length are given in elements, not in bytes.

Note: this function does not do bounds or overlap checking.

Copy a slice of a byte array to an unmanaged pointer address. These must not overlap. The offset and length are given in elements, not in bytes.

Note: this function does not do bounds or overlap checking.

Since: primitive-0.7.1.0

Return a newly allocated Array with the specified subrange of the provided Array.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Create a pinned byte array of the specified size in bytes and with the given alignment. The garbage collector is guaranteed not to move it. The underlying memory is left uninitialized.

Note: this function does not check if the input is non-negative.

Mutable boxed arrays associated with a primitive state token.

Create an array of the given size with a default value, apply the monadic function and freeze the result. If the size is 0, return emptyArray (rather than a new copy thereof).

createArray 0 _ _ = emptyArray
createArray n x f = runArray $ do
  mary <- newArray n x
  f mary
  pure mary

Shrink a mutable byte array. The new size is given in bytes. It must be smaller than the old size. The array will be resized in place.

Since: primitive-0.7.1.0

Create a pinned byte array of the specified size in bytes. The garbage collector is guaranteed not to move it. The underlying memory is left uninitialized.

Note: this function does not check if the input is non-negative.

Fill a slice of a mutable byte array with a value. The offset and length are given in elements of type a rather than in bytes.

Note: this function does not do bounds checking.

The number of elements in an immutable array.

The number of elements in a mutable array.

Read a value from the immutable array at the given index.

Note: this function does not do bounds checking.

Read a value from the immutable array at the given index, returning the result in an unboxed unary tuple. This is currently used to implement folds.

Note: this function does not do bounds checking.

Read a value from the immutable array at the given index using an applicative. This allows us to be strict in the array while remaining lazy in the read element which is very useful for collective operations. Suppose we want to copy an array. We could do something like this:

copy marr arr ... = do ...
                       writeArray marr i (indexArray arr i) ...
                       ...

But since the arrays are lazy, the calls to indexArray will not be evaluated. Rather, marr will be filled with thunks each of which would retain a reference to arr. This is definitely not what we want!

With indexArrayM, we can instead write

copy marr arr ... = do ...
                       x <- indexArrayM arr i
                       writeArray marr i x
                       ...

Now, indexing is executed immediately although the returned element is still not evaluated.

Note: this function does not do bounds checking.

Create an immutable copy of a slice of an array.

This operation makes a copy of the specified section, so it is safe to continue using the mutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Convert a mutable array to an immutable one without copying. The array should not be modified after the conversion.

Create a mutable array from a slice of an immutable array.

This operation makes a copy of the specified slice, so it is safe to use the immutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Convert an immutable array to an mutable one without copying. The immutable array should not be used after the conversion.

Check whether the two arrays refer to the same memory block.

Execute the monadic action and freeze the resulting array.

runArray m = runST $ m >>= unsafeFreezeArray

This is the fastest, most straightforward way to traverse an array, but it only works correctly with a sufficiently "affine" PrimMonad instance. In particular, it must only produce one result array. ListT-transformed monads, for example, will not work right at all.

Strict map over the elements of the array.

Create an array from a list of a known length. If the length of the list does not match the given length, this throws an exception.

Create an array from a list.

Create a foreign pointer that points to the array's data. This operation is only safe on pinned byte arrays. The array's data is not garbage collected while references to the foreign pointer exist. Writing to the array through the foreign pointer results in undefined behavior.

Variant of byteArrayAsForeignPtr for mutable byte arrays. Similarly, this is only safe on pinned mutable byte arrays. This function differs from the variant for immutable arrays in that it is safe to write to the array though the foreign pointer.

Yield a pointer to the array's data. This operation is only safe on pinned byte arrays. Byte arrays allocated by newPinnedByteArray and newAlignedPinnedByteArray are guaranteed to be pinned. Byte arrays allocated by newByteArray may or may not be pinned (use isByteArrayPinned to figure out).

Prefer withByteArrayContents, which ensures that the array is not garbage collected while the pointer is being used.

A composition of byteArrayContents and keepAliveUnlifted. The callback function must not return the pointer. The argument byte array must be pinned. See byteArrayContents for an explanation of which byte arrays are pinned.

Note: This could be implemented with keepAlive instead of keepAliveUnlifted, but keepAlive here would cause GHC to materialize the wrapper data constructor on the heap.

Yield a pointer to the array's data. This operation is only safe on pinned byte arrays. See byteArrayContents for an explanation of which byte arrays are pinned.

Prefer withByteArrayContents, which ensures that the array is not garbage collected while the pointer is being used.

A composition of mutableByteArrayContents and keepAliveUnlifted. The callback function must not return the pointer. The argument byte array must be pinned. See byteArrayContents for an explanation of which byte arrays are pinned.

Check if the two arrays refer to the same memory block.

Resize a mutable byte array. The new size is given in bytes.

This will either resize the array in-place or, if not possible, allocate the contents into a new, unpinned array and copy the original array's contents.

To avoid undefined behaviour, the original MutableByteArray shall not be accessed anymore after a resizeMutableByteArray has been performed. Moreover, no reference to the old one should be kept in order to allow garbage collection of the original MutableByteArray in case a new MutableByteArray had to be allocated.

Since: primitive-0.6.4.0

Get the size of a byte array in bytes. Unlike sizeofMutableByteArray, this function ensures sequencing in the presence of resizing.

Create an immutable copy of a slice of a byte array. The offset and length are given in bytes.

This operation makes a copy of the specified section, so it is safe to continue using the mutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Create a mutable byte array from a slice of an immutable byte array. The offset and length are given in bytes.

This operation makes a copy of the specified slice, so it is safe to use the immutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Since: primitive-0.7.2.0

Convert an immutable byte array to a mutable one without copying. The original array should not be used after the conversion.

Size of the mutable byte array in bytes.

This function is deprecated and will be removed. Its behavior is undefined if resizeMutableByteArray is ever called on the mutable byte array given as the argument. Prefer getSizeofMutableByteArray, which ensures correct sequencing in the presence of resizing.

Check whether or not the mutable byte array is pinned.

Caution: This function is only available when compiling with GHC 8.2 or newer.

Since: primitive-0.6.4.0

Create a ByteArray from a list.

byteArrayFromList xs = byteArrayFromListN (length xs) xs

Copy a slice of a mutable byte array to an unmanaged pointer address. These must not overlap. The offset and length are given in elements, not in bytes.

Note: this function does not do bounds or overlap checking.

Since: primitive-0.7.1.0

Copy a slice of a byte array to an unmanaged address. These must not overlap.

Note: This function is just copyByteArrayToPtr where a is Word8.

Since: primitive-0.6.4.0

Copy a slice of a mutable byte array to an unmanaged address. These must not overlap.

Note: This function is just copyMutableByteArrayToPtr where a is Word8.

Since: primitive-0.6.4.0

Fill a slice of a mutable byte array with a byte.

Note: this function does not do bounds checking.

Lexicographic comparison of equal-length slices into two byte arrays. This wraps the compareByteArrays# primop, which wraps memcmp.

Return a newly allocated array with the specified subrange of the provided array. The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Return a newly allocated mutable array with the specified subrange of the provided mutable array. The provided mutable array should contain the full subrange specified by the two Ints, but this is not checked.

Execute the monadic action and freeze the resulting array.

runByteArray m = runST $ m >>= unsafeFreezeByteArray

Read an 8-bit element from the byte array, interpreting it as a Latin-1-encoded character. The offset is given in bytes.

Note: this function does not do bounds checking.

Write a character to the byte array, encoding it with Latin-1 as a single byte. Behavior is undefined for codepoints outside of the ASCII and Latin-1 blocks. The offset is given in bytes.

Note: this function does not do bounds checking.

Read an 8-bit element from the byte array, interpreting it as a Latin-1-encoded character. The offset is given in bytes.

Note: this function does not do bounds checking.

Mutable primitive arrays associated with a primitive state token. These can be written to and read from in a monadic context that supports sequencing, such as IO or ST. Typically, a mutable primitive array will be built and then converted to an immutable primitive array using unsafeFreezePrimArray. However, it is also acceptable to simply discard a mutable primitive array since it lives in managed memory and will be garbage collected when no longer referenced.

Arrays of unboxed elements. This accepts types like Double, Char, Int and Word, as well as their fixed-length variants (Word8, Word16, etc.). Since the elements are unboxed, a PrimArray is strict in its elements. This differs from the behavior of Array, which is lazy in its elements.

Create a PrimArray from a list.

primArrayFromList vs = primArrayFromListN (length vs) vs

Create a PrimArray from a list of a known length. If the length of the list does not match the given length, this throws an exception.

Convert a PrimArray to a list.

The empty PrimArray.

Create a new mutable primitive array of the given length. The underlying memory is left uninitialized.

Note: this function does not check if the input is non-negative.

Resize a mutable primitive array. The new size is given in elements.

This will either resize the array in-place or, if not possible, allocate the contents into a new, unpinned array and copy the original array's contents.

To avoid undefined behaviour, the original MutablePrimArray shall not be accessed anymore after a resizeMutablePrimArray has been performed. Moreover, no reference to the old one should be kept in order to allow garbage collection of the original MutablePrimArray in case a new MutablePrimArray had to be allocated.

Shrink a mutable primitive array. The new size is given in elements. It must be smaller than the old size. The array will be resized in place.

Copy part of a mutable array into another mutable array. In the case that the destination and source arrays are the same, the regions may overlap.

Note: this function does not do bounds or overlap checking.

Copy part of an array into another mutable array.

Note: this function does not do bounds or overlap checking.

Copy a slice of an immutable primitive array to a pointer. The offset and length are given in elements of type a. This function assumes that the Prim instance of a agrees with the Storable instance.

Note: this function does not do bounds or overlap checking.

Copy a slice of a mutable primitive array to a pointer. The offset and length are given in elements of type a. This function assumes that the Prim instance of a agrees with the Storable instance.

Note: this function does not do bounds or overlap checking.

Copy from a pointer to a mutable primitive array. The offset and length are given in elements of type a. This function assumes that the Prim instance of a agrees with the Storable instance.

Note: this function does not do bounds or overlap checking.

Fill a slice of a mutable primitive array with a value.

Note: this function does not do bounds checking.

Get the size of a mutable primitive array in elements. Unlike sizeofMutablePrimArray, this function ensures sequencing in the presence of resizing.

Size of the mutable primitive array in elements. This function shall not be used on primitive arrays that are an argument to or a result of resizeMutablePrimArray or shrinkMutablePrimArray.

This function is deprecated and will be removed.

Check if the two arrays refer to the same memory block.

Create an immutable copy of a slice of a primitive array. The offset and length are given in elements.

This operation makes a copy of the specified section, so it is safe to continue using the mutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Create a mutable primitive array from a slice of an immutable primitive array. The offset and length are given in elements.

This operation makes a copy of the specified slice, so it is safe to use the immutable array afterward.

Note: The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Since: primitive-0.7.2.0

Convert a mutable primitive array to an immutable one without copying. The array should not be modified after the conversion.

Convert an immutable array to a mutable one without copying. The original array should not be used after the conversion.

Get the size, in elements, of the primitive array.

Check whether or not the primitive array is pinned. Pinned primitive arrays cannot be moved by the garbage collector. It is safe to use primArrayContents on such arrays. This function is only available when compiling with GHC 8.2 or newer.

Since: primitive-0.7.1.0

Check whether or not the mutable primitive array is pinned. This function is only available when compiling with GHC 8.2 or newer.

Since: primitive-0.7.1.0

Lazy right-associated fold over the elements of a PrimArray.

Strict right-associated fold over the elements of a PrimArray.

Lazy left-associated fold over the elements of a PrimArray.

Strict left-associated fold over the elements of a PrimArray.

Strict left-associated fold over the elements of a PrimArray.

Traverse a primitive array. The traversal forces the resulting values and writes them to the new primitive array as it performs the monadic effects. Consequently:

>>> traversePrimArrayP (\x -> print x $> bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
1
2
*** Exception: Prelude.undefined

In many situations, traversePrimArrayP can replace traversePrimArray, changing the strictness characteristics of the traversal but typically improving the performance. Consider the following short-circuiting traversal:

incrPositiveA :: PrimArray Int -> Maybe (PrimArray Int)
incrPositiveA xs = traversePrimArray (\x -> bool Nothing (Just (x + 1)) (x > 0)) xs

This can be rewritten using traversePrimArrayP. To do this, we must change the traversal context to MaybeT (ST s), which has a PrimMonad instance:

incrPositiveB :: PrimArray Int -> Maybe (PrimArray Int)
incrPositiveB xs = runST $ runMaybeT $ traversePrimArrayP
  (\x -> bool (MaybeT (return Nothing)) (MaybeT (return (Just (x + 1)))) (x > 0))
  xs

Benchmarks demonstrate that the second implementation runs 150 times faster than the first. It also results in fewer allocations.

Filter the primitive array, keeping the elements for which the monadic predicate evaluates to true.

Map over the primitive array, keeping the elements for which the monadic predicate provides a Just.

Generate a primitive array by evaluating the monadic generator function at each index.

Execute the monadic action the given number of times and store the results in a primitive array.

Map over the elements of a primitive array.

Indexed map over the elements of a primitive array.

Filter elements of a primitive array according to a predicate.

Filter the primitive array, keeping the elements for which the monadic predicate evaluates true.

Map over the primitive array, keeping the elements for which the applicative predicate provides a Just.

Map over a primitive array, optionally discarding some elements. This has the same behavior as Data.Maybe.mapMaybe.

Traverse a primitive array. The traversal performs all of the applicative effects before forcing the resulting values and writing them to the new primitive array. Consequently:

>>> traversePrimArray (\x -> print x $> bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
1
2
3
*** Exception: Prelude.undefined

The function traversePrimArrayP always outperforms this function, but it requires a PrimMonad constraint, and it forces the values as it performs the effects.

Traverse a primitive array with the index of each element.

Traverse a primitive array with the indices. The traversal forces the resulting values and writes them to the new primitive array as it performs the monadic effects.

Generate a primitive array.

Create a primitive array by copying the element the given number of times.

Generate a primitive array by evaluating the applicative generator function at each index.

Execute the applicative action the given number of times and store the results in a PrimArray.

Traverse the primitive array, discarding the results. There is no PrimMonad variant of this function, since it would not provide any performance benefit.

Traverse the primitive array with the indices, discarding the results. There is no PrimMonad variant of this function, since it would not provide any performance benefit.

Create a pinned primitive array of the specified size (in elements). The garbage collector is guaranteed not to move it. The underlying memory is left uninitialized.

Since: primitive-0.7.1.0

Create a pinned primitive array of the specified size (in elements) and with the alignment given by its Prim instance. The garbage collector is guaranteed not to move it. The underlying memory is left uninitialized.

Since: primitive-0.7.0.0

Yield a pointer to the array's data. This operation is only safe on pinned prim arrays allocated by newPinnedByteArray or newAlignedPinnedByteArray.

Since: primitive-0.7.1.0

Yield a pointer to the array's data. This operation is only safe on pinned byte arrays allocated by newPinnedByteArray or newAlignedPinnedByteArray.

Since: primitive-0.7.1.0

Return a newly allocated array with the specified subrange of the provided array. The provided array should contain the full subrange specified by the two Ints, but this is not checked.

Return a newly allocated mutable array with the specified subrange of the provided mutable array. The provided mutable array should contain the full subrange specified by the two Ints, but this is not checked.

Execute the monadic action and freeze the resulting array.

runPrimArray m = runST $ m >>= unsafeFreezePrimArray

Create an uninitialized array of the given length, apply the function to it, and freeze the result.

Note: this function does not check if the input is non-negative.

@since FIXME

A composition of primArrayContents and keepAliveUnlifted. The callback function must not return the pointer. The argument array must be pinned. See primArrayContents for an explanation of which primitive arrays are pinned.

Note: This could be implemented with keepAlive instead of keepAliveUnlifted, but keepAlive here would cause GHC to materialize the wrapper data constructor on the heap.

A composition of mutablePrimArrayContents and keepAliveUnlifted. The callback function must not return the pointer. The argument array must be pinned. See primArrayContents for an explanation of which primitive arrays are pinned.