A time and space-efficient implementation of Unicode text using packed Word16 arrays. Suitable for performance critical use, both in terms of large data quantities and high speed.

This module is intended to be imported qualified, to avoid name clashes with Prelude functions, e.g.

 import qualified Data.Text as T

O(n) Convert a string to folded case. This function is mainly useful for performing caseless (also known as case insensitive) string comparisons.

A string x is a caseless match for a string y if and only if:

toCaseFold x == toCaseFold y

The result string may be longer than the input string, and may differ from applying toLower to the input string. For instance, the Armenian small ligature "ﬓ" (men now, U+FB13) is case folded to the sequence "մ" (men, U+0574) followed by "ն" (now, U+0576), while the Greek "µ" (micro sign, U+00B5) is case folded to "μ" (small letter mu, U+03BC) instead of itself.

O(n) Left-justify a string to the given length, using the specified fill character on the right. Subject to fusion. Examples:

 justifyLeft 7 'x' "foo"    == "fooxxxx"
 justifyLeft 3 'x' "foobar" == "foobar"

O(n) Right-justify a string to the given length, using the specified fill character on the left. Examples:

 justifyRight 7 'x' "bar"    == "xxxxbar"
 justifyRight 3 'x' "foobar" == "foobar"

O(n) Center a string to the given length, using the specified fill character on either side. Examples:

 center 8 'x' "HS" = "xxxHSxxx"

O(n) scanl is similar to foldl, but returns a list of successive reduced values from the left. Subject to fusion.

 scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]

Note that

 last (scanl f z xs) == foldl f z xs.

O(n) scanl1 is a variant of scanl that has no starting value argument. Subject to fusion.

 scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]

O(n) scanr is the right-to-left dual of scanl.

 scanr f v == reverse . scanl (flip f) v . reverse

O(n) dropWhileEnd p t returns the prefix remaining after dropping characters that fail the predicate p from the end of t. Subject to fusion. Examples:

 dropWhileEnd (=='.') "foo..." == "foo"

O(n) Remove leading and trailing white space from a string. Equivalent to:

 dropAround isSpace

O(n) Remove leading white space from a string. Equivalent to:

 dropWhile isSpace

O(n) Remove trailing white space from a string. Equivalent to:

 dropWhileEnd isSpace

O(n+m) Find the first instance of needle (which must be non-null) in haystack. The first element of the returned tuple is the prefix of haystack before needle is matched. The second is the remainder of haystack, starting with the match.

Examples:

 break "::" "a::b::c" ==> ("a", "::b::c")
 break "/" "foobar"   ==> ("foobar", "")

Laws:

 append prefix match == haystack
   where (prefix, match) = break needle haystack

If you need to break a string by a substring repeatedly (e.g. you want to break on every instance of a substring), use find instead, as it has lower startup overhead.

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).

O(n+m) Similar to break, but searches from the end of the string.

The first element of the returned tuple is the prefix of haystack up to and including the last match of needle. The second is the remainder of haystack, following the match.

 breakEnd "::" "a::b::c" ==> ("a::b::", "c")

O(m+n) Break a Text into pieces separated by the first Text argument, consuming the delimiter. An empty delimiter is invalid, and will cause an error to be raised.

Examples:

 split "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
 split "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
 split "x"    "x"                == ["",""]

and

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

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).

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

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

O(n) Splits a Text into components of length k. The last element may be shorter than the other chunks, depending on the length of the input. Examples:

 chunksOf 3 "foobarbaz"   == ["foo","bar","baz"]
 chunksOf 4 "haskell.org" == ["hask","ell.","org"]

O(n+m) The isInfixOf function takes two Texts and returns True iff the first is contained, wholly and intact, anywhere within the second.

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).

O(n+m) Find all non-overlapping instances of needle in haystack. The first element of the returned pair is the prefix of haystack prior to any matches of needle. The second is a list of pairs.

The first element of each pair in the list is a span from the beginning of a match to the beginning of the next match, while the second is a span from the beginning of the match to the end of the input.

Examples:

 find "::" ""
 ==> ("", [])
 find "/" "a/b/c/d"
 ==> ("a", [("/b","/b/c/d"), ("/c","/c/d"), ("/d","/d")])

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).

O(n) The partitionBy function takes a predicate and a Text, and returns the pair of Texts with elements which do and do not satisfy the predicate, respectively; i.e.

 partitionBy p t == (filter p t, filter (not . p) t)

If you think of a Text value as an array of Char values (which it is not), you run the risk of writing inefficient code.

An idiom that is common in some languages is to find the numeric offset of a character or substring, then use that number to split or trim the searched string. With a Text value, this approach would require two O(n) operations: one to perform the search, and one to operate from wherever the search ended.

For example, suppose you have a string that you want to split on the substring "::", such as "foo::bar::quux". Instead of searching for the index of "::" and taking the substrings before and after that index, you would instead use find "::".

O(n+m) The count function returns the number of times the query string appears in the given Text. An empty query string is invalid, and will cause an error to be raised.

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).