| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.Text.Conversions
Description
This module provides a set of typeclasses for safely converting between
textual data. The built-in String type, as well as strict Text
and lazy Text, are safely convertible between one another.
The ByteString type is frequently treated in much the same
manner, but this is unsafe for two reasons:
- Since
ByteStringencodes binary data, it does not specify a particular encoding, so assuming a particular encoding like UTF-8 would be incorrect. - Furthermore, decoding binary data into text given a particular encoding can
fail. Most systems simply use
decodeUtf8and similar functions, which will dangerously throw exceptions when given invalid data.
This module addresses both problems by providing a DecodeText typeclass for
decoding binary data in a way that can fail and by providing a UTF8 wrapper
type for selecting the desired encoding.
Most of the time, you will not need to create your own instances or use the
underlying functions that make the conversion machinery tick. Instead, just
use the convertText method to convert between two textual datatypes or the
decodeConvertText method to perform a conversion that can fail.
Examples:
>>>convertText ("hello" :: String) :: Text"hello">>>decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe TextJust "hello">>>decodeConvertText (UTF8 ("\xc3\x28" :: ByteString)) :: Maybe TextNothing
- newtype Base16 a = Base16 {
- unBase16 :: a
- newtype Base64 a = Base64 {
- unBase64 :: a
- class Functor f => DecodeText f a where
- class FromText a where
- class ToText a where
- newtype UTF8 a = UTF8 {
- unUTF8 :: a
- convertText :: (ToText a, FromText b) => a -> b
- decodeConvertText :: (DecodeText f a, FromText b) => a -> f b
Documentation
Wrapper type used to select a base 16 encoding when encoding or decoding binary data. Safe because base 16 encoding will always produce ASCII output.
Wrapper type used to select a base 64 encoding when encoding or decoding binary data. Safe because base 64 encoding will always produce ASCII output.
class Functor f => DecodeText f a where Source #
A simple typeclass that handles converting arbitrary datatypes to
Text when the operation can fail. If you have a type that
satisfies that requirement, implement this typeclass, but if the operation
cannot fail, use ToText instead.
Minimal complete definition
Methods
decodeText :: a -> f Text Source #
Instances
class FromText a where Source #
A simple typeclass that handles converting Text to arbitrary
datatypes. If you have a type that can be produced from text, implement this
typeclass, not ConvertText. However, you probably do not want to call
fromText directly; call convertText, instead.
Minimal complete definition
Instances
A simple typeclass that handles converting arbitrary datatypes to
Text when the operation cannot fail. If you have a type that
satisfies that requirement, implement this typeclass, but if the operation can
fail, use DecodeText instead.
Minimal complete definition
Simple wrapper type that is used to select a desired encoding when encoding or
decoding text from binary data, such as ByteStrings.
convertText :: (ToText a, FromText b) => a -> b Source #
A function that provides a way to safely convert between arbitrary textual datatypes where the conversion to text cannot fail.
>>>convertText ("hello" :: String) :: Text"hello"
decodeConvertText :: (DecodeText f a, FromText b) => a -> f b Source #
A function that provides a way to safely convert between arbitrary textual
datatypes where the conversion to text can fail, such as decoding binary data
to text. Since binary data can represent text in many different potential
encodings, it is necessary to use a newtype that picks the particular
encoding, like UTF8:
>>>convertText (UTF8 ("hello" :: ByteString)) :: Maybe TextJust "hello"