relude-1.2.0.0: Safe, performant, user-friendly and lightweight Haskell Standard Library
Copyright(c) 2016 Stephen Diehl
(c) 2016-2018 Serokell
(c) 2018-2023 Kowainik
LicenseMIT
MaintainerKowainik <xrom.xkov@gmail.com>
StabilityStable
PortabilityPortable
Safe HaskellSafe
LanguageHaskell2010

Relude.String.Conversion

Description

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.

Synopsis

Convenient type aliases

type LText = Text Source #

Type synonym for Text.

type LByteString = ByteString Source #

Type synonym for ByteString.

Conversion type classes

class ConvertUtf8 a b where Source #

Type class for conversion to utf8 representation of text.

Methods

encodeUtf8 :: a -> b Source #

Encode as utf8 string (usually ByteString).

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

decodeUtf8 :: b -> a Source #

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 Source #

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': Data.Text.Internal.Encoding.decodeUtf8: Invalid UTF-8 stream

Instances

Instances details
ConvertUtf8 LText ByteString Source # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 LText ShortByteString Source #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 LText LByteString Source # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text ByteString Source # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text ShortByteString Source #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text LByteString Source # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String ByteString Source # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String ShortByteString Source #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String LByteString Source #

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

Instance details

Defined in Relude.String.Conversion

class ToText a where Source #

Type class for converting other strings to Text.

Methods

toText :: a -> Text Source #

Instances

Instances details
EncodingError ToText "ByteString" "Text" => ToText ByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToText "ShortByteString" "Text" => ToText ShortByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToText "LByteString" "Text" => ToText LByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

ToText LText Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toText :: LText -> Text Source #

ToText Text Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toText :: Text -> Text Source #

ToText String Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toText :: String -> Text Source #

class ToLText a where Source #

Type class for converting other strings to Text.

Methods

toLText :: a -> LText Source #

Instances

Instances details
EncodingError ToLText "ByteString" "LText" => ToLText ByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToLText "ShortByteString" "LText" => ToLText ShortByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToLText "LByteString" "LText" => ToLText LByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

ToLText Text Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText Source #

ToLText Text Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText Source #

ToLText String Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toLText :: String -> LText Source #

class ToString a where Source #

Type class for converting other strings to String.

Methods

toString :: a -> String Source #

Instances

Instances details
EncodingError ToString "ByteString" "String" => ToString ByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToString "ShortByteString" "String" => ToString ShortByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

EncodingError ToString "LByteString" "String" => ToString LByteString Source #

⚠️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

Instance details

Defined in Relude.String.Conversion

ToString LText Source # 
Instance details

Defined in Relude.String.Conversion

ToString Text Source # 
Instance details

Defined in Relude.String.Conversion

Methods

toString :: Text -> String Source #

ToString String Source # 
Instance details

Defined in Relude.String.Conversion

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

Type class for lazy-strict conversions.

Since: 0.1.0

Methods

toLazy :: s -> l Source #

toStrict :: l -> s Source #

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

Alias for toStrict function.

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

Alias for toLazy function.

Show and read functions

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

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 Source #

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"