Data.Text.Conversions

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 ByteString encodes 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 decodeUtf8 and 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 Text
Just "hello"
>>> decodeConvertText (UTF8 ("\xc3\x28" :: ByteString)) :: Maybe Text
Nothing

Conversion typeclasses and functions

class FromText a where

A simple typeclass that handles converting Text to arbitrary datatypes. If you have a type that can be produced from text, implement this typeclass. However, you probably do not want to call fromText directly; call convertText, instead.

Methods

fromText :: Text -> a

Instances

FromText String

Defined in Data.Text.Conversions

Methods

fromText :: Text -> String

FromText Text

Defined in Data.Text.Conversions

Methods

fromText :: Text0 -> Text

FromText Text

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Text

FromText (Maybe (Base64 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base64 ByteString)

FromText (Maybe (Base64 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base64 ByteString)

FromText (Maybe (Base16 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base16 ByteString)

FromText (Maybe (Base16 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base16 ByteString)

FromText (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

fromText :: Text -> UTF8 ByteString

FromText (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

fromText :: Text -> UTF8 ByteString

class ToText a where

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.

Methods

toText :: a -> Text

Instances

ToText String

Defined in Data.Text.Conversions

Methods

toText :: String -> Text

ToText Text

Defined in Data.Text.Conversions

Methods

toText :: Text -> Text0

ToText Text

Defined in Data.Text.Conversions

Methods

toText :: Text -> Text

ToText (Base64 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base64 ByteString -> Text

ToText (Base64 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base64 ByteString -> Text

ToText (Base16 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base16 ByteString -> Text

ToText (Base16 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base16 ByteString -> Text

class Functor f => DecodeText f a where

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.

Methods

decodeText :: a -> f Text

Instances

DecodeText Maybe (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

decodeText :: UTF8 ByteString -> Maybe Text

DecodeText Maybe (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

decodeText :: UTF8 ByteString -> Maybe Text

convertText :: (ToText a, FromText b) => a -> b

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

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:

>>> decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
Just "hello"

Encoding newtypes

newtype UTF8 a

Simple wrapper type that is used to select a desired encoding when encoding or decoding text from binary data, such as ByteStrings. The conversion is not partial; it will result in Nothing when a ByteString is provided with data that is not valid in UTF-8.

>>> convertText ("hello" :: Text) :: UTF8 ByteString
UTF8 "hello"
>>> decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
Just "hello"
>>> decodeConvertText (UTF8 ("invalid \xc3\x28" :: ByteString)) :: Maybe Text
Nothing

Constructors

UTF8

Fields

• unUTF8 :: a

Instances

Functor UTF8

Defined in Data.Text.Conversions

Methods

fmap :: (a -> b) -> UTF8 a -> UTF8 b

(<$) :: a -> UTF8 b -> UTF8 a

DecodeText Maybe (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

decodeText :: UTF8 ByteString -> Maybe Text

DecodeText Maybe (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

decodeText :: UTF8 ByteString -> Maybe Text

Eq a => Eq (UTF8 a)

Defined in Data.Text.Conversions

Methods

(==) :: UTF8 a -> UTF8 a -> Bool

(/=) :: UTF8 a -> UTF8 a -> Bool

Show a => Show (UTF8 a)

Defined in Data.Text.Conversions

Methods

showsPrec :: Int -> UTF8 a -> ShowS

show :: UTF8 a -> String

showList :: [UTF8 a] -> ShowS

FromText (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

fromText :: Text -> UTF8 ByteString

FromText (UTF8 ByteString)

Defined in Data.Text.Conversions

Methods

fromText :: Text -> UTF8 ByteString

newtype Base16 a

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.

Constructors

Base16

Fields

• unBase16 :: a

Instances

Functor Base16

Defined in Data.Text.Conversions

Methods

fmap :: (a -> b) -> Base16 a -> Base16 b

(<$) :: a -> Base16 b -> Base16 a

Eq a => Eq (Base16 a)

Defined in Data.Text.Conversions

Methods

(==) :: Base16 a -> Base16 a -> Bool

(/=) :: Base16 a -> Base16 a -> Bool

Show a => Show (Base16 a)

Defined in Data.Text.Conversions

Methods

showsPrec :: Int -> Base16 a -> ShowS

show :: Base16 a -> String

showList :: [Base16 a] -> ShowS

FromText (Maybe (Base16 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base16 ByteString)

FromText (Maybe (Base16 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base16 ByteString)

ToText (Base16 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base16 ByteString -> Text

ToText (Base16 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base16 ByteString -> Text

newtype Base64 a

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.

Constructors

Base64

Fields

• unBase64 :: a

Instances

Functor Base64

Defined in Data.Text.Conversions

Methods

fmap :: (a -> b) -> Base64 a -> Base64 b

(<$) :: a -> Base64 b -> Base64 a

Eq a => Eq (Base64 a)

Defined in Data.Text.Conversions

Methods

(==) :: Base64 a -> Base64 a -> Bool

(/=) :: Base64 a -> Base64 a -> Bool

Show a => Show (Base64 a)

Defined in Data.Text.Conversions

Methods

showsPrec :: Int -> Base64 a -> ShowS

show :: Base64 a -> String

showList :: [Base64 a] -> ShowS

FromText (Maybe (Base64 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base64 ByteString)

FromText (Maybe (Base64 ByteString))

Defined in Data.Text.Conversions

Methods

fromText :: Text -> Maybe (Base64 ByteString)

ToText (Base64 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base64 ByteString -> Text

ToText (Base64 ByteString)

Defined in Data.Text.Conversions

Methods

toText :: Base64 ByteString -> Text