primitive-0.9.0.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.Ptr

Contents

- Types
- Address arithmetic
- Element access
- Block operations

Description

Primitive operations on machine addresses.

Since: 0.6.4.0

Synopsis

- data Ptr a = Ptr Addr#
- nullPtr :: Ptr a
- advancePtr :: Prim a => Ptr a -> Int -> Ptr a
- subtractPtr :: Prim a => Ptr a -> Ptr a -> Int
- indexOffPtr :: Prim a => Ptr a -> Int -> a
- readOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> m a
- writeOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m ()
- copyPtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()
- movePtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()
- setPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m ()
- copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()
- copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> Int -> m ()

# Types

data Ptr a #

A value of type ``Ptr` a` represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type `a`.

The type `a` will often be an instance of class `Storable` which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C `struct`.

Constructors

Ptr Addr# |

#### Instances

Instances details

NFData1 Ptr | Since: deepseq-1.4.3.0
Instance details Defined in Control.DeepSeq Methods liftRnf :: (a -> ()) -> Ptr a -> () #
Generic1 (URec (Ptr ()) :: k -> Type) |
Instance details Defined in GHC.Generics Associated Types
type Rep1 (URec (Ptr ()) :: k -> Type) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics type Rep1 (URec (Ptr ()) :: k -> Type) = D1 ('MetaData "URec" "GHC.Generics" "base" 'False) (C1 ('MetaCons "UAddr" 'PrefixI 'True) (S1 ('MetaSel ('Just "uAddr#") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (UAddr :: k -> Type)))
Methods from1 :: forall (a :: k). URec (Ptr ()) a -> Rep1 (URec (Ptr ()) :: k -> Type) a # to1 :: forall (a :: k). Rep1 (URec (Ptr ()) :: k -> Type) a -> URec (Ptr ()) a #
Data a => Data (Ptr a) | Since: base-4.8.0.0
Instance details Defined in Data.Data Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Ptr a -> c (Ptr a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Ptr a) # toConstr :: Ptr a -> Constr # dataTypeOf :: Ptr a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Ptr a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Ptr a)) # gmapT :: (forall b. Data b => b -> b) -> Ptr a -> Ptr a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r # gmapQ :: (forall d. Data d => d -> u) -> Ptr a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Ptr a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) #
Foldable (UAddr :: Type -> Type) | Since: base-4.9.0.0
Instance details Defined in Data.Foldable Methods fold :: Monoid m => UAddr m -> m # foldMap :: Monoid m => (a -> m) -> UAddr a -> m # foldMap' :: Monoid m => (a -> m) -> UAddr a -> m # foldr :: (a -> b -> b) -> b -> UAddr a -> b # foldr' :: (a -> b -> b) -> b -> UAddr a -> b # foldl :: (b -> a -> b) -> b -> UAddr a -> b # foldl' :: (b -> a -> b) -> b -> UAddr a -> b # foldr1 :: (a -> a -> a) -> UAddr a -> a # foldl1 :: (a -> a -> a) -> UAddr a -> a # toList :: UAddr a -> [a] # null :: UAddr a -> Bool # length :: UAddr a -> Int # elem :: Eq a => a -> UAddr a -> Bool # maximum :: Ord a => UAddr a -> a # minimum :: Ord a => UAddr a -> a # sum :: Num a => UAddr a -> a # product :: Num a => UAddr a -> a #
Traversable (UAddr :: Type -> Type) | Since: base-4.9.0.0
Instance details Defined in Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UAddr a -> f (UAddr b) # sequenceA :: Applicative f => UAddr (f a) -> f (UAddr a) # mapM :: Monad m => (a -> m b) -> UAddr a -> m (UAddr b) # sequence :: Monad m => UAddr (m a) -> m (UAddr a) #
Storable (Ptr a) | Since: base-2.1
Instance details Defined in Foreign.Storable Methods sizeOf :: Ptr a -> Int # alignment :: Ptr a -> Int # peekElemOff :: Ptr (Ptr a) -> Int -> IO (Ptr a) # pokeElemOff :: Ptr (Ptr a) -> Int -> Ptr a -> IO () # peekByteOff :: Ptr b -> Int -> IO (Ptr a) # pokeByteOff :: Ptr b -> Int -> Ptr a -> IO () # peek :: Ptr (Ptr a) -> IO (Ptr a) # poke :: Ptr (Ptr a) -> Ptr a -> IO () #
Show (Ptr a) | Since: base-2.1
Instance details Defined in GHC.Ptr Methods showsPrec :: Int -> Ptr a -> ShowS # show :: Ptr a -> String # showList :: [Ptr a] -> ShowS #
NFData (Ptr a) | Since: deepseq-1.4.2.0
Instance details Defined in Control.DeepSeq Methods rnf :: Ptr a -> () #
Eq (Ptr a) | Since: base-2.1
Instance details Defined in GHC.Ptr Methods (==) :: Ptr a -> Ptr a -> Bool # (/=) :: Ptr a -> Ptr a -> Bool #
Ord (Ptr a) | Since: base-2.1
Instance details Defined in GHC.Ptr Methods compare :: Ptr a -> Ptr a -> Ordering # (<) :: Ptr a -> Ptr a -> Bool # (<=) :: Ptr a -> Ptr a -> Bool # (>) :: Ptr a -> Ptr a -> Bool # (>=) :: Ptr a -> Ptr a -> Bool # max :: Ptr a -> Ptr a -> Ptr a # min :: Ptr a -> Ptr a -> Ptr a #
Prim (Ptr a) # |
Instance details Defined in Data.Primitive.Types Methods sizeOfType# :: Proxy (Ptr a) -> Int# # sizeOf# :: Ptr a -> Int# # alignmentOfType# :: Proxy (Ptr a) -> Int# # alignment# :: Ptr a -> Int# # indexByteArray# :: ByteArray# -> Int# -> Ptr a # readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Ptr a #) # writeByteArray# :: MutableByteArray# s -> Int# -> Ptr a -> State# s -> State# s # setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Ptr a -> State# s -> State# s # indexOffAddr# :: Addr# -> Int# -> Ptr a # readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, Ptr a #) # writeOffAddr# :: Addr# -> Int# -> Ptr a -> State# s -> State# s # setOffAddr# :: Addr# -> Int# -> Int# -> Ptr a -> State# s -> State# s #
Functor (URec (Ptr ()) :: Type -> Type) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics Methods fmap :: (a -> b) -> URec (Ptr ()) a -> URec (Ptr ()) b # (<$) :: a -> URec (Ptr ()) b -> URec (Ptr ()) a #
Generic (URec (Ptr ()) p) |
Instance details Defined in GHC.Generics Associated Types
type Rep (URec (Ptr ()) p) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics type Rep (URec (Ptr ()) p) = D1 ('MetaData "URec" "GHC.Generics" "base" 'False) (C1 ('MetaCons "UAddr" 'PrefixI 'True) (S1 ('MetaSel ('Just "uAddr#") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (UAddr :: Type -> Type)))
Methods from :: URec (Ptr ()) p -> Rep (URec (Ptr ()) p) x # to :: Rep (URec (Ptr ()) p) x -> URec (Ptr ()) p #
Eq (URec (Ptr ()) p) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics Methods (==) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (/=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool #
Ord (URec (Ptr ()) p) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics Methods compare :: URec (Ptr ()) p -> URec (Ptr ()) p -> Ordering # (<) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (<=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (>) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (>=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # max :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p # min :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p #
data URec (Ptr ()) (p :: k) | Used for marking occurrences of `Addr#` Since: base-4.9.0.0
Instance details Defined in GHC.Generics data URec (Ptr ()) (p :: k) = UAddr { uAddr# :: Addr# }
type Rep1 (URec (Ptr ()) :: k -> Type) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics type Rep1 (URec (Ptr ()) :: k -> Type) = D1 ('MetaData "URec" "GHC.Generics" "base" 'False) (C1 ('MetaCons "UAddr" 'PrefixI 'True) (S1 ('MetaSel ('Just "uAddr#") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (UAddr :: k -> Type)))
type Rep (URec (Ptr ()) p) | Since: base-4.9.0.0
Instance details Defined in GHC.Generics type Rep (URec (Ptr ()) p) = D1 ('MetaData "URec" "GHC.Generics" "base" 'False) (C1 ('MetaCons "UAddr" 'PrefixI 'True) (S1 ('MetaSel ('Just "uAddr#") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (UAddr :: Type -> Type)))

# Address arithmetic

nullPtr :: Ptr a #

The constant `nullPtr` contains a distinguished value of `Ptr` that is not associated with a valid memory location.

advancePtr :: Prim a => Ptr a -> Int -> Ptr a #

Offset a pointer by the given number of elements.

subtractPtr :: Prim a => Ptr a -> Ptr a -> Int #

Subtract a pointer from another pointer. The result represents the number of elements of type `a` that fit in the contiguous memory range bounded by these two pointers.

# Element access

indexOffPtr :: Prim a => Ptr a -> Int -> a #

Read a value from a memory position given by a pointer and an offset. The memory block the address refers to must be immutable. The offset is in elements of type `a` rather than in bytes.

readOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> m a #

Read a value from a memory position given by an address and an offset. The offset is in elements of type `a` rather than in bytes.

writeOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m () #

Write a value to a memory position given by an address and an offset. The offset is in elements of type `a` rather than in bytes.

# Block operations

copyPtr #

Arguments

:: (PrimMonad m, Prim a) |
=> Ptr a | destination pointer
-> Ptr a | source pointer
-> Int | number of elements
-> m () |

Copy the given number of elements from the second `Ptr` to the first. The areas may not overlap.

movePtr #

Arguments

:: (PrimMonad m, Prim a) |
=> Ptr a | destination pointer
-> Ptr a | source pointer
-> Int | number of elements
-> m () |

Copy the given number of elements from the second `Ptr` to the first. The areas may overlap.

setPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m () #

Fill a memory block with the given value. The length is in elements of type `a` rather than in bytes.

copyPtrToMutablePrimArray #

Arguments

:: (PrimMonad m, Prim a) |
=> MutablePrimArray (PrimState m) a | destination array
-> Int | destination offset
-> Ptr a | source pointer
-> Int | number of elements
-> m () |

Copy from a pointer to a mutable primitive array. The offset and length are given in elements of type `a`. This function assumes that the `Prim` instance of `a` agrees with the `Storable` instance.

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

copyPtrToMutableByteArray #

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.