-- 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>
@package text
@version 1.2.0.3


-- | Common internal functiopns for reading textual data.
module Data.Text.Internal.Read
type IReader t a = t -> Either String (a, t)
newtype IParser t a
P :: IReader t a -> IParser t a
runP :: IParser t a -> IReader t a
data T
T :: !Integer -> !Int -> T
digitToInt :: Char -> Int
hexDigitToInt :: Char -> Int
perhaps :: a -> IParser t a -> IParser t a
instance Monad (IParser t)
instance Applicative (IParser t)
instance Functor (IParser t)


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Basic UTF-32 validation.
module Data.Text.Internal.Encoding.Utf32
validate :: Word32 -> Bool


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
module Data.Text.Internal.Builder.RealFloat.Functions
roundTo :: Int -> [Int] -> (Int, [Int])

module Data.Text.Internal.Builder.Int.Digits
digits :: ByteString


-- | 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 NFData UnicodeException
instance Exception UnicodeException
instance Show UnicodeException


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Fast, unchecked bit shifting functions.
module Data.Text.Internal.Unsafe.Shift

-- | This is a workaround for poor optimisation in GHC 6.8.2. It fails to
--   notice constant-width shifts, and adds a test and branch to every
--   shift. This imposes about a 10% performance hit.
--   
--   These functions are undefined when the amount being shifted by is
--   greater than the size in bits of a machine Int#.
class UnsafeShift a
shiftL :: UnsafeShift a => a -> Int -> a
shiftR :: UnsafeShift a => a -> Int -> a
instance UnsafeShift Int
instance UnsafeShift Word64
instance UnsafeShift Word32
instance UnsafeShift Word16


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Basic UTF-16 validation and character manipulation.
module Data.Text.Internal.Encoding.Utf16
chr2 :: Word16 -> Word16 -> Char
validate1 :: Word16 -> Bool
validate2 :: Word16 -> Word16 -> Bool


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Useful functions.
module Data.Text.Internal.Functions

-- | A lazier version of Data.List.intersperse. The other version causes
--   space leaks!
intersperse :: a -> [a] -> [a]


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   A module containing <i>unsafe</i> operations, for <i>very very
--   careful</i> use in <i>heavily tested</i> code.
module Data.Text.Internal.Unsafe

-- | Allow an <a>ST</a> computation to be deferred lazily. When passed an
--   action of type <a>ST</a> <tt>s</tt> <tt>a</tt>, the action will only
--   be performed when the value of <tt>a</tt> is demanded.
--   
--   This function is identical to the normal unsafeInterleaveST, but is
--   inlined and hence faster.
--   
--   <i>Note</i>: This operation is highly unsafe, as it can introduce
--   externally visible non-determinism into an <a>ST</a> action.
inlineInterleaveST :: ST s a -> ST s a

-- | Just like unsafePerformIO, but we inline it. Big performance gains as
--   it exposes lots of things to further inlining. <i>Very unsafe</i>. In
--   particular, you should do no memory allocation inside an
--   <a>inlinePerformIO</a> block. On Hugs this is just
--   <tt>unsafePerformIO</tt>.
inlinePerformIO :: IO a -> a


-- | 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
Array :: ByteArray# -> Array
aBA :: Array -> ByteArray#

-- | Mutable array type, for use in the ST monad.
data MArray s
MArray :: MutableByteArray# s -> MArray s
maBA :: MArray s -> MutableByteArray# 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 ()


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Fast character manipulation functions.
module Data.Text.Internal.Unsafe.Char
ord :: Char -> Int
unsafeChr :: Word16 -> Char
unsafeChr8 :: Word8 -> Char
unsafeChr32 :: Word32 -> Char

-- | Write a character into the array at the given offset. Returns the
--   number of <a>Word16</a>s written.
unsafeWrite :: MArray s -> Int -> Char -> ST s Int


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

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

-- | <i>Deprecated: Use text instead</i>
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
--   (U+FFFD, '�'), and leaves other code points unchanged.
safe :: Char -> Char

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

-- | A non-inlined version of <a>empty</a>.
empty_ :: Text

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

-- | Checked multiplication. Calls <a>error</a> if the result would
--   overflow.
mul :: Int -> Int -> Int

-- | Checked multiplication. Calls <a>error</a> if the result would
--   overflow.
mul32 :: Int32 -> Int32 -> Int32

-- | Checked multiplication. Calls <a>error</a> if the result would
--   overflow.
mul64 :: Int64 -> Int64 -> Int64

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


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Size hints.
module Data.Text.Internal.Fusion.Size
data Size
exactly :: Size -> Maybe Int
exactSize :: Int -> Size
maxSize :: Int -> Size
betweenSize :: Int -> Int -> Size
unknownSize :: Size

