Safe Haskell | None |
---|---|
Language | Haskell98 |
This module provides the Format
class definition,
without exporting the pre-defined formats.
- class Format f where
- class Format format => Packable format where
- data Packer = Packer {}
- unsafeRunPacker :: Packer -> Ptr Word8 -> IO (Maybe (Ptr Word8))
- class Format format => Unpackable format where
- data Unpacker a = Unpacker {}
- unsafeRunUnpacker :: Unpacker a -> Ptr Word8 -> Int -> (Word8 -> Bool) -> IO (Maybe (a, Ptr Word8))
Packing single fields
Relates a storage format to the Haskell type of the value that is stored in that format.
fieldCount :: f -> Int Source
Yield the number of separate fields in this format.
Yield the minumum number of bytes that a value of this format will take up.
Packing a value into this format is guaranteed to use at least this many bytes. This is exact for fixed-size formats.
fixedSize :: f -> Maybe Int Source
For fixed size formats, yield their size (length) in bytes.
Yields Nothing
if this is not a fixed size format.
packedSize :: f -> Value f -> Maybe Int Source
Yield the maximum packed size of the value in this format.
If fixedSize
returns a size then packedSize
returns the same size.
For variable length formats, packedSize
is an over-approximation.
We allow the actual packed value to use less space, as it may not be
possible to determine how much space it needs without actually packing it.
Yields Nothing
when a collection of values is to be packed into a
fixed length format, but the size of the collection does not match
the format.
Format Float64be Source | |
Format Float32be Source | |
Format Int64be Source | |
Format Word64be Source | |
Format Int32be Source | |
Format Word32be Source | |
Format Int16be Source | |
Format Word16be Source | |
Format Int8be Source | |
Format Word8be Source | |
Format VarBytes Source | |
Format DoubleFixedPack Source | |
Format DoubleAsc Source | |
Format IntAsc0 Source | |
Format IntAsc Source | |
Format DDsMMsYYYY Source | |
Format YYYYsMMsDD Source | |
Format ExactChars Source | |
Format VarCharString Source | |
Format VarChars Source | |
Format FixChars Source | |
Format VarTextString Source | |
Format VarText Source | |
Format UnitAsc Source | |
Format (App ()) Source | |
(Format f1, Format (App fs), (~) * (Value (App fs)) (Value fs)) => Format (App ((:*:) f1 fs)) Source | |
Format f => Format (MaybeBytes f) Source | |
Format f => Format (MaybeChars f) Source | |
Format (Sep ()) Source | |
(Format f1, Format (Sep fs), (~) * (Value (Sep fs)) (Value fs)) => Format (Sep ((:*:) f1 fs)) Source | |
(Format (ObjectFields fs), (~) * (Value (ObjectFields fs)) (Value fs)) => Format (Object fs) Source |
Packable
class Format format => Packable format where Source
Class of storage formats that can have values packed and unpacked from foreign bufferes.
The methods are written using continuations to make it easier for GHC to optimise its core code when packing/unpacking many fields.
Pack a value into a buffer using the given format.
:: format | Data format. |
-> Value format | Value to pack. |
-> Addr# | Pointer to start of buffer. |
-> IO () | Signal failure. |
-> (Addr# -> IO ()) | Accept the address after the packed field. |
-> IO () |
Low level packing function for the given format.
Packer wraps a function that can write to a buffer.
Packer | |
|
:: Packer | Packer to run. |
-> Ptr Word8 | Start of buffer. |
-> IO (Maybe (Ptr Word8)) | Pointer to the byte after the last one written. |
Pack data into the given buffer.
PRECONDITION: The buffer needs to be big enough to hold the packed data,
otherwise you'll corrupt the heap (bad). Use packedSize
to work out
how big it needs to be.
Unpackable
class Format format => Unpackable format where Source
Unpack a value from a buffer using the given format.
:: format | Data format. |
-> Addr# | Start of buffer. |
-> Addr# | Pointer to first byte after end of buffer. |
-> (Word8 -> Bool) | Detect a field terminator. |
-> IO () | Signal failure. |
-> (Addr# -> Value format -> IO ()) | Accept an unpacked value. |
-> IO () |
Low level unpacking function for the given format.
Unpacker | |
|
:: Unpacker a | Unpacker to run. |
-> Ptr Word8 | Source buffer. |
-> Int | Length of source buffer. |
-> (Word8 -> Bool) | Detect a field terminator. |
-> IO (Maybe (a, Ptr Word8)) | Unpacked result, and pointer to the byte after the last one read. |
Unpack data from the given buffer.
PRECONDITION: The buffer must be at least the minimum size of the format (minSize). This allows us to avoid repeatedly checking for buffer overrun when unpacking fixed size format. If the buffer is not long enough then you'll get an indeterminate result (bad).