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

Safe Haskell | None
Language | Haskell98

Data.Binary.Get.Internal

Contents

- The Get type
- Parsing
- Utility
  - ByteStrings

Synopsis

- data Get a
- runCont :: Get a -> forall r. ByteString -> Success a r -> Decoder r
- data Decoder a
  - = Fail !ByteString String
  - | Partial (Maybe ByteString -> Decoder a)
  - | Done !ByteString a
  - | BytesRead !Int64 (Int64 -> Decoder a)
- runGetIncremental :: Get a -> Decoder a
- readN :: Int -> (ByteString -> a) -> Get a
- readNWith :: Int -> (Ptr a -> IO a) -> Get a
- skip :: Int -> Get ()
- bytesRead :: Get Int64
- get :: Get ByteString
- put :: ByteString -> Get ()
- demandInput :: Get ()
- ensureN :: Int -> Get ()
- remaining :: Get Int64
- getBytes :: Int -> Get ByteString
- isEmpty :: Get Bool
- lookAhead :: Get a -> Get a
- lookAheadM :: Get (Maybe a) -> Get (Maybe a)
- lookAheadE :: Get (Either a b) -> Get (Either a b)
- getByteString :: Int -> Get ByteString

# The Get type

data Get a

Instances

Alternative Get |
Monad Get |
Functor Get |
MonadPlus Get |
Applicative Get |

runCont :: Get a -> forall r. ByteString -> Success a r -> Decoder r

data Decoder a

A decoder produced by running a `Get` monad.

Constructors

Fail !ByteString String | The decoder ran into an error. The decoder either used `fail` or was not provided enough input.
Partial (Maybe ByteString -> Decoder a) | The decoder has consumed the available input and needs more to continue. Provide `Just` if more input is available and `Nothing` otherwise, and you will get a new `Decoder`.
Done !ByteString a | The decoder has successfully finished. Except for the output value you also get the unused input.
BytesRead !Int64 (Int64 -> Decoder a) | The decoder needs to know the current position in the input. Given the number of bytes remaning in the decoder, the outer decoder runner needs to calculate the position and resume the decoding.

Instances

Functor Decoder |
Show a => Show (Decoder a) |

runGetIncremental :: Get a -> Decoder a

Run a `Get` monad. See `Decoder` for what to do next, like providing input, handling decoding errors and to get the output value.

readN :: Int -> (ByteString -> a) -> Get a

Return at least `n` bytes, maybe more. If not enough data is available the computation will escape with `Partial`.

readNWith :: Int -> (Ptr a -> IO a) -> Get a

# Parsing

skip :: Int -> Get ()

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

bytesRead :: Get Int64

Get the total number of bytes read to this point.

get :: Get ByteString

Get the current chunk.

put :: ByteString -> Get ()

Replace the current chunk.

demandInput :: Get ()

Demand more input. If none available, fail.

ensureN :: Int -> Get ()

Ensure that there are at least `n` bytes available. If not, the computation will escape with `Partial`.

# Utility

remaining :: Get Int64

Deprecated: This will force all remaining input, don't use it.

DEPRECATED. Get the number of bytes of remaining input. Note that this is an expensive function to use as in order to calculate how much input remains, all input has to be read and kept in-memory. The decoder keeps the input as a strict bytestring, so you are likely better off by calculating the remaining input in another way.

getBytes :: Int -> Get ByteString

Deprecated: Use `getByteString` instead of `getBytes`.

DEPRECATED. Same as `getByteString`.

isEmpty :: Get Bool

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

lookAhead :: Get a -> Get a

Run the given decoder, but without consuming its input. If the given decoder fails, then so will this function.

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

Run the given decoder, and only consume its input if it returns `Just`. If `Nothing` is returned, the input will be unconsumed. If the given decoder fails, then so will this function.

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

Run the given decoder, and only consume its input if it returns `Right`. If `Left` is returned, the input will be unconsumed. If the given decoder fails, then so will this function.

## ByteStrings

getByteString :: Int -> Get ByteString

An efficient get method for strict ByteStrings. Fails if fewer than `n` bytes are left in the input. If `n <= 0` then the empty string is returned.