primitive-0.9.0.0: Primitive memory-related operations
Copyright(c) Roman Leshchinskiy 2009-2012
LicenseBSD-style
MaintainerRoman Leshchinskiy <rl@cse.unsw.edu.au>
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Data.Primitive.ByteArray

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

Types

data ByteArray #

Constructors

ByteArray ByteArray# 

Instances

Instances details
Data ByteArray 
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

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

Monoid ByteArray 
Instance details

Defined in Data.Array.Byte

Semigroup ByteArray 
Instance details

Defined in Data.Array.Byte

Methods

(<>) :: ByteArray -> ByteArray -> ByteArray

sconcat :: NonEmpty ByteArray -> ByteArray

stimes :: Integral b => b -> ByteArray -> ByteArray

IsList ByteArray 
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

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

toList :: ByteArray -> [Item ByteArray]

Show ByteArray 
Instance details

Defined in Data.Array.Byte

Methods

showsPrec :: Int -> ByteArray -> ShowS

show :: ByteArray -> String

showList :: [ByteArray] -> ShowS

NFData ByteArray 
Instance details

Defined in Control.DeepSeq

Methods

rnf :: ByteArray -> ()

Eq ByteArray 
Instance details

Defined in Data.Array.Byte

Methods

(==) :: ByteArray -> ByteArray -> Bool

(/=) :: ByteArray -> ByteArray -> Bool

Ord ByteArray 
Instance details

Defined in Data.Array.Byte

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

Lift ByteArray 
Instance details

Defined in Language.Haskell.TH.Syntax

Methods

lift :: Quote m => ByteArray -> m Exp

liftTyped :: forall (m :: Type -> Type). Quote m => ByteArray -> Code m ByteArray

type Item ByteArray 
Instance details

Defined in Data.Array.Byte

type Item ByteArray = Word8

data MutableByteArray s #

Instances

Instances details
Typeable s => Data (MutableByteArray s) 
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)

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 Control.DeepSeq

Methods

rnf :: MutableByteArray s -> ()

Eq (MutableByteArray s) 
Instance details

Defined in Data.Array.Byte

data ByteArray# :: UnliftedType #

data MutableByteArray# a :: UnliftedType #

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

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

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

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.