+
+ getState :: IO state,
+ -- ^ Return the current state of the codec.
+ --
+ -- Many codecs are not stateful, and in these case the state can be
+ -- represented as '()'. Other codecs maintain a state. For
+ -- example, UTF-16 recognises a BOM (byte-order-mark) character at
+ -- the beginning of the input, and remembers thereafter whether to
+ -- use big-endian or little-endian mode. In this case, the state
+ -- of the codec would include two pieces of information: whether we
+ -- are at the beginning of the stream (the BOM only occurs at the
+ -- beginning), and if not, whether to use the big or little-endian
+ -- encoding.
+
+ setState :: state -> IO()
+ -- restore the state of the codec using the state from a previous
+ -- call to 'getState'.