-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | An efficient packed Unicode text type. -- -- An efficient packed, immutable Unicode text type (both strict and -- lazy), with a powerful loop fusion optimization framework. -- -- The Text type represents Unicode character strings, in a time -- and space-efficient manner. This package provides text processing -- capabilities that are optimized for performance critical use, both in -- terms of large data quantities and high speed. -- -- The Text type provides character-encoding, type-safe case -- conversion via whole-string case conversion functions. It also -- provides a range of functions for converting Text values to and -- from ByteStrings, using several standard encodings. -- -- Efficient locale-sensitive support for text IO is also supported. -- -- These modules are intended to be imported qualified, to avoid name -- clashes with Prelude functions, e.g. -- --

--   import qualified Data.Text as T
--

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. type OnError a b = String -> Maybe a -> Maybe b -- | A handler for a decoding error. type OnDecodeError = OnError Word8 Char -- | A handler for an encoding error. type OnEncodeError = OnError Char Word8 -- | Replace an invalid input byte with the Unicode replacement character -- U+FFFD. lenientDecode :: OnDecodeError -- | Throw a UnicodeException if decoding fails. strictDecode :: OnDecodeError -- | Throw a UnicodeException if encoding fails. strictEncode :: OnEncodeError -- | Ignore an invalid input, substituting nothing in the output. ignore :: OnError a b -- | Replace an invalid input with a valid output. replace :: b -> OnError a b instance Typeable UnicodeException instance Exception UnicodeException instance Show UnicodeException -- | Functions for converting Text values to and from -- ByteString, using several standard encodings. -- -- To gain access to a much larger family of encodings, use the -- text-icu package: -- http://hackage.haskell.org/package/text-icu module Data.Text.Encoding -- | Decode a ByteString containing 7-bit ASCII encoded text. decodeASCII :: ByteString -> Text -- | Decode a ByteString containing UTF-8 encoded text. -- -- If the input contains any invalid UTF-8 data, an exception will be -- thrown. For more control over the handling of invalid data, use -- decodeUtf8With. decodeUtf8 :: ByteString -> Text -- | Decode text from little endian UTF-16 encoding. -- -- If the input contains any invalid little endian UTF-16 data, an -- exception will be thrown. For more control over the handling of -- invalid data, use decodeUtf16LEWith. decodeUtf16LE :: ByteString -> Text -- | Decode text from big endian UTF-16 encoding. -- -- If the input contains any invalid big endian UTF-16 data, an exception -- will be thrown. For more control over the handling of invalid data, -- use decodeUtf16BEWith. decodeUtf16BE :: ByteString -> Text -- | Decode text from little endian UTF-32 encoding. -- -- If the input contains any invalid little endian UTF-32 data, an -- exception will be thrown. For more control over the handling of -- invalid data, use decodeUtf32LEWith. decodeUtf32LE :: ByteString -> Text -- | Decode text from big endian UTF-32 encoding. -- -- If the input contains any invalid big endian UTF-32 data, an exception -- will be thrown. For more control over the handling of invalid data, -- use decodeUtf32BEWith. decodeUtf32BE :: ByteString -> Text -- | Decode a ByteString containing UTF-8 encoded text. decodeUtf8With :: OnDecodeError -> ByteString -> Text -- | Decode text from little endian UTF-16 encoding. decodeUtf16LEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from big endian UTF-16 encoding. decodeUtf16BEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from little endian UTF-32 encoding. decodeUtf32LEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from big endian UTF-32 encoding. decodeUtf32BEWith :: OnDecodeError -> ByteString -> Text -- | Encode text using UTF-8 encoding. encodeUtf8 :: Text -> ByteString -- | Encode text using little endian UTF-16 encoding. encodeUtf16LE :: Text -> ByteString -- | Encode text using big endian UTF-16 encoding. encodeUtf16BE :: Text -> ByteString -- | Encode text using little endian UTF-32 encoding. encodeUtf32LE :: Text -> ByteString -- | Encode text using big endian UTF-32 encoding. encodeUtf32BE :: Text -> ByteString -- | Support for using Text data with native code via the Haskell -- foreign function interface. module Data.Text.Foreign -- | A type representing a number of UTF-16 code units. data I16 -- | O(n) Create a new Text from a Ptr Word16 -- by copying the contents of the array. fromPtr :: Ptr Word16 -> I16 -> IO Text -- | O(n) Perform an action on a temporary, mutable copy of a -- Text. The copy is freed as soon as the action returns. useAsPtr :: Text -> (Ptr Word16 -> I16 -> IO a) -> IO a -- | O(n) Make a mutable copy of a Text. asForeignPtr :: Text -> IO (ForeignPtr Word16, I16) -- | O(1) Return the length of a Text in units of -- Word16. This is useful for sizing a target array -- appropriately before using unsafeCopyToPtr. lengthWord16 :: Text -> Int -- | O(n) Copy a Text to an array. The array is assumed to be -- big enough to hold the contents of the entire Text. unsafeCopyToPtr :: Text -> Ptr Word16 -> IO () -- | O(1) Return the suffix of the Text, with n -- Word16 units dropped from its beginning. -- -- If n would cause the Text to begin inside a surrogate -- pair, the beginning of the suffix will be advanced by one additional -- Word16 unit to maintain its validity. dropWord16 :: I16 -> Text -> Text -- | O(1) Return the prefix of the Text of n -- Word16 units in length. -- -- If n would cause the Text to end inside a surrogate -- pair, the end of the prefix will be advanced by one additional -- Word16 unit to maintain its validity. takeWord16 :: I16 -> Text -> Text instance Bounded I16 instance Enum I16 instance Eq I16 instance Integral I16 instance Num I16 instance Ord I16 instance Read I16 instance Real I16 instance Show I16 -- | A time and space-efficient implementation of Unicode text. Suitable -- for performance critical use, both in terms of large data quantities -- and high speed. -- -- Note: Read below the synopsis for important notes on the use of -- this module. -- -- This module is intended to be imported qualified, to avoid -- name clashes with Prelude functions, e.g. -- --

