-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Safe conversions between textual types
--   
--   Safe conversions between textual types
@package text-conversions
@version 0.2.0


-- | This module provides a set of typeclasses for safely converting
--   between textual data. The built-in <a>String</a> type, as well as
--   strict <a>Text</a> and lazy <a>Text</a>, are safely convertible
--   between one another. The <a>ByteString</a> type is frequently treated
--   in much the same manner, but this is unsafe for two reasons:
--   
--   <ul>
--   <li>Since <a>ByteString</a> encodes binary data, it does not specify a
--   particular encoding, so assuming a particular encoding like UTF-8
--   would be incorrect.</li>
--   <li>Furthermore, decoding binary data into text given a particular
--   encoding can fail. Most systems simply use <a>decodeUtf8</a> and
--   similar functions, which will dangerously throw exceptions when given
--   invalid data.</li>
--   </ul>
--   
--   This module addresses both problems by providing a <a>DecodeText</a>
--   typeclass for decoding binary data in a way that can fail and by
--   providing a <a>UTF8</a> 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 <a>convertText</a> method to convert between two
--   textual datatypes or the <a>decodeConvertText</a> method to perform a
--   conversion that can fail.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; convertText ("hello" :: String) :: Text
--   "hello"
--   
--   &gt;&gt;&gt; decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
--   Just "hello"
--   
--   &gt;&gt;&gt; decodeConvertText (UTF8 ("\xc3\x28" :: ByteString)) :: Maybe Text
--   Nothing
--   </pre>
module Data.Text.Conversions

-- | A simple typeclass that handles converting arbitrary datatypes to
--   <a>Text</a> when the operation can fail. If you have a type that
--   satisfies that requirement, implement this typeclass, but if the
--   operation cannot fail, use <a>ToText</a> instead.
class Functor f => DecodeText f a
decodeText :: DecodeText f a => a -> f Text

-- | A simple typeclass that handles converting <a>Text</a> to arbitrary
--   datatypes. If you have a type that can be produced from text,
--   implement this typeclass, <i>not</i> <tt>ConvertText</tt>. However,
--   you probably do not want to call <a>fromText</a> directly; call
--   <a>convertText</a>, instead.
class FromText a
fromText :: FromText a => Text -> a

-- | A simple typeclass that handles converting arbitrary datatypes to
--   <a>Text</a> when the operation cannot fail. If you have a type that
--   satisfies that requirement, implement this typeclass, but if the
--   operation can fail, use <a>DecodeText</a> instead.
class ToText a
toText :: ToText a => a -> Text

-- | Simple wrapper type that is used to select a desired encoding when
--   encoding or decoding text from binary data, such as
--   <a>ByteString</a>s.
newtype UTF8 a
UTF8 :: a -> UTF8 a
[unUTF8] :: UTF8 a -> a

-- | A function that provides a way to <i>safely</i> convert between
--   arbitrary textual datatypes where the conversion to text cannot fail.
--   
--   <pre>
--   &gt;&gt;&gt; convertText ("hello" :: String) :: Text
--   "hello"
--   </pre>
convertText :: (ToText a, FromText b) => a -> b

-- | A function that provides a way to <i>safely</i> 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 <a>UTF8</a>:
--   
--   <pre>
--   &gt;&gt;&gt; convertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
--   Just "hello"
--   </pre>
decodeConvertText :: (DecodeText f a, FromText b) => a -> f b
instance GHC.Base.Functor Data.Text.Conversions.UTF8
instance GHC.Show.Show a => GHC.Show.Show (Data.Text.Conversions.UTF8 a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Conversions.UTF8 a)
instance Data.Text.Conversions.ToText Data.Text.Internal.Text
instance Data.Text.Conversions.FromText Data.Text.Internal.Text
instance Data.Text.Conversions.ToText GHC.Base.String
instance Data.Text.Conversions.FromText GHC.Base.String
instance Data.Text.Conversions.ToText Data.Text.Internal.Lazy.Text
instance Data.Text.Conversions.FromText Data.Text.Internal.Lazy.Text
instance Data.Text.Conversions.DecodeText GHC.Base.Maybe (Data.Text.Conversions.UTF8 Data.ByteString.Internal.ByteString)
instance Data.Text.Conversions.FromText (Data.Text.Conversions.UTF8 Data.ByteString.Internal.ByteString)
instance Data.Text.Conversions.DecodeText GHC.Base.Maybe (Data.Text.Conversions.UTF8 Data.ByteString.Lazy.Internal.ByteString)
instance Data.Text.Conversions.FromText (Data.Text.Conversions.UTF8 Data.ByteString.Lazy.Internal.ByteString)