Storable -is:module
base Foreign.Storable,
protolude Protolude,
rio RIO.Prelude.Types RIO.Vector.Storable,
base-prelude BasePrelude,
classy-prelude ClassyPrelude,
basic-prelude CorePrelude,
massiv Data.Massiv.Array.Manifest,
derive-storable Foreign.Storable.Generic Foreign.Storable.Generic.Internal,
ghc-internal GHC.Internal.Foreign.Storable,
fixed-vector Data.Vector.Fixed.Storable,
mutable-containers Data.Mutable,
pvar Data.Primitive.PVar The member functions of this class facilitate writing values of
primitive types to raw memory (which may have been allocated with the
above mentioned routines) and reading values from blocks of raw
memory. The class, furthermore, includes support for computing the
storage requirements and alignment restrictions of storable types.
Memory addresses are represented as values of type
Ptr
a, for some
a which is an instance of class
Storable. The type argument to
Ptr helps provide some
valuable type safety in FFI code (you can't mix pointers of different
types without an explicit cast), while helping the Haskell type system
figure out which marshalling method is needed for a given pointer.
All marshalling between Haskell and a foreign language ultimately
boils down to translating Haskell data structures into the binary
representation of a corresponding data structure of the foreign
language and vice versa. To code this marshalling in Haskell, it is
necessary to manipulate primitive data types stored in unstructured
memory blocks. The class
Storable facilitates this manipulation
on all types for which it is instantiated, which are the standard
basic types of Haskell, the fixed size
Int types
(
Int8,
Int16,
Int32,
Int64), the fixed
size
Word types (
Word8,
Word16,
Word32,
Word64),
StablePtr, all types from
Foreign.C.Types, as well as
Ptr.
The member functions of this class facilitate writing values of
primitive types to raw memory (which may have been allocated with the
above mentioned routines) and reading values from blocks of raw
memory. The class, furthermore, includes support for computing the
storage requirements and alignment restrictions of storable types.
Memory addresses are represented as values of type
Ptr
a, for some
a which is an instance of class
Storable. The type argument to
Ptr helps provide some
valuable type safety in FFI code (you can't mix pointers of different
types without an explicit cast), while helping the Haskell type system
figure out which marshalling method is needed for a given pointer.
All marshalling between Haskell and a foreign language ultimately
boils down to translating Haskell data structures into the binary
representation of a corresponding data structure of the foreign
language and vice versa. To code this marshalling in Haskell, it is
necessary to manipulate primitive data types stored in unstructured
memory blocks. The class
Storable facilitates this manipulation
on all types for which it is instantiated, which are the standard
basic types of Haskell, the fixed size
Int types
(
Int8,
Int16,
Int32,
Int64), the fixed
size
Word types (
Word8,
Word16,
Word32,
Word64),
StablePtr, all types from
Foreign.C.Types, as well as
Ptr.
Storable type of self determined size.
Not on Stackage, so not searched.
Storable type class for variable-sized data
Capture a
Storable dictionary along with a byte offset from
some origin address.
Extending the Storable type class to the types that can be sequenced
in a structure.
Newtype for deriving
Storable instance for data types which has
instance of
Vector
Class of values that support storable vector like operations
Deprecated: Deprecated since bytestring-0.12.1.0. This
function is dangerous in the presence of internal padding and makes
naive assumptions about alignment. * For a primitive Haskell type like
Int64, use the corresponding primitive like int64Host. *
For other types, it is recommended to manually write a small function
that performs the necessary unaligned write and zeroes or removes any
internal padding bits.
storableCastArray takes a list of values of a first type,
stores it at a contiguous memory area (that is first blanked with 0s),
and then reads it as if it was a list of a second type, with enough
elements to fill at least the same space.
ghci
:m + Bindings.Sandbox Data.Int
storableCastArray (replicate 13 (1::Int8)) :: IO [Int32]
==> [16843009,16843009,16843009,1]
Tests the following
Storable properties:
Elegant definition of Storable instances for records
With this package you can build a Storable instance of a record type
from Storable instances of its elements in an elegant way. It does not
do any magic, just a bit arithmetic to compute the right offsets, that
would be otherwise done manually or by a preprocessor like C2HS. I
cannot promise that the generated memory layout is compatible with
that of a corresponding C struct. However, the module generates the
smallest layout that is possible with respect to the alignment of the
record elements. If you encounter, that a record does not have a
compatible layout, we should fix that. But also without C
compatibility this package is useful e.g. in connection with
StorableVector.
We provide Storable instance support for several cases:
- If you wrap a type in a newtype, then you can lift its
Storable instance to that newtype with the module
Foreign.Storable.Newtype. This way you do not need the
GeneralizedNewtypeDeriving feature of GHC.
- If you have a type that is an instance of Traversable, you
can use that feature for implementation of Storable methods.
The module Foreign.Storable.Traversable allows manipulation of
the portion of your type, that is accessible by Traversable
methods. For instance with the type data T a = Cons Int [a]
and an according Traversable implementation, you can load and
store the elements of the contained list. This may be part of a
Storable implementation of the whole type.
- If you have a record containing elements of various types, then
you need module Foreign.Storable.Record.
Note however that the Storable instances defined with this package are
quite slow in (up to) GHC-6.12.1. I'm afraid this is due to incomplete
inlining, but we have still to investigate the problem.
For examples see packages
storable-tuple and
sample-frame.
Fast, packed, strict storable arrays with a list interface like ByteString
Fast, packed, strict storable arrays with a list interface, a chunky
lazy list interface with variable chunk size and an interface for
write access via the
ST monad. This is much like
bytestring and
binary but can be used for every
Foreign.Storable.Storable type. See also package
http://hackage.haskell.org/package/vector with a similar
intention.
We do not provide advanced fusion optimization, since especially for
lazy vectors this would either be incorrect or not applicable. However
we provide fusion with lazy lists in the package
http://hackage.haskell.org/package/storablevector-streamfusion.
Storable instance for Complex
Provides a Storable instance for Complex which is binary compatible
with C99, C++ and Fortran complex data types.
The only purpose of this package is to provide a standard location for
this instance so that other packages needing this instance can play
nicely together.
Storable instance for pairs and triples
Provides a Storable instance for pair and triple which should be
binary compatible with C99 and C++. The only purpose of this package
is to provide a standard location for this instance so that other
packages needing this instance can play nicely together. Note however,
that the original purpose of the Storable class was the
transfer of primitive types between Haskell and foreign code. This
purpose was already extended by HSC, which creates Storable
instances for records from C header files. Nonetheless,
Storable instances for tuples were omitted from base
by intention. Instead of using the orphan instances from this package,
you may instead use the custom class or the wrapper type from the
module Foreign.Storable.Record.Tuple from the package
storable-record.