--   import qualified Data.Text as T
--

-- -- To use an extended and very rich family of functions for working with -- Unicode text (including normalization, regular expressions, -- non-standard encodings, text breaking, and locales), see the -- text-icu package: -- http://hackage.haskell.org/package/text-icu module Data.Text -- | A space efficient, packed, unboxed Unicode text type. data Text -- | O(n) Convert a String into a Text. Subject to -- fusion. Performs replacement on invalid scalar values. pack :: String -> Text -- | O(n) Convert a Text into a String. Subject to fusion. unpack :: Text -> String -- | O(1) Convert a character into a Text. Subject to fusion. -- Performs replacement on invalid scalar values. singleton :: Char -> Text -- | O(1) The empty Text. empty :: Text -- | 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. cons :: Char -> Text -> 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. snoc :: Text -> Char -> Text -- | O(n) Appends one Text to the other by copying both of -- them into a new Text. Subject to fusion. append :: Text -> Text -> Text -- | O(1) Returns the first character and rest of a Text, or -- Nothing if empty. Subject to fusion. uncons :: Text -> Maybe (Char, Text) -- | O(1) Returns the first character of a Text, which must -- be non-empty. Subject to fusion. head :: Text -> Char -- | O(1) Returns the last character of a Text, which must be -- non-empty. Subject to fusion. last :: Text -> Char -- | O(1) Returns all characters after the head of a Text, -- which must be non-empty. Subject to fusion. tail :: Text -> Text -- | O(1) Returns all but the last character of a Text, which -- must be non-empty. Subject to fusion. init :: Text -> Text -- | O(1) Tests whether a Text is empty or not. Subject to -- fusion. null :: Text -> Bool -- | O(n) Returns the number of characters in a Text. Subject -- to fusion. length :: Text -> Int -- | O(n) Compare the count of characters in a Text to a -- number. Subject to fusion. -- -- This function gives the same answer as comparing against the result of -- length, but can short circuit if the count of characters is -- greater than the number, and hence be more efficient. compareLength :: Text -> Int -> Ordering -- | 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. map :: (Char -> Char) -> 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. intercalate :: Text -> [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. intersperse :: Char -> Text -> Text -- | O(n) The transpose function transposes the rows and -- columns of its Text argument. Note that this function uses -- pack, unpack, and the list version of transpose, and is -- thus not very efficient. transpose :: [Text] -> [Text] -- | O(n) Reverse the characters of a string. Subject to fusion. reverse :: Text -> Text -- | O(m+n) Replace every occurrence of one substring with another. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). replace :: Text -> Text -> Text -> Text -- | 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. toCaseFold :: Text -> Text -- | O(n) Convert a string to lower case, using simple case -- conversion. 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). toLower :: Text -> Text -- | O(n) Convert a string to upper case, using simple case -- conversion. The result string may be longer than the input string. For -- instance, the German "ß" (eszett, U+00DF) maps to the two-letter -- sequence "SS". toUpper :: Text -> Text -- | O(n) Left-justify a string to the given length, using the -- specified fill character on the right. Subject to fusion. Performs -- replacement on invalid scalar values. -- -- Examples: -- --

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

justifyLeft :: Int -> Char -> Text -> Text -- | O(n) Right-justify a string to the given length, using the -- specified fill character on the left. Performs replacement on invalid -- scalar values. -- -- Examples: -- --

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

justifyRight :: Int -> Char -> Text -> Text -- | O(n) Center a string to the given length, using the specified -- fill character on either side. Performs replacement on invalid scalar -- values. -- -- Examples: -- --

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

center :: Int -> Char -> Text -> Text -- | O(n) foldl, applied to a binary operator, a starting -- value (typically the left-identity of the operator), and a -- Text, reduces the Text using the binary operator, from -- left to right. Subject to fusion. foldl :: (a -> Char -> a) -> a -> Text -> a -- | O(n) A strict version of foldl. Subject to fusion. foldl' :: (a -> Char -> a) -> a -> Text -> a -- | O(n) A variant of foldl that has no starting value -- argument, and thus must be applied to a non-empty Text. Subject -- to fusion. foldl1 :: (Char -> Char -> Char) -> Text -> Char -- | O(n) A strict version of foldl1. Subject to fusion. foldl1' :: (Char -> Char -> Char) -> Text -> Char -- | O(n) foldr, applied to a binary operator, a starting -- value (typically the right-identity of the operator), and a -- Text, reduces the Text using the binary operator, from -- right to left. Subject to fusion. foldr :: (Char -> a -> a) -> a -> Text -> a -- | O(n) A variant of foldr that has no starting value -- argument, and thust must be applied to a non-empty Text. -- Subject to fusion. foldr1 :: (Char -> Char -> Char) -> Text -> Char -- | O(n) Concatenate a list of Texts. concat :: [Text] -> Text -- | O(n) Map a function over a Text that results in a -- Text, and concatenate the results. concatMap :: (Char -> Text) -> Text -> Text -- | O(n) any p t determines whether any -- character in the Text t satisifes the predicate -- p. Subject to fusion. any :: (Char -> Bool) -> Text -> Bool -- | O(n) all p t determines whether all -- characters in the Text t satisify the predicate -- p. Subject to fusion. all :: (Char -> Bool) -> Text -> Bool -- | O(n) maximum returns the maximum value from a -- Text, which must be non-empty. Subject to fusion. maximum :: Text -> Char -- | O(n) minimum returns the minimum value from a -- Text, which must be non-empty. Subject to fusion. minimum :: Text -> Char -- | O(n) scanl is similar to foldl, but returns a -- list of successive reduced values from the left. Subject to fusion. -- Performs replacement on invalid scalar values. -- --

--   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.
--

