Fay.Text

Module to be shared between server and client.

This module must be valid for both GHC and Fay.

For GHC this is an alias for Data.Text, for Fay it's an opaque data type represented by JavaScript strings.

Documentation

data Text :: *

A space efficient, packed, unboxed Unicode text type.

Instances

IsList Text

Eq Text

Data Text

This instance preserves data abstraction at the cost of inefficiency. We omit reflection services for the sake of data abstraction.

This instance was created by copying the updated behavior of Data.Set.Set and Data.Map.Map. If you feel a mistake has been made, please feel free to submit improvements.

The original discussion is archived here: could we get a Data instance for Data.Text.Text?

The followup discussion that changed the behavior of Set and Map is archived here: Proposal: Allow gunfold for Data.Map, ...

Ord Text

Read Text

Show Text

IsString Text

Monoid Text

NFData Text

Typeable * Text

type Item Text = Char

Creation and elimination

pack :: String -> Text

O(n) Convert a String into a Text. Subject to fusion. Performs replacement on invalid scalar values.

unpack :: Text -> String

O(n) Convert a Text into a String. Subject to fusion.

fromString :: String -> Text

Have this in scope with the OverloadedStrings and BindableSyntax extensions and Fay will replace all string literals with Text.

empty :: Text

O(1) The empty Text.

Breaking into many substrings

splitOn

Arguments

:: Text

String to split on. If this string is empty, an error will occur.

-> Text

Input text.

-> [Text]

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

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)

(Note: the string s to split on above cannot be empty.)

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

stripSuffix :: Text -> Text -> Maybe Text

O(n) Return the prefix of the second string if its suffix matches the entire first string.

Examples:

stripSuffix "bar" "foobar" == Just "foo"
stripSuffix ""    "baz"    == Just "baz"
stripSuffix "foo" "quux"   == Nothing

This is particularly useful with the ViewPatterns extension to GHC, as follows:

{-# LANGUAGE ViewPatterns #-}
import Data.Text as T

quuxLength :: Text -> Int
quuxLength (stripSuffix "quux" -> Just pre) = T.length pre
quuxLength _                                = -1

Basic interface

cons :: Char -> Text -> Text infixr 5

O(n) Adds a character to the front of a Text. This function is more costly than its List counterpart because it requires copying a new array. Subject to fusion. Performs replacement on invalid scalar values.

snoc :: Text -> Char -> Text

O(n) Adds a character to the end of a Text. This copies the entire array in the process, unless fused. Subject to fusion. Performs replacement on invalid scalar values.

append :: Text -> Text -> Text

O(n) Appends one Text to the other by copying both of them into a new Text. Subject to fusion.

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

O(1) Returns the first character and rest of a Text, or Nothing if empty. Subject to fusion.

head :: Text -> Char

O(1) Returns the first character of a Text, which must be non-empty. Subject to fusion.

init :: Text -> Text

O(1) Returns all but the last character of a Text, which must be non-empty. Subject to fusion.

last :: Text -> Char

O(1) Returns the last character of a Text, which must be non-empty. Subject to fusion.

tail :: Text -> Text

O(1) Returns all characters after the head of a Text, which must be non-empty. Subject to fusion.

null :: Text -> Bool

O(1) Tests whether a Text is empty or not. Subject to fusion.

length :: Text -> Int

O(n) Returns the number of characters in a Text. Subject to fusion.

Special folds

maximum :: Text -> Char

O(n) maximum returns the maximum value from a Text, which must be non-empty. Subject to fusion.

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

O(n) all p t determines whether all characters in the Text t satisify the predicate p. Subject to fusion.

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

O(n) any p t determines whether any character in the Text t satisifes the predicate p. Subject to fusion.

concatMap :: (Char -> Text) -> Text -> Text

O(n) Map a function over a Text that results in a Text, and concatenate the results.

concat :: [Text] -> Text

O(n) Concatenate a list of Texts.

minimum :: Text -> Char

O(n) minimum returns the minimum value from a Text, which must be non-empty. Subject to fusion.

Case conversion

toLower :: Text -> Text

O(n) Convert a string to lower case, using simple case conversion. Subject to fusion.

The result string may be longer than the input string. For instance, "İ" (Latin capital letter I with dot above, U+0130) maps to the sequence "i" (Latin small letter i, U+0069) followed by " ̇" (combining dot above, U+0307).

toUpper :: Text -> Text

O(n) Convert a string to upper case, using simple case conversion. Subject to fusion.

The result string may be longer than the input string. For instance, the German "ß" (eszett, U+00DF) maps to the two-letter sequence "SS".

Transformations

map :: (Char -> Char) -> Text -> Text

O(n) map f t is the Text obtained by applying f to each element of t. Subject to fusion. 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.

intersperse :: Char -> Text -> Text

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

reverse :: Text -> Text

O(n) Reverse the characters of a string. Subject to fusion.

Predicates

isPrefixOf :: Text -> Text -> Bool

O(n) The isPrefixOf function takes two Texts and returns True iff the first is a prefix of the second. Subject to fusion.

Substrings

drop :: Int -> Text -> Text

O(n) drop n, applied to a Text, returns the suffix of the Text after the first n characters, or the empty Text if n is greater than the length of the Text. Subject to fusion.

take :: Int -> Text -> Text

O(n) take n, applied to a Text, returns the prefix of the Text of length n, or the Text itself if n is greater than the length of the Text. Subject to fusion.

Breaking into lines and words

unlines :: [Text] -> Text

O(n) Joins lines, after appending a terminating newline to each.

lines :: Text -> [Text]

O(n) Breaks a Text up into a list of Texts at newline Chars. The resulting strings do not contain newlines.