-- 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 <a>Text</a> 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 <a>Text</a> type provides character-encoding, type-safe case
--   conversion via whole-string case conversion functions. It also
--   provides a range of functions for converting <a>Text</a> values to and
--   from <a>ByteStrings</a>, 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.
--   
--   <pre>
--   import qualified Data.Text as T
--   </pre>
--   
--   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
--   <tt>text-icu</tt> package:
--   <a>http://hackage.haskell.org/package/text-icu</a>
--   
--   —— RELEASE NOTES ——
--   
--   Changes in 0.11.2.0:
--   
--   <ul>
--   <li>String literals are now converted directly from the format in
--   which GHC stores them into <a>Text</a>, without an intermediate
--   transformation through <a>String</a>, and without inlining of
--   conversion code at each site where a string literal is declared.</li>
--   </ul>
@package text
@version 0.11.2.3


-- | Types and functions for dealing with encoding and decoding errors in
--   Unicode text.
--   
--   The standard functions for encoding and decoding text are strict,
--   which is to say that they throw exceptions on invalid input. This is
--   often unhelpful on real world input, so alternative functions exist
--   that accept custom handlers for dealing with invalid inputs. These
--   <a>OnError</a> handlers are normal Haskell functions. You can use one
--   of the presupplied functions in this module, or you can write a custom
--   handler of your own.
module Data.Text.Encoding.Error

-- | An exception type for representing Unicode encoding errors.
data UnicodeException

-- | Could not decode a byte sequence because it was invalid under the
--   given encoding, or ran out of input in mid-decode.
DecodeError :: String -> (Maybe Word8) -> UnicodeException

-- | Tried to encode a character that could not be represented under the
--   given encoding, or ran out of input in mid-encode.
EncodeError :: String -> (Maybe Char) -> UnicodeException

-- | Function type for handling a coding error. It is supplied with two
--   inputs:
--   
--   <ul>
--   <li>A <a>String</a> that describes the error.</li>
--   <li>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 <a>Nothing</a>.</li>
--   </ul>
--   
--   If the handler returns a value wrapped with <a>Just</a>, that value
--   will be used in the output as the replacement for the invalid input.
--   If it returns <a>Nothing</a>, no value will be used in the output.
--   
--   Should the handler need to abort processing, it should use
--   <a>error</a> or <a>throw</a> an exception (preferably a
--   <a>UnicodeException</a>). 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 <a>UnicodeException</a> if decoding fails.
strictDecode :: OnDecodeError

-- | Throw a <a>UnicodeException</a> 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 Eq UnicodeException
instance Exception UnicodeException
instance Show UnicodeException


-- | Packed, unboxed, heap-resident arrays. Suitable for performance
--   critical use, both in terms of large data quantities and high speed.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.Text.Array as A
--   </pre>
--   
--   The names in this module resemble those in the <a>Array</a> family of
--   modules, but are shorter due to the assumption of qualifid naming.
module Data.Text.Array

-- | Immutable array type.
data Array

-- | Mutable array type, for use in the ST monad.
data MArray s

-- | Copy some elements of a mutable array.
copyM :: MArray s -> Int -> MArray s -> Int -> Int -> ST s ()

-- | Copy some elements of an immutable array.
copyI :: MArray s -> Int -> Array -> Int -> Int -> ST s ()

-- | An empty immutable array.
empty :: Array

-- | Compare portions of two arrays for equality. No bounds checking is
--   performed.
equal :: Array -> Int -> Array -> Int -> Int -> Bool

-- | Run an action in the ST monad and return an immutable array of its
--   result.
run :: (forall s. ST s (MArray s)) -> Array

-- | Run an action in the ST monad and return an immutable array of its
--   result paired with whatever else the action returns.
run2 :: (forall s. ST s (MArray s, a)) -> (Array, a)

-- | Convert an immutable array to a list.
toList :: Array -> Int -> Int -> [Word16]

-- | Freeze a mutable array. Do not mutate the <a>MArray</a> afterwards!
unsafeFreeze :: MArray s -> ST s Array

-- | Unchecked read of an immutable array. May return garbage or crash on
--   an out-of-bounds access.
unsafeIndex :: Array -> Int -> Word16

-- | Create an uninitialized mutable array.
new :: Int -> ST s (MArray s)

-- | Unchecked write of a mutable array. May return garbage or crash on an
--   out-of-bounds access.
unsafeWrite :: MArray s -> Int -> Word16 -> ST s ()


-- | A module containing private <a>Text</a> internals. This exposes the
--   <a>Text</a> representation and low level construction functions.
--   Modules which extend the <a>Text</a> system may need to use this
--   module.
--   
--   You should not use this module unless you are determined to monkey
--   with the internals, as the functions here do just about nothing to
--   preserve data invariants. You have been warned!
module Data.Text.Internal

