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


-- | 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 <a>Text</a> 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
--   <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

-- | 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 :: Type -> Type) a
decodeText :: DecodeText f a => a -> f Text

-- | 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; decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
--   Just "hello"
--   </pre>
decodeConvertText :: (DecodeText f a, FromText b) => a -> f b

-- | 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. The conversion is not partial; it will result in
--   <a>Nothing</a> when a <a>ByteString</a> is provided with data that is
--   not valid in UTF-8.
--   
--   <pre>
--   &gt;&gt;&gt; convertText ("hello" :: Text) :: UTF8 ByteString
--   UTF8 "hello"
--   
--   &gt;&gt;&gt; decodeConvertText (UTF8 ("hello" :: ByteString)) :: Maybe Text
--   Just "hello"
--   
--   &gt;&gt;&gt; decodeConvertText (UTF8 ("invalid \xc3\x28" :: ByteString)) :: Maybe Text
--   Nothing
--   </pre>
newtype UTF8 a
UTF8 :: a -> UTF8 a
[unUTF8] :: UTF8 a -> 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.
newtype Base16 a
Base16 :: a -> Base16 a
[unBase16] :: Base16 a -> 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.
newtype Base64 a
Base64 :: a -> Base64 a
[unBase64] :: Base64 a -> a
instance Data.Text.Conversions.DecodeText GHC.Internal.Maybe.Maybe (Data.Text.Conversions.UTF8 Data.ByteString.Internal.Type.ByteString)
instance Data.Text.Conversions.DecodeText GHC.Internal.Maybe.Maybe (Data.Text.Conversions.UTF8 Data.ByteString.Lazy.Internal.ByteString)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Conversions.Base16 a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Conversions.Base64 a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Conversions.UTF8 a)
instance Data.Text.Conversions.FromText GHC.Internal.Base.String
instance Data.Text.Conversions.FromText (GHC.Internal.Maybe.Maybe (Data.Text.Conversions.Base16 Data.ByteString.Internal.Type.ByteString))
instance Data.Text.Conversions.FromText (GHC.Internal.Maybe.Maybe (Data.Text.Conversions.Base64 Data.ByteString.Internal.Type.ByteString))
instance Data.Text.Conversions.FromText (GHC.Internal.Maybe.Maybe (Data.Text.Conversions.Base16 Data.ByteString.Lazy.Internal.ByteString))
instance Data.Text.Conversions.FromText (GHC.Internal.Maybe.Maybe (Data.Text.Conversions.Base64 Data.ByteString.Lazy.Internal.ByteString))
instance Data.Text.Conversions.FromText Data.Text.Internal.Lazy.Text
instance Data.Text.Conversions.FromText Data.Text.Internal.Text
instance Data.Text.Conversions.FromText (Data.Text.Conversions.UTF8 Data.ByteString.Internal.Type.ByteString)
instance Data.Text.Conversions.FromText (Data.Text.Conversions.UTF8 Data.ByteString.Lazy.Internal.ByteString)
instance GHC.Internal.Base.Functor Data.Text.Conversions.Base16
instance GHC.Internal.Base.Functor Data.Text.Conversions.Base64
instance GHC.Internal.Base.Functor Data.Text.Conversions.UTF8
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Text.Conversions.Base16 a)
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Text.Conversions.Base64 a)
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Text.Conversions.UTF8 a)
instance Data.Text.Conversions.ToText (Data.Text.Conversions.Base16 Data.ByteString.Internal.Type.ByteString)
instance Data.Text.Conversions.ToText (Data.Text.Conversions.Base16 Data.ByteString.Lazy.Internal.ByteString)
instance Data.Text.Conversions.ToText (Data.Text.Conversions.Base64 Data.ByteString.Internal.Type.ByteString)
instance Data.Text.Conversions.ToText (Data.Text.Conversions.Base64 Data.ByteString.Lazy.Internal.ByteString)
instance Data.Text.Conversions.ToText GHC.Internal.Base.String
instance Data.Text.Conversions.ToText Data.Text.Internal.Lazy.Text
instance Data.Text.Conversions.ToText Data.Text.Internal.Text