scanl :: (Char -> Char -> Char) -> Char -> Text -> Text -- | O(n) scanl1 is a variant of scanl that has no -- starting value argument. Subject to fusion. Performs replacement on -- invalid scalar values. -- --

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

scanl1 :: (Char -> Char -> Char) -> Text -> Text -- | O(n) scanr is the right-to-left dual of scanl. -- Performs replacement on invalid scalar values. -- --

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

scanr :: (Char -> Char -> Char) -> Char -> Text -> Text -- | O(n) scanr1 is a variant of scanr that has no -- starting value argument. Subject to fusion. Performs replacement on -- invalid scalar values. scanr1 :: (Char -> Char -> Char) -> Text -> Text -- | O(n) Like a combination of map and foldl'. -- Applies a function to each element of a Text, passing an -- accumulating parameter from left to right, and returns a final -- Text. Performs replacement on invalid scalar values. mapAccumL :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text) -- | The mapAccumR function behaves like a combination of map -- and a strict foldr; it applies a function to each element of a -- Text, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- Text. Performs replacement on invalid scalar values. mapAccumR :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text) -- | O(n*m) replicate n t is a Text -- consisting of the input t repeated n times. replicate :: Int -> Text -> Text -- | O(n), where n is the length of the result. The -- unfoldr function is analogous to the List unfoldr. -- unfoldr builds a Text from a seed value. The function -- takes the element and returns Nothing if it is done producing -- the Text, otherwise Just (a,b). In this case, -- a is the next Char in the string, and b is -- the seed value for further production. Subject to fusion. Performs -- replacement on invalid scalar values. unfoldr :: (a -> Maybe (Char, a)) -> a -> Text -- | O(n) Like unfoldr, unfoldrN builds a Text -- from a seed value. However, the length of the result should be limited -- by the first argument to unfoldrN. This function is more -- efficient than unfoldr when the maximum length of the result is -- known and correct, otherwise its performance is similar to -- unfoldr. Subject to fusion. Performs replacement on invalid -- scalar values. unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> 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. take :: 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. drop :: Int -> Text -> Text -- | O(n) takeWhile, applied to a predicate p and a -- Text, returns the longest prefix (possibly empty) of elements -- that satisfy p. Subject to fusion. takeWhile :: (Char -> Bool) -> Text -> Text -- | O(n) dropWhile p t returns the suffix -- remaining after takeWhile p t. Subject to -- fusion. dropWhile :: (Char -> Bool) -> Text -> Text -- | 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"
--

dropWhileEnd :: (Char -> Bool) -> Text -> Text -- | O(n) dropAround p t returns the -- substring remaining after dropping characters that fail the predicate -- p from both the beginning and end of t. Subject to -- fusion. dropAround :: (Char -> Bool) -> Text -> Text -- | O(n) Remove leading and trailing white space from a string. -- Equivalent to: -- --

--   dropAround isSpace
--

strip :: Text -> Text -- | O(n) Remove leading white space from a string. Equivalent to: -- --

--   dropWhile isSpace
--

stripStart :: Text -> Text -- | O(n) Remove trailing white space from a string. Equivalent to: -- --

--   dropWhileEnd isSpace
--

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

-- -- Laws: -- --

--   append prefix match == haystack
--     where (prefix, match) = breakOn 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 breakOnAll -- instead, as it has lower startup overhead. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). breakOn :: Text -> Text -> (Text, Text) -- | O(n+m) Similar to breakOn, 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. -- --

--   breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
--

breakOnEnd :: Text -> Text -> (Text, Text) -- | O(n) break is like span, but the prefix returned -- is over elements that fail the predicate p. break :: (Char -> Bool) -> Text -> (Text, Text) -- | O(n) span, applied to a predicate p and text -- t, returns a pair whose first element is the longest prefix -- (possibly empty) of t of elements that satisfy p, -- and whose second is the remainder of the list. span :: (Char -> Bool) -> Text -> (Text, Text) -- | O(n) Group characters in a string by equality. group :: Text -> [Text] -- | O(n) Group characters in a string according to a predicate. groupBy :: (Char -> Char -> Bool) -> Text -> [Text] -- | O(n) Return all initial segments of the given Text, -- shortest first. inits :: Text -> [Text] -- | O(n) Return all final segments of the given Text, -- longest first. tails :: Text -> [Text] -- | 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: -- --

--   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)
--

-- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). splitOn :: Text -> Text -> [Text] -- | 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. -- --

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

split :: (Char -> Bool) -> Text -> [Text] -- | 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"]
--

chunksOf :: Int -> Text -> [Text] -- | O(n) Breaks a Text up into a list of Texts at -- newline Chars. The resulting strings do not contain newlines. lines :: Text -> [Text] -- | O(n) Breaks a Text up into a list of words, delimited by -- Chars representing white space. words :: Text -> [Text] -- | O(n) Joins lines, after appending a terminating newline to -- each. unlines :: [Text] -> Text -- | O(n) Joins words using single space characters. unwords :: [Text] -> Text -- | O(n) The isPrefixOf function takes two Texts and -- returns True iff the first is a prefix of the second. Subject -- to fusion. isPrefixOf :: Text -> Text -> Bool -- | O(n) The isSuffixOf function takes two Texts and -- returns True iff the first is a suffix of the second. isSuffixOf :: Text -> Text -> Bool -- | 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). isInfixOf :: Text -> Text -> Bool -- | O(n) Return the suffix of the second string if its prefix -- matches the entire first string. -- -- Examples: -- --

--   stripPrefix "foo" "foobar" == Just "bar"
--   stripPrefix ""    "baz"    == Just "baz"
--   stripPrefix "foo" "quux"   == Nothing
--

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

--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text as T
--   
--   fnordLength :: Text -> Int
--   fnordLength (stripPrefix "fnord" -> Just suf) = T.length suf
--   fnordLength _                                 = -1
--

stripPrefix :: 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
--

