text-conversions-0.1.0: Safe conversions between textual types

Safe HaskellNone
LanguageHaskell2010

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 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 automatically convert between two textual datatypes automatically, whatever they may be.

Examples:

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

Synopsis

Documentation

class ConvertText a b where Source

A typeclass that provides a way to safely convert between arbitrary textual datatypes, including conversions that can potentially fail. Do not implement this typeclass directly, implement ToText, FromText, or DecodeText, instead, which this typeclass defers to. Use the convertText function to actually perform conversions.

At a basic level, convertText can convert between textual types, like between String and Text:

>>> convertText ("hello" :: String) :: Text
"hello"

More interestingly, convertText can also convert between binary data and textual data in the form of ByteString. 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 Text
Just "hello"

Note that the result of converting a ByteString is a Maybe Text since the decoding can fail.

Methods

convertText :: a -> b Source

Instances

class Functor f => DecodeText f a where Source

A simple typeclass that handles converting arbitrary datatypes to Text when the operation can fail (the functor in question is expected to be Maybe or Either). If you have a type that satisfies that requirement, implement this typeclass, not ConvertText. However, you probably do not want to call decodeText directly; call convertText, instead.

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.

Methods

fromText :: Text -> a Source

Instances

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

Methods

toText :: a -> Text Source

Instances

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 ByteStrings.

Constructors

UTF8 

Fields

unUTF8 :: a
 

Instances