-- | A space efficient, packed, unboxed Unicode text type.
data Text
Text :: {-# UNPACK #-} !Array -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Text

-- | Smart constructor.
text :: Array -> Int -> Int -> Text

-- | Construct a <a>Text</a> without invisibly pinning its byte array in
--   memory if its length has dwindled to zero.
textP :: Array -> Int -> Int -> Text

-- | Map a <a>Char</a> to a <a>Text</a>-safe value.
--   
--   UTF-16 surrogate code points are not included in the set of Unicode
--   scalar values, but are unfortunately admitted as valid <a>Char</a>
--   values by Haskell. They cannot be represented in a <a>Text</a>. This
--   function remaps those code points to the Unicode replacement character
--   "�", and leaves other code points unchanged.
safe :: Char -> Char

-- | <i>O(1)</i> The empty <a>Text</a>.
empty :: Text

-- | Apply a function to the first element of an optional pair.
firstf :: (a -> c) -> Maybe (a, b) -> Maybe (c, b)

-- | A useful <a>show</a>-like function for debugging purposes.
showText :: Text -> String
instance Typeable Text


-- | Functions for converting <a>Text</a> values to and from
--   <a>ByteString</a>, using several standard encodings.
--   
--   To gain access to a much larger family of encodings, use the
--   <tt>text-icu</tt> package:
--   <a>http://hackage.haskell.org/package/text-icu</a>
module Data.Text.Encoding

-- | <i>Deprecated</i>. Decode a <a>ByteString</a> containing 7-bit ASCII
--   encoded text.
--   
--   This function is deprecated. Use <a>decodeUtf8</a> instead.

-- | <i>Deprecated: Use decodeUtf8 instead</i>
decodeASCII :: ByteString -> Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text that is known
--   to be valid.
--   
--   If the input contains any invalid UTF-8 data, an exception will be
--   thrown that cannot be caught in pure code. For more control over the
--   handling of invalid data, use <a>decodeUtf8'</a> or
--   <a>decodeUtf8With</a>.
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 <a>decodeUtf16LEWith</a>.
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 <a>decodeUtf16BEWith</a>.
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 <a>decodeUtf32LEWith</a>.
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 <a>decodeUtf32BEWith</a>.
decodeUtf32BE :: ByteString -> Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text..
--   
--   If the input contains any invalid UTF-8 data, the relevant exception
--   will be returned, otherwise the decoded text.
decodeUtf8' :: ByteString -> Either UnicodeException Text

-- | Decode a <a>ByteString</a> 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 <a>Text</a> 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

-- | <i>O(n)</i> Create a new <a>Text</a> from a <a>Ptr</a> <a>Word16</a>
--   by copying the contents of the array.
fromPtr :: Ptr Word16 -> I16 -> IO Text

-- | <i>O(n)</i> Perform an action on a temporary, mutable copy of a
--   <a>Text</a>. The copy is freed as soon as the action returns.
useAsPtr :: Text -> (Ptr Word16 -> I16 -> IO a) -> IO a

-- | <i>O(n)</i> Make a mutable copy of a <a>Text</a>.
asForeignPtr :: Text -> IO (ForeignPtr Word16, I16)

-- | <i>O(1)</i> Return the length of a <a>Text</a> in units of
--   <tt>Word16</tt>. This is useful for sizing a target array
--   appropriately before using <tt>unsafeCopyToPtr</tt>.
lengthWord16 :: Text -> Int

-- | <i>O(n)</i> Copy a <a>Text</a> to an array. The array is assumed to be
--   big enough to hold the contents of the entire <a>Text</a>.
unsafeCopyToPtr :: Text -> Ptr Word16 -> IO ()

-- | <i>O(1)</i> Return the suffix of the <a>Text</a>, with <tt>n</tt>
--   <a>Word16</a> units dropped from its beginning.
--   
--   If <tt>n</tt> would cause the <a>Text</a> to begin inside a surrogate
--   pair, the beginning of the suffix will be advanced by one additional
--   <a>Word16</a> unit to maintain its validity.
dropWord16 :: I16 -> Text -> Text

-- | <i>O(1)</i> Return the prefix of the <a>Text</a> of <tt>n</tt>
--   <a>Word16</a> units in length.
--   
--   If <tt>n</tt> would cause the <a>Text</a> to end inside a surrogate
--   pair, the end of the prefix will be advanced by one additional
--   <a>Word16</a> 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.
--   
--   <i>Note</i>: Read below the synopsis for important notes on the use of
--   this module.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.Text as T
--   </pre>
--   
--   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
--   <tt>text-icu</tt> package:
--   <a>http://hackage.haskell.org/package/text-icu</a>
module Data.Text

-- | A space efficient, packed, unboxed Unicode text type.
data Text

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>Text</a>. Subject to
--   fusion. Performs replacement on invalid scalar values.
pack :: String -> Text

-- | <i>O(n)</i> Convert a Text into a String. Subject to fusion.
unpack :: Text -> String

-- | <i>O(1)</i> Convert a character into a Text. Subject to fusion.
--   Performs replacement on invalid scalar values.
singleton :: Char -> Text

-- | <i>O(1)</i> The empty <a>Text</a>.
empty :: Text

-- | <i>O(n)</i> Adds a character to the front of a <a>Text</a>. This
--   function is more costly than its <tt>List</tt> counterpart because it
--   requires copying a new array. Subject to fusion. Performs replacement
--   on invalid scalar values.
cons :: Char -> Text -> Text

-- | <i>O(n)</i> Adds a character to the end of a <a>Text</a>. This copies
--   the entire array in the process, unless fused. Subject to fusion.
--   Performs replacement on invalid scalar values.
snoc :: Text -> Char -> Text

-- | <i>O(n)</i> Appends one <a>Text</a> to the other by copying both of
--   them into a new <a>Text</a>. Subject to fusion.
append :: Text -> Text -> Text

-- | <i>O(1)</i> Returns the first character and rest of a <a>Text</a>, or
--   <a>Nothing</a> if empty. Subject to fusion.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(1)</i> Returns the first character of a <a>Text</a>, which must
--   be non-empty. Subject to fusion.
head :: Text -> Char

-- | <i>O(1)</i> Returns the last character of a <a>Text</a>, which must be
--   non-empty. Subject to fusion.
last :: Text -> Char

-- | <i>O(1)</i> Returns all characters after the head of a <a>Text</a>,
--   which must be non-empty. Subject to fusion.
tail :: Text -> Text

-- | <i>O(1)</i> Returns all but the last character of a <a>Text</a>, which
--   must be non-empty. Subject to fusion.
init :: Text -> Text

-- | <i>O(1)</i> Tests whether a <a>Text</a> is empty or not. Subject to
--   fusion.
null :: Text -> Bool

-- | <i>O(n)</i> Returns the number of characters in a <a>Text</a>. Subject
--   to fusion.
length :: Text -> Int

-- | <i>O(n)</i> Compare the count of characters in a <a>Text</a> to a
--   number. Subject to fusion.
--   
--   This function gives the same answer as comparing against the result of
--   <a>length</a>, but can short circuit if the count of characters is
--   greater than the number, and hence be more efficient.
compareLength :: Text -> Int -> Ordering

-- | <i>O(n)</i> <a>map</a> <tt>f</tt> <tt>t</tt> is the <a>Text</a>
--   obtained by applying <tt>f</tt> to each element of <tt>t</tt>. Subject
--   to fusion. Performs replacement on invalid scalar values.
map :: (Char -> Char) -> Text -> Text

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>Text</a> and a
--   list of <a>Text</a>s and concatenates the list after interspersing the
--   first argument between each element of the list.
intercalate :: Text -> [Text] -> Text

-- | <i>O(n)</i> The <a>intersperse</a> function takes a character and
--   places it between the characters of a <a>Text</a>. Subject to fusion.
--   Performs replacement on invalid scalar values.
intersperse :: Char -> Text -> Text

-- | <i>O(n)</i> The <a>transpose</a> function transposes the rows and
--   columns of its <a>Text</a> argument. Note that this function uses
--   <a>pack</a>, <a>unpack</a>, and the list version of transpose, and is
--   thus not very efficient.
transpose :: [Text] -> [Text]

-- | <i>O(n)</i> Reverse the characters of a string. Subject to fusion.
reverse :: Text -> Text

-- | <i>O(m+n)</i> Replace every occurrence of one substring with another.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
replace :: Text -> Text -> Text -> Text

-- | <i>O(n)</i> Convert a string to folded case. This function is mainly
--   useful for performing caseless (also known as case insensitive) string
--   comparisons.
--   
--   A string <tt>x</tt> is a caseless match for a string <tt>y</tt> if and
--   only if:
--   
--   <pre>
--   toCaseFold x == toCaseFold y
--   </pre>
--   
--   The result string may be longer than the input string, and may differ
--   from applying <a>toLower</a> 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

-- | <i>O(n)</i> 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

-- | <i>O(n)</i> 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

-- | <i>O(n)</i> 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:
--   
--   <pre>
--   justifyLeft 7 'x' "foo"    == "fooxxxx"
--   justifyLeft 3 'x' "foobar" == "foobar"
--   </pre>
justifyLeft :: Int -> Char -> Text -> Text

-- | <i>O(n)</i> Right-justify a string to the given length, using the
--   specified fill character on the left. Performs replacement on invalid
--   scalar values.
--   
--   Examples:
--   
--   <pre>
--   justifyRight 7 'x' "bar"    == "xxxxbar"
--   justifyRight 3 'x' "foobar" == "foobar"
--   </pre>
justifyRight :: Int -> Char -> Text -> Text

-- | <i>O(n)</i> Center a string to the given length, using the specified
--   fill character on either side. Performs replacement on invalid scalar
--   values.
--   
--   Examples:
--   
--   <pre>
--   center 8 'x' "HS" = "xxxHSxxx"
--   </pre>
center :: Int -> Char -> Text -> Text

-- | <i>O(n)</i> <a>foldl</a>, applied to a binary operator, a starting
--   value (typically the left-identity of the operator), and a
--   <a>Text</a>, reduces the <a>Text</a> using the binary operator, from
--   left to right. Subject to fusion.
foldl :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A strict version of <a>foldl</a>. Subject to fusion.
foldl' :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to a non-empty <a>Text</a>. Subject
--   to fusion.
foldl1 :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A strict version of <a>foldl1</a>. Subject to fusion.
foldl1' :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> <a>foldr</a>, applied to a binary operator, a starting
--   value (typically the right-identity of the operator), and a
--   <a>Text</a>, reduces the <a>Text</a> using the binary operator, from
--   right to left. Subject to fusion.
foldr :: (Char -> a -> a) -> a -> Text -> a

-- | <i>O(n)</i> A variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to a non-empty <a>Text</a>. Subject
--   to fusion.
foldr1 :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> Concatenate a list of <a>Text</a>s.
concat :: [Text] -> Text

-- | <i>O(n)</i> Map a function over a <a>Text</a> that results in a
--   <a>Text</a>, and concatenate the results.
concatMap :: (Char -> Text) -> Text -> Text

-- | <i>O(n)</i> <a>any</a> <tt>p</tt> <tt>t</tt> determines whether any
--   character in the <a>Text</a> <tt>t</tt> satisifes the predicate
--   <tt>p</tt>. Subject to fusion.
any :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>all</a> <tt>p</tt> <tt>t</tt> determines whether all
--   characters in the <a>Text</a> <tt>t</tt> satisify the predicate
--   <tt>p</tt>. Subject to fusion.
all :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>Text</a>, which must be non-empty. Subject to fusion.
maximum :: Text -> Char

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>Text</a>, which must be non-empty. Subject to fusion.
minimum :: Text -> Char

-- | <i>O(n)</i> <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   list of successive reduced values from the left. Subject to fusion.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> Text -> Text

-- | <i>O(n)</i> <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument. Subject to fusion. Performs replacement on
--   invalid scalar values.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Char -> Char -> Char) -> Text -> Text