stripSuffix :: Text -> Text -> Maybe 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. -- -- If the strings do not have a common prefix or either one is empty, -- this function returns Nothing. -- -- Examples: -- --

--   commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
--   commonPrefixes "veeble" "fetzer"  == Nothing
--   commonPrefixes "" "baz"           == Nothing
--

commonPrefixes :: Text -> Text -> Maybe (Text, Text, Text) -- | O(n) filter, applied to a predicate and a Text, -- returns a Text containing those characters that satisfy the -- predicate. filter :: (Char -> Bool) -> 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: -- --

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

-- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). -- -- The needle parameter may not be empty. breakOnAll :: Text -> Text -> [(Text, Text)] -- | O(n) The find function takes a predicate and a -- Text, and returns the first element matching the predicate, or -- Nothing if there is no such element. find :: (Char -> Bool) -> Text -> Maybe Char -- | O(n) The partition 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. -- --

--   partition p t == (filter p t, filter (not . p) t)
--

partition :: (Char -> Bool) -> Text -> (Text, Text) -- | O(n) Text index (subscript) operator, starting from 0. index :: Text -> Int -> Char -- | O(n) The findIndex function takes a predicate and a -- Text and returns the index of the first element in the -- Text satisfying the predicate. Subject to fusion. findIndex :: (Char -> Bool) -> Text -> Maybe Int -- | 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). count :: Text -> Text -> Int -- | O(n) zip takes two Texts and returns a list of -- corresponding pairs of bytes. If one input Text is short, -- excess elements of the longer Text are discarded. This is -- equivalent to a pair of unpack operations. zip :: Text -> Text -> [(Char, Char)] -- | O(n) zipWith generalises zip by zipping with the -- function given as the first argument, instead of a tupling function. -- Performs replacement on invalid scalar values. zipWith :: (Char -> Char -> Char) -> Text -> Text -> Text instance Data Text instance NFData Text instance IsString Text instance Monoid Text instance Read Text instance Show Text instance Ord Text instance Eq Text -- | Efficient locale-sensitive support for text I/O. -- -- Skip past the synopsis for some important notes on performance and -- portability across different versions of GHC. module Data.Text.IO -- | The readFile function reads a file and returns the contents of -- the file as a string. The entire file is read strictly, as with -- getContents. readFile :: FilePath -> IO Text -- | Write a string to a file. The file is truncated to zero length before -- writing begins. writeFile :: FilePath -> Text -> IO () -- | Write a string the end of a file. appendFile :: FilePath -> Text -> IO () -- | Read the remaining contents of a Handle as a string. The -- Handle is closed once the contents have been read, or if an -- exception is thrown. -- -- Internally, this function reads a chunk at a time from the lower-level -- buffering abstraction, and concatenates the chunks into a single -- string once the entire file has been read. -- -- As a result, it requires approximately twice as much memory as its -- result to construct its result. For files more than a half of -- available RAM in size, this may result in memory exhaustion. hGetContents :: Handle -> IO Text -- | Read a single line from a handle. hGetLine :: Handle -> IO Text -- | Write a string to a handle. hPutStr :: Handle -> Text -> IO () -- | Write a string to a handle, followed by a newline. hPutStrLn :: Handle -> Text -> IO () -- | The interact function takes a function of type Text -> -- Text as its argument. The entire input from the standard input -- device is passed to this function as its argument, and the resulting -- string is output on the standard output device. interact :: (Text -> Text) -> IO () -- | Read all user input on stdin as a single string. getContents :: IO Text -- | Read a single line of user input from stdin. getLine :: IO Text -- | Write a string to stdout. putStr :: Text -> IO () -- | Write a string to stdout, followed by a newline. putStrLn :: Text -> IO () -- | A time and space-efficient implementation of Unicode text using lists -- of packed arrays. -- -- Note: Read below the synopsis for important notes on the use of -- this module. -- -- The representation used by this module is suitable for high -- performance use and for streaming large quantities of data. It -- provides a means to manipulate a large body of text without requiring -- that the entire content be resident in memory. -- -- Some operations, such as concat, append, reverse -- and cons, have better time complexity than their -- Data.Text equivalents, due to the underlying representation -- being a list of chunks. For other operations, lazy Texts are -- usually within a few percent of strict ones, but often with better -- heap usage if used in a streaming fashion. For data larger than -- available memory, or if you have tight memory constraints, this module -- will be the only option. -- -- This module is intended to be imported qualified, to avoid -- name clashes with Prelude functions. eg. -- --

--   import qualified Data.Text.Lazy as L
--

