Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Interface for incremental decoding
Synopsis
- data Decoder s a
- liftDecoder :: ST s a -> Decoder s a
- data DeserialiseFailure = DeserialiseFailure ByteOffset String
- deserialiseByteString :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, ByteOffset, a)
- decodeLargeToken :: Word32 -> Decoder s ByteString
- decodeIncremental :: Word32 -> Decoder s a -> Decoder s [a]
- decodeIncremental_ :: Word32 -> Decoder s () -> Decoder s ()
Definition
Decoder
A decoder describes how to match against a single chunk of the input.
For decoders for primitive types, use FromBorsh
instances.
Running decoders
data DeserialiseFailure Source #
Error type for deserialisation.
DeserialiseFailure | |
|
Instances
Exception DeserialiseFailure Source # | |
Show DeserialiseFailure Source # | |
Defined in Codec.Borsh.Incremental.Monad showsPrec :: Int -> DeserialiseFailure -> ShowS # show :: DeserialiseFailure -> String # showList :: [DeserialiseFailure] -> ShowS # | |
Eq DeserialiseFailure Source # | |
Defined in Codec.Borsh.Incremental.Monad (==) :: DeserialiseFailure -> DeserialiseFailure -> Bool # (/=) :: DeserialiseFailure -> DeserialiseFailure -> Bool # |
deserialiseByteString Source #
:: (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
:: 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).
:: Word32 | Number of elements in the sequence to decode |
-> Decoder s a |
|
-> 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.
:: Word32 | Number of elements in the sequence to decode |
-> Decoder s () |
|
-> 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.