 | text-0.8.1.0: An efficient packed Unicode text type. | Contents | Index |
|
| Data.Text.Encoding.Error | | Portability | GHC | | Stability | experimental | | Maintainer | bos@serpentine.com, rtomharper@googlemail.com,
duncan@haskell.org |
|
|
|
|
|
| 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 |
|
|
|
|
| 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) | Tried to encode a character that could not be represented
under the given encoding, or ran out of input in mid-encode.
|
|  Instances | |
|
|
| 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 |
| 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 |
| 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.
|
|
| Produced by Haddock version 2.4.2 |