module Data.Text.Lazy data Text -- | O(n) Convert a String into a Text. -- -- Subject to fusion. Performs replacement on invalid scalar values. pack :: String -> Text -- | O(n) Convert a Text into a String. Subject to -- fusion. unpack :: Text -> String -- | O(1) Convert a character into a Text. Subject to fusion. -- Performs replacement on invalid scalar values. singleton :: Char -> Text -- | Smart constructor for Empty. empty :: Text -- | O(c) Convert a list of strict Texts into a lazy -- Text. fromChunks :: [Text] -> Text -- | O(n) Convert a lazy Text into a list of strict -- Texts. toChunks :: Text -> [Text] -- | O(n) Convert a lazy Text into a strict Text. toStrict :: Text -> Text -- | O(c) Convert a strict Text into a lazy Text. fromStrict :: Text -> Text -- | Consume the chunks of a lazy Text with a natural right fold. foldrChunks :: (Text -> a -> a) -> a -> Text -> a -- | Consume the chunks of a lazy Text with a strict, -- tail-recursive, accumulating left fold. foldlChunks :: (a -> Text -> a) -> a -> Text -> a -- | 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. cons :: Char -> Text -> 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. snoc :: Text -> Char -> Text -- | O(n\c)/ Appends one Text to another. Subject to fusion. append :: Text -> Text -> Text -- | O(1) Returns the first character and rest of a Text, or -- Nothing if empty. Subject to fusion. uncons :: Text -> Maybe (Char, Text) -- | O(1) Returns the first character of a Text, which must -- be non-empty. Subject to fusion. head :: Text -> Char -- | O(1) Returns the last character of a Text, which must be -- non-empty. Subject to fusion. last :: Text -> Char -- | O(1) Returns all characters after the head of a Text, -- which must be non-empty. Subject to fusion. tail :: Text -> Text -- | O(1) Returns all but the last character of a Text, which -- must be non-empty. Subject to fusion. init :: Text -> Text -- | O(1) Tests whether a Text is empty or not. Subject to -- fusion. null :: Text -> Bool -- | O(n) Returns the number of characters in a Text. Subject -- to fusion. length :: Text -> Int64 -- | O(n) Compare the count of characters in a Text to a -- number. Subject to fusion. -- -- This function gives the same answer as comparing against the result of -- length, but can short circuit if the count of characters is -- greater than the number, and hence be more efficient. compareLength :: Text -> Int64 -> Ordering -- | 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. map :: (Char -> Char) -> 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. intercalate :: Text -> [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. intersperse :: Char -> Text -> Text -- | O(n) The transpose function transposes the rows and -- columns of its Text argument. Note that this function uses -- pack, unpack, and the list version of transpose, and is -- thus not very efficient. transpose :: [Text] -> [Text] -- | O(n) reverse t returns the elements of -- t in reverse order. reverse :: Text -> Text -- | O(m+n) Replace every occurrence of one substring with another. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). replace :: Text -> Text -> Text -> Text -- | O(n) Convert a string to folded case. This function is mainly -- useful for performing caseless (or 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 bigram -- men now (U+0574 U+0576), while the micro sign (U+00B5) is case folded -- to the Greek small letter letter mu (U+03BC) instead of itself. toCaseFold :: Text -> Text -- | O(n) Convert a string to lower case, using simple case -- conversion. The result string may be longer than the input string. For -- instance, the Latin capital letter I with dot above (U+0130) maps to -- the sequence Latin small letter i (U+0069) followed by combining dot -- above (U+0307). toLower :: Text -> Text -- | O(n) Convert a string to upper case, using simple case -- conversion. The result string may be longer than the input string. For -- instance, the German eszett (U+00DF) maps to the two-letter sequence -- SS. toUpper :: Text -> Text -- | O(n) Left-justify a string to the given length, using the -- specified fill character on the right. Subject to fusion. Performs -- replacement on invalid scalar values. -- -- Examples: -- --

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

justifyLeft :: Int64 -> Char -> Text -> Text -- | O(n) Right-justify a string to the given length, using the -- specified fill character on the left. Performs replacement on invalid -- scalar values. -- -- Examples: -- --

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

justifyRight :: Int64 -> Char -> Text -> Text -- | O(n) Center a string to the given length, using the specified -- fill character on either side. Performs replacement on invalid scalar -- values. -- -- Examples: -- --

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

center :: Int64 -> Char -> Text -> Text -- | O(n) foldl, applied to a binary operator, a starting -- value (typically the left-identity of the operator), and a -- Text, reduces the Text using the binary operator, from -- left to right. Subject to fusion. foldl :: (a -> Char -> a) -> a -> Text -> a -- | O(n) A strict version of foldl. Subject to fusion. foldl' :: (a -> Char -> a) -> a -> Text -> a -- | O(n) A variant of foldl that has no starting value -- argument, and thus must be applied to a non-empty Text. Subject -- to fusion. foldl1 :: (Char -> Char -> Char) -> Text -> Char -- | O(n) A strict version of foldl1. Subject to fusion. foldl1' :: (Char -> Char -> Char) -> Text -> Char -- | O(n) foldr, applied to a binary operator, a starting -- value (typically the right-identity of the operator), and a -- Text, reduces the Text using the binary operator, from -- right to left. Subject to fusion. foldr :: (Char -> a -> a) -> a -> Text -> a -- | O(n) A variant of foldr that has no starting value -- argument, and thust must be applied to a non-empty Text. -- Subject to fusion. foldr1 :: (Char -> Char -> Char) -> Text -> Char -- | O(n) Concatenate a list of Texts. concat :: [Text] -> Text -- | O(n) Map a function over a Text that results in a -- Text, and concatenate the results. concatMap :: (Char -> Text) -> Text -> Text -- | O(n) any p t determines whether any -- character in the Text t satisifes the predicate -- p. Subject to fusion. any :: (Char -> Bool) -> Text -> Bool -- | O(n) all p t determines whether all -- characters in the Text t satisify the predicate -- p. Subject to fusion. all :: (Char -> Bool) -> Text -> Bool -- | O(n) maximum returns the maximum value from a -- Text, which must be non-empty. Subject to fusion. maximum :: Text -> Char -- | O(n) minimum returns the minimum value from a -- Text, which must be non-empty. Subject to fusion. minimum :: Text -> Char -- | O(n) scanl is similar to foldl, but returns a -- list of successive reduced values from the left. Subject to fusion. -- Performs replacement on invalid scalar values. -- --

--   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.
--

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

scanl1 :: (Char -> Char -> Char) -> Text -> Text -- | O(n) scanr is the right-to-left dual of scanl. -- Performs replacement on invalid scalar values. -- --

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

scanr :: (Char -> Char -> Char) -> Char -> Text -> Text -- | O(n) scanr1 is a variant of scanr that has no -- starting value argument. Performs replacement on invalid scalar -- values. scanr1 :: (Char -> Char -> Char) -> Text -> Text -- | O(n) Like a combination of map and foldl'. -- Applies a function to each element of a Text, passing an -- accumulating parameter from left to right, and returns a final -- Text. Performs replacement on invalid scalar values. mapAccumL :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text) -- | The mapAccumR function behaves like a combination of map -- and a strict foldr; it applies a function to each element of a -- Text, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- Text. Performs replacement on invalid scalar values. mapAccumR :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text) -- | O(n*m) replicate n t is a Text -- consisting of the input t repeated n times. replicate :: Int64 -> Text -> Text -- | O(n), where n is the length of the result. The -- unfoldr function is analogous to the List unfoldr. -- unfoldr builds a Text from a seed value. The function -- takes the element and returns Nothing if it is done producing -- the Text, otherwise Just (a,b). In this case, -- a is the next Char in the string, and b is -- the seed value for further production. Performs replacement on invalid -- scalar values. unfoldr :: (a -> Maybe (Char, a)) -> a -> Text -- | O(n) Like unfoldr, unfoldrN builds a Text -- from a seed value. However, the length of the result should be limited -- by the first argument to unfoldrN. This function is more -- efficient than unfoldr when the maximum length of the result is -- known and correct, otherwise its performance is similar to -- unfoldr. Performs replacement on invalid scalar values. unfoldrN :: Int64 -> (a -> Maybe (Char, a)) -> a -> 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. take :: Int64 -> 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. drop :: Int64 -> Text -> Text -- | O(n) takeWhile, applied to a predicate p and a -- Text, returns the longest prefix (possibly empty) of elements -- that satisfy p. Subject to fusion. takeWhile :: (Char -> Bool) -> Text -> Text -- | O(n) dropWhile p t returns the suffix -- remaining after takeWhile p t. Subject to -- fusion. dropWhile :: (Char -> Bool) -> Text -> Text -- | O(n) dropWhileEnd p t returns the -- prefix remaining after dropping characters that fail the predicate -- p from the end of t. Examples: -- --

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

--   dropAround isSpace
--

strip :: Text -> Text -- | O(n) Remove leading white space from a string. Equivalent to: -- --

--   dropWhile isSpace
--

stripStart :: Text -> Text -- | O(n) Remove trailing white space from a string. Equivalent to: -- --

--   dropWhileEnd isSpace
--

stripEnd :: Text -> Text -- | O(n) splitAt n t returns a pair whose first -- element is a prefix of t of length n, and whose -- second is the remainder of the string. It is equivalent to -- (take n t, drop n t). splitAt :: Int64 -> Text -> (Text, Text) -- | O(n) span, applied to a predicate p and text -- t, returns a pair whose first element is the longest prefix -- (possibly empty) of t of elements that satisfy p, -- and whose second is the remainder of the list. span :: (Char -> Bool) -> Text -> (Text, Text) -- | 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: -- --

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

-- -- Laws: -- --

--   append prefix match == haystack
--     where (prefix, match) = breakOn 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. -- -- This function is strict in its first argument, and lazy in its second. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). breakOn :: Text -> Text -> (Text, Text) -- | O(n+m) Similar to breakOn, 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. -- --

