primitive-0.9.1.0: Primitive memory-related operations

Copyright | (c) Roman Leshchinskiy 2009-2012
License | BSD-style
Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au>
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Data.Primitive.ByteArray

Contents

- Types
- Allocation
- Element access
- Char Element Access
- Constructing
- Folding
- Comparing
- Freezing and thawing
- Block operations
- Information

Description

Primitive operations on byte arrays. Most functions in this module include an element type in their type signature and interpret the unit for offsets and lengths as that element. A few functions (e.g. `copyByteArray`, `freezeByteArray`) do not include an element type. Such functions interpret offsets and lengths as units of 8-bit words.

Synopsis

- data ByteArray = ByteArray ByteArray#
- data MutableByteArray s = MutableByteArray (MutableByteArray# s)
- data ByteArray# :: UnliftedType
- data MutableByteArray# a :: UnliftedType
- newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))
- newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))
- newAlignedPinnedByteArray :: PrimMonad m => Int -> Int -> m (MutableByteArray (PrimState m))
- resizeMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m (MutableByteArray (PrimState m))
- shrinkMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m ()
- readByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> m a
- writeByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> a -> m ()
- indexByteArray :: Prim a => ByteArray -> Int -> a
- readCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m Char
- writeCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Char -> m ()
- indexCharArray :: ByteArray -> Int -> Char
- emptyByteArray :: ByteArray
- byteArrayFromList :: Prim a => [a] -> ByteArray
- byteArrayFromListN :: Prim a => Int -> [a] -> ByteArray
- foldrByteArray :: Prim a => (a -> b -> b) -> b -> ByteArray -> b
- compareByteArrays :: ByteArray -> Int -> ByteArray -> Int -> Int -> Ordering
- freezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m ByteArray
- thawByteArray :: PrimMonad m => ByteArray -> Int -> Int -> m (MutableByteArray (PrimState m))
- runByteArray :: (forall s. ST s (MutableByteArray s)) -> ByteArray
- createByteArray :: Int -> (forall s. MutableByteArray s -> ST s ()) -> ByteArray
- unsafeFreezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m ByteArray
- unsafeThawByteArray :: PrimMonad m => ByteArray -> m (MutableByteArray (PrimState m))
- copyByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> ByteArray -> Int -> Int -> m ()
- copyMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
- copyByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> ByteArray -> Int -> Int -> m ()
- copyMutableByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
- copyByteArrayToAddr :: PrimMonad m => Ptr Word8 -> ByteArray -> Int -> Int -> m ()
- copyMutableByteArrayToAddr :: PrimMonad m => Ptr Word8 -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
- copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> Int -> m ()
- moveByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
- setByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> Int -> a -> m ()
- fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> m ()
- cloneByteArray :: ByteArray -> Int -> Int -> ByteArray
- cloneMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m (MutableByteArray (PrimState m))
- sizeofByteArray :: ByteArray -> Int
- sizeofMutableByteArray :: MutableByteArray s -> Int
- getSizeofMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m Int
- sameMutableByteArray :: MutableByteArray s -> MutableByteArray s -> Bool
- isByteArrayPinned :: ByteArray -> Bool
- isMutableByteArrayPinned :: MutableByteArray s -> Bool
- byteArrayAsForeignPtr :: ByteArray -> ForeignPtr Word8
- mutableByteArrayAsForeignPtr :: MutableByteArray RealWorld -> ForeignPtr Word8
- byteArrayContents :: ByteArray -> Ptr Word8
- withByteArrayContents :: PrimBase m => ByteArray -> (Ptr Word8 -> m a) -> m a
- mutableByteArrayContents :: MutableByteArray s -> Ptr Word8
- withMutableByteArrayContents :: PrimBase m => MutableByteArray (PrimState m) -> (Ptr Word8 -> m a) -> m a

# Types

data ByteArray Source #

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

Constructors

ByteArray ByteArray# |

#### Instances

Instances details

NFData ByteArray | Since: deepseq-1.4.7.0
Instance details Defined in Control.DeepSeq Methods rnf :: ByteArray -> () Source #
Monoid ByteArray | Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods mempty :: ByteArray Source # mappend :: ByteArray -> ByteArray -> ByteArray Source # mconcat :: [ByteArray] -> ByteArray Source #
Semigroup ByteArray | Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods (<>) :: ByteArray -> ByteArray -> ByteArray Source # sconcat :: NonEmpty ByteArray -> ByteArray Source # stimes :: Integral b => b -> ByteArray -> ByteArray Source #
Data ByteArray | Since: base-4.17.0.0

Instance details

Defined in Data.Array.Byte

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ByteArray -> c ByteArray Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ByteArray Source #

toConstr :: ByteArray -> Constr Source #

dataTypeOf :: ByteArray -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ByteArray) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ByteArray) Source #

gmapT :: (forall b. Data b => b -> b) -> ByteArray -> ByteArray Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ByteArray -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ByteArray -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> ByteArray -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> ByteArray -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray Source #

