text-0.11.3.1: An efficient packed Unicode text type.

Portability | portable
Stability | experimental
Maintainer | bos@serpentine.com, rtomharper@googlemail.com, duncan@haskell.org
Safe Haskell | Trustworthy

Data.Text.Encoding

Contents

- Decoding ByteStrings to Text
  - Catchable failure
  - Controllable error handling
- Encoding Text to ByteStrings

Description

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

To gain access to a much larger family of encodings, use the `text-icu` package: http://hackage.haskell.org/package/text-icu

Synopsis

- decodeASCII :: ByteString -> Text
- decodeLatin1 :: ByteString -> Text
- decodeUtf8 :: ByteString -> Text
- decodeUtf16LE :: ByteString -> Text
- decodeUtf16BE :: ByteString -> Text
- decodeUtf32LE :: ByteString -> Text
- decodeUtf32BE :: ByteString -> Text
- decodeUtf8' :: ByteString -> Either UnicodeException Text
- decodeUtf8With :: OnDecodeError -> ByteString -> Text
- decodeUtf16LEWith :: OnDecodeError -> ByteString -> Text
- decodeUtf16BEWith :: OnDecodeError -> ByteString -> Text
- decodeUtf32LEWith :: OnDecodeError -> ByteString -> Text
- decodeUtf32BEWith :: OnDecodeError -> ByteString -> Text
- encodeUtf8 :: Text -> ByteString
- encodeUtf16LE :: Text -> ByteString
- encodeUtf16BE :: Text -> ByteString
- encodeUtf32LE :: Text -> ByteString
- encodeUtf32BE :: Text -> ByteString

# 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.

decodeASCII :: ByteString -> Text

Deprecated: Use decodeUtf8 instead

Deprecated. Decode a `ByteString` containing 7-bit ASCII encoded text.

This function is deprecated. Use `decodeLatin1` instead.

decodeLatin1 :: ByteString -> Text

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

`decodeLatin1` is semantically equivalent to `Data.Text.pack . Data.ByteString.Char8.unpack`

decodeUtf8 :: 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 :: 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 :: 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 :: 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 :: 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`.

## Catchable failure

decodeUtf8' :: 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.

## Controllable error handling

decodeUtf8With :: OnDecodeError -> ByteString -> Text

Decode a `ByteString` containing UTF-8 encoded text.

decodeUtf16LEWith :: OnDecodeError -> ByteString -> Text

Decode text from little endian UTF-16 encoding.

decodeUtf16BEWith :: OnDecodeError -> ByteString -> Text

Decode text from big endian UTF-16 encoding.

decodeUtf32LEWith :: OnDecodeError -> ByteString -> Text

Decode text from little endian UTF-32 encoding.

decodeUtf32BEWith :: OnDecodeError -> ByteString -> Text

Decode text from big endian UTF-32 encoding.

# Encoding Text to ByteStrings

encodeUtf8 :: Text -> ByteString

Encode text using UTF-8 encoding.

encodeUtf16LE :: Text -> ByteString

Encode text using little endian UTF-16 encoding.

encodeUtf16BE :: Text -> ByteString

Encode text using big endian UTF-16 encoding.

encodeUtf32LE :: Text -> ByteString

Encode text using little endian UTF-32 encoding.

encodeUtf32BE :: Text -> ByteString

Encode text using big endian UTF-32 encoding.