primitive-0.6.4.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
- Constructing
- Folding
- Freezing and thawing
- Block operations
- Information

Description

Primitive operations on ByteArrays

Synopsis

- data ByteArray = ByteArray ByteArray#
- data MutableByteArray s = MutableByteArray (MutableByteArray# s)
- data ByteArray# :: TYPE UnliftedRep
- data MutableByteArray# (a :: Type) :: Type -> 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))
- 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
- 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 ()
- copyByteArrayToAddr :: PrimMonad m => Addr -> ByteArray -> Int -> Int -> m ()
- copyMutableByteArrayToAddr :: PrimMonad m => Addr -> 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 ()
- 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 -> Addr
- mutableByteArrayContents :: MutableByteArray s -> Addr

# Types

data ByteArray #

Byte arrays

Constructors

ByteArray ByteArray# |

Instances

IsList ByteArray # | Since: 0.6.3.0
Instance details Defined in Data.Primitive.ByteArray Associated Types type Item ByteArray :: Type # 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 :: (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 # | 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 #
PrimUnlifted ByteArray # |
Instance details Defined in Data.Primitive.UnliftedArray Methods toArrayArray# :: ByteArray -> ArrayArray# # fromArrayArray# :: ArrayArray# -> 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

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 :: (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) #
PrimUnlifted (MutableByteArray s) # |
Instance details Defined in Data.Primitive.UnliftedArray Methods toArrayArray# :: MutableByteArray s -> ArrayArray# # fromArrayArray# :: ArrayArray# -> MutableByteArray s #

data ByteArray# :: TYPE UnliftedRep #

data MutableByteArray# (a :: Type) :: Type -> TYPE UnliftedRep #

# Allocation

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

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

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.

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.

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

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

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.

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.

# Constructing

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

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

# Folding

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

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

# Freezing and thawing

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.

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.

copyByteArrayToAddr #

Arguments

:: PrimMonad m |
=> Addr | 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.

Since: 0.6.4.0

copyMutableByteArrayToAddr #

Arguments

:: PrimMonad m |
=> Addr | 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.

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.

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.

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

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

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