Community
Modules 50

Data.Text.Lazy.Encoding

License : BSD-style Maintainer : bos@serpentine.com Portability : portable

Functions for converting lazy Text values to and from lazy ByteString, using several standard encodings.

To gain access to a much larger family of encodings, use the text-icu package.

Decoding ByteStrings to Text

All of the single-parameter functions for decoding bytestrings encoded in one of the Unicode Transformation Formats (UTF) operate in a strict mode: each will throw an exception if given invalid input.

Each function has a variant, whose name is suffixed with -With, that gives greater control over the handling of decoding errors. For instance, decodeUtf8 will throw an exception, but decodeUtf8With allows the programmer to determine what to do on a decoding error.

Total Functions

These functions facilitate total decoding and should be preferred over their partial counterparts.

decodeLatin1 :: B.ByteString -> Text

Decode a ByteString containing Latin-1 (aka ISO-8859-1) encoded text.

decodeUtf8Lenient :: B.ByteString -> Text

Decode a lazy ByteString containing UTF-8 encoded text.

Any invalid input bytes will be replaced with the Unicode replacement character U+FFFD.

Catchable failure

decodeUtf8' :: B.ByteString -> Either UnicodeException Text

Decode a ByteString containing UTF-8 encoded text..

If the input contains any invalid UTF-8 data, the relevant exception will be returned, otherwise the decoded text.

Note: this function is not lazy, as it must decode its entire input before it can return a result. If you need lazy (streaming) decoding, use decodeUtf8With in lenient mode.

Controllable error handling

decodeUtf8With :: OnDecodeError -> B.ByteString -> Text

Decode a ByteString containing UTF-8 encoded text.

decodeUtf16LEWith :: OnDecodeError -> B.ByteString -> Text

Decode text from little endian UTF-16 encoding.

decodeUtf16BEWith :: OnDecodeError -> B.ByteString -> Text

Decode text from big endian UTF-16 encoding.

decodeUtf32LEWith :: OnDecodeError -> B.ByteString -> Text

Decode text from little endian UTF-32 encoding.

decodeUtf32BEWith :: OnDecodeError -> B.ByteString -> Text

Decode text from big endian UTF-32 encoding.

Partial Functions

These functions are partial and should only be used with great caution (preferably not at all). See "Data.Text.Lazy.Encoding#g:total" for better solutions.

decodeASCII :: B.ByteString -> Text

Decode a ByteString containing 7-bit ASCII encoded text.

decodeUtf8 :: B.ByteString -> Text

Decode a ByteString containing UTF-8 encoded text that is known to be valid.

If the input contains any invalid UTF-8 data, an exception will be thrown that cannot be caught in pure code. For more control over the handling of invalid data, use decodeUtf8' or decodeUtf8With.

decodeUtf16LE :: B.ByteString -> Text

Decode text from little endian UTF-16 encoding.

If the input contains any invalid little endian UTF-16 data, an exception will be thrown. For more control over the handling of invalid data, use decodeUtf16LEWith.

decodeUtf16BE :: B.ByteString -> Text

Decode text from big endian UTF-16 encoding.

If the input contains any invalid big endian UTF-16 data, an exception will be thrown. For more control over the handling of invalid data, use decodeUtf16BEWith.

decodeUtf32LE :: B.ByteString -> Text

Decode text from little endian UTF-32 encoding.

If the input contains any invalid little endian UTF-32 data, an exception will be thrown. For more control over the handling of invalid data, use decodeUtf32LEWith.

decodeUtf32BE :: B.ByteString -> Text

Decode text from big endian UTF-32 encoding.

If the input contains any invalid big endian UTF-32 data, an exception will be thrown. For more control over the handling of invalid data, use decodeUtf32BEWith.

Encoding Text to ByteStrings

encodeUtf8 :: Text -> B.ByteString

Encode text using UTF-8 encoding.

encodeUtf16LE :: Text -> B.ByteString

Encode text using little endian UTF-16 encoding.

encodeUtf16BE :: Text -> B.ByteString

Encode text using big endian UTF-16 encoding.

encodeUtf32LE :: Text -> B.ByteString

Encode text using little endian UTF-32 encoding.

encodeUtf32BE :: Text -> B.ByteString

Encode text using big endian UTF-32 encoding.

Encoding Text using ByteString Builders

encodeUtf8Builder :: Text -> B.Builder

Encode text to a ByteString Builder using UTF-8 encoding.

encodeUtf8BuilderEscaped :: BP.BoundedPrim Word8 -> Text -> B.Builder

Encode text using UTF-8 encoding and escape the ASCII characters using a BoundedPrim.

Use this function is to implement efficient encoders for text-based formats like JSON or HTML.

Copyright
(c) 2009, 2010 Bryan O'Sullivan
Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 2 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-858b1951-web-1

Metadata snapshot: 0b0724abd14577f7a6c8172d62e3e1c0808feb114d4d379402e17f37e3c7801e

Open the dependency plan · Download the documentation model

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.