Z.Data.Text.Extra

Various combinators works on Texts.

Slice manipulation

cons :: Char -> Text -> Text

O(n) cons is analogous to (:) for lists, but of different complexity, as it requires making a copy.

snoc :: Text -> Char -> Text

O(n) Append a char to the end of a text.

uncons :: Text -> Maybe (Char, Text)

O(1) Extract the head and tail of a text, return Nothing if it is empty.

unsnoc :: Text -> Maybe (Text, Char)

O(1) Extract the init and last of a text, return Nothing if text is empty.

headMaybe :: Text -> Maybe Char

O(1) Extract the first char of a text.

tailMayEmpty :: Text -> Text

O(1) Extract the chars after the head of a text.

NOTE: tailMayEmpty return empty text in the case of an empty text.

lastMaybe :: Text -> Maybe Char

O(1) Extract the last char of a text.

initMayEmpty :: Text -> Text

O(1) Extract the chars before of the last one.

NOTE: initMayEmpty return empty text in the case of an empty text.

head :: Text -> Char

O(1) Extract the first char of a text.

Throw EmptyText if text is empty.

tail :: Text -> Text

O(1) Extract the chars after the head of a text.

Throw EmptyText if text is empty.

last :: Text -> Char

O(1) Extract the last char of a text.

Throw EmptyText if text is empty.

init :: Text -> Text

O(1) Extract the chars before of the last one.

Throw EmptyText if text is empty.

inits :: Text -> [Text]

O(n) Return all initial segments of the given text, empty first.

tails :: Text -> [Text]

O(n) Return all final segments of the given text, whole text first.

take :: Int -> Text -> Text

O(1) take n, applied to a text xs, returns the prefix of xs of length n, or xs itself if n > length xs.

drop :: Int -> Text -> Text

O(1) drop n xs returns the suffix of xs after the first n char, or [] if n > length xs.

takeR :: Int -> Text -> Text

O(1) takeR n, applied to a text xs, returns the suffix of xs of length n, or xs itself if n > length xs.

dropR :: Int -> Text -> Text

O(1) dropR n xs returns the prefix of xs before the last n char, or [] if n > length xs.

slice :: Int -> Int -> Text -> Text

O(1) Extract a sub-range text with give start index and length.

This function is a total function just like 'take/drop', index/length exceeds range will be ingored, e.g.

slice 1 3 "hello"   == "ell"
slice -1 -1 "hello" == ""
slice -2 2 "hello"  == ""
slice 2 10 "hello"  == "llo"

This holds for all x y: slice x y vs == drop x . take (x+y) vs

splitAt :: Int -> Text -> (Text, Text)

O(n) splitAt n xs is equivalent to (take n xs, drop n xs).

takeWhile :: (Char -> Bool) -> Text -> Text

O(n) Applied to a predicate p and a text t, returns the longest prefix (possibly empty) of t of elements that satisfy p.

takeWhileR :: (Char -> Bool) -> Text -> Text

O(n) Applied to a predicate p and a text t, returns the longest suffix (possibly empty) of t of elements that satisfy p.

dropWhile :: (Char -> Bool) -> Text -> Text

O(n) Applied to a predicate p and a text vs, returns the suffix (possibly empty) remaining after takeWhile p vs.

dropWhileR :: (Char -> Bool) -> Text -> Text

O(n) Applied to a predicate p and a text vs, returns the prefix (possibly empty) remaining before takeWhileR p vs.

dropAround :: (Char -> Bool) -> Text -> Text

O(n) dropAround f = dropWhile f . dropWhileR f

break :: (Char -> Bool) -> Text -> (Text, Text)

O(n) Split the text into the longest prefix of elements that do not satisfy the predicate and the rest without copying.

span :: (Char -> Bool) -> Text -> (Text, Text)

O(n) Split the text into the longest prefix of elements that satisfy the predicate and the rest without copying.

breakR :: (Char -> Bool) -> Text -> (Text, Text)

breakR behaves like break but from the end of the text.

breakR p == spanR (not.p)

spanR :: (Char -> Bool) -> Text -> (Text, Text)

spanR behaves like span but from the end of the text.

breakOn :: Text -> Text -> (Text, Text)

Break a text on a subtext, returning a pair of the part of the text prior to the match, and the rest of the text, e.g.

break "wor" "hello, world" = ("hello, ", "world")

breakOnAll

Arguments

:: Text

needle to search for

