add some utf8 decoding convenience functions

- decodeUtf8Either (alias for decodeUtf8')
- decodeUtf8Maybe
- decodeUtf8Lenient ( = decodeUtf8With lenientDecode)

Author: pearcedavis

src/Data/Text/Encoding.hs

@@ -31,9 +31,12 @@ module Data.Text.Encoding
 
     -- ** Catchable failure
     , decodeUtf8'
+    , decodeUtf8Either
+    , decodeUtf8Maybe
 
     -- ** Controllable error handling
     , decodeUtf8With
+    , decodeUtf8Lenient
     , decodeUtf16LEWith
     , decodeUtf16BEWith
     , decodeUtf32LEWith
@@ -64,7 +67,7 @@ import Control.Monad.ST (runST)
 import Data.Bits ((.&.))
 import Data.ByteString as B
 import qualified Data.ByteString.Internal as B
-import Data.Text.Encoding.Error (OnDecodeError, UnicodeException, strictDecode)
+import Data.Text.Encoding.Error (OnDecodeError, UnicodeException, strictDecode, lenientDecode)
 import Data.Text.Internal (Text(..), safe, text)
 import Data.Text.Internal.Functions
 import Data.Text.Internal.Private (runText)
@@ -353,6 +356,27 @@ decodeUtf8' :: ByteString -> Either UnicodeException Text
 decodeUtf8' = unsafeDupablePerformIO . try . evaluate . decodeUtf8With strictDecode
 {-# INLINE decodeUtf8' #-}
 
+-- | Decode a 'ByteString' containing UTF-8 encoded text.
+--
+-- If the input contains any invalid UTF-8 data, the relevant
+-- exception will be returned, otherwise the decoded text.
+decodeUtf8Either :: ByteString -> Either UnicodeException Text
+decodeUtf8Either = decodeUtf8'
+
+-- | Decode a 'ByteString' containing UTF-8 encoded text.
+--
+-- If the input contains any invalid UTF-8 data, 'Nothing' will be
+-- returned, otherwise the decoded text.
+decodeUtf8Maybe :: ByteString -> Maybe Text
+decodeUtf8Maybe = either (const Nothing) Just . decodeUtf8'
+
+-- | Decode a 'ByteString' containing UTF-8 encoded text.
+--
+-- Any invalid input bytes will be replaced with the Unicode replacement
+-- character U+FFFD.
+decodeUtf8Lenient :: ByteString -> Text
+decodeUtf8Lenient = decodeUtf8With lenientDecode
+
 -- | Encode text to a ByteString 'B.Builder' using UTF-8 encoding.
 --
 -- @since 1.1.0.0