relude-1.2.1.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 #

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

Instances details
ConvertUtf8 LText ByteString # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 LText ShortByteString #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 LText LByteString # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text ByteString # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text ShortByteString #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 Text LByteString # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String ByteString # 
Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String ShortByteString #

Since: 0.6.0.0

Instance details

Defined in Relude.String.Conversion

ConvertUtf8 String LByteString #

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 #

Type class for converting other strings to Text.

Methods

toText :: a -> Text #

Instances

Instances details
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

Instance details

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

Instance details

Defined in Relude.String.Conversion

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

Instance details

Defined in Relude.String.Conversion

Methods

toText :: LByteString -> Text #

ToText LText # 
Instance details

Defined in Relude.String.Conversion

Methods

toText :: LText -> Text #

ToText Text # 
Instance details

Defined in Relude.String.Conversion

Methods

toText :: Text -> Text #

ToText String # 
Instance details

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

Instances details
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

Instance details

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

Instance details

Defined in Relude.String.Conversion

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

Instance details

Defined in Relude.String.Conversion

Methods

toLText :: LByteString -> LText #

ToLText Text # 
Instance details

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText #

ToLText Text # 
Instance details

Defined in Relude.String.Conversion

Methods

toLText :: Text -> LText #

ToLText String # 
Instance details

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

Instances details
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

Instance details

Defined in Relude.String.Conversion

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

Instance details

Defined in Relude.String.Conversion

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

Instance details

Defined in Relude.String.Conversion

ToString LText # 
Instance details

Defined in Relude.String.Conversion

Methods

toString :: LText -> String #

ToString Text # 
Instance details

Defined in Relude.String.Conversion

Methods

toString :: Text -> String #

ToString String # 
Instance details

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

Instances details
LazyStrict LByteString ByteString # 
Instance details

Defined in Relude.String.Conversion

LazyStrict LText Text # 
Instance details

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"