-- | Minimum of two size hints.
smaller :: Size -> Size -> Size

-- | Maximum of two size hints.
larger :: Size -> Size -> Size

-- | Compute the maximum size from a size hint, if possible.
upperBound :: Int -> Size -> Int

-- | Compute the maximum size from a size hint, if possible.
lowerBound :: Int -> Size -> Int
compareSize :: Size -> Int -> Maybe Ordering
isEmpty :: Size -> Bool
instance Eq Size
instance Show Size
instance Num Size


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Core stream fusion functionality for text.
module Data.Text.Internal.Fusion.Types

-- | Specialised tuple for case conversion.
data CC s
CC :: !s -> {-# UNPACK #-} !Char -> {-# UNPACK #-} !Char -> CC s

-- | Specialised, strict Maybe-like type.
data M a
N :: M a
J :: !a -> M a
type M8 = M Word8
data PairS a b
(:*:) :: !a -> !b -> PairS a b
data RS s
RS0 :: !s -> RS s
RS1 :: !s -> {-# UNPACK #-} !Word8 -> RS s
RS2 :: !s -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> RS s
RS3 :: !s -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> RS s
data Step s a
Done :: Step s a
Skip :: !s -> Step s a
Yield :: !a -> !s -> Step s a
data Stream a
Stream :: (s -> Step s a) -> !s -> !Size -> Stream a

-- | Allow a function over a stream to switch between two states.
data Switch
S1 :: Switch
S2 :: Switch

-- | The empty stream.
empty :: Stream a
instance Ord a => Ord (Stream a)
instance Eq a => Eq (Stream a)

module Data.Text.Internal.Fusion.CaseMapping
upperMapping :: Char -> s -> Step (CC s) Char
lowerMapping :: Char -> s -> Step (CC s) Char
titleMapping :: Char -> s -> Step (CC s) Char
foldMapping :: Char -> s -> Step (CC s) Char


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Common stream fusion functionality for text.
module Data.Text.Internal.Fusion.Common
singleton :: Char -> Stream Char
streamList :: [a] -> Stream a
unstreamList :: Stream a -> [a]

-- | Stream the UTF-8-like packed encoding used by GHC to represent
--   constant strings in generated code.
--   
--   This encoding uses the byte sequence "xc0x80" to represent NUL, and
--   the string is NUL-terminated.
streamCString# :: Addr# -> Stream Char

-- | <i>O(n)</i> Adds a character to the front of a Stream Char.
cons :: Char -> Stream Char -> Stream Char

-- | <i>O(n)</i> Adds a character to the end of a stream.
snoc :: Stream Char -> Char -> Stream Char

-- | <i>O(n)</i> Appends one Stream to the other.
append :: Stream Char -> Stream Char -> Stream Char

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

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

-- | <i>O(n)</i> Returns the last character of a 'Stream Char', which must
--   be non-empty.
last :: Stream Char -> Char

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

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

-- | <i>O(1)</i> Tests whether a Stream Char is empty or not.
null :: Stream Char -> Bool

-- | <i>O(n)</i> Returns the number of characters in a string.
lengthI :: Integral a => Stream Char -> a

-- | <i>O(n)</i> Compares the count of characters in a string to a number.
--   Subject to fusion.
--   
--   This function gives the same answer as comparing against the result of
--   <a>lengthI</a>, but can short circuit if the count of characters is
--   greater than the number or if the stream can't possibly be as long as
--   the number supplied, and hence be more efficient.
compareLengthI :: Integral a => Stream Char -> a -> Ordering

-- | <i>O(n)</i> Indicate whether a string contains exactly one element.
isSingleton :: Stream Char -> Bool

-- | <i>O(n)</i> <a>map</a> <tt>f </tt>xs is the Stream Char obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Char -> Char) -> Stream Char -> Stream Char
intercalate :: Stream Char -> [Stream Char] -> Stream Char

-- | <i>O(n)</i> Take a character and place it between each of the
--   characters of a 'Stream Char'.
intersperse :: Char -> Stream Char -> Stream Char

-- | <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 :: Stream Char -> Stream Char

-- | <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 :: Stream Char -> Stream Char

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion.
--   
--   The first letter of the input is converted to title case, as is every
--   subsequent letter that immediately follows a non-letter. Every letter
--   that immediately follows another letter is converted to lower case.
--   
--   The result string may be longer than the input string. For example,
--   the Latin small ligature fl (U+FB02) is converted to the sequence Latin
--   capital letter F (U+0046) followed by Latin small letter l (U+006C).
--   
--   <i>Note</i>: this function does not take language or culture specific
--   rules into account. For instance, in English, different style guides
--   disagree on whether the book name "The Hill of the Red Fox" is
--   correctly title cased—but this function will capitalize <i>every</i>
--   word.
toTitle :: Stream Char -> Stream Char

-- | <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 :: Stream Char -> Stream Char
justifyLeftI :: Integral a => a -> Char -> Stream Char -> Stream Char

-- | foldl, applied to a binary operator, a starting value (typically the
--   left-identity of the operator), and a Stream, reduces the Stream using
--   the binary operator, from left to right.
foldl :: (b -> Char -> b) -> b -> Stream Char -> b

-- | A strict version of foldl.
foldl' :: (b -> Char -> b) -> b -> Stream Char -> b

-- | foldl1 is a variant of foldl that has no starting value argument, and
--   thus must be applied to non-empty Streams.
foldl1 :: (Char -> Char -> Char) -> Stream Char -> Char

-- | A strict version of foldl1.
foldl1' :: (Char -> Char -> Char) -> Stream Char -> Char

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a stream, reduces
--   the stream using the binary operator, from right to left.
foldr :: (Char -> b -> b) -> b -> Stream Char -> b

-- | foldr1 is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty streams. Subject to
--   array fusion.
foldr1 :: (Char -> Char -> Char) -> Stream Char -> Char

-- | <i>O(n)</i> Concatenate a list of streams. Subject to array fusion.
concat :: [Stream Char] -> Stream Char

-- | Map a function over a stream that results in a stream and concatenate
--   the results.
concatMap :: (Char -> Stream Char) -> Stream Char -> Stream Char

-- | <i>O(n)</i> any <tt>p </tt>xs determines if any character in the
--   stream <tt>xs</tt> satisifes the predicate <tt>p</tt>.
any :: (Char -> Bool) -> Stream Char -> Bool

-- | <i>O(n)</i> all <tt>p </tt>xs determines if all characters in the
--   <tt>Text</tt> <tt>xs</tt> satisify the predicate <tt>p</tt>.
all :: (Char -> Bool) -> Stream Char -> Bool

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

-- | <i>O(n)</i> minimum returns the minimum value from a <tt>Text</tt>,
--   which must be non-empty.
minimum :: Stream Char -> Char
scanl :: (Char -> Char -> Char) -> Char -> Stream Char -> Stream Char
replicateCharI :: Integral a => a -> Char -> Stream Char
replicateI :: Int64 -> Stream Char -> Stream Char

-- | <i>O(n)</i>, where <tt>n</tt> is the length of the result. The unfoldr
--   function is analogous to the List <a>unfoldr</a>. unfoldr builds a
--   stream from a seed value. The function takes the element and returns
--   Nothing if it is done producing the stream or returns Just (a,b), in
--   which case, a is the next Char in the string, and b is the seed value
--   for further production.
unfoldr :: (a -> Maybe (Char, a)) -> a -> Stream Char

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrNI</a> builds a stream from
--   a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrNI</a>. This function is more efficient
--   than <a>unfoldr</a> when the length of the result is known.
unfoldrNI :: Integral a => a -> (b -> Maybe (Char, b)) -> b -> Stream Char

-- | <i>O(n)</i> take n, applied to a stream, returns the prefix of the
--   stream of length <tt>n</tt>, or the stream itself if <tt>n</tt> is
--   greater than the length of the stream.
take :: Integral a => a -> Stream Char -> Stream Char

-- | <i>O(n)</i> drop n, applied to a stream, returns the suffix of the
--   stream after the first <tt>n</tt> characters, or the empty stream if
--   <tt>n</tt> is greater than the length of the stream.
drop :: Integral a => a -> Stream Char -> Stream Char

-- | takeWhile, applied to a predicate <tt>p</tt> and a stream, returns the
--   longest prefix (possibly empty) of elements that satisfy p.
takeWhile :: (Char -> Bool) -> Stream Char -> Stream Char

-- | dropWhile <tt>p </tt>xs returns the suffix remaining after takeWhile
--   <tt>p </tt>xs.
dropWhile :: (Char -> Bool) -> Stream Char -> Stream Char

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

-- | <i>O(n)</i> elem is the stream membership predicate.
elem :: Char -> Stream Char -> Bool

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

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

-- | <i>O(n)</i> Stream index (subscript) operator, starting from 0.
indexI :: Integral a => Stream Char -> a -> Char

-- | The <a>findIndexI</a> function takes a predicate and a stream and
--   returns the index of the first element in the stream satisfying the
--   predicate.
findIndexI :: Integral a => (Char -> Bool) -> Stream Char -> Maybe a

-- | <i>O(n)</i> The <a>countCharI</a> function returns the number of times
--   the query element appears in the given stream.
countCharI :: Integral a => Char -> Stream Char -> a

-- | zipWith generalises <tt>zip</tt> by zipping with the function given as
--   the first argument, instead of a tupling function.
zipWith :: (a -> a -> b) -> Stream a -> Stream a -> Stream b


-- | A module containing unsafe <a>Text</a> operations, for very very
--   careful use in heavily tested code.
module Data.Text.Unsafe

-- | Allow an <a>ST</a> computation to be deferred lazily. When passed an
--   action of type <a>ST</a> <tt>s</tt> <tt>a</tt>, the action will only
--   be performed when the value of <tt>a</tt> is demanded.
--   
--   This function is identical to the normal unsafeInterleaveST, but is
--   inlined and hence faster.
--   
--   <i>Note</i>: This operation is highly unsafe, as it can introduce
--   externally visible non-determinism into an <a>ST</a> action.
inlineInterleaveST :: ST s a -> ST s a

-- | Just like unsafePerformIO, but we inline it. Big performance gains as
--   it exposes lots of things to further inlining. <i>Very unsafe</i>. In
--   particular, you should do no memory allocation inside an
--   <a>inlinePerformIO</a> block. On Hugs this is just
--   <tt>unsafePerformIO</tt>.
inlinePerformIO :: IO a -> a

-- | This version of <a>unsafePerformIO</a> is more efficient because it
--   omits the check that the IO is only being performed by a single
--   thread. Hence, when you use <a>unsafeDupablePerformIO</a>, there is a
--   possibility that the IO action may be performed multiple times (on a
--   multiprocessor), and you should therefore ensure that it gives the
--   same results each time. It may even happen that one of the duplicated
--   IO actions is only run partially, and then interrupted in the middle
--   without an exception being raised. Therefore, functions like
--   <a>bracket</a> cannot be used safely within
--   <a>unsafeDupablePerformIO</a>.
--   
--   <i>Since: 4.4.0.0</i>
unsafeDupablePerformIO :: IO a -> a
data Iter
Iter :: {-# UNPACK #-} !Char -> {-# UNPACK #-} !Int -> Iter

-- | <i>O(1)</i> Iterate (unsafely) one step forwards through a UTF-16
--   array, returning the current character and the delta to add to give
--   the next offset to iterate at.
iter :: Text -> Int -> Iter

-- | <i>O(1)</i> Iterate one step through a UTF-16 array, returning the
--   delta to add to give the next offset to iterate at.
iter_ :: Text -> Int -> Int

-- | <i>O(1)</i> Iterate one step backwards through a UTF-16 array,
--   returning the current character and the delta to add (i.e. a negative
--   number) to give the next offset to iterate at.
reverseIter :: Text -> Int -> (Char, Int)

-- | <i>O(1)</i> Iterate one step backwards through a UTF-16 array,
--   returning the delta to add (i.e. a negative number) to give the next
--   offset to iterate at.
reverseIter_ :: Text -> Int -> Int

-- | <i>O(1)</i> A variant of <a>head</a> for non-empty <a>Text</a>.
--   <a>unsafeHead</a> omits the check for the empty case, so there is an
--   obligation on the programmer to provide a proof that the <a>Text</a>
--   is non-empty.
unsafeHead :: Text -> Char

-- | <i>O(1)</i> A variant of <a>tail</a> for non-empty <a>Text</a>.
--   <a>unsafeTail</a> omits the check for the empty case, so there is an
--   obligation on the programmer to provide a proof that the <a>Text</a>
--   is non-empty.
unsafeTail :: Text -> Text

-- | <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(1)</i> Unchecked take of <tt>k</tt> <tt>Word16</tt>s from the
--   front of a <a>Text</a>.
takeWord16 :: Int -> Text -> Text

-- | <i>O(1)</i> Unchecked drop of <tt>k</tt> <tt>Word16</tt>s from the
--   front of a <a>Text</a>.
dropWord16 :: Int -> Text -> Text


module Data.Text.Internal.Private
runText :: (forall s. (MArray s -> Int -> ST s Text) -> ST s Text) -> Text
span_ :: (Char -> Bool) -> Text -> (# Text, Text #)


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Text manipulation functions represented as fusible operations over
--   streams.
module Data.Text.Internal.Fusion
data Stream a
Stream :: (s -> Step s a) -> !s -> !Size -> Stream a
data Step s a
Done :: Step s a
Skip :: !s -> Step s a
Yield :: !a -> !s -> Step s a

-- | <i>O(n)</i> Convert a <a>Text</a> into a 'Stream Char'.
stream :: Text -> Stream Char

-- | <i>O(n)</i> Convert a 'Stream Char' into a <a>Text</a>.
unstream :: Stream Char -> Text

-- | <i>O(n)</i> Convert a <a>Text</a> into a 'Stream Char', but iterate
--   backwards.
reverseStream :: Text -> Stream Char
length :: Stream Char -> Int

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

-- | <i>O(n)</i> Perform the equivalent of <tt>scanr</tt> over a list, only
--   with the input and result reversed.
reverseScanr :: (Char -> Char -> Char) -> Char -> Stream Char -> Stream Char

-- | <i>O(n)</i> Like a combination of <tt>map</tt> and <tt>foldl'</tt>.
--   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>.
mapAccumL :: (a -> Char -> (a, Char)) -> a -> Stream Char -> (a, Text)

-- | <i>O(n)</i> Like <tt>unfoldr</tt>, <a>unfoldrN</a> builds a stream
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <tt>unfoldr</tt> when the length of the result is known.
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> Stream Char

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

-- | The <a>findIndex</a> function takes a predicate and a stream and
--   returns the index of the first element in the stream satisfying the
--   predicate.
findIndex :: (Char -> Bool) -> Stream Char -> Maybe Int

-- | <i>O(n)</i> The <tt>count</tt> function returns the number of times
--   the query element appears in the given stream.
countChar :: Char -> Stream Char -> Int


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Use at your own risk!
--   
--   Fusible <a>Stream</a>-oriented functions for converting between
--   <tt>Text</tt> and several common encodings.
module Data.Text.Internal.Encoding.Fusion.Common
restreamUtf16LE :: Stream Char -> Stream Word8
restreamUtf16BE :: Stream Char -> Stream Word8
restreamUtf32LE :: Stream Char -> Stream Word8
restreamUtf32BE :: Stream Char -> Stream Word8


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Basic UTF-8 validation and character manipulation.
module Data.Text.Internal.Encoding.Utf8
ord2 :: Char -> (Word8, Word8)
ord3 :: Char -> (Word8, Word8, Word8)
ord4 :: Char -> (Word8, Word8, Word8, Word8)
chr2 :: Word8 -> Word8 -> Char
chr3 :: Word8 -> Word8 -> Word8 -> Char
chr4 :: Word8 -> Word8 -> Word8 -> Word8 -> Char
validate1 :: Word8 -> Bool
validate2 :: Word8 -> Word8 -> Bool
validate3 :: Word8 -> Word8 -> Word8 -> Bool
validate4 :: Word8 -> Word8 -> Word8 -> Word8 -> Bool


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Fusible <a>Stream</a>-oriented functions for converting between
--   <tt>Text</tt> and several common encodings.
module Data.Text.Internal.Encoding.Fusion

-- | <i>Deprecated: Do not use this function</i>
streamASCII :: ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   UTF-8 encoding.
streamUtf8 :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   little endian UTF-16 encoding.
streamUtf16LE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   big endian UTF-16 encoding.
streamUtf16BE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   little endian UTF-32 encoding.
streamUtf32LE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   big endian UTF-32 encoding.
streamUtf32BE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>Stream</a> <a>Word8</a> to a
--   <a>ByteString</a>.
unstream :: Stream Word8 -> ByteString


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Fusible <a>Stream</a>-oriented functions for converting between lazy
--   <tt>Text</tt> and several common encodings.
module Data.Text.Internal.Lazy.Encoding.Fusion

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a 'Stream Char',
--   using UTF-8 encoding.
streamUtf8 :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   little endian UTF-16 encoding.
streamUtf16LE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   big endian UTF-16 encoding.
streamUtf16BE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   little endian UTF-32 encoding.
streamUtf32LE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>ByteString</a> into a 'Stream Char', using
--   big endian UTF-32 encoding.
streamUtf32BE :: OnDecodeError -> ByteString -> Stream Char

-- | <i>O(n)</i> Convert a <a>Stream</a> <a>Word8</a> to a lazy
--   <a>ByteString</a>.
unstream :: Stream Word8 -> ByteString


-- | Fast substring search for <a>Text</a>, based on work by Boyer, Moore,
--   Horspool, Sunday, and Lundh.
--   
--   References:
--   
--   <ul>
--   <li>R. S. Boyer, J. S. Moore: A Fast String Searching Algorithm.
--   Communications of the ACM, 20, 10, 762-772 (1977)</li>
--   <li>R. N. Horspool: Practical Fast Searching in Strings. Software -
--   Practice and Experience 10, 501-506 (1980)</li>
--   <li>D. M. Sunday: A Very Fast Substring Search Algorithm.
--   Communications of the ACM, 33, 8, 132-142 (1990)</li>
--   <li>F. Lundh: The Fast Search Algorithm.
--   <a>http://effbot.org/zone/stringlib.htm</a> (2006)</li>
--   </ul>
module Data.Text.Internal.Search

-- | <i>O(n+m)</i> Find the offsets of all non-overlapping indices of
--   <tt>needle</tt> within <tt>haystack</tt>. The offsets returned
--   represent uncorrected indices in the low-level "needle" array, to
--   which its offset must be added.
--   
--   In (unlikely) bad cases, this algorithm's complexity degrades towards
--   <i>O(n*m)</i>.
indices :: Text -> Text -> [Int]


-- | 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 <a>the
--   text-icu package</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 <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

-- | <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 non-overlapping occurrence of
--   <tt>needle</tt> in <tt>haystack</tt> with <tt>replacement</tt>.
--   
--   This function behaves as though it was defined as follows:
--   
--   <pre>
--   replace needle replacement haystack =
--     <a>intercalate</a> replacement (<a>splitOn</a> needle haystack)
--   </pre>
--   
--   As this suggests, each occurrence is replaced exactly once. So if
--   <tt>needle</tt> occurs in <tt>replacement</tt>, that occurrence will
--   <i>not</i> itself be replaced recursively:
--   
--   <pre>
--   replace "oo" "foo" "oo" == "foo"
--   </pre>
--   
--   In cases where several instances of <tt>needle</tt> overlap, only the
--   first one will be replaced:
--   
--   <pre>
--   replace "ofo" "bar" "ofofo" == "barfo"
--   </pre>
--   
--   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. Subject to fusion.
--   
--   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. Subject to fusion.
--   
--   The result string may be longer than the input string. For instance,
--   "İ" (Latin capital letter I with dot above, U+0130) maps to the
--   sequence "i" (Latin small letter i, U+0069) followed by " ̇"
--   (combining dot above, U+0307).
toLower :: Text -> Text

-- | <i>O(n)</i> Convert a string to upper case, using simple case
--   conversion. Subject to fusion.
--   
--   The result string may be longer than the input string. For instance,
--   the German "ß" (eszett, U+00DF) maps to the two-letter sequence "SS".
toUpper :: Text -> Text

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion. Subject to fusion.
--   
--   The first letter of the input is converted to title case, as is every
--   subsequent letter that immediately follows a non-letter. Every letter
--   that immediately follows another letter is converted to lower case.
--   
--   The result string may be longer than the input string. For example,
--   the Latin small ligature fl (U+FB02) is converted to the sequence Latin
--   capital letter F (U+0046) followed by Latin small letter l (U+006C).
--   
--   <i>Note</i>: this function does not take language or culture specific
--   rules into account. For instance, in English, different style guides
--   disagree on whether the book name "The Hill of the Red Fox" is
--   correctly title cased—but this function will capitalize <i>every</i>
--   word.
toTitle :: 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>takeEnd</a> <tt>n</tt> <tt>t</tt> returns the suffix
--   remaining after taking <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   takeEnd 3 "foobar" == "bar"
--   </pre>
takeEnd :: 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>dropEnd</a> <tt>n</tt> <tt>t</tt> returns the prefix
--   remaining after dropping <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   dropEnd 3 "foobar" == "foo"
--   </pre>
dropEnd :: 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 (which cannot be empty), 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>
--   
--   (Note: the string <tt>s</tt> to split on above cannot be empty.)
--   
--   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

-- | <i>O(n)</i> Make a distinct copy of the given string, sharing no
--   storage with the original string.
--   
--   As an example, suppose you read a large string, of which you need only
--   a small portion. If you do not use <a>copy</a>, the entire original
--   array will be kept alive in memory by the smaller string. Making a
--   copy "breaks the link" to the original array, allowing it to be
--   garbage collected if there are no other live references to it.
copy :: Text -> Text
instance Data Text
instance NFData Text
instance IsList Text
instance IsString Text
instance Monoid Text
instance Read Text
instance Show Text
instance Ord Text
instance Eq 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.

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

-- | Decode a <a>ByteString</a> containing Latin-1 (aka ISO-8859-1) encoded
--   text.
--   
--   <a>decodeLatin1</a> is semantically equivalent to <tt>Data.Text.pack .
--   Data.ByteString.Char8.unpack</tt>
decodeLatin1 :: 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

-- | Decode, in a stream oriented way, 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 (either by this function or a continuation) that cannot be
--   caught in pure code. For more control over the handling of invalid
--   data, use <a>streamDecodeUtf8With</a>.
streamDecodeUtf8 :: ByteString -> Decoding

-- | Decode, in a stream oriented way, a <a>ByteString</a> containing UTF-8
--   encoded text.
streamDecodeUtf8With :: OnDecodeError -> ByteString -> Decoding

-- | A stream oriented decoding result.
data Decoding
Some :: Text -> ByteString -> (ByteString -> Decoding) -> Decoding

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

-- | Encode text to a ByteString <a>Builder</a> using UTF-8 encoding.
encodeUtf8Builder :: Text -> Builder

-- | Encode text using UTF-8 encoding and escape the ASCII characters using
--   a <a>BoundedPrim</a>.
--   
--   Use this function is to implement efficient encoders for text-based
--   formats like JSON or HTML.
encodeUtf8BuilderEscaped :: BoundedPrim Word8 -> Text -> Builder
instance Eq CodePoint
instance Show CodePoint
instance Num CodePoint
instance Storable CodePoint
instance Eq DecoderState
instance Show DecoderState
instance Num DecoderState
instance Storable DecoderState
instance Show Decoding


-- | 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(n)</i> Decode a C string with explicit length, which is assumed
--   to have been encoded as UTF-8. If decoding fails, a
--   <tt>UnicodeException</tt> is thrown.
peekCStringLen :: CStringLen -> IO Text

-- | Marshal a <a>Text</a> into a C string encoded as UTF-8 in temporary
--   storage, with explicit length information. The encoded string may
--   contain NUL bytes, and is not followed by a trailing NUL byte.
--   
--   The temporary storage is freed when the subcomputation terminates
--   (either normally or via an exception), so the pointer to the temporary
--   storage must <i>not</i> be used after this function returns.
withCStringLen :: Text -> (CStringLen -> IO a) -> IO a

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


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Low-level support for text I/O.
module Data.Text.Internal.IO

-- | Read a single line of input from a handle, constructing a list of
--   decoded chunks as we go. When we're done, transform them into the
--   destination type.
hGetLineWith :: ([Text] -> t) -> Handle -> IO t

-- | Read a single chunk of strict text from a buffer. Used by both the
--   strict and lazy implementations of hGetContents.
readChunk :: Handle__ -> CharBuffer -> IO 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

-- | <i>Experimental.</i> Read a single chunk of strict text from a
--   <a>Handle</a>. The size of the chunk depends on the amount of input
--   currently buffered.
--   
--   This function blocks only if there is no data available, and EOF has
--   not yet been reached. Once EOF is reached, this function returns an
--   empty string instead of throwing an exception.
hGetChunk :: 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 ()


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   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.
module Data.Text.Internal.Lazy
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


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Core stream fusion functionality for text.
module Data.Text.Internal.Lazy.Fusion

-- | <i>O(n)</i> Convert a <a>Text</a> into a 'Stream Char'.
stream :: Text -> Stream Char

-- | <i>O(n)</i> Convert a 'Stream Char' into a <a>Text</a>, using
--   <a>defaultChunkSize</a>.
unstream :: Stream Char -> Text

-- | <i>O(n)</i> Convert a 'Stream Char' into a <a>Text</a>, using the
--   given chunk size.
unstreamChunks :: Int -> Stream Char -> Text

-- | <i>O(n)</i> Returns the number of characters in a text.
length :: Stream Char -> Int64

-- | <i>O(n)</i> Like <tt>unfoldr</tt>, <a>unfoldrN</a> builds a stream
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <tt>unfoldr</tt> when the length of the result is known.
unfoldrN :: Int64 -> (a -> Maybe (Char, a)) -> a -> Stream Char

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

-- | <i>O(n)</i> The <tt>count</tt> function returns the number of times
--   the query element appears in the given stream.
countChar :: Char -> Stream Char -> Int64


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Fast substring search for lazy <a>Text</a>, based on work by Boyer,
--   Moore, Horspool, Sunday, and Lundh. Adapted from the strict
--   implementation.
module Data.Text.Internal.Lazy.Search

-- | <i>O(n+m)</i> Find the offsets of all non-overlapping indices of
--   <tt>needle</tt> within <tt>haystack</tt>.
--   
--   This function is strict in <tt>needle</tt>, and lazy (as far as
--   possible) in the chunks of <tt>haystack</tt>.
--   
--   In (unlikely) bad cases, this algorithm's complexity degrades towards
--   <i>O(n*m)</i>.
indices :: Text -> Text -> [Int64]


-- | This module has been renamed to <a>Lazy</a>. This name for the module
--   will be removed in the next major release.

-- | <i>Deprecated: Use Data.Text.Internal.Lazy instead</i>
module Data.Text.Lazy.Internal


-- | 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/c)</i> 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 non-overlapping occurrence of
--   <tt>needle</tt> in <tt>haystack</tt> with <tt>replacement</tt>.
--   
--   This function behaves as though it was defined as follows:
--   
--   <pre>
--   replace needle replacement haystack =
--     <a>intercalate</a> replacement (<a>splitOn</a> needle haystack)
--   </pre>
--   
--   As this suggests, each occurrence is replaced exactly once. So if
--   <tt>needle</tt> occurs in <tt>replacement</tt>, that occurrence will
--   <i>not</i> itself be replaced recursively:
--   
--   <pre>
--   replace "oo" "foo" "oo" == "foo"
--   </pre>
--   
--   In cases where several instances of <tt>needle</tt> overlap, only the
--   first one will be replaced:
--   
--   <pre>
--   replace "ofo" "bar" "ofofo" == "barfo"
--   </pre>
--   
--   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. Subject to fusion.
--   
--   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. Subject to fusion.
--   
--   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. Subject to fusion.
--   
--   The result string may be longer than the input string. For instance,
--   the German eszett (U+00DF) maps to the two-letter sequence SS.
toUpper :: Text -> Text

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion. Subject to fusion.
--   
--   The first letter of the input is converted to title case, as is every
--   subsequent letter that immediately follows a non-letter. Every letter
--   that immediately follows another letter is converted to lower case.
--   
--   The result string may be longer than the input string. For example,
--   the Latin small ligature fl (U+FB02) is converted to the sequence Latin
--   capital letter F (U+0046) followed by Latin small letter l (U+006C).
--   
--   <i>Note</i>: this function does not take language or culture specific
--   rules into account. For instance, in English, different style guides
--   disagree on whether the book name "The Hill of the Red Fox" is
--   correctly title cased—but this function will capitalize <i>every</i>
--   word.
toTitle :: 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>takeEnd</a> <tt>n</tt> <tt>t</tt> returns the suffix
--   remaining after taking <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   takeEnd 3 "foobar" == "bar"
--   </pre>
takeEnd :: 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>dropEnd</a> <tt>n</tt> <tt>t</tt> returns the prefix
--   remaining after dropping <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   dropEnd 3 "foobar" == "foo"
--   </pre>
dropEnd :: 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 (which cannot be an empty string), 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>
--   
--   (Note: the string <tt>s</tt> to split on above cannot be empty.)
--   
--   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 IsList Text
instance IsString Text
instance Monoid Text
instance Read Text
instance Show Text
instance Ord Text
instance Eq Text


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   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.Internal.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
append' :: Builder -> Builder -> Builder

-- | Ensure that there are at least <tt>n</tt> many elements available.
ensureFree :: Int -> Builder

-- | Ensure that <tt>n</tt> many elements are available, and then use
--   <tt>f</tt> to write some elements into the memory.
writeN :: Int -> (forall s. MArray s -> Int -> ST s ()) -> Builder
instance Ord Builder
instance Eq Builder
instance Show Builder
instance IsString Builder
instance Monoid Builder


-- | 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 <tt>mappend</tt>, 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. Or,
--   equivalently, prefer
--   
--   <pre>
--   singleton 'a' &lt;&gt; singleton 'b' &lt;&gt; singleton 'c'
--   </pre>
--   
--   since the <tt>&lt;&gt;</tt> from recent versions of <a>Monoid</a>
--   associates to the right.
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


-- | <i>Warning</i>: this is an internal module, and does not have a stable
--   API or name. Functions in this module may not check or enforce
--   preconditions expected by public modules. Use at your own risk!
--   
--   Useful functions and combinators.
module Data.Text.Internal.Builder.Functions

-- | The normal <a>mappend</a> function with right associativity instead of
--   left.
(<>) :: Builder -> Builder -> Builder

-- | Unsafe conversion for decimal digits.
i2d :: Int -> Char

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


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


-- | 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 = IReader Text a

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


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

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

-- | Decode a <tt>ByteString</tt> containing Latin-1 (aka ISO-8859-1)
--   encoded text.
decodeLatin1 :: 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
encodeUtf8Builder :: Text -> Builder
encodeUtf8BuilderEscaped :: BoundedPrim Word8 -> Text -> Builder


-- | 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 = IReader Text a

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