IsList ByteArray | Since: base-4.17.0.0

Instance details

Defined in Data.Array.Byte

Associated Types

type Item ByteArray |
Instance details Defined in Data.Array.Byte type Item ByteArray = Word8

Methods

fromList :: [Item ByteArray] -> ByteArray Source #

fromListN :: Int -> [Item ByteArray] -> ByteArray Source #

toList :: ByteArray -> [Item ByteArray] Source #

Show ByteArray | Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods showsPrec :: Int -> ByteArray -> ShowS Source # show :: ByteArray -> String Source # showList :: [ByteArray] -> ShowS Source #
Eq ByteArray | Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods (==) :: ByteArray -> ByteArray -> Bool Source # (/=) :: ByteArray -> ByteArray -> Bool Source #
Ord ByteArray | Non-lexicographic ordering. This compares the lengths of the byte arrays first and uses a lexicographic ordering if the lengths are equal. Subject to change between major versions. Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods compare :: ByteArray -> ByteArray -> Ordering Source # (<) :: ByteArray -> ByteArray -> Bool Source # (<=) :: ByteArray -> ByteArray -> Bool Source # (>) :: ByteArray -> ByteArray -> Bool Source # (>=) :: ByteArray -> ByteArray -> Bool Source # max :: ByteArray -> ByteArray -> ByteArray Source # min :: ByteArray -> ByteArray -> ByteArray Source #
Lift ByteArray | Since: template-haskell-2.19.0.0
Instance details Defined in Language.Haskell.TH.Syntax Methods lift :: Quote m => ByteArray -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => ByteArray -> Code m ByteArray Source #
type Item ByteArray |
Instance details Defined in Data.Array.Byte type Item ByteArray = Word8

data MutableByteArray s Source #

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

Constructors

MutableByteArray (MutableByteArray# s) |

#### Instances

Instances details

NFData (MutableByteArray s) | Since: deepseq-1.4.8.0
Instance details Defined in Control.DeepSeq Methods rnf :: MutableByteArray s -> () Source #
Typeable s => Data (MutableByteArray s) | Since: base-4.17.0.0

Instance details

Defined in Data.Array.Byte

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> MutableByteArray s -> c (MutableByteArray s) Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (MutableByteArray s) Source #

toConstr :: MutableByteArray s -> Constr Source #

dataTypeOf :: MutableByteArray s -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (MutableByteArray s)) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (MutableByteArray s)) Source #

gmapT :: (forall b. Data b => b -> b) -> MutableByteArray s -> MutableByteArray s Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> MutableByteArray s -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> MutableByteArray s -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> MutableByteArray s -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> MutableByteArray s -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) Source #

Eq (MutableByteArray s) | Since: base-4.17.0.0
Instance details Defined in Data.Array.Byte Methods (==) :: MutableByteArray s -> MutableByteArray s -> Bool Source # (/=) :: MutableByteArray s -> MutableByteArray s -> Bool Source #

data ByteArray# :: UnliftedType Source #

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.

data MutableByteArray# a :: UnliftedType Source #

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

# Allocation

newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m)) Source #

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.

newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m)) Source #

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.

newAlignedPinnedByteArray Source #

Arguments

:: PrimMonad m |
=> Int | size
-> Int | alignment
-> m (MutableByteArray (PrimState m)) |

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.

resizeMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m (MutableByteArray (PrimState m)) Source #

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: 0.6.4.0

shrinkMutableByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) |
-> Int | new size
-> m () |

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: 0.7.1.0

# Element access

readByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> m a Source #

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.

writeByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> a -> m () Source #

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.

indexByteArray :: Prim a => ByteArray -> Int -> a Source #

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.

# Char Element Access

GHC provides two sets of element accessors for `Char`. One set faithfully represents `Char` as 32-bit words using UTF-32. The other set represents `Char` as 8-bit words using Latin-1 (ISO-8859-1), and the write operation has undefined behavior for codepoints outside of the ASCII and Latin-1 blocks. The `Prim` instance for `Char` uses the UTF-32 set of operators.

readCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m Char Source #

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.

writeCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Char -> m () Source #

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.

indexCharArray :: ByteArray -> Int -> Char Source #

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.

# Constructing

emptyByteArray :: ByteArray Source #

The empty `ByteArray`.

byteArrayFromList :: Prim a => [a] -> ByteArray Source #

Create a `ByteArray` from a list.

    byteArrayFromList xs = byteArrayFromListN (length xs) xs

byteArrayFromListN :: Prim a => Int -> [a] -> ByteArray Source #

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.

# Folding

foldrByteArray :: Prim a => (a -> b -> b) -> b -> ByteArray -> b Source #

Right-fold over the elements of a `ByteArray`.

# Comparing

compareByteArrays Source #

Arguments

:: ByteArray | array A
-> Int | offset A, given in bytes
-> ByteArray | array B
-> Int | offset B, given in bytes
-> Int | length of the slice, given in bytes
-> Ordering |

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