-> Text

haystack in which to search

-> [(Text, Text)]

O(n+m) Find all non-overlapping instances of needle in haystack. Each element of the returned list consists of a pair:

• The entire string prior to the kth match (i.e. the prefix)
• The kth match, followed by the remainder of the string

Examples:

breakOnAll "::" ""
==> []
breakOnAll "" "abc"
==> [("a", "bc"), ("ab", "c"), ("abc", "/")]

The result list is lazy, search is performed when you force the list.

group :: Text -> [Text]

The group function takes a text and returns a list of texts such that the concatenation of the result is equal to the argument. Moreover, each sublist in the result contains only equal elements. For example,

group Mississippi = [M,"i","ss","i","ss","i","pp","i"]

It is a special case of groupBy, which allows the programmer to supply their own equality test.

groupBy :: (Char -> Char -> Bool) -> Text -> [Text]

The groupBy function is the non-overloaded version of group.

stripPrefix :: Text -> Text -> Maybe Text

O(n) The stripPrefix function takes two texts and returns Just the remainder of the second iff the first is its prefix, and otherwise Nothing.

stripSuffix :: Text -> Text -> Maybe Text

O(n) The stripSuffix function takes two texts and returns Just the remainder of the second iff the first is its suffix, and otherwise Nothing.

split :: Char -> Text -> [Text]

O(n) Break a text into pieces separated by the delimiter element consuming the delimiter. I.e.

split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
split 'a'  "aXaXaXa"    == ["","X","X","X",""]
split 'x'  "x"          == ["",""]

and

intercalate [c] . split c == id
split == splitWith . (==)

NOTE, this function behavior different with bytestring's. see #56.

splitWith :: (Char -> Bool) -> Text -> [Text]

O(n) Splits a text into components delimited by separators, where the predicate returns True for a separator char. The resulting components do not contain the separators. Two adjacent separators result in an empty component in the output. eg.

splitWith (=='a') "aabbaca" == ["","","bb","c",""]
splitWith (=='a') []        == [""]

splitOn :: Text -> Text -> [Text]

O(m+n) Break haystack into pieces separated by needle.

Note: An empty needle will essentially split haystack element by element.

Examples:

>>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
["a","b","d","e"]

>>> splitOn "aaa"  "aaaXaaaXaaaXaaa"
["","X","X","X",""]

>>> splitOn "x"  "x"
["",""]

and

intercalate s . splitOn s         == id
splitOn (singleton c)             == split (==c)

isPrefixOf :: Text -> Text -> Bool

The isPrefix function returns True if the first argument is a prefix of the second.

isSuffixOf :: Text -> Text -> Bool

O(n) The isSuffixOf function takes two text and returns True if the first is a suffix of the second.

isInfixOf :: Text -> Text -> Bool

Check whether one text is a subtext of another.

needle isInfixOf haystack === null haystack || indices needle haystake /= [].

commonPrefix :: Text -> Text -> (Text, Text, Text)

O(n) Find the longest non-empty common prefix of two strings and return it, along with the suffixes of each string at which they no longer match. e.g.

>>> commonPrefix "foobar" "fooquux"
("foo","bar","quux")

>>> commonPrefix "veeble" "fetzer"
("","veeble","fetzer")

words :: Text -> [Text]

O(n) Breaks a Bytes up into a list of words, delimited by unicode space.

lines :: Text -> [Text]

O(n) Breaks a text up into a list of lines, delimited by ascii n.

unwords :: [Text] -> Text

O(n) Joins words with ascii space.

unlines :: [Text] -> Text

O(n) Joins lines with ascii n.

NOTE: This functions is different from unlines, it DOES NOT add a trailing n.

padLeft :: Int -> Char -> Text -> Text

Add padding to the left so that the whole text's length is at least n.

padRight :: Int -> Char -> Text -> Text

Add padding to the right so that the whole text's length is at least n.

Transform

reverse :: Text -> Text

O(n) Reverse the characters of a string.

intersperse :: Char -> Text -> Text

O(n) The intersperse function takes a character and places it between the characters of a Text. Performs replacement on invalid scalar values.

intercalate :: Text -> [Text] -> Text

O(n) The intercalate function takes a Text and a list of Texts and concatenates the list after interspersing the first argument between each element of the list.

intercalateElem :: Char -> [Text] -> Text

transpose :: [Text] -> [Text]

The transpose function transposes the rows and columns of its text argument.