--   breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
--

breakOnEnd :: Text -> Text -> (Text, Text) -- | O(n) break is like span, but the prefix returned -- is over elements that fail the predicate p. break :: (Char -> Bool) -> Text -> (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. group :: Text -> [Text] -- | The groupBy function is the non-overloaded version of -- group. groupBy :: (Char -> Char -> Bool) -> Text -> [Text] -- | O(n) Return all initial segments of the given Text, -- shortest first. inits :: Text -> [Text] -- | O(n) Return all final segments of the given Text, -- longest first. tails :: Text -> [Text] -- | 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: -- --

--   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)
--

-- -- This function is strict in its first argument, and lazy in its second. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). splitOn :: Text -> Text -> [Text] -- | 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. -- --

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

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

chunksOf :: Int64 -> Text -> [Text] -- | O(n) Breaks a Text up into a list of Texts at -- newline Chars. The resulting strings do not contain newlines. lines :: Text -> [Text] -- | O(n) Breaks a Text up into a list of words, delimited by -- Chars representing white space. words :: Text -> [Text] -- | O(n) Joins lines, after appending a terminating newline to -- each. unlines :: [Text] -> Text -- | O(n) Joins words using single space characters. unwords :: [Text] -> Text -- | O(n) The isPrefixOf function takes two Texts and -- returns True iff the first is a prefix of the second. Subject -- to fusion. isPrefixOf :: Text -> Text -> Bool -- | O(n) The isSuffixOf function takes two Texts and -- returns True iff the first is a suffix of the second. isSuffixOf :: Text -> Text -> Bool -- | O(n+m) The isInfixOf function takes two Texts and -- returns True iff the first is contained, wholly and intact, -- anywhere within the second. -- -- This function is strict in its first argument, and lazy in its second. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). isInfixOf :: Text -> Text -> Bool -- | O(n) Return the suffix of the second string if its prefix -- matches the entire first string. -- -- Examples: -- --

--   stripPrefix "foo" "foobar" == Just "bar"
--   stripPrefix ""    "baz"    == Just "baz"
--   stripPrefix "foo" "quux"   == Nothing
--

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

--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text.Lazy as T
--   
--   fnordLength :: Text -> Int
--   fnordLength (stripPrefix "fnord" -> Just suf) = T.length suf
--   fnordLength _                                 = -1
--

stripPrefix :: 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.Lazy as T
--   
--   quuxLength :: Text -> Int
--   quuxLength (stripSuffix "quux" -> Just pre) = T.length pre
--   quuxLength _                                = -1
--

--   commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
--   commonPrefixes "veeble" "fetzer"  == Nothing
--   commonPrefixes "" "baz"           == Nothing
--

