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
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# :: TYPE 'UnliftedRep
data MutableByteArray# a :: TYPE 'UnliftedRep
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
byteArrayFromList :: Prim a => [a] -> ByteArray
byteArrayFromListN :: Prim a => Int -> [a] -> ByteArray
foldrByteArray :: forall a b. 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))
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 :: forall m a. (PrimMonad m, Prim a) => Ptr a -> ByteArray -> Int -> Int -> m ()
copyMutableByteArrayToPtr :: forall m a. (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 ()
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
byteArrayContents :: ByteArray -> Ptr Word8
mutableByteArrayContents :: MutableByteArray s -> Ptr Word8

Types

data ByteArray #

Byte arrays

Constructors

ByteArray ByteArray#

Instances

Instances details

IsList ByteArray #	Since: 0.6.3.0
Instance details Defined in Data.Primitive.ByteArray Associated Types type Item ByteArray # Methods fromList :: [Item ByteArray] -> ByteArray # fromListN :: Int -> [Item ByteArray] -> ByteArray # toList :: ByteArray -> [Item ByteArray] #
Eq ByteArray #	Since: 0.6.3.0
Instance details Defined in Data.Primitive.ByteArray Methods (==) :: ByteArray -> ByteArray -> Bool # (/=) :: ByteArray -> ByteArray -> Bool #
Data ByteArray #
Instance details Defined in Data.Primitive.ByteArray Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ByteArray -> c ByteArray # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ByteArray # toConstr :: ByteArray -> Constr # dataTypeOf :: ByteArray -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ByteArray) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ByteArray) # gmapT :: (forall b. Data b => b -> b) -> ByteArray -> ByteArray # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ByteArray -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ByteArray -> r # gmapQ :: (forall d. Data d => d -> u) -> ByteArray -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> ByteArray -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteArray -> m ByteArray #
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: 0.6.3.0
Instance details Defined in Data.Primitive.ByteArray Methods compare :: ByteArray -> ByteArray -> Ordering # (<) :: ByteArray -> ByteArray -> Bool # (<=) :: ByteArray -> ByteArray -> Bool # (>) :: ByteArray -> ByteArray -> Bool # (>=) :: ByteArray -> ByteArray -> Bool # max :: ByteArray -> ByteArray -> ByteArray # min :: ByteArray -> ByteArray -> ByteArray #
Show ByteArray #	Behavior changed in 0.7.2.0. Before 0.7.2.0, this instance rendered 8-bit words less than 16 as a single hexadecimal digit (e.g. 13 was `0xD`). Starting with 0.7.2.0, all 8-bit words are represented as two digits (e.g. 13 is `0x0D`). Since: 0.6.3.0
Instance details Defined in Data.Primitive.ByteArray Methods showsPrec :: Int -> ByteArray -> ShowS # show :: ByteArray -> String # showList :: [ByteArray] -> ShowS #
Semigroup ByteArray #
Instance details Defined in Data.Primitive.ByteArray Methods (<>) :: ByteArray -> ByteArray -> ByteArray # sconcat :: NonEmpty ByteArray -> ByteArray # stimes :: Integral b => b -> ByteArray -> ByteArray #
Monoid ByteArray #
Instance details Defined in Data.Primitive.ByteArray Methods mempty :: ByteArray # mappend :: ByteArray -> ByteArray -> ByteArray # mconcat :: [ByteArray] -> ByteArray #
NFData ByteArray #
Instance details Defined in Data.Primitive.ByteArray Methods rnf :: ByteArray -> () #
type Item ByteArray #
Instance details Defined in Data.Primitive.ByteArray type Item ByteArray = Word8

data MutableByteArray s #

Mutable byte arrays associated with a primitive state token

Constructors

MutableByteArray (MutableByteArray# s)

Instances

Instances details

Eq (MutableByteArray s) #
Instance details Defined in Data.Primitive.ByteArray Methods (==) :: MutableByteArray s -> MutableByteArray s -> Bool # (/=) :: MutableByteArray s -> MutableByteArray s -> Bool #
Typeable s => Data (MutableByteArray s) #
Instance details Defined in Data.Primitive.ByteArray Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> MutableByteArray s -> c (MutableByteArray s) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (MutableByteArray s) # toConstr :: MutableByteArray s -> Constr # dataTypeOf :: MutableByteArray s -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (MutableByteArray s)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (MutableByteArray s)) # gmapT :: (forall b. Data b => b -> b) -> MutableByteArray s -> MutableByteArray s # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> MutableByteArray s -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> MutableByteArray s -> r # gmapQ :: (forall d. Data d => d -> u) -> MutableByteArray s -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> MutableByteArray s -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> MutableByteArray s -> m (MutableByteArray s) #
NFData (MutableByteArray s) #
Instance details Defined in Data.Primitive.ByteArray Methods rnf :: MutableByteArray s -> () #

data ByteArray# :: TYPE 'UnliftedRep #

data MutableByteArray# a :: TYPE 'UnliftedRep #

Allocation

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

Create a new mutable byte array of the specified size in bytes.

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

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

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

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

newAlignedPinnedByteArray #

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.

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

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

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 #

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. This function is only available when compiling with GHC 7.10 or newer.

Since: 0.7.1.0

Element access

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

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 () #

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 #

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.

Constructing

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

Create a ByteArray from a list.

byteArrayFromList xs = byteArrayFromListN (length xs) xs

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

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 :: forall a b. Prim a => (a -> b -> b) -> b -> ByteArray -> b #

Right-fold over the elements of a ByteArray.

Comparing

compareByteArrays #

Arguments

:: ByteArray	Array A
-> Int	Offset A, given in bytes
-> ByteArray	Array B
-> Int	Offset B, given in bytes
-> Int	Length of 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 #

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.

thawByteArray #

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.

Since: 0.7.2.0

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

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

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

Block operations

copyByteArray #

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 #

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 #

Arguments

:: forall m a. (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 given in elements, not in bytes. This function is only available when compiling with GHC 7.8 or newer.

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

Since: 0.7.1.0

copyMutableByteArrayToPtr #

Arguments

:: forall m a. (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 given in elements, not in bytes. This function is only available when compiling with GHC 7.8 or newer.

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

Since: 0.7.1.0

copyByteArrayToAddr #

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. This function is only available when compiling with GHC 7.8 or newer.

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

Since: 0.6.4.0

copyMutableByteArrayToAddr #

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. This function is only available when compiling with GHC 7.8 or newer.

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

Since: 0.6.4.0

moveByteArray #

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 #

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 #

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 #

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 #

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 #

Size of the byte array in bytes.

sizeofMutableByteArray :: MutableByteArray s -> Int #

Size of the mutable byte array in bytes. This function's behavior is undefined if resizeMutableByteArray is ever called on the mutable byte array given as the argument. Consequently, use of this function is discouraged. Prefer getSizeofMutableByteArray, which ensures correct sequencing in the presence of resizing.

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

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 #

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

isByteArrayPinned :: ByteArray -> Bool #

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. This function is only available when compiling with GHC 8.2 or newer.

Since: 0.6.4.0

isMutableByteArrayPinned :: MutableByteArray s -> Bool #

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

Since: 0.6.4.0

byteArrayContents :: ByteArray -> Ptr Word8 #

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

mutableByteArrayContents :: MutableByteArray s -> Ptr Word8 #

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