binary-0.5.1.0: Binary serialisation for Haskell values using lazy ByteStrings

Portability | portable to Hugs and GHC.
Stability | experimental
Maintainer | Lennart Kolmodin <kolmodin@dtek.chalmers.se>
Safe Haskell | Trustworthy

Data.Binary.Get

Contents

- The Get type
- Parsing
- Utility
- Parsing particular types
  - ByteStrings
  - Big-endian reads
  - Little-endian reads
  - Host-endian, unaligned reads

Description

The Get monad. A monad for efficiently building structures from encoded lazy ByteStrings

Synopsis

- data Get a
- runGet :: Get a -> ByteString -> a
- runGetState :: Get a -> ByteString -> Int64 -> (a, ByteString, Int64)
- skip :: Int -> Get ()
- uncheckedSkip :: Int64 -> Get ()
- lookAhead :: Get a -> Get a
- lookAheadM :: Get (Maybe a) -> Get (Maybe a)
- lookAheadE :: Get (Either a b) -> Get (Either a b)
- uncheckedLookAhead :: Int64 -> Get ByteString
- bytesRead :: Get Int64
- getBytes :: Int -> Get ByteString
- remaining :: Get Int64
- isEmpty :: Get Bool
- getWord8 :: Get Word8
- getByteString :: Int -> Get ByteString
- getLazyByteString :: Int64 -> Get ByteString
- getLazyByteStringNul :: Get ByteString
- getRemainingLazyByteString :: Get ByteString
- getWord16be :: Get Word16
- getWord32be :: Get Word32
- getWord64be :: Get Word64
- getWord16le :: Get Word16
- getWord32le :: Get Word32
- getWord64le :: Get Word64
- getWordhost :: Get Word
- getWord16host :: Get Word16
- getWord32host :: Get Word32
- getWord64host :: Get Word64

# The Get type

data Get a

The Get monad is just a State monad carrying around the input ByteString We treat it as a strict state monad.

Instances

Monad Get |
Functor Get |
MonadFix Get |
Applicative Get |

runGet :: Get a -> ByteString -> a

Run the Get monad applies a `get`-based parser on the input ByteString

runGetState :: Get a -> ByteString -> Int64 -> (a, ByteString, Int64)

Run the Get monad applies a `get`-based parser on the input ByteString. Additional to the result of get it returns the number of consumed bytes and the rest of the input.

# Parsing

skip :: Int -> Get ()

Skip ahead `n` bytes. Fails if fewer than `n` bytes are available.

uncheckedSkip :: Int64 -> Get ()

Skip ahead `n` bytes. No error if there isn't enough bytes.

lookAhead :: Get a -> Get a

Run `ga`, but return without consuming its input. Fails if `ga` fails.

lookAheadM :: Get (Maybe a) -> Get (Maybe a)

Like `lookAhead`, but consume the input if `gma` returns 'Just _'. Fails if `gma` fails.

lookAheadE :: Get (Either a b) -> Get (Either a b)

Like `lookAhead`, but consume the input if `gea` returns 'Right _'. Fails if `gea` fails.

uncheckedLookAhead :: Int64 -> Get ByteString

Get the next up to `n` bytes as a lazy ByteString, without consuming them.

# Utility

bytesRead :: Get Int64

Get the total number of bytes read to this point.

getBytes :: Int -> Get ByteString

important

Pull `n` bytes from the input, as a strict ByteString.

remaining :: Get Int64

Get the number of remaining unparsed bytes. Useful for checking whether all input has been consumed. Note that this forces the rest of the input.

isEmpty :: Get Bool

Test whether all input has been consumed, i.e. there are no remaining unparsed bytes.

# Parsing particular types

getWord8 :: Get Word8

Read a Word8 from the monad state

## ByteStrings

getByteString :: Int -> Get ByteString

An efficient `get` method for strict ByteStrings. Fails if fewer than `n` bytes are left in the input.

getLazyByteString :: Int64 -> Get ByteString

An efficient `get` method for lazy ByteStrings. Does not fail if fewer than `n` bytes are left in the input.

getLazyByteStringNul :: Get ByteString

Get a lazy ByteString that is terminated with a NUL byte. Fails if it reaches the end of input without hitting a NUL.

getRemainingLazyByteString :: Get ByteString

Get the remaining bytes as a lazy ByteString

## Big-endian reads

getWord16be :: Get Word16

Read a Word16 in big endian format

getWord32be :: Get Word32

Read a Word32 in big endian format

getWord64be :: Get Word64

Read a Word64 in big endian format

## Little-endian reads

getWord16le :: Get Word16

Read a Word16 in little endian format

getWord32le :: Get Word32

Read a Word32 in little endian format

getWord64le :: Get Word64

Read a Word64 in little endian format

## Host-endian, unaligned reads

getWordhost :: Get Word

O(1). Read a single native machine word. The word is read in host order, host endian form, for the machine you're on. On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.

getWord16host :: Get Word16

O(1). Read a 2 byte Word16 in native host order and host endianness.

getWord32host :: Get Word32

O(1). Read a Word32 in native host order and host endianness.

getWord64host :: Get Word64

O(1). Read a Word64 in native host order and host endianess.