text-conversions-0.3.1.1: Safe conversions between textual types

Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Text.Conversions

Contents

- Conversion typeclasses and functions
- Encoding newtypes

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 `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

Synopsis

- class FromText a where
  - fromText :: Text -> a
- class ToText a where
  - toText :: a -> Text
- class Functor f => DecodeText (f :: Type -> Type) a where
  - decodeText :: a -> f Text
- convertText :: (ToText a, FromText b) => a -> b
- decodeConvertText :: (DecodeText f a, FromText b) => a -> f b
- newtype UTF8 a = UTF8 {
  - unUTF8 :: a
  }
- newtype Base16 a = Base16 {
  - unBase16 :: a
  }
- newtype Base64 a = Base64 {
  - unBase64 :: a
  }

# Conversion typeclasses and functions

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. However, you probably do not want to call `fromText` directly; call `convertText`, instead.

Methods

fromText :: Text -> a Source #

#### Instances

Instances details

FromText Text Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Text Source #
FromText Text Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Text Source #
FromText String Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> String Source #
FromText (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> UTF8 ByteString Source #
FromText (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> UTF8 ByteString Source #
FromText (Maybe (Base16 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base16 ByteString) Source #
FromText (Maybe (Base16 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base16 ByteString) Source #
FromText (Maybe (Base64 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base64 ByteString) Source #
FromText (Maybe (Base64 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base64 ByteString) Source #

class ToText a where Source #

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

#### Instances

Instances details

ToText Text Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Text -> Text Source #
ToText Text Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Text -> Text Source #
ToText String Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: String -> Text Source #
ToText (Base16 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base16 ByteString -> Text Source #
ToText (Base16 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base16 ByteString -> Text Source #
ToText (Base64 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base64 ByteString -> Text Source #
ToText (Base64 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base64 ByteString -> Text Source #

class Functor f => DecodeText (f :: Type -> Type) 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.

Methods

decodeText :: a -> f Text Source #

#### Instances

Instances details

DecodeText Maybe (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods decodeText :: UTF8 ByteString -> Maybe Text Source #
DecodeText Maybe (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods decodeText :: UTF8 ByteString -> Maybe Text Source #

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

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

# Encoding newtypes

newtype UTF8 a Source #

Simple wrapper type that is used to select a desired encoding when encoding or decoding text from binary data, such as `ByteString`s. 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

Instances details

Functor UTF8 Source # |
Instance details Defined in Data.Text.Conversions Methods fmap :: (a -> b) -> UTF8 a -> UTF8 b Source # (<$) :: a -> UTF8 b -> UTF8 a Source #
DecodeText Maybe (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods decodeText :: UTF8 ByteString -> Maybe Text Source #
DecodeText Maybe (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods decodeText :: UTF8 ByteString -> Maybe Text Source #
Show a => Show (UTF8 a) Source # |
Instance details Defined in Data.Text.Conversions Methods showsPrec :: Int -> UTF8 a -> ShowS Source # show :: UTF8 a -> String Source # showList :: [UTF8 a] -> ShowS Source #
Eq a => Eq (UTF8 a) Source # |
Instance details Defined in Data.Text.Conversions Methods (==) :: UTF8 a -> UTF8 a -> Bool Source # (/=) :: UTF8 a -> UTF8 a -> Bool Source #
FromText (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> UTF8 ByteString Source #
FromText (UTF8 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> UTF8 ByteString Source #

newtype Base16 a Source #

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

Instances details

Functor Base16 Source # |
Instance details Defined in Data.Text.Conversions Methods fmap :: (a -> b) -> Base16 a -> Base16 b Source # (<$) :: a -> Base16 b -> Base16 a Source #
Show a => Show (Base16 a) Source # |
Instance details Defined in Data.Text.Conversions Methods showsPrec :: Int -> Base16 a -> ShowS Source # show :: Base16 a -> String Source # showList :: [Base16 a] -> ShowS Source #
Eq a => Eq (Base16 a) Source # |
Instance details Defined in Data.Text.Conversions Methods (==) :: Base16 a -> Base16 a -> Bool Source # (/=) :: Base16 a -> Base16 a -> Bool Source #
FromText (Maybe (Base16 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base16 ByteString) Source #
FromText (Maybe (Base16 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base16 ByteString) Source #
ToText (Base16 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base16 ByteString -> Text Source #
ToText (Base16 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base16 ByteString -> Text Source #

newtype Base64 a Source #

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

Instances details

Functor Base64 Source # |
Instance details Defined in Data.Text.Conversions Methods fmap :: (a -> b) -> Base64 a -> Base64 b Source # (<$) :: a -> Base64 b -> Base64 a Source #
Show a => Show (Base64 a) Source # |
Instance details Defined in Data.Text.Conversions Methods showsPrec :: Int -> Base64 a -> ShowS Source # show :: Base64 a -> String Source # showList :: [Base64 a] -> ShowS Source #
Eq a => Eq (Base64 a) Source # |
Instance details Defined in Data.Text.Conversions Methods (==) :: Base64 a -> Base64 a -> Bool Source # (/=) :: Base64 a -> Base64 a -> Bool Source #
FromText (Maybe (Base64 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base64 ByteString) Source #
FromText (Maybe (Base64 ByteString)) Source # |
Instance details Defined in Data.Text.Conversions Methods fromText :: Text -> Maybe (Base64 ByteString) Source #
ToText (Base64 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base64 ByteString -> Text Source #
ToText (Base64 ByteString) Source # |
Instance details Defined in Data.Text.Conversions Methods toText :: Base64 ByteString -> Text Source #