Relude.String.Conversion

This module implements type class which allow to have conversion to and from Text, String and ByteString types (including both strict and lazy versions). Usually you need to export Text modules qualified and use pack / unpack functions to convert to/from Text. Now you can just use toText / toString functions.

Convenient type aliases

type LText = Text

Type synonym for Text.

type LByteString = ByteString

Type synonym for ByteString.

Conversion type classes

class ConvertUtf8 a b where

Type class for conversion to utf8 representation of text.

Methods

encodeUtf8 :: a -> b

Encode as utf8 string (usually ByteString).

>>> encodeUtf8 @Text @ByteString "патак"
"\208\191\208\176\209\130\208\176\208\186"

decodeUtf8 :: b -> a

Decode from utf8 string.

>>> decodeUtf8 @Text @ByteString "\208\191\208\176\209\130\208\176\208\186"
"\1087\1072\1090\1072\1082"
>>> putTextLn $ decodeUtf8 @Text @ByteString "\208\191\208\176\209\130\208\176\208\186"
патак

decodeUtf8Strict :: b -> Either UnicodeException a

Decode as utf8 string but returning execption if byte sequence is malformed.

>>> decodeUtf8 @Text @ByteString "\208\208\176\209\130\208\176\208\186"
"\65533\1072\1090\1072\1082"

>>> decodeUtf8Strict @Text @ByteString "\208\208\176\209\130\208\176\208\186"
Left Cannot decode byte '\xd0': ...: Invalid UTF-8 stream

Instances

ConvertUtf8 LText ByteString

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: LText -> ByteString

decodeUtf8 :: ByteString -> LText

decodeUtf8Strict :: ByteString -> Either UnicodeException LText

ConvertUtf8 LText ShortByteString

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: LText -> ShortByteString

decodeUtf8 :: ShortByteString -> LText

decodeUtf8Strict :: ShortByteString -> Either UnicodeException LText

ConvertUtf8 LText LByteString

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: LText -> LByteString

decodeUtf8 :: LByteString -> LText

decodeUtf8Strict :: LByteString -> Either UnicodeException LText

ConvertUtf8 Text ByteString

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: Text -> ByteString

decodeUtf8 :: ByteString -> Text

decodeUtf8Strict :: ByteString -> Either UnicodeException Text

ConvertUtf8 Text ShortByteString

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: Text -> ShortByteString

decodeUtf8 :: ShortByteString -> Text

decodeUtf8Strict :: ShortByteString -> Either UnicodeException Text

ConvertUtf8 Text LByteString

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: Text -> LByteString

decodeUtf8 :: LByteString -> Text

decodeUtf8Strict :: LByteString -> Either UnicodeException Text

ConvertUtf8 String ByteString

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: String -> ByteString

decodeUtf8 :: ByteString -> String

decodeUtf8Strict :: ByteString -> Either UnicodeException String

ConvertUtf8 String ShortByteString

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: String -> ShortByteString

decodeUtf8 :: ShortByteString -> String

decodeUtf8Strict :: ShortByteString -> Either UnicodeException String

ConvertUtf8 String LByteString

Converting String to ByteString might be a slow operation. Consider using lazy bytestring at first place.

Defined in Relude.String.Conversion

Methods

encodeUtf8 :: String -> LByteString

decodeUtf8 :: LByteString -> String

decodeUtf8Strict :: LByteString -> Either UnicodeException String

class ToText a where

Type class for converting other strings to Text.

Methods

toText :: a -> Text

Instances

EncodingError ToText "ByteString" "Text" => ToText ByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toText ("some string" :: ByteString)
...
... Type 'ByteString' doesn't have instance of 'ToText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ByteString -> Text
          decodeUtf8Strict :: ByteString -> Either UnicodeException Text
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toText :: ByteString -> Text

EncodingError ToText "ShortByteString" "Text" => ToText ShortByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toText ("some string" :: ShortByteString)
...
... Type 'ShortByteString' doesn't have instance of 'ToText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ShortByteString -> Text
          decodeUtf8Strict :: ShortByteString -> Either UnicodeException Text
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toText :: ShortByteString -> Text

EncodingError ToText "LByteString" "Text" => ToText LByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toText ("some string" :: LByteString)
...
... Type 'LByteString' doesn't have instance of 'ToText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: LByteString -> Text
          decodeUtf8Strict :: LByteString -> Either UnicodeException Text
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toText :: LByteString -> Text

ToText LText