commonPrefixes :: Text -> Text -> Maybe (Text, Text, Text) -- | O(n) filter, applied to a predicate and a Text, -- returns a Text containing those characters that satisfy the -- predicate. filter :: (Char -> Bool) -> Text -> Text -- | O(n) The find function takes a predicate and a -- Text, and returns the first element in matching the predicate, -- or Nothing if there is no such element. find :: (Char -> Bool) -> Text -> Maybe Char -- | 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 "/" "a/b/c/"
--   ==> [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
--

-- -- This function is strict in its first argument, and lazy in its second. -- -- In (unlikely) bad cases, this function's time complexity degrades -- towards O(n*m). -- -- The needle parameter may not be empty. breakOnAll :: Text -> Text -> [(Text, Text)] -- | O(n) The partition 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. -- --

--   partition p t == (filter p t, filter (not . p) t)
--

partition :: (Char -> Bool) -> Text -> (Text, Text) -- | O(n) Text index (subscript) operator, starting from 0. index :: Text -> Int64 -> Char -- | 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). count :: Text -> Text -> Int64 -- | O(n) zip takes two Texts and returns a list of -- corresponding pairs of bytes. If one input Text is short, -- excess elements of the longer Text are discarded. This is -- equivalent to a pair of unpack operations. zip :: Text -> Text -> [(Char, Char)] -- | O(n) zipWith generalises zip by zipping with the -- function given as the first argument, instead of a tupling function. -- Performs replacement on invalid scalar values. zipWith :: (Char -> Char -> Char) -> Text -> Text -> Text instance Data Text instance NFData Text instance IsString Text instance Monoid Text instance Read Text instance Show Text instance Ord Text instance Eq Text -- | Functions used frequently when reading textual data. module Data.Text.Lazy.Read -- | Read some text. If the read succeeds, return its value and the -- remaining text, otherwise an error message. type Reader a = Text -> Either String (a, Text) -- | Read a decimal integer. The input must begin with at least one decimal -- digit, and is consumed until a non-digit or end of string is reached. -- -- This function does not handle leading sign characters. If you need to -- handle signed input, use signed decimal. -- -- Note: For fixed-width integer types, this function does not -- attempt to detect overflow, so a sufficiently long input may give -- incorrect results. If you are worried about overflow, use -- Integer for your result type. decimal :: Integral a => Reader a -- | Read a hexadecimal integer, consisting of an optional leading -- "0x" followed by at least one decimal digit. Input is -- consumed until a non-hex-digit or end of string is reached. This -- function is case insensitive. -- -- This function does not handle leading sign characters. If you need to -- handle signed input, use signed hexadecimal. -- -- Note: For fixed-width integer types, this function does not -- attempt to detect overflow, so a sufficiently long input may give -- incorrect results. If you are worried about overflow, use -- Integer for your result type. hexadecimal :: Integral a => Reader a -- | Read an optional leading sign character ('-' or '+') -- and apply it to the result of applying the given reader. signed :: Num a => Reader a -> Reader a -- | Read a rational number. -- -- This function accepts an optional leading sign character, followed by -- at least one decimal digit. The syntax similar to that accepted by the -- read function, with the exception that a trailing '.' -- or 'e' not followed by a number is not consumed. -- -- Examples: -- --

--   rational "3"     == Right (3.0, "")
--   rational "3.1"   == Right (3.1, "")
--   rational "3e4"   == Right (30000.0, "")
--   rational "3.1e4" == Right (31000.0, "")
--   rational ".3"    == Left "input does not start with a digit"
--   rational "e3"    == Left "input does not start with a digit"
--

-- -- Examples of differences from read: -- --

--   rational "3.foo" == Right (3.0, ".foo")
--   rational "3e"    == Right (3.0, "e")
--

rational :: RealFloat a => Reader a -- | Read a rational number. -- -- The syntax accepted by this function is the same as for -- rational. -- -- Note: This function is almost ten times faster than -- rational, but is slightly less accurate. -- -- The Double type supports about 16 decimal places of accuracy. -- For 94.2% of numbers, this function and rational give identical -- results, but for the remaining 5.8%, this function loses precision -- around the 15th decimal place. For 0.001% of numbers, this function -- will lose precision at the 13th or 14th decimal place. double :: Reader Double instance Monad Parser -- | Efficient locale-sensitive support for lazy text I/O. -- -- Skip past the synopsis for some important notes on performance and -- portability across different versions of GHC. module Data.Text.Lazy.IO -- | Read a file and return its contents as a string. The file is read -- lazily, as with getContents. readFile :: FilePath -> IO Text -- | Write a string to a file. The file is truncated to zero length before -- writing begins. writeFile :: FilePath -> Text -> IO () -- | Write a string the end of a file. appendFile :: FilePath -> Text -> IO () -- | Lazily read the remaining contents of a Handle. The -- Handle will be closed after the read completes, or on error. hGetContents :: Handle -> IO Text -- | Read a single line from a handle. hGetLine :: Handle -> IO Text -- | Write a string to a handle. hPutStr :: Handle -> Text -> IO () -- | Write a string to a handle, followed by a newline. hPutStrLn :: Handle -> Text -> IO () -- | The interact function takes a function of type Text -> -- Text as its argument. The entire input from the standard input -- device is passed (lazily) to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (Text -> Text) -> IO () -- | Lazily read all user input on stdin as a single string. getContents :: IO Text -- | Read a single line of user input from stdin. getLine :: IO Text -- | Write a string to stdout. putStr :: Text -> IO () -- | Write a string to stdout, followed by a newline. putStrLn :: Text -> IO () -- | Efficient construction of lazy Text values. The principal -- operations on a Builder are singleton, -- fromText, and fromLazyText, which construct new -- builders, and mappend, which concatenates two builders. -- -- To get maximum performance when building lazy Text values -- using a builder, associate mappend calls to the right. For -- example, prefer -- --

--   singleton 'a' `mappend` (singleton 'b' `mappend` singleton 'c')
--

-- -- to -- --

--   singleton 'a' `mappend` singleton 'b' `mappend` singleton 'c'
--

