Pass primitive array to unsafe FFI as pointer.

Enable UnliftedFFITypes extension in your haskell code, use proper pointer type and HsInt to marshall ByteArray# and Int arguments on C side.

The second Int arguement is the element size not the bytes size.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Allocate some bytes and pass to FFI as pointer, freeze result into a PrimArray.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Pass PrimVector to unsafe FFI as pointer

The PrimVector version of withPrimArrayUnsafe.

The second Int arguement is the first element offset, the third Int argument is the element length.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Allocate a prim array and pass to FFI as pointer, freeze result into a PrimVector.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Allocate some bytes and pass to FFI as pointer, freeze result into a Bytes.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Create an one element primitive array and use it as a pointer to the primitive element.

Return the element and the computation result.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

like withPrimUnsafe, but don't write initial value.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Pass primitive array list to unsafe FFI as StgArrBytes**.

Enable UnliftedFFITypes extension in your haskell code, use StgArrBytes**(>=8.10) or StgMutArrPtrs*(<8.10) pointer type and HsInt to marshall BAArray# and Int arguments on C side, check the example with BAArray#.

The second Int arguement is the list size.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

Pass primitive array to safe FFI as pointer.

Use proper pointer type and HsInt to marshall Ptr a and Int arguments on C side. The memory pointed by 'Ptr a' will not moved during call. After call returned, pointer is no longer valid.

The second Int arguement is the element size not the bytes size.

Don't pass a forever loop to this function, see #14346.

Allocate a prim array and pass to FFI as pointer, freeze result into a PrimVector.

Pass PrimVector to safe FFI as pointer

The PrimVector version of withPrimArraySafe. The Ptr is already pointed to the first element, thus no offset is provided. After call returned, pointer is no longer valid.

Don't pass a forever loop to this function, see #14346.

Allocate a prim array and pass to FFI as pointer, freeze result into a PrimVector.

Allocate some bytes and pass to FFI as pointer, freeze result into a PrimVector.

Create an one element primitive array and use it as a pointer to the primitive element.

Don't pass a forever loop to this function, see #14346.

like withPrimSafe, but don't write initial value.

Pass primitive array list to safe FFI as pointer.

Use proper pointer type and HsInt to marshall Ptr (Ptr a) and Int arguments on C side. The memory pointed by 'Ptr a' will not moved during call. After call returned, pointer is no longer valid.

The second Int arguement is the list size.

Don't pass a forever loop to this function, see #14346.

Convert a PrimArray to a pinned one(memory won't moved by GC) if necessary.

Convert a PrimVector to a pinned one(memory won't moved by GC) if necessary.

Type alias for ByteArray#.

Describe a ByteArray# which we are going to pass across FFI. Use this type with UnliftedFFITypes extension, At C side you should use a proper const pointer type.

Don't cast BA# to Addr# since the heap object offset is hard-coded in code generator: Note [Unlifted boxed arguments to foreign calls]

In haskell side we use type system to distinguish immutable / mutable arrays, but in C side we can't. So it's users' responsibility to make sure the array content is not mutated (a const pointer type may help).

USE THIS TYPE WITH UNSAFE FFI CALL ONLY. A ByteArray# COULD BE MOVED BY GC DURING SAFE FFI CALL.

Type alias for MutableByteArray# RealWorld.

Describe a MutableByteArray# which we are going to pass across FFI. Use this type with UnliftedFFITypes extension, At C side you should use a proper pointer type.

Don't cast MBA# to Addr# since the heap object offset is hard-coded in code generator: Note [Unlifted boxed arguments to foreign calls]

USE THIS TYPE WITH UNSAFE FFI CALL ONLY. A MutableByteArray# COULD BE MOVED BY GC DURING SAFE FFI CALL.

Type alias for ArrayArray#.

Describe a array of ByteArray# which we are going to pass across FFI. Use this type with UnliftedFFITypes extension, At C side you should use StgArrBytes**(>=8.10) or StgMutArrPtrs*(<8.10) type from "Rts.h", example code modified from GHC manual:

// C source, must include the RTS to make the struct StgArrBytes
// available along with its fields: ptrs and payload.
#include "Rts.h"
// GHC 8.10 changes the way how ArrayArray# is passed to C, so...
#if __GLASGOW_HASKELL__ < 810
HsInt sum_first (StgMutArrPtrs *arr, HsInt len) {
  StgArrBytes **bufs = (StgArrBytes**)arr->payload;
#else
HsInt sum_first (StgArrBytes **bufs, HsInt len) {
#endif
  int res = 0;
  for(StgWord ix = 0;ix < len;ix++) {
     // payload pointer type is StgWord*, cast it before use!
     res = res + ((HsInt*)(bufs[ix]->payload))[0];
  }
  return res;
}

-- Haskell source, all elements in the argument array must be
-- either ByteArray# or MutableByteArray#. This is not enforced
-- by the type system in this example since ArrayArray is untyped.
foreign import ccall unsafe "sum_first" sumFirst :: BAArray# Int -> Int -> IO CInt

Clear MBA# with given length to zero.

Zero a structure.

There's no Storable or Prim constraint on a type, the length should be given in bytes.

The castPtr function casts a pointer from one type to another.

Copy some bytes from a null terminated pointer(without copying the null terminator).

You should consider using CBytes type for storing NULL terminated bytes first, This method is provided if you really need to read Bytes, there's no encoding guarantee, result could be any bytes sequence.

Copy some bytes from a pointer.

There's no encoding guarantee, result could be any bytes sequence.

Copy some bytes from a pointer.

There's no encoding guarantee, result could be any bytes sequence.

std::string Pointer tag.

Run FFI in bracket and marshall std::string* result into Haskell heap bytes, memory pointed by std::string* will be delete ed.

O(n), Convert from ByteString.

O(n), Convert tp ByteString.

RealWorld is deeply magical. It is primitive, but it is not unlifted (hence ptrArg). We never manipulate values of type RealWorld; it's only used in the type system, to parameterise State#.

Ensure that the value is considered alive by the garbage collection. Warning: GHC has optimization passes that can erase touch if it is certain that an exception is thrown afterward. Prefer keepAlive.

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.

Read a value from the array at the given index.

Note: this function does not do bounds checking.

Write an element to the given index.

Note: this function does not do bounds checking.

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.

Read a primitive value from the primitive array.

Note: this function does not do bounds checking.

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

Obtain the pointer to the content of an mutable array, and the pointer should only be used during the IO action.

This operation is only safe on pinned primitive arrays (Arrays allocated by newPinnedPrimArray or newAlignedPinnedPrimArray).

Don't pass a forever loop to this function, see #14346.

Obtain the pointer to the content of an array, and the pointer should only be used during the IO action.

This operation is only safe on pinned primitive arrays (Arrays allocated by newPinnedPrimArray or newAlignedPinnedPrimArray).

Don't pass a forever loop to this function, see #14346.