Data.Primitive.ByteArray

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.

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.

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).

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.

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.

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.

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.

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.

Read a primitive value from the byte array. The offset is given in elements of type a rather than in bytes.

Note: this function does not do bounds checking.

Write a primitive value to the byte array. The offset is given in elements of type a rather than in bytes.

Note: this function does not do bounds checking.

Read a primitive value from the byte array. The offset is given in elements of type a rather than 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.

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.

The empty ByteArray.

Create a ByteArray from a list.

byteArrayFromList xs = byteArrayFromListN (length xs) xs

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.

Right-fold over the elements of a ByteArray.

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

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.

Execute the monadic action and freeze the resulting array.

runByteArray m = runST $ m >>= unsafeFreezeByteArray

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

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

Copy a slice of an immutable byte array to a mutable byte array.

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

Copy a slice of a mutable byte array into another array. The two slices may not overlap.

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.

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.

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.

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.

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 mutable byte array into another, potentially overlapping array.

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.

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

Note: this function does not do bounds checking.

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.

Size of the byte array in bytes.

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.

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

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

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.

Check whether or not the mutable byte array is pinned.

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

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.