-- | <i>O(n)</i> <a>scanr</a> is the right-to-left dual of <a>scanl</a>.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanr f v == reverse . scanl (flip f) v . reverse
--   </pre>
scanr :: (Char -> Char -> Char) -> Char -> Text -> Text

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

-- | <i>O(n)</i> Like a combination of <a>map</a> and <a>foldl'</a>.
--   Applies a function to each element of a <a>Text</a>, passing an
--   accumulating parameter from left to right, and returns a final
--   <a>Text</a>. Performs replacement on invalid scalar values.
mapAccumL :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and a strict <a>foldr</a>; it applies a function to each element of a
--   <a>Text</a>, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   <a>Text</a>. Performs replacement on invalid scalar values.
mapAccumR :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text)

-- | <i>O(n*m)</i> <a>replicate</a> <tt>n</tt> <tt>t</tt> is a <a>Text</a>
--   consisting of the input <tt>t</tt> repeated <tt>n</tt> times.
replicate :: Int -> Text -> Text

-- | <i>O(n)</i>, where <tt>n</tt> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List <a>unfoldr</a>.
--   <a>unfoldr</a> builds a <a>Text</a> from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the <a>Text</a>, otherwise <a>Just</a> <tt>(a,b)</tt>. In this case,
--   <tt>a</tt> is the next <a>Char</a> in the string, and <tt>b</tt> is
--   the seed value for further production. Subject to fusion. Performs
--   replacement on invalid scalar values.
unfoldr :: (a -> Maybe (Char, a)) -> a -> Text

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a <a>Text</a>
--   from a seed value. However, the length of the result should be limited
--   by the first argument to <a>unfoldrN</a>. This function is more
--   efficient than <a>unfoldr</a> when the maximum length of the result is
--   known and correct, otherwise its performance is similar to
--   <a>unfoldr</a>. Subject to fusion. Performs replacement on invalid
--   scalar values.
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> Text

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a <a>Text</a>, returns
--   the prefix of the <a>Text</a> of length <tt>n</tt>, or the <a>Text</a>
--   itself if <tt>n</tt> is greater than the length of the Text. Subject
--   to fusion.
take :: Int -> Text -> Text

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt>, applied to a <a>Text</a>, returns
--   the suffix of the <a>Text</a> after the first <tt>n</tt> characters,
--   or the empty <a>Text</a> if <tt>n</tt> is greater than the length of
--   the <a>Text</a>. Subject to fusion.
drop :: Int -> Text -> Text

-- | <i>O(n)</i> <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a
--   <a>Text</a>, returns the longest prefix (possibly empty) of elements
--   that satisfy <tt>p</tt>. Subject to fusion.
takeWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhile</a> <tt>p</tt> <tt>t</tt> returns the suffix
--   remaining after <a>takeWhile</a> <tt>p</tt> <tt>t</tt>. Subject to
--   fusion.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhileEnd</a> <tt>p</tt> <tt>t</tt> returns the
--   prefix remaining after dropping characters that fail the predicate
--   <tt>p</tt> from the end of <tt>t</tt>. Subject to fusion. Examples:
--   
--   <pre>
--   dropWhileEnd (=='.') "foo..." == "foo"
--   </pre>
dropWhileEnd :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropAround</a> <tt>p</tt> <tt>t</tt> returns the
--   substring remaining after dropping characters that fail the predicate
--   <tt>p</tt> from both the beginning and end of <tt>t</tt>. Subject to
--   fusion.
dropAround :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Remove leading and trailing white space from a string.
--   Equivalent to:
--   
--   <pre>
--   dropAround isSpace
--   </pre>
strip :: Text -> Text

-- | <i>O(n)</i> Remove leading white space from a string. Equivalent to:
--   
--   <pre>
--   dropWhile isSpace
--   </pre>
stripStart :: Text -> Text

-- | <i>O(n)</i> Remove trailing white space from a string. Equivalent to:
--   
--   <pre>
--   dropWhileEnd isSpace
--   </pre>
stripEnd :: Text -> Text

-- | <i>O(n)</i> <a>splitAt</a> <tt>n t</tt> returns a pair whose first
--   element is a prefix of <tt>t</tt> of length <tt>n</tt>, and whose
--   second is the remainder of the string. It is equivalent to
--   <tt>(<a>take</a> n t, <a>drop</a> n t)</tt>.
splitAt :: Int -> Text -> (Text, Text)

-- | <i>O(n+m)</i> Find the first instance of <tt>needle</tt> (which must
--   be non-<a>null</a>) in <tt>haystack</tt>. The first element of the
--   returned tuple is the prefix of <tt>haystack</tt> before
--   <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match.
--   
--   Examples:
--   
--   <pre>
--   breakOn "::" "a::b::c" ==&gt; ("a", "::b::c")
--   breakOn "/" "foobar"   ==&gt; ("foobar", "")
--   </pre>
--   
--   Laws:
--   
--   <pre>
--   append prefix match == haystack
--     where (prefix, match) = breakOn needle haystack
--   </pre>
--   
--   If you need to break a string by a substring repeatedly (e.g. you want
--   to break on every instance of a substring), use <a>breakOnAll</a>
--   instead, as it has lower startup overhead.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
breakOn :: Text -> Text -> (Text, Text)

-- | <i>O(n+m)</i> Similar to <a>breakOn</a>, but searches from the end of
--   the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" ==&gt; ("a::b::", "c")
--   </pre>
breakOnEnd :: Text -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>break</a> is like <a>span</a>, but the prefix returned
--   is over elements that fail the predicate <tt>p</tt>.
break :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>span</a>, applied to a predicate <tt>p</tt> and text
--   <tt>t</tt>, returns a pair whose first element is the longest prefix
--   (possibly empty) of <tt>t</tt> of elements that satisfy <tt>p</tt>,
--   and whose second is the remainder of the list.
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> Group characters in a string by equality.
group :: Text -> [Text]

