relude-1.2.2.0: Safe, performant, user-friendly and lightweight Haskell Standard Library

Copyright | (c) 2016 Stephen Diehl (c) 2016-2018 Serokell (c) 2018-2023 Kowainik
License | MIT
Maintainer | Kowainik <xrom.xkov@gmail.com>
Stability | Stable
Portability | Portable
Safe Haskell | Safe
Language | Haskell2010

Relude.String.Conversion

Contents

- Convenient type aliases
- Conversion type classes
- Show and read functions

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

- type LText = Text
- type LByteString = ByteString
- class ConvertUtf8 a b where
  - encodeUtf8 :: a -> b
  - decodeUtf8 :: b -> a
  - decodeUtf8Strict :: b -> Either UnicodeException a
- class ToText a where
  - toText :: a -> Text
- class ToLText a where
  - toLText :: a -> LText
- class ToString a where
  - toString :: a -> String
- class LazyStrict l s | l -> s, s -> l where
  - toLazy :: s -> l
  - toStrict :: l -> s
- fromLazy :: LazyStrict l s => l -> s
- fromStrict :: LazyStrict l s => s -> l
- readEither :: Read a => String -> Either Text a
- show :: forall b a. (Show a, IsString b) => a -> b

# 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 Methods encodeUtf8 :: LText -> ByteString # decodeUtf8 :: ByteString -> LText # decodeUtf8Strict :: ByteString -> Either UnicodeException LText #
ConvertUtf8 LText ShortByteString # | Since: 0.6.0.0
Instance details Defined in Relude.String.Conversion Methods encodeUtf8 :: LText -> ShortByteString # decodeUtf8 :: ShortByteString -> LText # decodeUtf8Strict :: ShortByteString -> Either UnicodeException LText #
ConvertUtf8 LText LByteString # |
Instance details Defined in Relude.String.Conversion Methods encodeUtf8 :: LText -> LByteString # decodeUtf8 :: LByteString -> LText # decodeUtf8Strict :: LByteString -> Either UnicodeException LText #
ConvertUtf8 Text ByteString # |
Instance details 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
Instance details Defined in Relude.String.Conversion Methods encodeUtf8 :: Text -> ShortByteString # decodeUtf8 :: ShortByteString -> Text # decodeUtf8Strict :: ShortByteString -> Either UnicodeException Text #
ConvertUtf8 Text LByteString # |
Instance details Defined in Relude.String.Conversion Methods encodeUtf8 :: Text -> LByteString # decodeUtf8 :: LByteString -> Text # decodeUtf8Strict :: LByteString -> Either UnicodeException Text #
ConvertUtf8 String ByteString # |
Instance details 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
Instance details 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.
Instance details 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

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

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

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

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

Instance details Defined in Relude.String.Conversion Methods toString :: LByteString -> String #
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 Methods toLazy :: ByteString -> LByteString # toStrict :: LByteString -> ByteString #
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"