1 -- |
    2 -- Module      : Data.Text.Encoding
    3 -- Copyright   : (c) Tom Harper 2008-2009,
    4 --               (c) Bryan O'Sullivan 2009,
    5 --               (c) Duncan Coutts 2009
    6 --
    7 -- License     : BSD-style
    8 -- Maintainer  : bos@serpentine.com, rtomharper@googlemail.com,
    9 --               duncan@haskell.org
   10 -- Stability   : experimental
   11 -- Portability : portable
   12 --
   13 -- Functions for converting 'Text' values to and from 'ByteString',
   14 -- using several standard encodings.
   15 --
   16 -- To make use of a much larger variety of encodings, use the @text-icu@
   17 -- package.
   18 
   19 module Data.Text.Encoding
   20     (
   21     -- * Decoding ByteStrings to Text
   22       decodeASCII
   23     , decodeUtf8
   24     , decodeUtf16LE
   25     , decodeUtf16BE
   26     , decodeUtf32LE
   27     , decodeUtf32BE
   28     -- ** Controllable error handling
   29     , decodeUtf8With
   30     , decodeUtf16LEWith
   31     , decodeUtf16BEWith
   32     , decodeUtf32LEWith
   33     , decodeUtf32BEWith
   34 
   35     -- * Encoding Text to ByteStrings
   36     , encodeUtf8
   37     , encodeUtf16LE
   38     , encodeUtf16BE
   39     , encodeUtf32LE
   40     , encodeUtf32BE
   41     ) where
   42     
   43 import Data.ByteString (ByteString)
   44 import qualified Data.Text.Fusion as F
   45 import Data.Text.Encoding.Error (OnDecodeError, strictDecode)
   46 import qualified Data.Text.Encoding.Fusion as E
   47 import Data.Text.Internal (Text)
   48 
   49 -- | Decode a 'ByteString' containing 7-bit ASCII encoded text.
   50 decodeASCII :: ByteString -> Text
   51 -- entered 182 timesdecodeASCII bs = F.unstream (E.streamASCII bs)
   52 {-# INLINE decodeASCII #-}
   53 
   54 -- | Decode a 'ByteString' containing UTF-8 encoded text.
   55 decodeUtf8With :: OnDecodeError -> ByteString -> Text
   56 -- entered 200 timesdecodeUtf8With onErr bs = F.unstream (E.streamUtf8 onErr bs)
   57 {-# INLINE decodeUtf8With #-}
   58 
   59 -- | Decode a 'ByteString' containing UTF-8 encoded text.
   60 decodeUtf8 :: ByteString -> Text
   61 -- entered 100 timesdecodeUtf8 = decodeUtf8With strictDecode
   62 {-# INLINE decodeUtf8 #-}
   63 
   64 -- | Encode text using UTF-8 encoding.
   65 encodeUtf8 :: Text -> ByteString
   66 -- entered 200 timesencodeUtf8 txt = E.unstream (E.restreamUtf8 (F.stream txt))
   67 {-# INLINE encodeUtf8 #-}
   68 
   69 -- | Decode text from little endian UTF-16 encoding.
   70 decodeUtf16LEWith :: OnDecodeError -> ByteString -> Text
   71 -- entered 100 timesdecodeUtf16LEWith onErr bs = F.unstream (E.streamUtf16LE onErr bs)
   72 {-# INLINE decodeUtf16LEWith #-}
   73 
   74 -- | Decode text from little endian UTF-16 encoding.
   75 decodeUtf16LE :: ByteString -> Text
   76 -- entered 100 timesdecodeUtf16LE = decodeUtf16LEWith strictDecode
   77 {-# INLINE decodeUtf16LE #-}
   78 
   79 -- | Decode text from big endian UTF-16 encoding.
   80 decodeUtf16BEWith :: OnDecodeError -> ByteString -> Text
   81 -- entered 100 timesdecodeUtf16BEWith onErr bs = F.unstream (E.streamUtf16BE onErr bs)
   82 {-# INLINE decodeUtf16BEWith #-}
   83 
   84 -- | Decode text from big endian UTF-16 encoding.
   85 decodeUtf16BE :: ByteString -> Text
   86 -- entered 100 timesdecodeUtf16BE = decodeUtf16BEWith strictDecode
   87 {-# INLINE decodeUtf16BE #-}
   88 
   89 -- | Encode text using little endian UTF-16 encoding.
   90 encodeUtf16LE :: Text -> ByteString
   91 -- entered 196 timesencodeUtf16LE txt = E.unstream (E.restreamUtf16LE (F.stream txt))
   92 {-# INLINE encodeUtf16LE #-}
   93 
   94 -- | Encode text using big endian UTF-16 encoding.
   95 encodeUtf16BE :: Text -> ByteString
   96 -- entered 197 timesencodeUtf16BE txt = E.unstream (E.restreamUtf16BE (F.stream txt))
   97 {-# INLINE encodeUtf16BE #-}
   98 
   99 -- | Decode text from little endian UTF-32 encoding.
  100 decodeUtf32LEWith :: OnDecodeError -> ByteString -> Text
  101 -- entered 100 timesdecodeUtf32LEWith onErr bs = F.unstream (E.streamUtf32LE onErr bs)
  102 {-# INLINE decodeUtf32LEWith #-}
  103 
  104 -- | Decode text from little endian UTF-32 encoding.
  105 decodeUtf32LE :: ByteString -> Text
  106 -- entered 100 timesdecodeUtf32LE = decodeUtf32LEWith strictDecode
  107 {-# INLINE decodeUtf32LE #-}
  108 
  109 -- | Decode text from big endian UTF-32 encoding.
  110 decodeUtf32BEWith :: OnDecodeError -> ByteString -> Text
  111 -- entered 100 timesdecodeUtf32BEWith onErr bs = F.unstream (E.streamUtf32BE onErr bs)
  112 {-# INLINE decodeUtf32BEWith #-}
  113 
  114 -- | Decode text from big endian UTF-32 encoding.
  115 decodeUtf32BE :: ByteString -> Text
  116 -- entered 100 timesdecodeUtf32BE = decodeUtf32BEWith strictDecode
  117 {-# INLINE decodeUtf32BE #-}
  118 
  119 -- | Encode text using little endian UTF-32 encoding.
  120 encodeUtf32LE :: Text -> ByteString
  121 -- entered 194 timesencodeUtf32LE txt = E.unstream (E.restreamUtf32LE (F.stream txt))
  122 {-# INLINE encodeUtf32LE #-}
  123 
  124 -- | Encode text using big endian UTF-32 encoding.
  125 encodeUtf32BE :: Text -> ByteString
  126 -- entered 194 timesencodeUtf32BE txt = E.unstream (E.restreamUtf32BE (F.stream txt))
  127 {-# INLINE encodeUtf32BE #-}