Data.Text.Encoding.Error

text-1.2.1.3: An efficient packed Unicode text type.

Copyright | (c) Bryan O'Sullivan 2009
License | BSD-style
Maintainer | bos@serpentine.com
Stability | experimental
Portability | GHC
Safe Haskell | Trustworthy
Language | Haskell98

Data.Text.Encoding.Error

Contents

- Error handling types
- Useful error handling functions

Description

Types and functions for dealing with encoding and decoding errors in Unicode text.

The standard functions for encoding and decoding text are strict, which is to say that they throw exceptions on invalid input. This is often unhelpful on real world input, so alternative functions exist that accept custom handlers for dealing with invalid inputs. These `OnError` handlers are normal Haskell functions. You can use one of the presupplied functions in this module, or you can write a custom handler of your own.

Synopsis

- data UnicodeException
  - = DecodeError String (Maybe Word8)
  - | EncodeError String (Maybe Char)
- type OnError a b = String -> Maybe a -> Maybe b
- type OnDecodeError = OnError Word8 Char
- type OnEncodeError = OnError Char Word8
- lenientDecode :: OnDecodeError
- strictDecode :: OnDecodeError
- strictEncode :: OnEncodeError
- ignore :: OnError a b
- replace :: b -> OnError a b

# Error handling types

data UnicodeException

An exception type for representing Unicode encoding errors.

Constructors

DecodeError String (Maybe Word8) | Could not decode a byte sequence because it was invalid under the given encoding, or ran out of input in mid-decode.
EncodeError String (Maybe Char) | Deprecated: This constructor is never used, and will be removed. Tried to encode a character that could not be represented under the given encoding, or ran out of input in mid-encode.

Instances

Eq UnicodeException |
Show UnicodeException |
Exception UnicodeException |
NFData UnicodeException |

type OnError a b = String -> Maybe a -> Maybe b

Function type for handling a coding error. It is supplied with two inputs:

- A `String` that describes the error.
- The input value that caused the error. If the error arose because the end of input was reached or could not be identified precisely, this value will be `Nothing`.

If the handler returns a value wrapped with `Just`, that value will be used in the output as the replacement for the invalid input. If it returns `Nothing`, no value will be used in the output.

Should the handler need to abort processing, it should use `error` or `throw` an exception (preferably a `UnicodeException`). It may use the description provided to construct a more helpful error report.

type OnDecodeError = OnError Word8 Char

A handler for a decoding error.

type OnEncodeError = OnError Char Word8

Deprecated: This exception is never used in practice, and will be removed.

A handler for an encoding error.

# Useful error handling functions

lenientDecode :: OnDecodeError

Replace an invalid input byte with the Unicode replacement character U+FFFD.

strictDecode :: OnDecodeError

Throw a `UnicodeException` if decoding fails.

strictEncode :: OnEncodeError

Deprecated: This function always throws an exception, and will be removed.

Throw a `UnicodeException` if encoding fails.

ignore :: OnError a b

Ignore an invalid input, substituting nothing in the output.

replace :: b -> OnError a b

Replace an invalid input with a valid output.