Relude.String.Reexport

IsString is used in combination with the -XOverloadedStrings language extension to convert the literals to different string types.

For example, if you use the text package, you can say

{-# LANGUAGE OverloadedStrings  #-}

myText = "hello world" :: Text

Internally, the extension will convert this to the equivalent of

myText = fromString @Text ("hello world" :: String)

Note: You can use fromString in normal code as well, but the usual performance/memory efficiency problems with String apply.

String is an alias for a list of characters.

String constants in Haskell are values of type String. That means if you write a string literal like "hello world", it will have the type [Char], which is the same as String.

Note: You can ask the compiler to automatically infer different types with the -XOverloadedStrings language extension, for example "hello world" :: Text. See IsString for more information.

Because String is just a list of characters, you can use normal list functions to do basic string manipulation. See Data.List for operations on lists.

Performance considerations

[Char] is a relatively memory-inefficient type. It is a linked list of boxed word-size characters, internally it looks something like:

╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭────╮
│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ [] │
╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰────╯
        v               v               v
       'a'             'b'             'c'

The String "abc" will use 5*3+1 = 16 (in general 5n+1) words of space in memory.

Furthermore, operations like (++) (string concatenation) are O(n) (in the left argument).

For historical reasons, the base library uses String in a lot of places for the conceptual simplicity, but library code dealing with user-data should use the text package for Unicode text, or the the bytestring package for binary data.

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

>>> readMaybe "123" :: Maybe IntJust 123

>>> readMaybe "hello" :: Maybe IntNothing

equivalent to readsPrec with a precedence of 0.

Parsing of Strings, producing values.

Derived instances of Read make the following assumptions, which derived instances of Text.Show.Show obey:

• If the constructor is defined to be an infix operator, then the derived Read instance will parse only infix applications of the constructor (not the prefix form).

• Associativity is not used to reduce the occurrence of parentheses, although precedence may be.

• If the constructor is defined using record syntax, the derived Read will parse only the record-syntax form, and furthermore, the fields must be given in the same order as the original declaration.

• The derived Read instance allows arbitrary Haskell whitespace between tokens of the input string. Extra parentheses are also allowed.

For example, given the declarations

infixr 5 :^:
data Tree a =  Leaf a  |  Tree a :^: Tree a

the derived instance of Read in Haskell 2010 is equivalent to

instance (Read a) => Read (Tree a) where

        readsPrec d r =  readParen (d > app_prec)
                         (\r -> [(Leaf m,t) |
                                 ("Leaf",s) <- lex r,
                                 (m,t) <- readsPrec (app_prec+1) s]) r

                      ++ readParen (d > up_prec)
                         (\r -> [(u:^:v,w) |
                                 (u,s) <- readsPrec (up_prec+1) r,
                                 (":^:",t) <- lex s,
                                 (v,w) <- readsPrec (up_prec+1) t]) r

          where app_prec = 10
                up_prec = 5

Note that right-associativity of :^: is unused.

The derived instance in GHC is equivalent to

instance (Read a) => Read (Tree a) where

        readPrec = parens $ (prec app_prec $ do
                                 Ident "Leaf" <- lexP
                                 m <- step readPrec
                                 return (Leaf m))

                     +++ (prec up_prec $ do
                                 u <- step readPrec
                                 Symbol ":^:" <- lexP
                                 v <- step readPrec
                                 return (u :^: v))

          where app_prec = 10
                up_prec = 5

        readListPrec = readListPrecDefault

Why do both readsPrec and readPrec exist, and why does GHC opt to implement readPrec in derived Read instances instead of readsPrec? The reason is that readsPrec is based on the ReadS type, and although ReadS is mentioned in the Haskell 2010 Report, it is not a very efficient parser data structure.

readPrec, on the other hand, is based on a much more efficient ReadPrec datatype (a.k.a "new-style parsers"), but its definition relies on the use of the RankNTypes language extension. Therefore, readPrec (and its cousin, readListPrec) are marked as GHC-only. Nevertheless, it is recommended to use readPrec instead of readsPrec whenever possible for the efficiency improvements it brings.

As mentioned above, derived Read instances in GHC will implement readPrec instead of readsPrec. The default implementations of readsPrec (and its cousin, readList) will simply use readPrec under the hood. If you are writing a Read instance by hand, it is recommended to write it like so:

instance Read T where
  readPrec     = ...
  readListPrec = readListPrecDefault

A space efficient, packed, unboxed Unicode text type.

lines takes Text and splits it into the list by lines.

Actual type of this function is the following:

lines :: Text -> [Text]

but it was given a more complex type to provide friendlier compile time errors.

>>> lines ""[]>>> lines "one line"["one line"]>>> lines "line 1\nline 2"["line 1","line 2"]>>> lines ("string line" :: String)...... 'lines' works with 'Text', not 'String'.      Possible fixes:          1. Make sure OverloadedStrings extension is enabled.          2. Apply 'toText' to a single value.          3. Apply 'map toText' to the list value....>>> lines True...... 'lines' works with 'Text'      But given: 'Bool'...

unlines takes list of Text values and joins them with line separator.

Actual type of this function is the following:

unlines :: [Text] -> Text

but it was given a more complex type to provide friendlier compile time errors.

>>> unlines []"">>> unlines ["line 1"]"line 1\n">>> unlines ["first line", "second line"]"first line\nsecond line\n">>> unlines (["line 1", "line 2"] :: [String])...... 'unlines' works with 'Text', not 'String'.      Possible fixes:          1. Make sure OverloadedStrings extension is enabled.          2. Apply 'toText' to a single value.          3. Apply 'map toText' to the list value....>>> unlines [True, False]...... 'unlines' works with 'Text'      But given: 'Bool'...

words takes Text and splits it into the list by words.

Actual type of this function is the following:

words :: Text -> [Text]

but it was given a more complex type to provide friendlier compile time errors.

>>> words ""[]>>> words "one line"["one","line"]>>> words "   >_<   "[">_<"]>>> words ("string words" :: String)...... 'words' works with 'Text', not 'String'.      Possible fixes:          1. Make sure OverloadedStrings extension is enabled.          2. Apply 'toText' to a single value.          3. Apply 'map toText' to the list value....>>> words True...... 'words' works with 'Text'      But given: 'Bool'...

unwords takes list of Text values and joins them with space character.

Actual type of this function is the following:

unwords :: [Text] -> Text

but it was given a more complex type to provide friendlier compile time errors.

>>> unwords []"">>> unwords ["singleWord"]"singleWord">>> unwords ["word", "another"]"word another">>> unwords (["word", "another"] :: [String])...... 'unwords' works with 'Text', not 'String'.      Possible fixes:          1. Make sure OverloadedStrings extension is enabled.          2. Apply 'toText' to a single value.          3. Apply 'map toText' to the list value....>>> unwords [True, False]...... 'unwords' works with 'Text'      But given: 'Bool'...

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.

Decode a ByteString containing UTF-8 encoded text.

Surrogate code points in replacement character returned by OnDecodeError will be automatically remapped to the replacement char U+FFFD.

Replace an invalid input byte with the Unicode replacement character U+FFFD.

Throw a UnicodeException if decoding fails.

A handler for a decoding error.

Function type for handling a coding error. It is supplied with two inputs:

• A String that describes the error.

• The input value that caused the error. If the error arose because the end of input was reached or could not be identified precisely, this value will be Nothing.

If the handler returns a value wrapped with Just, that value will be used in the output as the replacement for the invalid input. If it returns Nothing, no value will be used in the output.

Should the handler need to abort processing, it should use error or throw an exception (preferably a UnicodeException). It may use the description provided to construct a more helpful error report.

An exception type for representing Unicode encoding errors.

A space-efficient representation of a Word8 vector, supporting many efficient operations.

A ByteString contains 8-bit bytes, or by using the operations from Data.ByteString.Char8 it can be interpreted as containing 8-bit characters.

A compact representation of a Word8 vector.

It has a lower memory overhead than a ByteString and does not contribute to heap fragmentation. It can be converted to or from a ByteString (at the cost of copying the string data). It supports very few other operations.

O(n). Convert a ByteString into a ShortByteString.

This makes a copy, so does not retain the input string.

O(n). Convert a ShortByteString into a ByteString.