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 |
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
- emptyByteArray :: ByteArray
- 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))
- runByteArray :: (forall s. ST s (MutableByteArray 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 :: 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 ()
- copyPtrToMutableByteArray :: forall m a. (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
- byteArrayContents :: ByteArray -> Ptr Word8
- mutableByteArrayContents :: MutableByteArray s -> Ptr Word8
Types
Byte arrays.
Instances
IsList ByteArray Source # | Since: 0.6.3.0 |
Eq ByteArray Source # | Since: 0.6.3.0 |
Data ByteArray Source # | |
Defined in Data.Primitive.ByteArray 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 Source # | 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 |
Defined in Data.Primitive.ByteArray | |
Show ByteArray Source # | 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 Since: 0.6.3.0 |
Semigroup ByteArray Source # | |
Monoid ByteArray Source # | |
NFData ByteArray Source # | |
Defined in Data.Primitive.ByteArray | |
Lift ByteArray Source # | Respects array pinnedness for GHC >= 8.2 |
type Item ByteArray Source # | |
Defined in Data.Primitive.ByteArray |
data MutableByteArray s Source #
Mutable byte arrays associated with a primitive state token.
Instances
Eq (MutableByteArray s) Source # | |
Defined in Data.Primitive.ByteArray (==) :: MutableByteArray s -> MutableByteArray s -> Bool # (/=) :: MutableByteArray s -> MutableByteArray s -> Bool # | |
Typeable s => Data (MutableByteArray s) Source # | |
Defined in Data.Primitive.ByteArray 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) Source # | |
Defined in Data.Primitive.ByteArray rnf :: MutableByteArray s -> () # |
data ByteArray# :: TYPE 'UnliftedRep #
data MutableByteArray# a :: TYPE 'UnliftedRep #
Allocation
newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m)) Source #
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)) Source #
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 Source #
:: 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)) 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 #
:: 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.
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 :: forall a b. Prim a => (a -> b -> b) -> b -> ByteArray -> b Source #
Right-fold over the elements of a ByteArray
.
Comparing
:: 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
:: 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.
:: 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
:: 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.
:: 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.
:: forall m a. (PrimMonad m, Prim a) | |
=> Ptr a | destination |
-> ByteArray | source array |
-> Int | offset into source array, interpreted as elements of type |
-> 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 #
:: 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 |
-> 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
:: 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 #
:: 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 #
:: forall m a. (PrimMonad m, Prim a) | |
=> MutableByteArray (PrimState m) | destination array |
-> Int | destination offset given in elements of type |
-> 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.
:: 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.
:: (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.
:: 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.
:: 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 #
:: 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 #
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 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 allocated by newPinnedByteArray
or
newAlignedPinnedByteArray
.
mutableByteArrayContents :: MutableByteArray s -> Ptr Word8 Source #
Yield a pointer to the array's data. This operation is only safe on
pinned byte arrays allocated by newPinnedByteArray
or
newAlignedPinnedByteArray
.