-- | <i>O(n)</i> Group characters in a string according to a predicate.
groupBy :: (Char -> Char -> Bool) -> Text -> [Text]

-- | <i>O(n)</i> Return all initial segments of the given <a>Text</a>,
--   shortest first.
inits :: Text -> [Text]

-- | <i>O(n)</i> Return all final segments of the given <a>Text</a>,
--   longest first.
tails :: Text -> [Text]

-- | <i>O(m+n)</i> Break a <a>Text</a> into pieces separated by the first
--   <a>Text</a> argument, consuming the delimiter. An empty delimiter is
--   invalid, and will cause an error to be raised.
--   
--   Examples:
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate s . splitOn s         == id
--   splitOn (singleton c)             == split (==c)
--   </pre>
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
splitOn :: Text -> Text -> [Text]

-- | <i>O(n)</i> Splits a <a>Text</a> 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.
--   
--   <pre>
--   split (=='a') "aabbaca" == ["","","bb","c",""]
--   split (=='a') ""        == [""]
--   </pre>
split :: (Char -> Bool) -> Text -> [Text]

-- | <i>O(n)</i> Splits a <a>Text</a> into components of length <tt>k</tt>.
--   The last element may be shorter than the other chunks, depending on
--   the length of the input. Examples:
--   
--   <pre>
--   chunksOf 3 "foobarbaz"   == ["foo","bar","baz"]
--   chunksOf 4 "haskell.org" == ["hask","ell.","org"]
--   </pre>
chunksOf :: Int -> Text -> [Text]

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of <a>Text</a>s at
--   newline <a>Char</a>s. The resulting strings do not contain newlines.
lines :: Text -> [Text]

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of words, delimited by
--   <a>Char</a>s representing white space.
words :: Text -> [Text]

-- | <i>O(n)</i> Joins lines, after appending a terminating newline to
--   each.
unlines :: [Text] -> Text

-- | <i>O(n)</i> Joins words using single space characters.
unwords :: [Text] -> Text

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> iff the first is a prefix of the second. Subject
--   to fusion.
isPrefixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> iff the first is a suffix of the second.
isSuffixOf :: Text -> Text -> Bool

-- | <i>O(n+m)</i> The <a>isInfixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> iff the first is contained, wholly and intact,
--   anywhere within the second.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
isInfixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> Return the suffix of the second string if its prefix
--   matches the entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripPrefix "foo" "foobar" == Just "bar"
--   stripPrefix ""    "baz"    == Just "baz"
--   stripPrefix "foo" "quux"   == Nothing
--   </pre>
--   
--   This is particularly useful with the <tt>ViewPatterns</tt> extension
--   to GHC, as follows:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text as T
--   
--   fnordLength :: Text -&gt; Int
--   fnordLength (stripPrefix "fnord" -&gt; Just suf) = T.length suf
--   fnordLength _                                 = -1
--   </pre>
stripPrefix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> Return the prefix of the second string if its suffix
--   matches the entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
--   
--   This is particularly useful with the <tt>ViewPatterns</tt> extension
--   to GHC, as follows:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text as T
--   
--   quuxLength :: Text -&gt; Int
--   quuxLength (stripSuffix "quux" -&gt; Just pre) = T.length pre
--   quuxLength _                                = -1
--   </pre>
stripSuffix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> 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 <a>Nothing</a>.
--   
--   Examples:
--   
--   <pre>
--   commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
--   commonPrefixes "veeble" "fetzer"  == Nothing
--   commonPrefixes "" "baz"           == Nothing
--   </pre>
commonPrefixes :: Text -> Text -> Maybe (Text, Text, Text)

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a <a>Text</a>,
--   returns a <a>Text</a> containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> Text -> Text

