Antelude.String

Documentation

type String = [Char]

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.

class IsString a where

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.

Methods

fromString :: String -> a

Instances

IsString ByteString

Beware: fromString truncates multi-byte characters to octets. e.g. "枯朶に烏のとまりけり秋の暮" becomes �6k�nh~�Q��n�

Defined in Data.ByteString.Internal.Type

Methods

fromString :: String -> ByteString

IsString ByteString

Beware: fromString truncates multi-byte characters to octets. e.g. "枯朶に烏のとまりけり秋の暮" becomes �6k�nh~�Q��n�

Defined in Data.ByteString.Lazy.Internal

Methods

fromString :: String -> ByteString

IsString Doc

Defined in Text.PrettyPrint.HughesPJ

Methods

fromString :: String -> Doc

IsString a => IsString (Identity a)

Since: base-4.9.0.0

Defined in Data.String

Methods

fromString :: String -> Identity a

a ~ Char => IsString (Seq a)

Since: containers-0.5.7

Defined in Data.Sequence.Internal

Methods

fromString :: String -> Seq a

IsString (Doc a)

Defined in Text.PrettyPrint.Annotated.HughesPJ

Methods

fromString :: String -> Doc a

a ~ Char => IsString [a]

(a ~ Char) context was introduced in 4.9.0.0

Since: base-2.1

Defined in Data.String

Methods

fromString :: String -> [a]

IsString a => IsString (Const a b)

Since: base-4.9.0.0

Defined in Data.String

Methods

fromString :: String -> Const a b

Reexport from String

lines :: String -> [String]

Splits the argument into a list of lines stripped of their terminating \n characters. The \n terminator is optional in a final non-empty line of the argument string.

For example:

>>> lines ""           -- empty input contains no lines
[]
>>> lines "\n"         -- single empty line
[""]
>>> lines "one"        -- single unterminated line
["one"]
>>> lines "one\n"      -- single non-empty line
["one"]
>>> lines "one\n\n"    -- second line is empty
["one",""]
>>> lines "one\ntwo"   -- second line is unterminated
["one","two"]
>>> lines "one\ntwo\n" -- two non-empty lines
["one","two"]

When the argument string is empty, or ends in a \n character, it can be recovered by passing the result of lines to the unlines function. Otherwise, unlines appends the missing terminating \n. This makes unlines . lines idempotent:

(unlines . lines) . (unlines . lines) = (unlines . lines)

Reexport from String

unlines :: [String] -> String

Appends a \n character to each input string, then concatenates the results. Equivalent to foldMap (s -> s ++ "\n").

>>> unlines ["Hello", "World", "!"]
"Hello\nWorld\n!\n"

Note that unlines . lines /= id when the input is not \n-terminated:

>>> unlines . lines $ "foo\nbar"
"foo\nbar\n"

Reexport from String

unwords :: [String] -> String

unwords joins words with separating spaces (U+0020 SPACE).

>>> unwords ["Lorem", "ipsum", "dolor"]
"Lorem ipsum dolor"

unwords is neither left nor right inverse of words:

>>> words (unwords [" "])
[]
>>> unwords (words "foo\nbar")
"foo bar"

Reexport from String

words :: String -> [String]

words breaks a string up into a list of words, which were delimited by white space (as defined by isSpace). This function trims any white spaces at the beginning and at the end.

>>> words "Lorem ipsum\ndolor"
["Lorem","ipsum","dolor"]
>>> words " foo bar "
["foo","bar"]

bytestring :: String -> ByteString

Turn a String into a strict ByteString

bytestringLazy :: String -> ByteStringLazy

Turn a String into a lazy ByteString

contains :: String -> String -> Bool

Given a substring, see if it is within a provided String.

join :: List String -> String

Join a List of Strings together with no additional characters

joinWith :: String -> List String -> String

Join a List of Strings together with a specified character

pad :: Int -> Char -> String -> String

Add a specified number of Chars to the both side

padLeft :: Int -> Char -> String -> String

Add a specified number of Chars to the left side

padRight :: Int -> Char -> String -> String

Add a specified number of Chars to the right side

replace :: String -> String -> String -> String

Given a "replaceable" substring to replace, and a "replacement" substring, replace all instances of the "replaceable" within a String with the "replacement".

split :: String -> String -> List String

Given a substring, separate a String into a List containing all parts between (and not including) the substring.

text :: String -> Text

Turn a String into a strict Text

textLazy :: String -> TextLazy

Turn a String into a lazy Text

trim :: Char -> String -> String

Remove Chars from both sides

trimLeft :: Char -> String -> String

Remove Chars from the left

trimRight :: Char -> String -> String

Remove Chars from the right

unBytestring :: ByteString -> String

Turn a strict ByteString into a String

unBytestringLazy :: ByteStringLazy -> String

Turn a lazy ByteString into a String

unText :: Text -> String

Turn a strict Text into a String

unTextLazy :: TextLazy -> String

Turn a lazy Text into a String