# Freezing and thawing

freezeByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | source
-> Int | offset in bytes
-> Int | length in bytes
-> m ByteArray |

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.

thawByteArray Source #

Arguments

:: PrimMonad m |
=> ByteArray | source
-> Int | offset in bytes
-> Int | length in bytes
-> m (MutableByteArray (PrimState m)) |

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: 0.7.2.0

runByteArray :: (forall s. ST s (MutableByteArray s)) -> ByteArray Source #

Execute the monadic action and freeze the resulting array.

    runByteArray m = runST $ m >>= unsafeFreezeByteArray

createByteArray :: Int -> (forall s. MutableByteArray s -> ST s ()) -> ByteArray Source #

unsafeFreezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m ByteArray Source #

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

unsafeThawByteArray :: PrimMonad m => ByteArray -> m (MutableByteArray (PrimState m)) Source #

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

# Block operations

copyByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | destination array
-> Int | offset into destination array
-> ByteArray | source array
-> Int | offset into source array
-> Int | number of bytes to copy
-> m () |

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

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

copyMutableByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | destination array
-> Int | offset into destination array
-> MutableByteArray (PrimState m) | source array
-> Int | offset into source array
-> Int | number of bytes to copy
-> m () |

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.

copyByteArrayToPtr Source #

Arguments

:: (PrimMonad m, Prim a) |
=> Ptr a | destination
-> ByteArray | source array
-> Int | offset into source array, interpreted as elements of type `a`
-> Int | number of elements to copy
-> m () |

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: 0.7.1.0

copyMutableByteArrayToPtr Source #

Arguments

:: (PrimMonad m, Prim a) |
=> Ptr a | destination
-> MutableByteArray (PrimState m) | source array
-> Int | offset into source array, interpreted as elements of type `a`
-> Int | number of elements to copy
-> m () |

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: 0.7.1.0

copyByteArrayToAddr Source #

Arguments

:: PrimMonad m |
=> Ptr Word8 | destination
-> ByteArray | source array
-> Int | offset into source array
-> Int | number of bytes to copy
-> m () |

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: 0.6.4.0

copyMutableByteArrayToAddr Source #

Arguments

:: PrimMonad m |
=> Ptr Word8 | destination
-> MutableByteArray (PrimState m) | source array
-> Int | offset into source array
-> Int | number of bytes to copy
-> m () |

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: 0.6.4.0

copyPtrToMutableByteArray Source #

Arguments

:: (PrimMonad m, Prim a) |
=> MutableByteArray (PrimState m) | destination array
-> Int | destination offset given in elements of type `a`
-> Ptr a | source pointer
-> Int | number of elements
-> m () |

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.

moveByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | destination array
-> Int | offset into destination array
-> MutableByteArray (PrimState m) | source array
-> Int | offset into source array
-> Int | number of bytes to copy
-> m () |

Copy a slice of a mutable byte array into another, potentially overlapping array.

setByteArray Source #

Arguments

:: (Prim a, PrimMonad m) |
=> MutableByteArray (PrimState m) | array to fill
-> Int | offset into array
-> Int | number of values to fill
-> a | value to fill with
-> m () |

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.

fillByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | array to fill
-> Int | offset into array
-> Int | number of bytes to fill
-> Word8 | byte to fill with
-> m () |

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

Note: this function does not do bounds checking.

cloneByteArray Source #

Arguments

:: ByteArray | source array
-> Int | offset into destination array
-> Int | number of bytes to copy
-> ByteArray |

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.

cloneMutableByteArray Source #

Arguments

:: PrimMonad m |
=> MutableByteArray (PrimState m) | source array
-> Int | offset into destination array
-> Int | number of bytes to copy
-> m (MutableByteArray (PrimState m)) |

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.

# Information

sizeofByteArray :: ByteArray -> Int Source #

Size of the byte array in bytes.

sizeofMutableByteArray :: MutableByteArray s -> Int Source #

Deprecated: use getSizeofMutableByteArray instead

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.

getSizeofMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m Int Source #

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

sameMutableByteArray :: MutableByteArray s -> MutableByteArray s -> Bool Source #

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

isByteArrayPinned :: ByteArray -> Bool Source #

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: 0.6.4.0

isMutableByteArrayPinned :: MutableByteArray s -> Bool Source #

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: 0.6.4.0

byteArrayAsForeignPtr :: ByteArray -> ForeignPtr Word8 Source #

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.

mutableByteArrayAsForeignPtr :: MutableByteArray RealWorld -> ForeignPtr Word8 Source #

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.

byteArrayContents :: ByteArray -> Ptr Word8 Source #

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.

withByteArrayContents :: PrimBase m => ByteArray -> (Ptr Word8 -> m a) -> m a Source #

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.

mutableByteArrayContents :: MutableByteArray s -> Ptr Word8 Source #

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.

withMutableByteArrayContents :: PrimBase m => MutableByteArray (PrimState m) -> (Ptr Word8 -> m a) -> m a Source #

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.