borsh-0.2.0: Implementation of BORSH serialisation
Safe HaskellSafe-Inferred
LanguageHaskell2010

Codec.Borsh.Incremental

Description

Interface for incremental decoding

Synopsis

Definition

data Decoder s a Source #

Decoder

A decoder describes how to match against a single chunk of the input.

For decoders for primitive types, use FromBorsh instances.

Instances

Instances details
MonadFail (Decoder s) Source # 
Instance details

Defined in Codec.Borsh.Incremental.Decoder

Methods

fail :: String -> Decoder s a #

Applicative (Decoder s) Source # 
Instance details

Defined in Codec.Borsh.Incremental.Decoder

Methods

pure :: a -> Decoder s a #

(<*>) :: Decoder s (a -> b) -> Decoder s a -> Decoder s b #

liftA2 :: (a -> b -> c) -> Decoder s a -> Decoder s b -> Decoder s c #

(*>) :: Decoder s a -> Decoder s b -> Decoder s b #

(<*) :: Decoder s a -> Decoder s b -> Decoder s a #

Functor (Decoder s) Source # 
Instance details

Defined in Codec.Borsh.Incremental.Decoder

Methods

fmap :: (a -> b) -> Decoder s a -> Decoder s b #

(<$) :: a -> Decoder s b -> Decoder s a #

Monad (Decoder s) Source # 
Instance details

Defined in Codec.Borsh.Incremental.Decoder

Methods

(>>=) :: Decoder s a -> (a -> Decoder s b) -> Decoder s b #

(>>) :: Decoder s a -> Decoder s b -> Decoder s b #

return :: a -> Decoder s a #

liftDecoder :: ST s a -> Decoder s a Source #

Lift an ST operation into the Decoder monad.

Running decoders

data DeserialiseFailure Source #

Error type for deserialisation.

Constructors

DeserialiseFailure 

Fields

  • ByteOffset

    The position of the decoder when the failure occurred

  • String

    Message explaining the failure

deserialiseByteString Source #

Arguments

:: (forall s. Decoder s a)

Decoder

-> ByteString

Input

-> Either DeserialiseFailure (ByteString, ByteOffset, a)

Left-over input, offset of the left-over input relative to the start, and the result.

Run decoder

Large tokens

decodeLargeToken Source #

Arguments

:: Word32

Number of bytes to decode

-> Decoder s ByteString 

Large token of known length that spans multiple chunks

This is NOT incremental: all chunks will be read into memory before the result is returned. Primarily useful for large types that are not easily split into (valid) chunks, such as UTF8-encoded text (if were wanted to split that, we'd have to split it at UTF8 boundaries).

decodeIncremental Source #

Arguments

:: Word32

Number of elements in the sequence to decode

-> Decoder s a

Decoder to run for the individual elements

-> Decoder s [a] 

Incremental interface

When decoding large objects such as lists, we do not want to bring all required chunks into memory before decoding the list. Instead, we want to decode the list elements as we go. In this case, DecodeIncremental can be used to repeatedly decode a value using decoder for the elements.

NOTE: This interface is incremental in the sense that the input chunks are read one at a time. It is NOT incremental in the generated output.

decodeIncremental_ Source #

Arguments

:: Word32

Number of elements in the sequence to decode

-> Decoder s ()

Decoder to run for the individual elements

-> Decoder s () 

Variation on decoreIncremental, where we do not accumulate results

This is useful for example for datatypes that we can update imperatively (using the ST monad), such as mutable arrays. It could also be used to skip over unused parts of the input.