Defined in Relude.String.Conversion

Methods

toText :: LText -> Text

ToText Text

Defined in Relude.String.Conversion

Methods

toText :: Text -> Text

ToText String

Defined in Relude.String.Conversion

Methods

toText :: String -> Text

class ToLText a where

Type class for converting other strings to Text.

Methods

toLText :: a -> LText

Instances

EncodingError ToLText "ByteString" "LText" => ToLText ByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toLText ("some string" :: ByteString)
...
... Type 'ByteString' doesn't have instance of 'ToLText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ByteString -> LText
          decodeUtf8Strict :: ByteString -> Either UnicodeException LText
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toLText :: ByteString -> LText

EncodingError ToLText "ShortByteString" "LText" => ToLText ShortByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toLText ("some string" :: ShortByteString)
...
... Type 'ShortByteString' doesn't have instance of 'ToLText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ShortByteString -> LText
          decodeUtf8Strict :: ShortByteString -> Either UnicodeException LText
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toLText :: ShortByteString -> LText

EncodingError ToLText "LByteString" "LText" => ToLText LByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toLText ("some string" :: LByteString)
...
... Type 'LByteString' doesn't have instance of 'ToLText'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: LByteString -> LText
          decodeUtf8Strict :: LByteString -> Either UnicodeException LText
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toLText :: LByteString -> LText

ToLText Text

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText

ToLText Text

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText

ToLText String

Defined in Relude.String.Conversion

Methods

toLText :: String -> LText

class ToString a where

Type class for converting other strings to String.

Methods

toString :: a -> String

Instances

EncodingError ToString "ByteString" "String" => ToString ByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toString ("some string" :: ByteString)
...
... Type 'ByteString' doesn't have instance of 'ToString'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ByteString -> String
          decodeUtf8Strict :: ByteString -> Either UnicodeException String
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toString :: ByteString -> String

EncodingError ToString "ShortByteString" "String" => ToString ShortByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toString ("some string" :: ShortByteString)
...
... Type 'ShortByteString' doesn't have instance of 'ToString'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: ShortByteString -> String
          decodeUtf8Strict :: ShortByteString -> Either UnicodeException String
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toString :: ShortByteString -> String

EncodingError ToString "LByteString" "String" => ToString LByteString

⚠️CAUTION⚠️ This instance is for custom error display only.

You should always specify encoding of bytes explicitly.

In case it is used by mistake, the user will see the following:

>>> toString ("some string" :: LByteString)
...
... Type 'LByteString' doesn't have instance of 'ToString'.
      Use 'decodeUtf8' or 'decodeUtf8Strict' to convert from UTF-8:
          decodeUtf8       :: LByteString -> String
          decodeUtf8Strict :: LByteString -> Either UnicodeException String
...

Since: 0.6.0.0

Defined in Relude.String.Conversion

Methods

toString :: LByteString -> String

ToString LText

Defined in Relude.String.Conversion

Methods

toString :: LText -> String

ToString Text

Defined in Relude.String.Conversion

Methods

toString :: Text -> String

ToString String

Defined in Relude.String.Conversion

Methods

toString :: String -> String

class LazyStrict l s | l -> s, s -> l where

Type class for lazy-strict conversions.

Since: 0.1.0

Methods

toLazy :: s -> l

toStrict :: l -> s

Instances

LazyStrict LByteString ByteString

Defined in Relude.String.Conversion

Methods

toLazy :: ByteString -> LByteString

toStrict :: LByteString -> ByteString

LazyStrict LText Text

Defined in Relude.String.Conversion

Methods

toLazy :: Text -> LText

toStrict :: LText -> Text

fromLazy :: LazyStrict l s => l -> s

Alias for toStrict function.

fromStrict :: LazyStrict l s => s -> l

Alias for toLazy function.

Show and read functions

readEither :: Read a => String -> Either Text a

Version of readEither that returns Text in case of the parse error.

>>> readEither @Int "123"
Right 123
>>> readEither @Int "aa"
Left "Prelude.read: no parse"

show :: forall b a. (Show a, IsString b) => a -> b

Generalized version of show. Unlike show this function is polymorphic in its result type. This makes it more convenient to work with data types like Text or ByteString. However, if you pass the result of show to a function that expects polymorphic argument, this can break type inference, so use -XTypeApplications to specify the textual type explicitly.

>>> show (42 :: Int)
"42"
>>> show (42 :: Double)
"42.0"
>>> print (show @Text True)
"True"