|Text codecs for I/O
|data BufferCodec from to state ||Source|
|encode :: Buffer from -> Buffer to -> IO (Buffer from, Buffer to)|
The encode function translates elements of the buffer from
to the buffer to. It should translate as many elements as possible
given the sizes of the buffers, including translating zero elements
if there is either not enough room in to, or from does not
contain a complete multibyte sequence.
encode should raise an exception if, and only if, from
begins with an illegal sequence, or the first element of from
is not representable in the encoding of to. That is, if any
elements can be successfully translated before an error is
encountered, then encode should translate as much as it can
and not throw an exception. This behaviour is used by the IO
library in order to report translation errors at the point they
actually occur, rather than when the buffer is translated.
|close :: IO ()||Resources associated with the encoding may now be released.
The encode function may not be called again after calling
|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
|setState :: state -> IO ()|
A TextEncoding is a specification of a conversion scheme
between sequences of bytes and sequences of Unicode characters.
For example, UTF-8 is an encoding of Unicode characters into a sequence
of bytes. The TextEncoding for UTF-8 is utf8.
|forall dstate estate . TextEncoding|
|The Latin1 (ISO8859-1) encoding. This encoding maps bytes
directly to the first 256 Unicode code points, and is thus not a
complete Unicode encoding. An attempt to write a character greater than
'\255' to a Handle using the latin1 encoding will result in an error.
|The UTF-8 Unicode encoding
The UTF-8 Unicode encoding, with a byte-order-mark (BOM; the byte
sequence 0xEF 0xBB 0xBF). This encoding behaves like utf8,
except that on input, the BOM sequence is ignored at the beginning
of the stream, and on output, the BOM sequence is prepended.
The byte-order-mark is strictly unnecessary in UTF-8, but is
sometimes used to identify the encoding of a file.
|The UTF-16 Unicode encoding (a byte-order-mark should be used to
|The UTF-16 Unicode encoding (litte-endian)
|The UTF-16 Unicode encoding (big-endian)
|The UTF-32 Unicode encoding (a byte-order-mark should be used to
|The UTF-32 Unicode encoding (litte-endian)
|The UTF-32 Unicode encoding (big-endian)
|The Unicode encoding of the current locale
Look up the named Unicode encoding. May fail with
- isDoesNotExistError if the encoding is unknown
The set of known encodings is system-dependent, but includes at least:
- UTF-16, UTF-16BE, UTF-16LE
- UTF-32, UTF-32BE, UTF-32LE
On systems using GNU iconv (e.g. Linux), there is additional
notation for specifying how illegal characters are handled:
- a suffix of //IGNORE, e.g. UTF-8//IGNORE, will cause
all illegal sequences on input to be ignored, and on output
will drop all code points that have no representation in the
- a suffix of //TRANSLIT will choose a replacement character
for illegal sequences or code points.
On Windows, you can access supported code pages with the prefix
CP; for example, "CP1250".
|Produced by Haddock version 2.6.0|