Basement.UArray

An array of type built on top of GHC primitive.

The elements need to have fixed sized and the representation is a packed contiguous array in memory that can easily be passed to foreign interface

Represent the accessor for types that can be stored in the UArray and MUArray.

Types need to be a instance of storable and have fixed sized.

Copy every cells of an existing array to a new array

Copy n sequential elements from the specified offset in a source array to the specified position in a destination array.

This function does not check bounds. Accessing invalid memory can return unpredictable and invalid values.

Recast an array of type a to an array of b

a and b need to have the same size otherwise this raise an async exception

Unsafely recast an UArray containing a to an UArray containing b

The offset and size are converted from units of a to units of b, but no check are performed to make sure this is compatible.

use recast if unsure.

Freeze a MUArray into a UArray by copying all the content is a pristine new buffer

The MUArray in parameter can be still be used after the call without changing the resulting frozen data.

Freeze a mutable array into an array.

the MUArray must not be changed after freezing.

Thaw an array to a mutable array.

the array is not modified, instead a new mutable array is created and every values is copied, before returning the mutable array.

Thaw an immutable array.

The UArray must not be used after thawing.

Make an array from a list of elements with a size hint.

The list should be of the same size as the hint, as otherwise:

• The length of the list is smaller than the hint: the array allocated is of the size of the hint, but is sliced to only represent the valid bits

• The length of the list is bigger than the hint: The allocated array is the size of the hint, and the list is truncated to fit.

Create a new mutable array of size @n.

When memory for a new array is allocated, we decide if that memory region should be pinned (will not be copied around by GC) or unpinned (can be moved around by GC) depending on its size.

You can change the threshold value used by setting the environment variable HS_FOUNDATION_UARRAY_UNPINNED_MAX.

Create a new array of size n by settings each cells through the function f.

Create a pinned array that is filled by a filler function (typically an IO call like hGetBuf)

Freeze a chunk of memory pointed, of specific size into a new unboxed array

Copy all the block content to the memory starting at the destination address

Get a Ptr pointing to the data in the UArray.

Since a UArray is immutable, this Ptr shouldn't be to use to modify the contents

If the UArray is pinned, then its address is returned as is, however if it's unpinned, a pinned copy of the UArray is made before getting the address.

Create a pointer on the beginning of the mutable array and call a function f.

The mutable buffer can be mutated by the f function and the change will be reflected in the mutable array

If the mutable array is unpinned, a trampoline buffer is created and the data is only copied when f return.

Just like freeze but copy only the first n bytes

The size requested need to be smaller or equal to the length of the MUArray, otherwise a Out of Bounds exception is raised

Create a UArray from a Block

The block is still used by the uarray

Create a Block from a UArray.

Note that because of the slice, the destination block is re-allocated and copied, unless the slice point at the whole array

update an array by creating a new array with the updates.

the operation copy the previous array, modify it in place, then freeze it.

Return the element at a specific index from an array without bounds checking.

Reading from invalid memory can return unpredictable and invalid values. use index if unsure.

read from a cell in a mutable array without bounds checking.

Reading from invalid memory can return unpredictable and invalid values. use read if unsure.

write to a cell in a mutable array without bounds checking.

Writing with invalid bounds will corrupt memory and your program will become unreliable. use write if unsure.

Return the element at a specific index from an array.

If the index @n is out of bounds, an error is raised.

Take a count of elements from the array and create an array with just those elements

Drop a count of elements from the array and return the new array minus those dropped elements

Split an array into two, with a count of at most N elements in the first one and the remaining in the other.

Drop the N elements from the end of the array

Take the N elements from the end of the array

Split an array at the N element from the end, and return the last N elements in the first part of the tuple, and whatever first elements remaining in the second

Similar to break but start the search of the breakpoint from the end

breakEnd (> 0) [1,2,3,0,0,0]

([1,2,3], [0,0,0])

Similar to breakElem specialized to split on linefeed

it either returns: * Left. no line has been found, and whether the last character is a CR * Right, a line has been found with an optional CR, and it returns the array of bytes on the left of the CR/LF, and the the array of bytes on the right of the LF.

Replace all the occurrencies of needle with replacement in the haystack string.

Create a foreign UArray from foreign memory and given offset/size

No check are performed to make sure this is valid, so this is unsafe.

This is particularly useful when dealing with foreign memory and ByteString