-- -- as the latter associates mappend to the left. module Data.Text.Lazy.Builder -- | A Builder is an efficient way to build lazy Text -- values. There are several functions for constructing builders, but -- only one to inspect them: to extract any data, you have to turn them -- into lazy Text values using toLazyText. -- -- Internally, a builder constructs a lazy Text by filling -- arrays piece by piece. As each buffer is filled, it is 'popped' off, -- to become a new chunk of the resulting lazy Text. All this is -- hidden from the user of the Builder. data Builder -- | O(n). Extract a lazy Text from a Builder with -- a default buffer size. The construction work takes place if and when -- the relevant part of the lazy Text is demanded. toLazyText :: Builder -> Text -- | O(n). Extract a lazy Text from a Builder, -- using the given size for the initial buffer. The construction work -- takes place if and when the relevant part of the lazy Text is -- demanded. -- -- If the initial buffer is too small to hold all data, subsequent -- buffers will be the default buffer size. toLazyTextWith :: Int -> Builder -> Text -- | O(1). A Builder taking a single character, satisfying -- --

toLazyText (singleton c) = singleton
--   c

singleton :: Char -> Builder -- | O(1). A Builder taking a Text, satisfying -- --

toLazyText (fromText t) = fromChunks
--   [t]

fromText :: Text -> Builder -- | O(1). A Builder taking a lazy Text, -- satisfying -- --

```
toLazyText (fromLazyText t) = t
```

fromLazyText :: Text -> Builder -- | O(1). Pop the strict Text we have constructed so far, -- if any, yielding a new chunk in the result lazy Text. flush :: Builder instance Show Builder instance IsString Builder instance Monoid Builder -- | Functions for converting lazy Text values to and from lazy -- ByteString, using several standard encodings. -- -- To gain access to a much larger variety of encodings, use the -- text-icu package: -- http://hackage.haskell.org/package/text-icu module Data.Text.Lazy.Encoding -- | Decode a ByteString containing 7-bit ASCII encoded text. decodeASCII :: ByteString -> Text -- | Decode a ByteString containing UTF-8 encoded text. -- -- If the input contains any invalid UTF-8 data, an exception will be -- thrown. For more control over the handling of invalid data, use -- decodeUtf8With. decodeUtf8 :: ByteString -> Text -- | Decode text from little endian UTF-16 encoding. -- -- If the input contains any invalid little endian UTF-16 data, an -- exception will be thrown. For more control over the handling of -- invalid data, use decodeUtf16LEWith. decodeUtf16LE :: ByteString -> Text -- | Decode text from big endian UTF-16 encoding. -- -- If the input contains any invalid big endian UTF-16 data, an exception -- will be thrown. For more control over the handling of invalid data, -- use decodeUtf16BEWith. decodeUtf16BE :: ByteString -> Text -- | Decode text from little endian UTF-32 encoding. -- -- If the input contains any invalid little endian UTF-32 data, an -- exception will be thrown. For more control over the handling of -- invalid data, use decodeUtf32LEWith. decodeUtf32LE :: ByteString -> Text -- | Decode text from big endian UTF-32 encoding. -- -- If the input contains any invalid big endian UTF-32 data, an exception -- will be thrown. For more control over the handling of invalid data, -- use decodeUtf32BEWith. decodeUtf32BE :: ByteString -> Text -- | Decode a ByteString containing UTF-8 encoded text. decodeUtf8With :: OnDecodeError -> ByteString -> Text -- | Decode text from little endian UTF-16 encoding. decodeUtf16LEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from big endian UTF-16 encoding. decodeUtf16BEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from little endian UTF-32 encoding. decodeUtf32LEWith :: OnDecodeError -> ByteString -> Text -- | Decode text from big endian UTF-32 encoding. decodeUtf32BEWith :: OnDecodeError -> ByteString -> Text encodeUtf8 :: Text -> ByteString -- | Encode text using little endian UTF-16 encoding. encodeUtf16LE :: Text -> ByteString -- | Encode text using big endian UTF-16 encoding. encodeUtf16BE :: Text -> ByteString -- | Encode text using little endian UTF-32 encoding. encodeUtf32LE :: Text -> ByteString -- | Encode text using big endian UTF-32 encoding. encodeUtf32BE :: Text -> ByteString -- | Functions used frequently when reading textual data. module Data.Text.Read -- | Read some text. If the read succeeds, return its value and the -- remaining text, otherwise an error message. type Reader a = Text -> Either String (a, Text) -- | Read a decimal integer. The input must begin with at least one decimal -- digit, and is consumed until a non-digit or end of string is reached. -- -- This function does not handle leading sign characters. If you need to -- handle signed input, use signed decimal. -- -- Note: For fixed-width integer types, this function does not -- attempt to detect overflow, so a sufficiently long input may give -- incorrect results. If you are worried about overflow, use -- Integer for your result type. decimal :: Integral a => Reader a -- | Read a hexadecimal integer, consisting of an optional leading -- "0x" followed by at least one decimal digit. Input is -- consumed until a non-hex-digit or end of string is reached. This -- function is case insensitive. -- -- This function does not handle leading sign characters. If you need to -- handle signed input, use signed hexadecimal. -- -- Note: For fixed-width integer types, this function does not -- attempt to detect overflow, so a sufficiently long input may give -- incorrect results. If you are worried about overflow, use -- Integer for your result type. hexadecimal :: Integral a => Reader a -- | Read an optional leading sign character ('-' or '+') -- and apply it to the result of applying the given reader. signed :: Num a => Reader a -> Reader a -- | Read a rational number. -- -- This function accepts an optional leading sign character, followed by -- at least one decimal digit. The syntax similar to that accepted by the -- read function, with the exception that a trailing '.' -- or 'e' not followed by a number is not consumed. -- -- Examples (with behaviour identical to read): -- --

--   rational "3"     == Right (3.0, "")
--   rational "3.1"   == Right (3.1, "")
--   rational "3e4"   == Right (30000.0, "")
--   rational "3.1e4" == Right (31000.0, "")
--   rational ".3"    == Left "input does not start with a digit"
--   rational "e3"    == Left "input does not start with a digit"
--

-- -- Examples of differences from read: -- --

--   rational "3.foo" == Right (3.0, ".foo")
--   rational "3e"    == Right (3.0, "e")
--