-- | <i>O(n+m)</i> Find all non-overlapping instances of <tt>needle</tt> in
--   <tt>haystack</tt>. Each element of the returned list consists of a
--   pair:
--   
--   <ul>
--   <li>The entire string prior to the <i>k</i>th match (i.e. the
--   prefix)</li>
--   <li>The <i>k</i>th match, followed by the remainder of the string</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   breakOnAll "::" ""
--   ==&gt; []
--   breakOnAll "/" "a/b/c/"
--   ==&gt; [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
--   </pre>
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
--   
--   The <tt>needle</tt> parameter may not be empty.
breakOnAll :: Text -> Text -> [(Text, Text)]

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   <a>Text</a>, and returns the first element matching the predicate, or
--   <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> Text -> Maybe Char

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate and a
--   <a>Text</a>, and returns the pair of <a>Text</a>s with elements which
--   do and do not satisfy the predicate, respectively; i.e.
--   
--   <pre>
--   partition p t == (filter p t, filter (not . p) t)
--   </pre>
partition :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>Text</a> index (subscript) operator, starting from 0.
index :: Text -> Int -> Char

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>Text</a> and returns the index of the first element in the
--   <a>Text</a> satisfying the predicate. Subject to fusion.
findIndex :: (Char -> Bool) -> Text -> Maybe Int

-- | <i>O(n+m)</i> The <a>count</a> function returns the number of times
--   the query string appears in the given <a>Text</a>. 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 <i>O(n*m)</i>.
count :: Text -> Text -> Int

-- | <i>O(n)</i> <a>zip</a> takes two <a>Text</a>s and returns a list of
--   corresponding pairs of bytes. If one input <a>Text</a> is short,
--   excess elements of the longer <a>Text</a> are discarded. This is
--   equivalent to a pair of <a>unpack</a> operations.
zip :: Text -> Text -> [(Char, Char)]

-- | <i>O(n)</i> <a>zipWith</a> generalises <a>zip</a> 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 <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The entire file is read strictly, as with
--   <a>getContents</a>.
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 <a>Handle</a> as a string. The
--   <a>Handle</a> 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 <a>interact</a> function takes a function of type <tt>Text -&gt;
--   Text</tt> 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 <a>stdin</a> as a single string.
getContents :: IO Text

-- | Read a single line of user input from <a>stdin</a>.
getLine :: IO Text

-- | Write a string to <a>stdout</a>.
putStr :: Text -> IO ()

-- | Write a string to <a>stdout</a>, followed by a newline.
putStrLn :: Text -> IO ()


-- | A module containing private <a>Text</a> internals. This exposes the
--   <a>Text</a> representation and low level construction functions.
--   Modules which extend the <a>Text</a> system may need to use this
--   module.
--   
--   You should not use this module unless you are determined to monkey
--   with the internals, as the functions here do just about nothing to
--   preserve data invariants. You have been warned!
module Data.Text.Lazy.Internal
data Text
Empty :: Text
Chunk :: {-# UNPACK #-} !Text -> Text -> Text

-- | Smart constructor for <a>Chunk</a>. Guarantees the data type
--   invariant.
chunk :: Text -> Text -> Text

-- | Smart constructor for <a>Empty</a>.
empty :: Text

-- | Consume the chunks of a lazy <a>Text</a> with a natural right fold.
foldrChunks :: (Text -> a -> a) -> a -> Text -> a

-- | Consume the chunks of a lazy <a>Text</a> with a strict,
--   tail-recursive, accumulating left fold.
foldlChunks :: (a -> Text -> a) -> a -> Text -> a

-- | Check the invariant strictly.
strictInvariant :: Text -> Bool

-- | Check the invariant lazily.
lazyInvariant :: Text -> Text

-- | Display the internal structure of a lazy <a>Text</a>.
showStructure :: Text -> String

-- | Currently set to 16 KiB, less the memory management overhead.
defaultChunkSize :: Int

-- | Currently set to 128 bytes, less the memory management overhead.
smallChunkSize :: Int

-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int
instance Typeable Text


-- | A time and space-efficient implementation of Unicode text using lists
--   of packed arrays.
--   
--   <i>Note</i>: 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 <a>concat</a>, <a>append</a>, <a>reverse</a>
--   and <a>cons</a>, have better time complexity than their
--   <a>Data.Text</a> equivalents, due to the underlying representation
--   being a list of chunks. For other operations, lazy <a>Text</a>s 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 <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.Text.Lazy as L
--   </pre>
module Data.Text.Lazy
data Text

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>Text</a>.
--   
--   Subject to fusion. Performs replacement on invalid scalar values.
pack :: String -> Text

-- | <i>O(n)</i> Convert a <a>Text</a> into a <a>String</a>. Subject to
--   fusion.
unpack :: Text -> String

-- | <i>O(1)</i> Convert a character into a Text. Subject to fusion.
--   Performs replacement on invalid scalar values.
singleton :: Char -> Text

-- | Smart constructor for <a>Empty</a>.
empty :: Text

-- | <i>O(c)</i> Convert a list of strict <a>Text</a>s into a lazy
--   <a>Text</a>.
fromChunks :: [Text] -> Text

-- | <i>O(n)</i> Convert a lazy <a>Text</a> into a list of strict
--   <a>Text</a>s.
toChunks :: Text -> [Text]

-- | <i>O(n)</i> Convert a lazy <a>Text</a> into a strict <a>Text</a>.
toStrict :: Text -> Text

-- | <i>O(c)</i> Convert a strict <a>Text</a> into a lazy <a>Text</a>.
fromStrict :: Text -> Text

-- | Consume the chunks of a lazy <a>Text</a> with a natural right fold.
foldrChunks :: (Text -> a -> a) -> a -> Text -> a

-- | Consume the chunks of a lazy <a>Text</a> with a strict,
--   tail-recursive, accumulating left fold.
foldlChunks :: (a -> Text -> a) -> a -> Text -> a

-- | <i>O(n)</i> Adds a character to the front of a <a>Text</a>. This
--   function is more costly than its <tt>List</tt> counterpart because it
--   requires copying a new array. Subject to fusion.
cons :: Char -> Text -> Text

-- | <i>O(n)</i> Adds a character to the end of a <a>Text</a>. This copies
--   the entire array in the process, unless fused. Subject to fusion.
snoc :: Text -> Char -> Text

-- | <i>O(n\</i>c)/ Appends one <a>Text</a> to another. Subject to fusion.
append :: Text -> Text -> Text

-- | <i>O(1)</i> Returns the first character and rest of a <a>Text</a>, or
--   <a>Nothing</a> if empty. Subject to fusion.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(1)</i> Returns the first character of a <a>Text</a>, which must
--   be non-empty. Subject to fusion.
head :: Text -> Char

-- | <i>O(1)</i> Returns the last character of a <a>Text</a>, which must be
--   non-empty. Subject to fusion.
last :: Text -> Char

-- | <i>O(1)</i> Returns all characters after the head of a <a>Text</a>,
--   which must be non-empty. Subject to fusion.
tail :: Text -> Text

-- | <i>O(1)</i> Returns all but the last character of a <a>Text</a>, which
--   must be non-empty. Subject to fusion.
init :: Text -> Text

-- | <i>O(1)</i> Tests whether a <a>Text</a> is empty or not. Subject to
--   fusion.
null :: Text -> Bool

-- | <i>O(n)</i> Returns the number of characters in a <a>Text</a>. Subject
--   to fusion.
length :: Text -> Int64

-- | <i>O(n)</i> Compare the count of characters in a <a>Text</a> to a
--   number. Subject to fusion.
--   
--   This function gives the same answer as comparing against the result of
--   <a>length</a>, but can short circuit if the count of characters is
--   greater than the number, and hence be more efficient.
compareLength :: Text -> Int64 -> Ordering

-- | <i>O(n)</i> <a>map</a> <tt>f</tt> <tt>t</tt> is the <a>Text</a>
--   obtained by applying <tt>f</tt> to each element of <tt>t</tt>. Subject
--   to fusion. Performs replacement on invalid scalar values.
map :: (Char -> Char) -> Text -> Text

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>Text</a> and a
--   list of <a>Text</a>s and concatenates the list after interspersing the
--   first argument between each element of the list.
intercalate :: Text -> [Text] -> Text

-- | <i>O(n)</i> The <a>intersperse</a> function takes a character and
--   places it between the characters of a <a>Text</a>. Subject to fusion.
--   Performs replacement on invalid scalar values.
intersperse :: Char -> Text -> Text

-- | <i>O(n)</i> The <a>transpose</a> function transposes the rows and
--   columns of its <a>Text</a> argument. Note that this function uses
--   <a>pack</a>, <a>unpack</a>, and the list version of transpose, and is
--   thus not very efficient.
transpose :: [Text] -> [Text]

-- | <i>O(n)</i> <a>reverse</a> <tt>t</tt> returns the elements of
--   <tt>t</tt> in reverse order.
reverse :: Text -> Text

-- | <i>O(m+n)</i> Replace every occurrence of one substring with another.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
replace :: Text -> Text -> Text -> Text

-- | <i>O(n)</i> Convert a string to folded case. This function is mainly
--   useful for performing caseless (or case insensitive) string
--   comparisons.
--   
--   A string <tt>x</tt> is a caseless match for a string <tt>y</tt> if and
--   only if:
--   
--   <pre>
--   toCaseFold x == toCaseFold y
--   </pre>
--   
--   The result string may be longer than the input string, and may differ
--   from applying <a>toLower</a> 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

-- | <i>O(n)</i> 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

-- | <i>O(n)</i> 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

-- | <i>O(n)</i> 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:
--   
--   <pre>
--   justifyLeft 7 'x' "foo"    == "fooxxxx"
--   justifyLeft 3 'x' "foobar" == "foobar"
--   </pre>
justifyLeft :: Int64 -> Char -> Text -> Text

-- | <i>O(n)</i> Right-justify a string to the given length, using the
--   specified fill character on the left. Performs replacement on invalid
--   scalar values.
--   
--   Examples:
--   
--   <pre>
--   justifyRight 7 'x' "bar"    == "xxxxbar"
--   justifyRight 3 'x' "foobar" == "foobar"
--   </pre>
justifyRight :: Int64 -> Char -> Text -> Text

-- | <i>O(n)</i> Center a string to the given length, using the specified
--   fill character on either side. Performs replacement on invalid scalar
--   values.
--   
--   Examples:
--   
--   <pre>
--   center 8 'x' "HS" = "xxxHSxxx"
--   </pre>
center :: Int64 -> Char -> Text -> Text

-- | <i>O(n)</i> <a>foldl</a>, applied to a binary operator, a starting
--   value (typically the left-identity of the operator), and a
--   <a>Text</a>, reduces the <a>Text</a> using the binary operator, from
--   left to right. Subject to fusion.
foldl :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A strict version of <a>foldl</a>. Subject to fusion.
foldl' :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to a non-empty <a>Text</a>. Subject
--   to fusion.
foldl1 :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A strict version of <a>foldl1</a>. Subject to fusion.
foldl1' :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> <a>foldr</a>, applied to a binary operator, a starting
--   value (typically the right-identity of the operator), and a
--   <a>Text</a>, reduces the <a>Text</a> using the binary operator, from
--   right to left. Subject to fusion.
foldr :: (Char -> a -> a) -> a -> Text -> a

-- | <i>O(n)</i> A variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to a non-empty <a>Text</a>. Subject
--   to fusion.
foldr1 :: (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> Concatenate a list of <a>Text</a>s.
concat :: [Text] -> Text

-- | <i>O(n)</i> Map a function over a <a>Text</a> that results in a
--   <a>Text</a>, and concatenate the results.
concatMap :: (Char -> Text) -> Text -> Text

-- | <i>O(n)</i> <a>any</a> <tt>p</tt> <tt>t</tt> determines whether any
--   character in the <a>Text</a> <tt>t</tt> satisifes the predicate
--   <tt>p</tt>. Subject to fusion.
any :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>all</a> <tt>p</tt> <tt>t</tt> determines whether all
--   characters in the <a>Text</a> <tt>t</tt> satisify the predicate
--   <tt>p</tt>. Subject to fusion.
all :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>Text</a>, which must be non-empty. Subject to fusion.
maximum :: Text -> Char

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>Text</a>, which must be non-empty. Subject to fusion.
minimum :: Text -> Char

-- | <i>O(n)</i> <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   list of successive reduced values from the left. Subject to fusion.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> Text -> Text

-- | <i>O(n)</i> <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument. Subject to fusion. Performs replacement on
--   invalid scalar values.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Char -> Char -> Char) -> Text -> Text

-- | <i>O(n)</i> <a>scanr</a> is the right-to-left dual of <a>scanl</a>.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanr f v == reverse . scanl (flip f) v . reverse
--   </pre>
scanr :: (Char -> Char -> Char) -> Char -> Text -> Text

-- | <i>O(n)</i> <a>scanr1</a> is a variant of <a>scanr</a> that has no
--   starting value argument. Performs replacement on invalid scalar
--   values.
scanr1 :: (Char -> Char -> Char) -> Text -> Text

-- | <i>O(n)</i> Like a combination of <a>map</a> and <a>foldl'</a>.
--   Applies a function to each element of a <a>Text</a>, passing an
--   accumulating parameter from left to right, and returns a final
--   <a>Text</a>. Performs replacement on invalid scalar values.
mapAccumL :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and a strict <a>foldr</a>; it applies a function to each element of a
--   <a>Text</a>, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   <a>Text</a>. Performs replacement on invalid scalar values.
mapAccumR :: (a -> Char -> (a, Char)) -> a -> Text -> (a, Text)

-- | <i>O(n*m)</i> <a>replicate</a> <tt>n</tt> <tt>t</tt> is a <a>Text</a>
--   consisting of the input <tt>t</tt> repeated <tt>n</tt> times.
replicate :: Int64 -> Text -> Text

-- | <i>O(n)</i>, where <tt>n</tt> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List <a>unfoldr</a>.
--   <a>unfoldr</a> builds a <a>Text</a> from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the <a>Text</a>, otherwise <a>Just</a> <tt>(a,b)</tt>. In this case,
--   <tt>a</tt> is the next <a>Char</a> in the string, and <tt>b</tt> is
--   the seed value for further production. Performs replacement on invalid
--   scalar values.
unfoldr :: (a -> Maybe (Char, a)) -> a -> Text

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a <a>Text</a>
--   from a seed value. However, the length of the result should be limited
--   by the first argument to <a>unfoldrN</a>. This function is more
--   efficient than <a>unfoldr</a> when the maximum length of the result is
--   known and correct, otherwise its performance is similar to
--   <a>unfoldr</a>. Performs replacement on invalid scalar values.
unfoldrN :: Int64 -> (a -> Maybe (Char, a)) -> a -> Text

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a <a>Text</a>, returns
--   the prefix of the <a>Text</a> of length <tt>n</tt>, or the <a>Text</a>
--   itself if <tt>n</tt> is greater than the length of the Text. Subject
--   to fusion.
take :: Int64 -> Text -> Text

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt>, applied to a <a>Text</a>, returns
--   the suffix of the <a>Text</a> after the first <tt>n</tt> characters,
--   or the empty <a>Text</a> if <tt>n</tt> is greater than the length of
--   the <a>Text</a>. Subject to fusion.
drop :: Int64 -> Text -> Text

-- | <i>O(n)</i> <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a
--   <a>Text</a>, returns the longest prefix (possibly empty) of elements
--   that satisfy <tt>p</tt>. Subject to fusion.
takeWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhile</a> <tt>p</tt> <tt>t</tt> returns the suffix
--   remaining after <a>takeWhile</a> <tt>p</tt> <tt>t</tt>. Subject to
--   fusion.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhileEnd</a> <tt>p</tt> <tt>t</tt> returns the
--   prefix remaining after dropping characters that fail the predicate
--   <tt>p</tt> from the end of <tt>t</tt>. Examples:
--   
--   <pre>
--   dropWhileEnd (=='.') "foo..." == "foo"
--   </pre>
dropWhileEnd :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropAround</a> <tt>p</tt> <tt>t</tt> returns the
--   substring remaining after dropping characters that fail the predicate
--   <tt>p</tt> from both the beginning and end of <tt>t</tt>. Subject to
--   fusion.
dropAround :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Remove leading and trailing white space from a string.
--   Equivalent to:
--   
--   <pre>
--   dropAround isSpace
--   </pre>
strip :: Text -> Text

-- | <i>O(n)</i> Remove leading white space from a string. Equivalent to:
--   
--   <pre>
--   dropWhile isSpace
--   </pre>
stripStart :: Text -> Text

-- | <i>O(n)</i> Remove trailing white space from a string. Equivalent to:
--   
--   <pre>
--   dropWhileEnd isSpace
--   </pre>
stripEnd :: Text -> Text

-- | <i>O(n)</i> <a>splitAt</a> <tt>n t</tt> returns a pair whose first
--   element is a prefix of <tt>t</tt> of length <tt>n</tt>, and whose
--   second is the remainder of the string. It is equivalent to
--   <tt>(<a>take</a> n t, <a>drop</a> n t)</tt>.
splitAt :: Int64 -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>span</a>, applied to a predicate <tt>p</tt> and text
--   <tt>t</tt>, returns a pair whose first element is the longest prefix
--   (possibly empty) of <tt>t</tt> of elements that satisfy <tt>p</tt>,
--   and whose second is the remainder of the list.
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n+m)</i> Find the first instance of <tt>needle</tt> (which must
--   be non-<a>null</a>) in <tt>haystack</tt>. The first element of the
--   returned tuple is the prefix of <tt>haystack</tt> before
--   <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match.
--   
--   Examples:
--   
--   <pre>
--   breakOn "::" "a::b::c" ==&gt; ("a", "::b::c")
--   breakOn "/" "foobar"   ==&gt; ("foobar", "")
--   </pre>
--   
--   Laws:
--   
--   <pre>
--   append prefix match == haystack
--     where (prefix, match) = breakOn needle haystack
--   </pre>
--   
--   If you need to break a string by a substring repeatedly (e.g. you want
--   to break on every instance of a substring), use <a>breakOnAll</a>
--   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 <i>O(n*m)</i>.
breakOn :: Text -> Text -> (Text, Text)

-- | <i>O(n+m)</i> Similar to <a>breakOn</a>, but searches from the end of
--   the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" ==&gt; ("a::b::", "c")
--   </pre>
breakOnEnd :: Text -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>break</a> is like <a>span</a>, but the prefix returned
--   is over elements that fail the predicate <tt>p</tt>.
break :: (Char -> Bool) -> Text -> (Text, Text)

-- | The <a>group</a> function takes a <a>Text</a> and returns a list of
--   <a>Text</a>s such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: Text -> [Text]

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: (Char -> Char -> Bool) -> Text -> [Text]

-- | <i>O(n)</i> Return all initial segments of the given <a>Text</a>,
--   shortest first.
inits :: Text -> [Text]

-- | <i>O(n)</i> Return all final segments of the given <a>Text</a>,
--   longest first.
tails :: Text -> [Text]

-- | <i>O(m+n)</i> Break a <a>Text</a> into pieces separated by the first
--   <a>Text</a> argument, consuming the delimiter. An empty delimiter is
--   invalid, and will cause an error to be raised.
--   
--   Examples:
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate s . splitOn s         == id
--   splitOn (singleton c)             == split (==c)
--   </pre>
--   
--   This function is strict in its first argument, and lazy in its second.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
splitOn :: Text -> Text -> [Text]

-- | <i>O(n)</i> Splits a <a>Text</a> 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.
--   
--   <pre>
--   split (=='a') "aabbaca" == ["","","bb","c",""]
--   split (=='a') []        == [""]
--   </pre>
split :: (Char -> Bool) -> Text -> [Text]

-- | <i>O(n)</i> Splits a <a>Text</a> into components of length <tt>k</tt>.
--   The last element may be shorter than the other chunks, depending on
--   the length of the input. Examples:
--   
--   <pre>
--   chunksOf 3 "foobarbaz"   == ["foo","bar","baz"]
--   chunksOf 4 "haskell.org" == ["hask","ell.","org"]
--   </pre>
chunksOf :: Int64 -> Text -> [Text]

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of <a>Text</a>s at
--   newline <a>Char</a>s. The resulting strings do not contain newlines.
lines :: Text -> [Text]

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of words, delimited by
--   <a>Char</a>s representing white space.
words :: Text -> [Text]

-- | <i>O(n)</i> Joins lines, after appending a terminating newline to
--   each.
unlines :: [Text] -> Text

-- | <i>O(n)</i> Joins words using single space characters.
unwords :: [Text] -> Text

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> iff the first is a prefix of the second. Subject
--   to fusion.
isPrefixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> iff the first is a suffix of the second.
isSuffixOf :: Text -> Text -> Bool

-- | <i>O(n+m)</i> The <a>isInfixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> 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 <i>O(n*m)</i>.
isInfixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> Return the suffix of the second string if its prefix
--   matches the entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripPrefix "foo" "foobar" == Just "bar"
--   stripPrefix ""    "baz"    == Just "baz"
--   stripPrefix "foo" "quux"   == Nothing
--   </pre>
--   
--   This is particularly useful with the <tt>ViewPatterns</tt> extension
--   to GHC, as follows:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text.Lazy as T
--   
--   fnordLength :: Text -&gt; Int
--   fnordLength (stripPrefix "fnord" -&gt; Just suf) = T.length suf
--   fnordLength _                                 = -1
--   </pre>
stripPrefix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> Return the prefix of the second string if its suffix
--   matches the entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
--   
--   This is particularly useful with the <tt>ViewPatterns</tt> extension
--   to GHC, as follows:
--   
--   <pre>
--   {-# LANGUAGE ViewPatterns #-}
--   import Data.Text.Lazy as T
--   
--   quuxLength :: Text -&gt; Int
--   quuxLength (stripSuffix "quux" -&gt; Just pre) = T.length pre
--   quuxLength _                                = -1
--   </pre>
stripSuffix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> 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 <a>Nothing</a>.
--   
--   Examples:
--   
--   <pre>
--   commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
--   commonPrefixes "veeble" "fetzer"  == Nothing
--   commonPrefixes "" "baz"           == Nothing
--   </pre>
commonPrefixes :: Text -> Text -> Maybe (Text, Text, Text)

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a <a>Text</a>,
--   returns a <a>Text</a> containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   <a>Text</a>, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> Text -> Maybe Char

-- | <i>O(n+m)</i> Find all non-overlapping instances of <tt>needle</tt> in
--   <tt>haystack</tt>. Each element of the returned list consists of a
--   pair:
--   
--   <ul>
--   <li>The entire string prior to the <i>k</i>th match (i.e. the
--   prefix)</li>
--   <li>The <i>k</i>th match, followed by the remainder of the string</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   breakOnAll "::" ""
--   ==&gt; []
--   breakOnAll "/" "a/b/c/"
--   ==&gt; [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
--   </pre>
--   
--   This function is strict in its first argument, and lazy in its second.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
--   
--   The <tt>needle</tt> parameter may not be empty.
breakOnAll :: Text -> Text -> [(Text, Text)]

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate and a
--   <a>Text</a>, and returns the pair of <a>Text</a>s with elements which
--   do and do not satisfy the predicate, respectively; i.e.
--   
--   <pre>
--   partition p t == (filter p t, filter (not . p) t)
--   </pre>
partition :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> <a>Text</a> index (subscript) operator, starting from 0.
index :: Text -> Int64 -> Char

-- | <i>O(n+m)</i> The <a>count</a> function returns the number of times
--   the query string appears in the given <a>Text</a>. 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 <i>O(n*m)</i>.
count :: Text -> Text -> Int64

-- | <i>O(n)</i> <a>zip</a> takes two <a>Text</a>s and returns a list of
--   corresponding pairs of bytes. If one input <a>Text</a> is short,
--   excess elements of the longer <a>Text</a> are discarded. This is
--   equivalent to a pair of <a>unpack</a> operations.
zip :: Text -> Text -> [(Char, Char)]

-- | <i>O(n)</i> <a>zipWith</a> generalises <a>zip</a> 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 <tt><a>signed</a> <a>decimal</a></tt>.
--   
--   <i>Note</i>: 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
--   <a>Integer</a> for your result type.
decimal :: Integral a => Reader a

-- | Read a hexadecimal integer, consisting of an optional leading
--   <tt>"0x"</tt> 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 <tt><a>signed</a> <a>hexadecimal</a></tt>.
--   
--   <i>Note</i>: 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
--   <a>Integer</a> for your result type.
hexadecimal :: Integral a => Reader a

-- | Read an optional leading sign character (<tt>'-'</tt> or <tt>'+'</tt>)
--   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
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples:
--   
--   <pre>
--   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"
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   rational "3.foo" == Right (3.0, ".foo")
--   rational "3e"    == Right (3.0, "e")
--   </pre>
rational :: Fractional a => Reader a

-- | Read a rational number.
--   
--   The syntax accepted by this function is the same as for
--   <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>, but is slightly less accurate.
--   
--   The <a>Double</a> type supports about 16 decimal places of accuracy.
--   For 94.2% of numbers, this function and <a>rational</a> 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 <a>getContents</a>.
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 <a>Handle</a>. The
--   <a>Handle</a> 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 <a>interact</a> function takes a function of type <tt>Text -&gt;
--   Text</tt> 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 <a>stdin</a> as a single string.
getContents :: IO Text

-- | Read a single line of user input from <a>stdin</a>.
getLine :: IO Text

-- | Write a string to <a>stdout</a>.
putStr :: Text -> IO ()

-- | Write a string to <a>stdout</a>, followed by a newline.
putStrLn :: Text -> IO ()


-- | Efficient construction of lazy <tt>Text</tt> values. The principal
--   operations on a <tt>Builder</tt> are <tt>singleton</tt>,
--   <tt>fromText</tt>, and <tt>fromLazyText</tt>, which construct new
--   builders, and <a>mappend</a>, which concatenates two builders.
--   
--   To get maximum performance when building lazy <tt>Text</tt> values
--   using a builder, associate <tt>mappend</tt> calls to the right. For
--   example, prefer
--   
--   <pre>
--   singleton 'a' `mappend` (singleton 'b' `mappend` singleton 'c')
--   </pre>
--   
--   to
--   
--   <pre>
--   singleton 'a' `mappend` singleton 'b' `mappend` singleton 'c'
--   </pre>
--   
--   as the latter associates <tt>mappend</tt> to the left.
module Data.Text.Lazy.Builder

-- | A <tt>Builder</tt> is an efficient way to build lazy <tt>Text</tt>
--   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 <tt>Text</tt> values using <tt>toLazyText</tt>.
--   
--   Internally, a builder constructs a lazy <tt>Text</tt> by filling
--   arrays piece by piece. As each buffer is filled, it is 'popped' off,
--   to become a new chunk of the resulting lazy <tt>Text</tt>. All this is
--   hidden from the user of the <tt>Builder</tt>.
data Builder

-- | <i>O(n).</i> Extract a lazy <tt>Text</tt> from a <tt>Builder</tt> with
--   a default buffer size. The construction work takes place if and when
--   the relevant part of the lazy <tt>Text</tt> is demanded.
toLazyText :: Builder -> Text

-- | <i>O(n).</i> Extract a lazy <tt>Text</tt> from a <tt>Builder</tt>,
--   using the given size for the initial buffer. The construction work
--   takes place if and when the relevant part of the lazy <tt>Text</tt> 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

-- | <i>O(1).</i> A <tt>Builder</tt> taking a single character, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyText</a> (<a>singleton</a> c) = <a>singleton</a>
--   c</pre></li>
--   </ul>
singleton :: Char -> Builder

-- | <i>O(1).</i> A <tt>Builder</tt> taking a <a>Text</a>, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyText</a> (<a>fromText</a> t) = <a>fromChunks</a>
--   [t]</pre></li>
--   </ul>
fromText :: Text -> Builder

-- | <i>O(1).</i> A <tt>Builder</tt> taking a lazy <tt>Text</tt>,
--   satisfying
--   
--   <ul>
--   <li><pre><a>toLazyText</a> (<a>fromLazyText</a> t) = t</pre></li>
--   </ul>
fromLazyText :: Text -> Builder

-- | <i>O(1).</i> A Builder taking a <tt>String</tt>, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyText</a> (<a>fromString</a> s) = <a>fromChunks</a>
--   [S.pack s]</pre></li>
--   </ul>
fromString :: String -> Builder

-- | <i>O(1).</i> Pop the strict <tt>Text</tt> we have constructed so far,
--   if any, yielding a new chunk in the result lazy <tt>Text</tt>.
flush :: Builder
instance Ord Builder
instance Eq Builder
instance Show Builder
instance IsString Builder
instance Monoid Builder

module Data.Text.Lazy.Builder.Int
decimal :: Integral a => a -> Builder
hexadecimal :: Integral a => a -> Builder


-- | Write a floating point value to a <a>Builder</a>.
module Data.Text.Lazy.Builder.RealFloat

-- | Control the rendering of floating point numbers.
data FPFormat

-- | Scientific notation (e.g. <tt>2.3e123</tt>).
Exponent :: FPFormat

-- | Standard decimal notation.
Fixed :: FPFormat

-- | Use decimal notation for values between <tt>0.1</tt> and
--   <tt>9,999,999</tt>, and scientific notation otherwise.
Generic :: FPFormat

-- | Show a signed <a>RealFloat</a> value to full precision, using standard
--   decimal notation for arguments whose absolute value lies between
--   <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific notation
--   otherwise.
realFloat :: RealFloat a => a -> Builder
formatRealFloat :: RealFloat a => FPFormat -> Maybe Int -> a -> Builder
instance Enum FPFormat
instance Read FPFormat
instance Show FPFormat


-- | Functions for converting lazy <a>Text</a> values to and from lazy
--   <tt>ByteString</tt>, using several standard encodings.
--   
--   To gain access to a much larger variety of encodings, use the
--   <tt>text-icu</tt> package:
--   <a>http://hackage.haskell.org/package/text-icu</a>
module Data.Text.Lazy.Encoding

-- | <i>Deprecated</i>. Decode a <tt>ByteString</tt> containing 7-bit ASCII
--   encoded text.
--   
--   This function is deprecated. Use <a>decodeUtf8</a> instead.

-- | <i>Deprecated: Use decodeUtf8 instead</i>
decodeASCII :: ByteString -> Text

-- | Decode a <tt>ByteString</tt> containing UTF-8 encoded text that is
--   known to be valid.
--   
--   If the input contains any invalid UTF-8 data, an exception will be
--   thrown that cannot be caught in pure code. For more control over the
--   handling of invalid data, use <a>decodeUtf8'</a> or
--   <a>decodeUtf8With</a>.
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 <a>decodeUtf16LEWith</a>.
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 <a>decodeUtf16BEWith</a>.
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 <a>decodeUtf32LEWith</a>.
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 <a>decodeUtf32BEWith</a>.
decodeUtf32BE :: ByteString -> Text

-- | Decode a <tt>ByteString</tt> containing UTF-8 encoded text..
--   
--   If the input contains any invalid UTF-8 data, the relevant exception
--   will be returned, otherwise the decoded text.
--   
--   <i>Note</i>: this function is <i>not</i> lazy, as it must decode its
--   entire input before it can return a result. If you need lazy
--   (streaming) decoding, use <a>decodeUtf8With</a> in lenient mode.
decodeUtf8' :: ByteString -> Either UnicodeException Text

-- | Decode a <tt>ByteString</tt> 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 <tt><a>signed</a> <a>decimal</a></tt>.
--   
--   <i>Note</i>: 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
--   <a>Integer</a> for your result type.
decimal :: Integral a => Reader a

-- | Read a hexadecimal integer, consisting of an optional leading
--   <tt>"0x"</tt> 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 <tt><a>signed</a> <a>hexadecimal</a></tt>.
--   
--   <i>Note</i>: 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
--   <a>Integer</a> for your result type.
hexadecimal :: Integral a => Reader a

-- | Read an optional leading sign character (<tt>'-'</tt> or <tt>'+'</tt>)
--   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
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples (with behaviour identical to <a>read</a>):
--   
--   <pre>
--   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"
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   rational "3.foo" == Right (3.0, ".foo")
--   rational "3e"    == Right (3.0, "e")
--   </pre>
rational :: Fractional a => Reader a

-- | Read a rational number.
--   
--   The syntax accepted by this function is the same as for
--   <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>, but is slightly less accurate.
--   
--   The <a>Double</a> type supports about 16 decimal places of accuracy.
--   For 94.2% of numbers, this function and <a>rational</a> 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
