-- 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).
--   
--   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 (see
--   <a>Data.Text</a>). It also provides a range of functions for
--   converting <a>Text</a> values to and from <a>ByteStrings</a>, using
--   several standard encodings (see <a>Data.Text.Encoding</a>).
--   
--   Efficient locale-sensitive support for text IO is also supported (see
--   <a>Data.Text.IO</a>).
--   
--   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>
--   
--   <h2>ICU Support</h2>
--   
--   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
--   <a>text-icu package</a> based on the well-respected and liberally
--   licensed <a>ICU library</a>.
@package text
@version 2.1.3


-- | 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 qualified naming.
module Data.Text.Array

-- | Immutable array type.
type Array = ByteArray
pattern ByteArray :: () => ByteArray# -> ByteArray

-- | Mutable array type, for use in the ST monad.
type MArray = MutableByteArray
pattern MutableByteArray :: () => MutableByteArray# s -> MutableByteArray s

resizeM :: MArray s -> Int -> ST s (MArray s)

shrinkM :: MArray s -> Int -> ST 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 :: Int -> MArray s -> Int -> Array -> Int -> ST s ()

-- | Copy from pointer.
copyFromPointer :: MArray s -> Int -> Ptr Word8 -> Int -> ST s ()

-- | Copy to pointer.
copyToPointer :: Array -> Int -> Ptr Word8 -> 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

-- | Compare portions of two arrays. No bounds checking is performed.
compare :: Array -> Int -> Array -> Int -> Int -> Ordering

-- | 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 -> [Word8]

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

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

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

newFilled :: Int -> 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 -> Word8 -> ST s ()

tile :: MArray s -> Int -> ST s ()

getSizeofMArray :: MArray s -> ST s Int


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

-- | <i>Deprecated: This constructor is never used, and will be
--   removed.</i>
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.

-- | <i>Deprecated: This exception is never used in practice, and will be
--   removed.</i>
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.

-- | <i>Deprecated: This function always throws an exception, and will be
--   removed.</i>
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 GHC.Classes.Eq Data.Text.Encoding.Error.UnicodeException
instance GHC.Internal.Exception.Type.Exception Data.Text.Encoding.Error.UnicodeException
instance Control.DeepSeq.NFData Data.Text.Encoding.Error.UnicodeException
instance GHC.Internal.Show.Show Data.Text.Encoding.Error.UnicodeException

module Data.Text.Internal.ArrayUtils
memchr :: ByteArray# -> Int -> Int -> Word8 -> Int

module Data.Text.Internal.Builder.Int.Digits
digits :: 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!
module Data.Text.Internal.Builder.RealFloat.Functions
roundTo :: Int -> [Int] -> (Int, [Int])

module Data.Text.Internal.ByteStringCompat
mkBS :: ForeignPtr Word8 -> Int -> ByteString
withBS :: ByteString -> (ForeignPtr Word8 -> Int -> r) -> r


-- | <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!
--   
--   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!
--   
--   Basic UTF-8 validation and character manipulation.
module Data.Text.Internal.Encoding.Utf8

utf8Length :: Char -> Int

utf8LengthByLeader :: Word8 -> Int
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
newtype DecoderState
DecoderState :: Word8 -> DecoderState
utf8AcceptState :: DecoderState
utf8RejectState :: DecoderState
updateDecoderState :: Word8 -> DecoderState -> DecoderState

data DecoderResult
Accept :: !Char -> DecoderResult
Incomplete :: !DecoderState -> !CodePoint -> DecoderResult
Reject :: DecoderResult
newtype CodePoint
CodePoint :: Int -> CodePoint

utf8DecodeStart :: Word8 -> DecoderResult

utf8DecodeContinue :: Word8 -> DecoderState -> CodePoint -> DecoderResult
instance GHC.Classes.Eq Data.Text.Internal.Encoding.Utf8.DecoderState
instance GHC.Internal.Show.Show Data.Text.Internal.Encoding.Utf8.DecoderState

module Data.Text.Internal.Fusion.CaseMapping
unI64 :: Int64 -> Int64#
upperMapping :: Char# -> Int64#
lowerMapping :: Char# -> Int64#
titleMapping :: Char# -> Int64#
foldMapping :: Char# -> Int64#

module Data.Text.Internal.PrimCompat
word8ToWord# :: Word8# -> Word#
wordToWord8# :: Word# -> Word8#
word16ToWord# :: Word16# -> Word#
wordToWord16# :: Word# -> Word16#
wordToWord32# :: Word# -> Word32#
word32ToWord# :: Word32# -> Word#


-- | Common internal functions 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 GHC.Internal.Base.Applicative (Data.Text.Internal.Read.IParser t)
instance GHC.Internal.Base.Functor (Data.Text.Internal.Read.IParser t)
instance GHC.Internal.Base.Monad (Data.Text.Internal.Read.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!
--   
--   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.
inlinePerformIO :: IO a -> a
unsafeWithForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b


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

unsafeChr16 :: Word16 -> Char
unsafeChr8 :: Word8 -> Char
unsafeChr32 :: Word32 -> Char

-- | Write a character into the array at the given offset. Returns the
--   number of <a>Word8</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

-- | Type synonym for the strict flavour of <a>Text</a>.
type StrictText = Text

-- | Construct a <a>Text</a> without invisibly pinning its byte array in
--   memory if its length has dwindled to zero. It ensures that empty
--   <a>Text</a> values are shared.
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.
--   
--   Unicode <a>Surrogate</a> 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

-- | <i>O(n)</i> Appends one <a>Text</a> to the other by copying both of
--   them into a new <a>Text</a>.
append :: Text -> Text -> 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
infixl 7 `mul`

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

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

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

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>Text</a>. Performs
--   replacement on invalid scalar values, so <tt><a>unpack</a> .
--   <a>pack</a></tt> is not <a>id</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Text.unpack (pack "\55555")
--   "\65533"
--   </pre>
pack :: String -> 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!
module Data.Text.Internal.StrictBuilder

-- | A delayed representation of strict <a>Text</a>.
data StrictTextBuilder
StrictTextBuilder :: {-# UNPACK #-} !Int -> (forall s. () => MArray s -> Int -> ST s ()) -> StrictTextBuilder
[sbLength] :: StrictTextBuilder -> {-# UNPACK #-} !Int
[sbWrite] :: StrictTextBuilder -> forall s. () => MArray s -> Int -> ST s ()

-- | A delayed representation of strict <a>Text</a>.

-- | <i>Deprecated: Use StrictTextBuilder instead</i>
type StrictBuilder = StrictTextBuilder

-- | Use <a>StrictBuilder</a> to build <a>Text</a>.
toText :: StrictTextBuilder -> Text

fromChar :: Char -> StrictTextBuilder

-- | Copy <a>Text</a> in a <a>StrictBuilder</a>
fromText :: Text -> StrictTextBuilder

-- | Copy a <a>ByteString</a>.
--   
--   Unsafe: This may not be valid UTF-8 text.
unsafeFromByteString :: ByteString -> StrictTextBuilder

-- | Unsafe: This may not be valid UTF-8 text.
unsafeFromWord8 :: Word8 -> StrictTextBuilder
instance GHC.Internal.Base.Monoid Data.Text.Internal.StrictBuilder.StrictTextBuilder
instance GHC.Internal.Base.Semigroup Data.Text.Internal.StrictBuilder.StrictTextBuilder


-- | 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: <a>The Fast Search Algorithm</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>.
--   
--   In (unlikely) bad cases, this algorithm's complexity degrades towards
--   <i>O(n*m)</i>.
indices :: Text -> Text -> [Int]


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

-- | A size in UTF-8 code units (which is bytes).
data Size
exactSize :: Int -> Size
maxSize :: Int -> Size
betweenSize :: Int -> Int -> Size
unknownSize :: Size
unionSize :: Size -> Size -> Size

-- | The <a>Size</a> of the given code point.
charSize :: Char -> Size

-- | The <a>Size</a> of <tt>n</tt> code points.
codePointsSize :: Int -> Size
exactly :: Size -> Maybe Int

-- | 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 minimum size from a size hint, if possible.
lowerBound :: Int -> Size -> Int

-- | Determine the ordering relationship between two <a>Size</a>s, or
--   <a>Nothing</a> in the indeterminate case.
compareSize :: Size -> Size -> Maybe Ordering
isEmpty :: Size -> Bool
instance GHC.Classes.Eq Data.Text.Internal.Fusion.Size.Size
instance GHC.Internal.Num.Num Data.Text.Internal.Fusion.Size.Size
instance GHC.Internal.Show.Show Data.Text.Internal.Fusion.Size.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 #-} !Int64 -> CC s

-- | Strict pair.
data PairS a b
(:*:) :: !a -> !b -> PairS a b
infixl 2 :*:

-- | An intermediate result in a scan.
data Scan s
Scan1 :: {-# UNPACK #-} !Char -> !s -> Scan s
Scan2 :: {-# UNPACK #-} !Char -> !s -> Scan s

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

-- | Intermediate result in a processing pipeline.
data Step s a
Done :: Step s a
Skip :: !s -> Step s a
Yield :: !a -> !s -> Step s a

-- | A co-recursive type yielding a single element at a time depending on
--   the internal state it carries.
data Stream a
Stream :: (s -> Step s a) -> !s -> !Size -> Stream a

-- | The empty stream.
empty :: Stream a
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Internal.Fusion.Types.Stream a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Text.Internal.Fusion.Types.Stream 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!
--   
--   This module provides a common stream fusion interface for text. The
--   stream interface allows us to write text pipelines which do not
--   allocate intermediate text values. For example, we could guarantee no
--   intermediate text is allocated by writing the following:
--   
--   <pre>
--   getNucleotides :: <a>Text</a> -&gt; <a>Text</a>
--   getNucleotides =
--         <a>unstream</a>
--       . <a>filter</a> isNucleotide
--       . <a>toLower</a>
--       . <a>stream</a>
--     where
--       isNucleotide chr =
--         chr == 'a' ||
--         chr == 'c' ||
--         chr == 't' ||
--         chr == 'g'
--   </pre>
module Data.Text.Internal.Fusion.Common

-- | <i>O(1)</i> Convert a character into a <a>Stream</a>
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>singleton</a> = <a>singleton</a>
--   </pre>
singleton :: Char -> Stream Char

-- | <i>O(n)</i> Convert a list into a <a>Stream</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>streamList</a> = <a>pack</a>
--   </pre>
streamList :: [a] -> Stream a

-- | <i>O(n)</i> Convert a <a>Stream</a> into a list.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstreamList</a> . <a>stream</a> = <a>unpack</a>
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>streamCString#</a> addr# = <a>unpackCString#</a> addr#
--   </pre>
streamCString# :: Addr# -> Stream Char

-- | <i>O(n)</i> Adds a character to the front of a Stream Char.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>cons</a> c . <a>stream</a> = <a>cons</a> c
--   </pre>
cons :: Char -> Stream Char -> Stream Char

-- | <i>O(n)</i> Adds a character to the end of a stream.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>snoc</a> c . <a>stream</a> = <a>snoc</a> c
--   </pre>
snoc :: Stream Char -> Char -> Stream Char

-- | <i>O(n)</i> Appends one Stream to the other.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> (<a>append</a> (<a>stream</a> t1) (<a>stream</a> t2)) = <a>append</a> t1 t2
--   </pre>
append :: Stream Char -> Stream Char -> Stream Char

-- | <i>O(1)</i> Returns the first character of a <a>Stream</a>
--   <a>Char</a>, which must be non-empty. This is a partial function,
--   consider using <a>uncons</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>head</a> . <a>stream</a> = <a>head</a>
--   </pre>
head :: HasCallStack => Stream Char -> Char

-- | <i>O(1)</i> Returns the first character and remainder of a
--   <a>Stream</a> <a>Char</a>, or <a>Nothing</a> if empty.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>fmap</a> <a>fst</a> . <a>uncons</a> . <a>stream</a> = <a>fmap</a> <a>fst</a> . <a>uncons</a>
--   </pre>
--   
--   <pre>
--   <a>fmap</a> (<a>unstream</a> . <a>snd</a>) . <a>uncons</a> . <a>stream</a> = <a>fmap</a> <a>snd</a> . <a>uncons</a>
--   </pre>
uncons :: Stream Char -> Maybe (Char, Stream Char)

-- | <i>O(n)</i> Returns the last character of a <a>Stream</a> <a>Char</a>,
--   which must be non-empty.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>last</a> . <a>stream</a> = <a>last</a>
--   </pre>
last :: HasCallStack => Stream Char -> Char

-- | <i>O(1)</i> Returns all characters after the head of a <a>Stream</a>
--   <a>Char</a>, which must be non-empty. This is a partial function,
--   consider using <a>uncons</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>tail</a> . <a>stream</a> = <a>tail</a>
--   </pre>
tail :: HasCallStack => Stream Char -> Stream Char

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

-- | <i>O(1)</i> Tests whether a <a>Stream</a> <a>Char</a> is empty or not.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>null</a> . <a>stream</a> = <a>null</a>
--   </pre>
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.
--   
--   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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>isSingleton</a> . <a>stream</a> = <a>isSingleton</a>
--   </pre>
isSingleton :: Stream Char -> Bool

-- | <i>O(n)</i> <a>map</a> <tt>f </tt>xs is the <a>Stream</a> <a>Char</a>
--   obtained by applying <tt>f</tt> to each element of <tt>xs</tt>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>map</a> f . <a>stream</a> = <a>map</a> f
--   </pre>
map :: (Char -> Char) -> Stream Char -> Stream Char

-- | intercalate str strs inserts the stream str in between the streams
--   strs and concatenates the result.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>intercalate</a> s = <a>concat</a> . <a>intersperse</a> s
--   </pre>
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'.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>intersperse</a> c . <a>stream</a> = <a>intersperse</a> c
--   </pre>
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>
--   <a>toCaseFold</a> x == <a>toCaseFold</a> 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).
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>toLower</a> . <a>stream</a> = <a>toLower</a>
--   </pre>
toLower :: Stream Char -> Stream Char

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion.
--   
--   The first letter (as determined by <a>isLetter</a>) 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).
--   
--   This function is not idempotent. Consider lower-case letter <tt>ʼn</tt>
--   (U+0149 LATIN SMALL LETTER N PRECEDED BY APOSTROPHE). Then
--   <a>toTitle</a> <tt>"ʼn"</tt> = <tt>"ʼN"</tt>: the first (and the only)
--   letter of the input is converted to title case, becoming two letters.
--   Now <tt>ʼ</tt> (U+02BC MODIFIER LETTER APOSTROPHE) is a modifier
--   letter and as such is recognised as a letter by <a>isLetter</a>, so
--   <a>toTitle</a> <tt>"ʼN"</tt> = <tt>"'n"</tt>.
--   
--   <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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>toTitle</a> . <a>stream</a> = <a>toTitle</a>
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>toUpper</a> . <a>stream</a> = <a>toUpper</a>
--   </pre>
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 <a>Stream</a>, reduces the
--   <a>Stream</a> using the binary operator, from left to right.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldl</a> f z0 . <a>stream</a> = <a>foldl</a> f z0
--   </pre>
foldl :: (b -> Char -> b) -> b -> Stream Char -> b

-- | A strict version of foldl.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldl'</a> f z0 . <a>stream</a> = <a>foldl'</a> f z0
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldl1</a> f . <a>stream</a> = <a>foldl1</a> f
--   </pre>
foldl1 :: HasCallStack => (Char -> Char -> Char) -> Stream Char -> Char

-- | A strict version of foldl1.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldl1'</a> f . <a>stream</a> = <a>foldl1'</a> f
--   </pre>
foldl1' :: HasCallStack => (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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldr</a> f z0 . <a>stream</a> = <a>foldr</a> f z0
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldr1</a> f . <a>stream</a> = <a>foldr1</a> f
--   </pre>
foldr1 :: HasCallStack => (Char -> Char -> Char) -> Stream Char -> Char

-- | A monadic version of <a>foldl</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>foldlM'</a> f z0 . <a>stream</a> = <a>foldlM'</a> f z0
--   </pre>
foldlM' :: Monad m => (b -> Char -> m b) -> b -> Stream Char -> m b

-- | <i>O(n)</i> Concatenate a list of streams.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>concat</a> . <a>fmap</a> <a>stream</a>  = <a>concat</a>
--   </pre>
concat :: [Stream Char] -> Stream Char

-- | Map a function over a stream that results in a stream and concatenate
--   the results.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>concatMap</a> (<a>stream</a> . f) . <a>stream</a> = <a>concatMap</a> f
--   </pre>
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> satisfies the predicate <tt>p</tt>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>any</a> f . <a>stream</a> = <a>any</a> f
--   </pre>
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> satisfy the predicate <tt>p</tt>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>all</a> f . <a>stream</a> = <a>all</a> f
--   </pre>
all :: (Char -> Bool) -> Stream Char -> Bool

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

-- | <i>O(n)</i> minimum returns the minimum value from a <tt>Text</tt>,
--   which must be non-empty.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>minimum</a> . <a>stream</a> = <a>minimum</a>
--   </pre>
minimum :: HasCallStack => Stream Char -> Char

-- | <i>O(n)</i> <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   stream of successive reduced values from the left. Conceptually, if we
--   write the input stream as a list then we have:
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z 'f' x1, (z 'f' x1) 'f' x2, ...]
--   </pre>
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>head</a> (<a>scanl</a> f z xs) = z
--   </pre>
--   
--   <pre>
--   <a>last</a> (<a>scanl</a> f z xs) = <a>foldl</a> f z xs
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> Stream Char -> Stream Char

-- | <i>O(n)</i> <a>replicateCharI</a> <tt>n</tt> <tt>c</tt> is a
--   <a>Stream</a> <a>Char</a> of length <tt>n</tt> with <tt>c</tt> the
--   value of every element.
replicateCharI :: Integral a => a -> Char -> Stream Char

-- | <i>O(n*m)</i> <a>replicateI</a> <tt>n</tt> <tt>t</tt> is a
--   <a>Stream</a> <a>Char</a> consisting of the input <tt>t</tt> repeated
--   <tt>n</tt> times.
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>unfoldr</a> f z = <a>unfoldr</a> f z
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> (<a>unfoldrNI</a> n f z) = <a>unfoldrN</a> n f z
--   </pre>
unfoldrNI :: Integral a => a -> (b -> Maybe (Char, b)) -> b -> Stream Char

-- | <i>O(n)</i> <tt><a>take</a> n</tt>, 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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>take</a> n . <a>stream</a> = <a>take</a> n
--   </pre>
take :: Integral a => a -> Stream Char -> Stream Char

-- | <i>O(n)</i> <tt><a>drop</a> n</tt>, 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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>drop</a> n . <a>stream</a> = <a>drop</a> n
--   </pre>
drop :: Integral a => a -> Stream Char -> Stream Char

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

-- | <tt><a>dropWhile</a> p xs</tt> returns the suffix remaining after
--   <tt><a>takeWhile</a> p xs</tt>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>dropWhile</a> p . <a>stream</a> = <a>dropWhile</a> p
--   </pre>
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> if and only if the first is a prefix of the
--   second.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>isPrefixOf</a> (<a>stream</a> t1) (<a>stream</a> t2) = <a>isPrefixOf</a> t1 t2
--   </pre>
isPrefixOf :: Eq a => Stream a -> Stream a -> Bool

-- | <i>O(n)</i> <a>elem</a> is the stream membership predicate.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>elem</a> c . <a>stream</a> = <a>elem</a> c
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>filter</a> p . <a>stream</a> = <a>filter</a> p
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>findBy</a> p . <a>stream</a> = <a>find</a> p
--   </pre>
findBy :: (Char -> Bool) -> Stream Char -> Maybe Char

-- | <i>O(n)</i> Stream index (subscript) operator, starting from 0.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>indexI</a> (<a>stream</a> t) n = <a>index</a> t n
--   </pre>
indexI :: (HasCallStack, 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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>findIndexI</a> p . <a>stream</a> = <a>findIndex</a> p
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>countCharI</a> c . <a>stream</a> = <a>countChar</a> c
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> (<a>zipWith</a> f (<a>stream</a> t1) (<a>stream</a> t2)) = <a>zipWith</a> f t1 t2
--   </pre>
zipWith :: (a -> a -> b) -> Stream a -> Stream a -> Stream b


-- | <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!
--   
--   Internals of <a>Data.Text.Encoding</a>.
module Data.Text.Internal.Encoding

-- | Validate a <a>ByteString</a> as UTF-8-encoded text. To be continued
--   using <a>validateUtf8More</a>.
--   
--   See also <a>validateUtf8More</a> for details on the result of this
--   function.
--   
--   <pre>
--   <a>validateUtf8Chunk</a> = <a>validateUtf8More</a> <a>startUtf8State</a>
--   </pre>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   <a>validateUtf8Chunk</a> chunk = (n, ms)
--   </pre>
--   
--   <ul>
--   <li>The prefix is valid UTF-8. In particular, it should be accepted by
--   this validation:<pre><a>validateUtf8Chunk</a> (<a>take</a> n chunk) =
--   (n, Just <a>startUtf8State</a>) </pre></li>
--   </ul>
validateUtf8Chunk :: ByteString -> (Int, Maybe Utf8State)

-- | Validate another <a>ByteString</a> chunk in an ongoing stream of
--   UTF-8-encoded text.
--   
--   Returns a pair:
--   
--   <ol>
--   <li>The first component <tt>n</tt> is the end position, relative to
--   the current chunk, of the longest prefix of the accumulated bytestring
--   which is valid UTF-8. <tt>n</tt> may be negative: that happens when an
--   incomplete code point started in a previous chunk and is not completed
--   by the current chunk (either that code point is still incomplete, or
--   it is broken by an invalid byte).</li>
--   <li>The second component <tt>ms</tt> indicates the
--   following:<ul><li>if <tt>ms = Nothing</tt>, the remainder of the chunk
--   contains an invalid byte, within four bytes from position
--   <tt>n</tt>;</li><li>if <tt>ms = Just s'</tt>, you can carry on
--   validating another chunk by calling <a>validateUtf8More</a> with the
--   new state <tt>s'</tt>.</li></ul></li>
--   </ol>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   <a>validateUtf8More</a> s chunk = (n, ms)
--   </pre>
--   
--   <ul>
--   <li>If the chunk is invalid, it cannot be extended to be valid.<pre>ms
--   = Nothing ==&gt; <a>validateUtf8More</a> s (chunk <a>&lt;&gt;</a>
--   more) = (n, Nothing) </pre></li>
--   <li>Validating two chunks sequentially is the same as validating them
--   together at once:<pre>ms = Just s' ==&gt; <a>validateUtf8More</a> s
--   (chunk <a>&lt;&gt;</a> more) = <a>first</a> (<a>length</a> chunk
--   <a>+</a>) (<a>validateUtf8More</a> s' more) </pre></li>
--   </ul>
validateUtf8More :: Utf8State -> ByteString -> (Int, Maybe Utf8State)

-- | Decode a chunk of UTF-8 text. To be continued with
--   <a>decodeUtf8More</a>.
--   
--   See <a>decodeUtf8More</a> for details on the result.
--   
--   <h3>Properties</h3>
--   
--   <pre>
--   <a>decodeUtf8Chunk</a> = <a>decodeUtf8More</a> <a>startUtf8State</a>
--   </pre>
--   
--   Given:
--   
--   <pre>
--   <a>decodeUtf8Chunk</a> chunk = (builder, rest, ms)
--   </pre>
--   
--   <tt>builder</tt> is a prefix and <tt>rest</tt> is a suffix of
--   <tt>chunk</tt>.
--   
--   <pre>
--   <a>encodeUtf8</a> (<a>strictBuilderToText</a> builder) <a>&lt;&gt;</a> rest = chunk
--   </pre>
decodeUtf8Chunk :: ByteString -> (StrictTextBuilder, ByteString, Maybe Utf8State)

-- | Decode another chunk in an ongoing UTF-8 stream.
--   
--   Returns a triple:
--   
--   <ol>
--   <li>A <a>StrictBuilder</a> for the decoded chunk of text. You can
--   accumulate chunks with <tt>(<a>&lt;&gt;</a>)</tt> or output them with
--   <a>toText</a>.</li>
--   <li>The undecoded remainder of the given chunk, for diagnosing errors
--   and resuming (presumably after skipping some bytes).</li>
--   <li><a>Just</a> the new state, or <a>Nothing</a> if an invalid byte
--   was encountered (it will be within the first 4 bytes of the undecoded
--   remainder).</li>
--   </ol>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   (pre, suf, ms) = <a>decodeUtf8More</a> s chunk
--   </pre>
--   
--   <ol>
--   <li>If the output <tt>pre</tt> is nonempty (alternatively, if
--   <tt>length chunk &gt; length suf</tt>)<pre>s2b pre `<a>append</a>` suf
--   = p2b s `<a>append</a>` chunk </pre>where<pre>s2b = <a>encodeUtf8</a>
--   . <a>toText</a> p2b = <a>partUtf8ToByteString</a> </pre></li>
--   <li>If the output <tt>pre</tt> is empty (alternatively, if <tt>length
--   chunk = length suf</tt>)<pre>suf = chunk</pre></li>
--   <li>Decoding chunks separately is equivalent to decoding their
--   concatenation.Given:<pre>(pre1, suf1, Just s1) = <a>decodeUtf8More</a>
--   s chunk1 (pre2, suf2, ms2) = <a>decodeUtf8More</a> s1 chunk2 (pre3,
--   suf3, ms3) = <a>decodeUtf8More</a> s (chunk1 `B.append` chunk2)
--   </pre>we have:<pre>s2b (pre1 <a>&lt;&gt;</a> pre2) = s2b pre3 ms2 =
--   ms3 </pre></li>
--   </ol>
decodeUtf8More :: Utf8State -> ByteString -> (StrictTextBuilder, ByteString, Maybe Utf8State)

-- | Helper for <a>decodeUtf8With</a>.
decodeUtf8With1 :: OnDecodeError -> String -> ByteString -> Text

-- | Helper for <a>decodeUtf8With</a>, <a>streamDecodeUtf8With</a>, and
--   lazy <a>decodeUtf8With</a>, which use an <a>OnDecodeError</a> to
--   process bad bytes.
--   
--   See <a>decodeUtf8Chunk</a> for a more flexible alternative.
decodeUtf8With2 :: OnDecodeError -> String -> Utf8State -> ByteString -> (StrictTextBuilder, ByteString, Utf8State)

-- | State of decoding a <a>ByteString</a> in UTF-8. Enables incremental
--   decoding (<a>validateUtf8Chunk</a>, <a>validateUtf8More</a>,
--   <a>decodeUtf8Chunk</a>, <a>decodeUtf8More</a>).
data Utf8State

-- | Initial <a>Utf8State</a>.
startUtf8State :: Utf8State

-- | A delayed representation of strict <a>Text</a>.
data StrictTextBuilder

-- | A delayed representation of strict <a>Text</a>.

-- | <i>Deprecated: Use StrictTextBuilder instead</i>
type StrictBuilder = StrictTextBuilder

-- | Use <a>StrictBuilder</a> to build <a>Text</a>.
strictBuilderToText :: StrictTextBuilder -> Text

-- | Copy <a>Text</a> in a <a>StrictBuilder</a>
textToStrictBuilder :: Text -> StrictTextBuilder

-- | Call the error handler on each byte of the partial code point stored
--   in <a>Utf8State</a> and append the results.
--   
--   Exported for use in lazy <a>decodeUtf8With</a>.
skipIncomplete :: OnDecodeError -> String -> Utf8State -> StrictTextBuilder

-- | Exported for testing.
getCompleteLen :: Utf8State -> Int

-- | Exported for testing.
getPartialUtf8 :: Utf8State -> ByteString
instance GHC.Classes.Eq Data.Text.Internal.Encoding.PartialUtf8CodePoint
instance GHC.Classes.Eq Data.Text.Internal.Encoding.Utf8State
instance GHC.Internal.Show.Show Data.Text.Internal.Encoding.PartialUtf8CodePoint
instance GHC.Internal.Show.Show Data.Text.Internal.Encoding.Utf8State


-- | Native implementation of <a>Validate</a>.
module Data.Text.Internal.Validate.Native

-- | Native implementation of <a>isValidUtf8ByteString</a>.
isValidUtf8ByteStringHaskell :: ByteString -> Bool

-- | Native implementation of <a>isValidUtf8ByteArrayUnpinned</a> and
--   <a>isValidUtf8ByteArrayPinned</a>.
isValidUtf8ByteArrayHaskell :: ByteArray -> Int -> Int -> Bool


-- | Test whether or not a sequence of bytes is a valid UTF-8 byte
--   sequence. In the GHC Haskell ecosystem, there are several
--   representations of byte sequences. The only one that the stable
--   <tt>text</tt> API concerns itself with is <a>ByteString</a>. Part of
--   bytestring-to-text decoding is <a>isValidUtf8ByteString</a>, a
--   high-performance UTF-8 validation routine written in C++ with
--   fallbacks for various platforms. The C++ code backing this routine is
--   nontrivial, so in the interest of reuse, this module additionally
--   exports functions for working with the GC-managed <tt>ByteArray</tt>
--   type. These <tt>ByteArray</tt> functions are not used anywhere else in
--   <tt>text</tt>. They are for the benefit of library and application
--   authors who do not use <a>ByteString</a> but still need to
--   interoperate with <tt>text</tt>.
module Data.Text.Internal.Validate

-- | Is the ByteString a valid UTF-8 byte sequence?
isValidUtf8ByteString :: ByteString -> Bool

-- | For pinned byte arrays larger than 128KiB, this switches to the safe
--   FFI so that it does not prevent GC. This threshold (128KiB) was chosen
--   somewhat arbitrarily and may change in the future.
isValidUtf8ByteArray :: ByteArray -> Int -> Int -> Bool

-- | This uses the <tt>unsafe</tt> FFI. GC waits for all <tt>unsafe</tt>
--   FFI calls to complete before starting. Consequently, an
--   <tt>unsafe</tt> FFI call does not run concurrently with GC and is not
--   interrupted by GC. Since relocation cannot happen concurrently with an
--   <tt>unsafe</tt> FFI call, it is safe to call this function with an
--   unpinned byte array argument. It is also safe to call this with a
--   pinned <tt>ByteArray</tt> argument.
isValidUtf8ByteArrayUnpinned :: ByteArray -> Int -> Int -> Bool

-- | This uses the <tt>safe</tt> FFI. GC may run concurrently with
--   <tt>safe</tt> FFI calls. Consequently, unpinned objects may be
--   relocated while a <tt>safe</tt> FFI call is executing. The byte array
--   argument <i>must</i> be pinned, and the calling context is responsible
--   for enforcing this. If the byte array is not pinned, this function's
--   behavior is undefined.
isValidUtf8ByteArrayPinned :: ByteArray -> Int -> Int -> Bool


-- | 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.
inlinePerformIO :: IO a -> a
unsafeDupablePerformIO :: IO a -> a
data Iter
Iter :: {-# UNPACK #-} !Char -> {-# UNPACK #-} !Int -> Iter

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

iterArray :: Array -> Int -> Iter

-- | <i>O(1)</i> Iterate one step through a UTF-8 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-8 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 -> Iter

reverseIterArray :: Array -> Int -> Iter

-- | <i>O(1)</i> Iterate one step backwards through a UTF-8 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>Word8</tt>. This is useful for sizing a target array appropriately
--   before using <tt>unsafeCopyToPtr</tt>.
lengthWord8 :: Text -> Int

-- | <i>O(1)</i> Unchecked take of <tt>k</tt> <tt>Word8</tt>s from the
--   front of a <a>Text</a>.
takeWord8 :: Int -> Text -> Text

-- | <i>O(1)</i> Unchecked drop of <tt>k</tt> <tt>Word8</tt>s from the
--   front of a <a>Text</a>.
dropWord8 :: Int -> Text -> Text
instance GHC.Internal.Show.Show Data.Text.Unsafe.Iter


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

-- | For the sake of performance this function does not check that a char
--   is in ASCII range; it is a responsibility of <tt>p</tt>.
spanAscii_ :: (Word8 -> 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

-- | A co-recursive type yielding a single element at a time depending on
--   the internal state it carries.
data Stream a
Stream :: (s -> Step s a) -> !s -> !Size -> Stream a

-- | Intermediate result in a processing pipeline.
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>Text</a> into a <a>Stream</a> <a>Char</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>stream</a> = <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>stream</a> . <a>unstream</a> = <a>id</a>
--   </pre>
stream :: Text -> Stream Char

-- | <i>O(n)</i> <tt><a>streamLn</a> t = <a>stream</a> (t &lt;&gt;
--   '\n')</tt>
streamLn :: Text -> Stream Char

-- | <i>O(n)</i> Convert <a>Stream</a> <a>Char</a> into a <a>Text</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>stream</a> = <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>stream</a> . <a>unstream</a> = <a>id</a>
--   </pre>
unstream :: Stream Char -> Text

-- | <i>O(n)</i> Converts <a>Text</a> into a <a>Stream</a> <a>Char</a>, but
--   iterates backwards through the text.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> . <a>reverseStream</a> = <a>reverse</a>
--   </pre>
reverseStream :: Text -> Stream Char

-- | <i>O(n)</i> Returns the number of characters in a <a>Stream</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>length</a> . <a>stream</a> = <a>length</a>
--   </pre>
length :: Stream Char -> Int

-- | <i>O(n)</i> Reverse the characters of a <a>Stream</a> returning
--   <a>Text</a>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>reverse</a> . <a>stream</a> = <a>reverse</a>
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>reverse</a> . <a>reverseScanr</a> f c . <a>reverseStream</a> = <a>scanr</a> f c
--   </pre>
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>.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>mapAccumL</a> g z0 . <a>stream</a> = <a>mapAccumL</a> g z0
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>unstream</a> (<a>unfoldrN</a> n f a) = <a>unfoldrN</a> n f a
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> Stream Char

-- | <i>O(n)</i> stream index (subscript) operator, starting from 0.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>index</a> (<a>stream</a> t) n  = <a>index</a> t n
--   </pre>
index :: HasCallStack => 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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>findIndex</a> p . <a>stream</a>  = <a>findIndex</a> p
--   </pre>
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.
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>countChar</a> c . <a>stream</a>  = <a>countChar</a> c
--   </pre>
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!
--   
--   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


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


-- | 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
--   <a>text-icu package</a>.
module Data.Text.Encoding

-- | 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>
--   
--   This is a total function. However, bear in mind that decoding Latin-1
--   (non-ASCII) characters to UTf-8 requires actual work and is not just
--   buffer copying.
decodeLatin1 :: ByteString -> Text

-- | Decode a <a>ByteString</a> containing ASCII text.
--   
--   This is a total function which returns a pair of the longest ASCII
--   prefix as <a>Text</a>, and the remaining suffix as <a>ByteString</a>.
--   
--   Important note: the pair is lazy. This lets you check for errors by
--   testing whether the second component is empty, without forcing the
--   first component (which does a copy). To drop references to the input
--   bytestring, force the prefix (using <a>seq</a> or
--   <tt>BangPatterns</tt>) and drop references to the suffix.
--   
--   <h3>Properties</h3>
--   
--   <ul>
--   <li>If <tt>(prefix, suffix) = decodeAsciiPrefix s</tt>, then
--   <tt><a>encodeUtf8</a> prefix &lt;&gt; suffix = s</tt>.</li>
--   <li>Either <tt>suffix</tt> is empty, or <tt><a>head</a> suffix &gt;
--   127</tt>.</li>
--   </ul>
decodeASCIIPrefix :: ByteString -> (Text, ByteString)

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text.
--   
--   Any invalid input bytes will be replaced with the Unicode replacement
--   character U+FFFD.
decodeUtf8Lenient :: 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 7-bit ASCII encoded text.
--   
--   This is a total function which returns either the <a>ByteString</a>
--   converted to a <a>Text</a> containing ASCII text, or <a>Nothing</a>.
--   
--   Use <a>decodeASCIIPrefix</a> to retain the longest ASCII prefix for an
--   invalid input instead of discarding it.
decodeASCII' :: ByteString -> Maybe Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text.
--   
--   Surrogate code points in replacement character returned by
--   <a>OnDecodeError</a> will be automatically remapped to the replacement
--   char <tt>U+FFFD</tt>.
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 lazy <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

-- | Decode a chunk of UTF-8 text. To be continued with
--   <a>decodeUtf8More</a>.
--   
--   See <a>decodeUtf8More</a> for details on the result.
--   
--   <h3>Properties</h3>
--   
--   <pre>
--   <a>decodeUtf8Chunk</a> = <a>decodeUtf8More</a> <a>startUtf8State</a>
--   </pre>
--   
--   Given:
--   
--   <pre>
--   <a>decodeUtf8Chunk</a> chunk = (builder, rest, ms)
--   </pre>
--   
--   <tt>builder</tt> is a prefix and <tt>rest</tt> is a suffix of
--   <tt>chunk</tt>.
--   
--   <pre>
--   <a>encodeUtf8</a> (<a>strictBuilderToText</a> builder) <a>&lt;&gt;</a> rest = chunk
--   </pre>
decodeUtf8Chunk :: ByteString -> (StrictTextBuilder, ByteString, Maybe Utf8State)

-- | Decode another chunk in an ongoing UTF-8 stream.
--   
--   Returns a triple:
--   
--   <ol>
--   <li>A <a>StrictBuilder</a> for the decoded chunk of text. You can
--   accumulate chunks with <tt>(<a>&lt;&gt;</a>)</tt> or output them with
--   <a>toText</a>.</li>
--   <li>The undecoded remainder of the given chunk, for diagnosing errors
--   and resuming (presumably after skipping some bytes).</li>
--   <li><a>Just</a> the new state, or <a>Nothing</a> if an invalid byte
--   was encountered (it will be within the first 4 bytes of the undecoded
--   remainder).</li>
--   </ol>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   (pre, suf, ms) = <a>decodeUtf8More</a> s chunk
--   </pre>
--   
--   <ol>
--   <li>If the output <tt>pre</tt> is nonempty (alternatively, if
--   <tt>length chunk &gt; length suf</tt>)<pre>s2b pre `<a>append</a>` suf
--   = p2b s `<a>append</a>` chunk </pre>where<pre>s2b = <a>encodeUtf8</a>
--   . <a>toText</a> p2b = <a>partUtf8ToByteString</a> </pre></li>
--   <li>If the output <tt>pre</tt> is empty (alternatively, if <tt>length
--   chunk = length suf</tt>)<pre>suf = chunk</pre></li>
--   <li>Decoding chunks separately is equivalent to decoding their
--   concatenation.Given:<pre>(pre1, suf1, Just s1) = <a>decodeUtf8More</a>
--   s chunk1 (pre2, suf2, ms2) = <a>decodeUtf8More</a> s1 chunk2 (pre3,
--   suf3, ms3) = <a>decodeUtf8More</a> s (chunk1 `B.append` chunk2)
--   </pre>we have:<pre>s2b (pre1 <a>&lt;&gt;</a> pre2) = s2b pre3 ms2 =
--   ms3 </pre></li>
--   </ol>
decodeUtf8More :: Utf8State -> ByteString -> (StrictTextBuilder, ByteString, Maybe Utf8State)

-- | State of decoding a <a>ByteString</a> in UTF-8. Enables incremental
--   decoding (<a>validateUtf8Chunk</a>, <a>validateUtf8More</a>,
--   <a>decodeUtf8Chunk</a>, <a>decodeUtf8More</a>).
data Utf8State

-- | Initial <a>Utf8State</a>.
startUtf8State :: Utf8State

-- | A delayed representation of strict <a>Text</a>.

-- | <i>Deprecated: Use StrictTextBuilder instead</i>
type StrictBuilder = StrictTextBuilder

-- | A delayed representation of strict <a>Text</a>.
data StrictTextBuilder

-- | Use <a>StrictBuilder</a> to build <a>Text</a>.
strictBuilderToText :: StrictTextBuilder -> Text

-- | Copy <a>Text</a> in a <a>StrictBuilder</a>
textToStrictBuilder :: Text -> StrictTextBuilder

-- | Decode a <a>ByteString</a> containing 7-bit ASCII encoded text.
--   
--   This is a partial function: it checks that input does not contain
--   anything except ASCII and copies buffer or throws an error otherwise.
decodeASCII :: ByteString -> Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text that is known
--   to be valid.
--   
--   If the input contains any invalid UTF-8 data, an exception will be
--   thrown that cannot be caught in pure code. For more control over the
--   handling of invalid data, use <a>decodeUtf8'</a> or
--   <a>decodeUtf8With</a>.
--   
--   This is a partial function: it checks that input is a well-formed
--   UTF-8 sequence and copies buffer or throws an error otherwise.
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, 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

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

-- | Validate a <a>ByteString</a> as UTF-8-encoded text. To be continued
--   using <a>validateUtf8More</a>.
--   
--   See also <a>validateUtf8More</a> for details on the result of this
--   function.
--   
--   <pre>
--   <a>validateUtf8Chunk</a> = <a>validateUtf8More</a> <a>startUtf8State</a>
--   </pre>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   <a>validateUtf8Chunk</a> chunk = (n, ms)
--   </pre>
--   
--   <ul>
--   <li>The prefix is valid UTF-8. In particular, it should be accepted by
--   this validation:<pre><a>validateUtf8Chunk</a> (<a>take</a> n chunk) =
--   (n, Just <a>startUtf8State</a>) </pre></li>
--   </ul>
validateUtf8Chunk :: ByteString -> (Int, Maybe Utf8State)

-- | Validate another <a>ByteString</a> chunk in an ongoing stream of
--   UTF-8-encoded text.
--   
--   Returns a pair:
--   
--   <ol>
--   <li>The first component <tt>n</tt> is the end position, relative to
--   the current chunk, of the longest prefix of the accumulated bytestring
--   which is valid UTF-8. <tt>n</tt> may be negative: that happens when an
--   incomplete code point started in a previous chunk and is not completed
--   by the current chunk (either that code point is still incomplete, or
--   it is broken by an invalid byte).</li>
--   <li>The second component <tt>ms</tt> indicates the
--   following:<ul><li>if <tt>ms = Nothing</tt>, the remainder of the chunk
--   contains an invalid byte, within four bytes from position
--   <tt>n</tt>;</li><li>if <tt>ms = Just s'</tt>, you can carry on
--   validating another chunk by calling <a>validateUtf8More</a> with the
--   new state <tt>s'</tt>.</li></ul></li>
--   </ol>
--   
--   <h3>Properties</h3>
--   
--   Given:
--   
--   <pre>
--   <a>validateUtf8More</a> s chunk = (n, ms)
--   </pre>
--   
--   <ul>
--   <li>If the chunk is invalid, it cannot be extended to be valid.<pre>ms
--   = Nothing ==&gt; <a>validateUtf8More</a> s (chunk <a>&lt;&gt;</a>
--   more) = (n, Nothing) </pre></li>
--   <li>Validating two chunks sequentially is the same as validating them
--   together at once:<pre>ms = Just s' ==&gt; <a>validateUtf8More</a> s
--   (chunk <a>&lt;&gt;</a> more) = <a>first</a> (<a>length</a> chunk
--   <a>+</a>) (<a>validateUtf8More</a> s' more) </pre></li>
--   </ul>
validateUtf8More :: Utf8State -> ByteString -> (Int, Maybe Utf8State)
instance GHC.Internal.Show.Show Data.Text.Encoding.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-8 code units.
data I8

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

-- | <i>O(n)</i> Create a new <a>Text</a> from a <a>Ptr</a> <a>Word8</a> by
--   copying the contents of the NUL-terminated array.
fromPtr0 :: Ptr Word8 -> 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 Word8 -> I8 -> IO a) -> IO a

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

-- | <i>O(n)</i> Decode a null-terminated C string, which is assumed to
--   have been encoded as UTF-8. If decoding fails, a
--   <tt>UnicodeException</tt> is thrown.
peekCString :: CString -> IO Text

-- | Marshal a <a>Text</a> into a C string with a trailing NUL byte,
--   encoded as UTF-8 in temporary storage.
--   
--   The <a>Text</a> itself must not contain any NUL bytes, this
--   precondition is not checked. Cf. <a>withCStringLen</a>.
--   
--   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.
withCString :: Text -> (CString -> IO a) -> IO a

-- | <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>Word8</tt>. This is useful for sizing a target array appropriately
--   before using <tt>unsafeCopyToPtr</tt>.
lengthWord8 :: 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 Word8 -> IO ()

-- | <i>O(1)</i> Return the suffix of the <a>Text</a>, with <tt>n</tt>
--   <a>Word8</a> units dropped from its beginning.
--   
--   If <tt>n</tt> would cause the <a>Text</a> to begin inside a code
--   point, the beginning of the suffix will be advanced by several
--   additional <a>Word8</a> unit to maintain its validity.
dropWord8 :: I8 -> Text -> Text

-- | <i>O(1)</i> Return the prefix of the <a>Text</a> of <tt>n</tt>
--   <a>Word8</a> units in length.
--   
--   If <tt>n</tt> would cause the <a>Text</a> to end inside a code point,
--   the end of the prefix will be advanced by several additional
--   <a>Word8</a> units to maintain its validity.
takeWord8 :: I8 -> Text -> Text
instance GHC.Internal.Enum.Bounded Data.Text.Foreign.I8
instance GHC.Internal.Enum.Enum Data.Text.Foreign.I8
instance GHC.Classes.Eq Data.Text.Foreign.I8
instance GHC.Internal.Real.Integral Data.Text.Foreign.I8
instance GHC.Internal.Num.Num Data.Text.Foreign.I8
instance GHC.Classes.Ord Data.Text.Foreign.I8
instance GHC.Internal.Read.Read Data.Text.Foreign.I8
instance GHC.Internal.Real.Real Data.Text.Foreign.I8
instance GHC.Internal.Show.Show Data.Text.Foreign.I8


-- | A time and space-efficient implementation of Unicode text. Suitable
--   for performance critical use, both in terms of large data quantities
--   and high speed.
--   
--   <i>Note</i>: Read below the synopsis for important notes on the use of
--   this module.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.Text as T
--   </pre>
--   
--   To use an extended and very rich family of functions for working with
--   Unicode text (including normalization, regular expressions,
--   non-standard encodings, text breaking, and locales), see the
--   <a>text-icu package</a>.
module Data.Text

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

-- | Type synonym for the strict flavour of <a>Text</a>.
type StrictText = Text

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>Text</a>. Performs
--   replacement on invalid scalar values, so <tt><a>unpack</a> .
--   <a>pack</a></tt> is not <a>id</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Text.unpack (pack "\55555")
--   "\65533"
--   </pre>
pack :: String -> Text

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

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

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

-- | Bidirectional pattern synonym for <a>empty</a> and <a>null</a> (both
--   <i>O(1)</i>), to be used together with <a>(:&lt;)</a> or
--   <a>(:&gt;)</a>.
pattern Empty :: Text

-- | Bidirectional pattern synonym for <a>cons</a> (<i>O(n)</i>) and
--   <a>uncons</a> (<i>O(1)</i>), to be used together with <a>Empty</a>.
pattern (:<) :: Char -> Text -> Text
infixr 5 :<

-- | Bidirectional pattern synonym for <a>snoc</a> (<i>O(n)</i>) and
--   <a>unsnoc</a> (<i>O(1)</i>) to be used together with <a>Empty</a>.
pattern (:>) :: Text -> Char -> Text
infixl 5 :>

-- | <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. Performs replacement on invalid scalar
--   values.
cons :: Char -> Text -> Text
infixr 5 `cons`

-- | <i>O(n)</i> Adds a character to the end of a <a>Text</a>. This copies
--   the entire array in the process. 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>.
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.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(1)</i> Returns all but the last character and the last character
--   of a <a>Text</a>, or <a>Nothing</a> if empty.
unsnoc :: Text -> Maybe (Text, Char)

-- | <i>O(1)</i> Returns the first character of a <a>Text</a>, which must
--   be non-empty. This is a partial function, consider using <a>uncons</a>
--   instead.
head :: HasCallStack => Text -> Char

-- | <i>O(1)</i> Returns the last character of a <a>Text</a>, which must be
--   non-empty. This is a partial function, consider using <a>unsnoc</a>
--   instead.
last :: HasCallStack => Text -> Char

-- | <i>O(1)</i> Returns all characters after the head of a <a>Text</a>,
--   which must be non-empty. This is a partial function, consider using
--   <a>uncons</a> instead.
tail :: HasCallStack => Text -> Text

-- | <i>O(1)</i> Returns all but the last character of a <a>Text</a>, which
--   must be non-empty. This is a partial function, consider using
--   <a>unsnoc</a> instead.
init :: HasCallStack => Text -> Text

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

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

-- | <i>O(min(n,c))</i> Compare the count of characters in a <a>Text</a> to
--   a number.
--   
--   <pre>
--   <a>compareLength</a> t c = <a>compare</a> (<a>length</a> t) c
--   </pre>
--   
--   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>.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; let message = pack "I am not angry. Not at all."
--   
--   &gt;&gt;&gt; T.map (\c -&gt; if c == '.' then '!' else c) message
--   "I am not angry! Not at all!"
--   </pre>
--   
--   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.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
--   "WeNI!seekNI!theNI!HolyNI!Grail"
--   </pre>
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>.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; T.intersperse '.' "SHIELD"
--   "S.H.I.E.L.D"
--   </pre>
--   
--   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.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; transpose ["green","orange"]
--   ["go","rr","ea","en","ng","e"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; transpose ["blue","red"]
--   ["br","le","ud","e"]
--   </pre>
transpose :: [Text] -> [Text]
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>
--   &gt;&gt;&gt; replace "oo" "foo" "oo"
--   "foo"
--   </pre>
--   
--   In cases where several instances of <tt>needle</tt> overlap, only the
--   first one will be replaced:
--   
--   <pre>
--   &gt;&gt;&gt; replace "ofo" "bar" "ofofo"
--   "barfo"
--   </pre>
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
replace :: HasCallStack => Text -> Text -> Text -> Text

-- | <i>O(n)</i> Convert a string to folded case.
--   
--   This function is mainly useful for performing caseless (also known as
--   case insensitive) string comparisons.
--   
--   A string <tt>x</tt> is a caseless match for a string <tt>y</tt> if and
--   only if:
--   
--   <pre>
--   toCaseFold x == toCaseFold y
--   </pre>
--   
--   The result string may be longer than the input string, and may differ
--   from applying <a>toLower</a> to the input string. For instance, the
--   Armenian small ligature "ﬓ" (men now, U+FB13) is case folded to the
--   sequence "մ" (men, U+0574) followed by "ն" (now, U+0576), while the
--   Greek "µ" (micro sign, U+00B5) is case folded to "μ" (small letter mu,
--   U+03BC) instead of itself.
toCaseFold :: Text -> Text

-- | <i>O(n)</i> Convert a string to lower case, using simple case
--   conversion.
--   
--   The result string may be longer than the input string. For instance,
--   "İ" (Latin capital letter I with dot above, U+0130) maps to the
--   sequence "i" (Latin small letter i, U+0069) followed by " ̇"
--   (combining dot above, U+0307).
toLower :: Text -> Text

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

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion.
--   
--   The first letter (as determined by <a>isLetter</a>) 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.
--   
--   This function is not idempotent. Consider lower-case letter <tt>ʼn</tt>
--   (U+0149 LATIN SMALL LETTER N PRECEDED BY APOSTROPHE). Then
--   <a>toTitle</a> <tt>"ʼn"</tt> = <tt>"ʼN"</tt>: the first (and the only)
--   letter of the input is converted to title case, becoming two letters.
--   Now <tt>ʼ</tt> (U+02BC MODIFIER LETTER APOSTROPHE) is a modifier
--   letter and as such is recognised as a letter by <a>isLetter</a>, so
--   <a>toTitle</a> <tt>"ʼN"</tt> = <tt>"'n"</tt>.
--   
--   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. Performs replacement on invalid
--   scalar values.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; justifyLeft 7 'x' "foo"
--   "fooxxxx"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; justifyRight 7 'x' "bar"
--   "xxxxbar"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; 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.
foldl :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A strict version of <a>foldl</a>.
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>.
foldl1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A strict version of <a>foldl1</a>.
foldl1' :: HasCallStack => (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.
--   
--   If the binary operator is strict in its second argument, use
--   <a>foldr'</a> instead.
--   
--   <a>foldr</a> is lazy like <a>foldr</a> for lists: evaluation actually
--   traverses the <a>Text</a> from left to right, only as far as it needs
--   to.
--   
--   For example, <a>head</a> can be defined with <i>O(1)</i> complexity
--   using <a>foldr</a>:
--   
--   <pre>
--   head :: Text -&gt; Char
--   head = foldr const (error "head empty")
--   </pre>
--   
--   Searches from left to right with short-circuiting behavior can also be
--   defined using <a>foldr</a> (<i>e.g.</i>, <a>any</a>, <a>all</a>,
--   <a>find</a>, <a>elem</a>).
foldr :: (Char -> a -> a) -> a -> Text -> a

-- | <i>O(n)</i> A strict version of <a>foldr</a>.
--   
--   <a>foldr'</a> evaluates as a right-to-left traversal using constant
--   stack space.
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>.
foldr1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A monadic version of <a>foldl'</a>.
foldlM' :: Monad m => (a -> Char -> m a) -> a -> Text -> m a

-- | <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> satisfies the predicate
--   <tt>p</tt>.
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> satisfy the predicate
--   <tt>p</tt>.
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.
maximum :: HasCallStack => Text -> Char

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

-- | O(n) Test whether <a>Text</a> contains only ASCII code-points (i.e.
--   only U+0000 through U+007F).
--   
--   This is a more efficient version of <tt><tt>all</tt>
--   <a>isAscii</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; isAscii ""
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abc\NUL"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abcd€"
--   False
--   </pre>
--   
--   <pre>
--   isAscii t == all (&lt; '\x80') t
--   </pre>
isAscii :: Text -> Bool

-- | <i>O(n)</i> <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   list of successive reduced values from the left. Performs replacement
--   on invalid scalar values.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   <b>Properties</b>
--   
--   <pre>
--   <a>head</a> (<a>scanl</a> f z xs) = z
--   </pre>
--   
--   <pre>
--   <a>last</a> (<a>scanl</a> f z xs) = <a>foldl</a> 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. 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 :: 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. 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 :: 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.
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>
--   &gt;&gt;&gt; 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>.
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>
--   &gt;&gt;&gt; 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>.
takeWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>takeWhileEnd</a>, applied to a predicate <tt>p</tt> and
--   a <a>Text</a>, returns the longest suffix (possibly empty) of elements
--   that satisfy <tt>p</tt>. Examples:
--   
--   <pre>
--   &gt;&gt;&gt; takeWhileEnd (=='o') "foo"
--   "oo"
--   </pre>
takeWhileEnd :: (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>.
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 satisfy the predicate
--   <tt>p</tt> from the end of <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; 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 satisfy the
--   predicate <tt>p</tt> from both the beginning and end of <tt>t</tt>.
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>
--   &gt;&gt;&gt; breakOn "::" "a::b::c"
--   ("a","::b::c")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; breakOn "/" "foobar"
--   ("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 :: HasCallStack => 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>
--   &gt;&gt;&gt; breakOnEnd "::" "a::b::c"
--   ("a::b::","c")
--   </pre>
breakOnEnd :: HasCallStack => 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>.
--   
--   <pre>
--   &gt;&gt;&gt; T.break (=='c') "180cm"
--   ("180","cm")
--   </pre>
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 text.
--   
--   <pre>
--   &gt;&gt;&gt; T.span (=='0') "000AB"
--   ("000","AB")
--   </pre>
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(length of prefix)</i> <a>spanM</a>, applied to a monadic
--   predicate <tt>p</tt>, a text <tt>t</tt>, returns a pair <tt>(t1,
--   t2)</tt> where <tt>t1</tt> is the longest prefix of <tt>t</tt> whose
--   elements satisfy <tt>p</tt>, and <tt>t2</tt> is the remainder of the
--   text.
--   
--   <pre>
--   &gt;&gt;&gt; T.spanM (\c -&gt; state $ \i -&gt; (fromEnum c == i, i+1)) "abcefg" `runState` 97
--   (("abc","efg"),101)
--   </pre>
--   
--   <a>span</a> is <a>spanM</a> specialized to <a>Identity</a>:
--   
--   <pre>
--   -- for all p :: Char -&gt; Bool
--   <a>span</a> p = <a>runIdentity</a> . <a>spanM</a> (<a>pure</a> . p)
--   </pre>
spanM :: Monad m => (Char -> m Bool) -> Text -> m (Text, Text)

-- | <i>O(length of suffix)</i> <a>spanEndM</a>, applied to a monadic
--   predicate <tt>p</tt>, a text <tt>t</tt>, returns a pair <tt>(t1,
--   t2)</tt> where <tt>t2</tt> is the longest suffix of <tt>t</tt> whose
--   elements satisfy <tt>p</tt>, and <tt>t1</tt> is the remainder of the
--   text.
--   
--   <pre>
--   &gt;&gt;&gt; T.spanEndM (\c -&gt; state $ \i -&gt; (fromEnum c == i, i-1)) "tuvxyz" `runState` 122
--   (("tuv","xyz"),118)
--   </pre>
--   
--   <pre>
--   <a>spanEndM</a> p . <a>reverse</a> = fmap (<a>bimap</a> <a>reverse</a> <a>reverse</a>) . <a>spanM</a> p
--   </pre>
spanEndM :: Monad m => (Char -> m Bool) -> Text -> m (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 initial segments of the given <a>Text</a>,
--   shortest first.
initsNE :: Text -> NonEmpty Text

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

-- | <i>O(n)</i> Return all final segments of the given <a>Text</a>,
--   longest first.
tailsNE :: Text -> NonEmpty 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>
--   &gt;&gt;&gt; splitOn "\r\n" "a\r\nb\r\nd\r\ne"
--   ["a","b","d","e"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitOn "aaa"  "aaaXaaaXaaaXaaa"
--   ["","X","X","X",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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 :: HasCallStack => 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>
--   &gt;&gt;&gt; split (=='a') "aabbaca"
--   ["","","bb","c",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; chunksOf 3 "foobarbaz"
--   ["foo","bar","baz"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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 characters <tt>'\n'</tt> (LF, line feed). The resulting
--   strings do not contain newlines.
--   
--   <a>lines</a> <b>does not</b> treat <tt>'\r'</tt> (CR, carriage return)
--   as a newline character.
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> if and only if the first is a prefix of the
--   second.
isPrefixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> if and only if 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> if and only if 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>
--   &gt;&gt;&gt; stripPrefix "foo" "foobar"
--   Just "bar"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix ""    "baz"
--   Just "baz"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; stripSuffix "bar" "foobar"
--   Just "foo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripSuffix ""    "baz"
--   Just "baz"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; commonPrefixes "foobar" "fooquux"
--   Just ("foo","bar","quux")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefixes "veeble" "fetzer"
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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>
--   &gt;&gt;&gt; breakOnAll "::" ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; breakOnAll "/" "a/b/c/"
--   [("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 :: HasCallStack => 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>elem</a> function takes a character and a
--   <a>Text</a>, and returns <a>True</a> if the element is found in the
--   given <a>Text</a>, or <a>False</a> otherwise.
elem :: Char -> Text -> Bool

-- | <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 :: HasCallStack => 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.
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 :: HasCallStack => 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

-- | Convert a value to <a>Text</a>.
show :: Show a => a -> 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

-- | <i>O(n)</i> Convert a null-terminated <a>modified UTF-8</a> (but with
--   a standard UTF-8 representation of characters from supplementary
--   planes) string to a <a>Text</a>. Counterpart to
--   <a>unpackCStringUtf8#</a>. No validation is performed, malformed input
--   can lead to memory access violation.
unpackCString# :: Addr# -> Text

-- | <i>O(n)</i> Convert a null-terminated ASCII string to a <a>Text</a>.
--   Counterpart to <a>unpackCString#</a>. No validation is performed,
--   malformed input can lead to memory access violation.
unpackCStringAscii# :: Addr# -> Text

-- | <i>O(n)</i> If <tt>t</tt> is long enough to contain <tt>n</tt>
--   characters, <a>measureOff</a> <tt>n</tt> <tt>t</tt> returns a
--   non-negative number, measuring their size in <a>Word8</a>. Otherwise,
--   if <tt>t</tt> is shorter, return a non-positive number, which is a
--   negated total count of <a>Char</a> available in <tt>t</tt>. If
--   <tt>t</tt> is empty or <tt>n = 0</tt>, return 0.
--   
--   This function is used to implement <a>take</a>, <a>drop</a>,
--   <a>splitAt</a> and <a>length</a> and is useful on its own in streaming
--   and parsing libraries.
measureOff :: Int -> Text -> Int
instance Data.Binary.Class.Binary Data.Text.Internal.Text
instance GHC.Internal.Data.Data.Data Data.Text.Internal.Text
instance GHC.Classes.Eq Data.Text.Internal.Text
instance GHC.Internal.IsList.IsList Data.Text.Internal.Text
instance GHC.Internal.Data.String.IsString Data.Text.Internal.Text
instance Language.Haskell.TH.Syntax.Lift Data.Text.Internal.Text
instance GHC.Internal.Base.Monoid Data.Text.Internal.Text
instance Control.DeepSeq.NFData Data.Text.Internal.Text
instance GHC.Classes.Ord Data.Text.Internal.Text
instance Text.Printf.PrintfArg Data.Text.Internal.Text
instance GHC.Internal.Read.Read Data.Text.Internal.Text
instance GHC.Internal.Base.Semigroup Data.Text.Internal.Text


-- | Functions used frequently when reading textual data.
module Data.Text.Read

-- | Read some text. If the read succeeds, return its value and the
--   remaining text, otherwise an error message.
type Reader a = Text -> Either String (a, Text)

-- | Read a decimal integer. The input must begin with at least one decimal
--   digit, and is consumed until a non-digit or end of string is reached.
--   
--   This function does not handle leading sign characters. If you need to
--   handle signed input, use <tt><a>signed</a> <a>decimal</a></tt>.
--   
--   <i>Note</i>: For fixed-width integer types, this function does not
--   attempt to detect overflow, so a sufficiently long input may give
--   incorrect results. If you are worried about overflow, use
--   <a>Integer</a> for your result type.
decimal :: Integral a => Reader a

-- | Read a hexadecimal integer, consisting of an optional leading
--   <tt>"0x"</tt> followed by at least one hexadecimal 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


-- | <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.
Empty :: Text

-- | Chunks must be non-empty, this invariant is not checked.
Chunk :: {-# UNPACK #-} !Text -> Text -> Text

-- | Type synonym for the lazy flavour of <a>Text</a>.
type LazyText = 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
equal :: Text -> Text -> Bool


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


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


-- | <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> <tt><a>streamLn</a> t = <a>stream</a> (t &lt;&gt;
--   '\n')</tt>
streamLn :: 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 :: HasCallStack => 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


-- | 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 family of encodings, use the
--   <a>text-icu package</a>.
module Data.Text.Lazy.Encoding

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

-- | Decode a <tt>ByteString</tt> containing 7-bit ASCII encoded text.
decodeASCII :: ByteString -> Text

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

-- | Decode text from little endian UTF-16 encoding.
--   
--   If the input contains any invalid little endian UTF-16 data, an
--   exception will be thrown. For more control over the handling of
--   invalid data, use <a>decodeUtf16LEWith</a>.
decodeUtf16LE :: ByteString -> Text

-- | Decode text from big endian UTF-16 encoding.
--   
--   If the input contains any invalid big endian UTF-16 data, an exception
--   will be thrown. For more control over the handling of invalid data,
--   use <a>decodeUtf16BEWith</a>.
decodeUtf16BE :: ByteString -> Text

-- | Decode text from little endian UTF-32 encoding.
--   
--   If the input contains any invalid little endian UTF-32 data, an
--   exception will be thrown. For more control over the handling of
--   invalid data, use <a>decodeUtf32LEWith</a>.
decodeUtf32LE :: ByteString -> Text

-- | Decode text from big endian UTF-32 encoding.
--   
--   If the input contains any invalid big endian UTF-32 data, an exception
--   will be thrown. For more control over the handling of invalid data,
--   use <a>decodeUtf32BEWith</a>.
decodeUtf32BE :: ByteString -> Text

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


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

-- | Type synonym for the lazy flavour of <a>Text</a>.
type LazyText = Text

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>Text</a>.
--   
--   Performs replacement on invalid scalar values, so <tt><a>unpack</a> .
--   <a>pack</a></tt> is not <tt>id</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Text.Lazy.unpack (Data.Text.Lazy.pack "\55555")
--   "\65533"
--   </pre>
pack :: String -> Text

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

-- | <i>O(1)</i> Convert a character into a Text. 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 :: LazyText -> StrictText

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

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

-- | Empty text.
pattern Empty :: () => Text

-- | Bidirectional pattern synonym for <a>cons</a> (<i>O(n)</i>) and
--   <a>uncons</a> (<i>O(1)</i>), to be used together with <a>Empty</a>.
pattern (:<) :: Char -> Text -> Text
infixr 5 :<

-- | Bidirectional pattern synonym for <a>snoc</a> (<i>O(n)</i>) and
--   <a>unsnoc</a> (<i>O(1)</i>) to be used together with <a>Empty</a>.
pattern (:>) :: Text -> Char -> Text
infixl 5 :>

-- | <i>O(1)</i> Adds a character to the front of a <a>Text</a>.
cons :: Char -> Text -> Text
infixr 5 `cons`

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

-- | <i>O(n/c)</i> Appends one <a>Text</a> to another.
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.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(n/c)</i> Returns the <a>init</a> and <a>last</a> of a
--   <a>Text</a>, or <a>Nothing</a> if empty.
--   
--   <ul>
--   <li>It is no faster than using <a>init</a> and <a>last</a>.</li>
--   </ul>
unsnoc :: Text -> Maybe (Text, Char)

-- | <i>O(1)</i> Returns the first character of a <a>Text</a>, which must
--   be non-empty. This is a partial function, consider using <a>uncons</a>
--   instead.
head :: HasCallStack => Text -> Char

-- | <i>O(n/c)</i> Returns the last character of a <a>Text</a>, which must
--   be non-empty. This is a partial function, consider using <a>unsnoc</a>
--   instead.
last :: HasCallStack => Text -> Char

-- | <i>O(1)</i> Returns all characters after the head of a <a>Text</a>,
--   which must be non-empty. This is a partial function, consider using
--   <a>uncons</a> instead.
tail :: HasCallStack => Text -> Text

-- | <i>O(n/c)</i> Returns all but the last character of a <a>Text</a>,
--   which must be non-empty. This is a partial function, consider using
--   <a>unsnoc</a> instead.
init :: HasCallStack => Text -> Text

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

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

-- | <i>O(min(n,c))</i> Compare the count of characters in a <a>Text</a> to
--   a number.
--   
--   <pre>
--   <a>compareLength</a> t c = <a>compare</a> (<a>length</a> t) c
--   </pre>
--   
--   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>.
--   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>. 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 :: HasCallStack => Text -> Text -> Text -> Text

-- | <i>O(n)</i> Convert a string to folded case.
--   
--   This function is mainly useful for performing caseless (or case
--   insensitive) string comparisons.
--   
--   A string <tt>x</tt> is a caseless match for a string <tt>y</tt> if and
--   only if:
--   
--   <pre>
--   toCaseFold x == toCaseFold y
--   </pre>
--   
--   The result string may be longer than the input string, and may differ
--   from applying <a>toLower</a> to the input string. For instance, the
--   Armenian small ligature men now (U+FB13) is case folded to the bigram
--   men now (U+0574 U+0576), while the micro sign (U+00B5) is case folded
--   to the Greek small letter letter mu (U+03BC) instead of itself.
toCaseFold :: Text -> Text

-- | <i>O(n)</i> Convert a string to lower case, using simple case
--   conversion.
--   
--   The result string may be longer than the input string. For instance,
--   the Latin capital letter I with dot above (U+0130) maps to the
--   sequence Latin small letter i (U+0069) followed by combining dot above
--   (U+0307).
toLower :: Text -> Text

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

-- | <i>O(n)</i> Convert a string to title case, using simple case
--   conversion.
--   
--   The first letter (as determined by <a>isLetter</a>) 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).
--   
--   This function is not idempotent. Consider lower-case letter <tt>ʼn</tt>
--   (U+0149 LATIN SMALL LETTER N PRECEDED BY APOSTROPHE). Then
--   <a>toTitle</a> <tt>"ʼn"</tt> = <tt>"ʼN"</tt>: the first (and the only)
--   letter of the input is converted to title case, becoming two letters.
--   Now <tt>ʼ</tt> (U+02BC MODIFIER LETTER APOSTROPHE) is a modifier
--   letter and as such is recognised as a letter by <a>isLetter</a>, so
--   <a>toTitle</a> <tt>"ʼN"</tt> = <tt>"'n"</tt>.
--   
--   <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. 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.
foldl :: (a -> Char -> a) -> a -> Text -> a

-- | <i>O(n)</i> A strict version of <a>foldl</a>.
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>.
foldl1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A strict version of <a>foldl1</a>.
foldl1' :: HasCallStack => (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.
--   
--   <a>foldr</a> is lazy like <a>foldr</a> for lists: evaluation actually
--   traverses the <a>Text</a> from left to right, only as far as it needs
--   to.
--   
--   For example, <a>head</a> can be defined with <i>O(1)</i> complexity
--   using <a>foldr</a>:
--   
--   <pre>
--   head :: Text -&gt; Char
--   head = foldr const (error "head empty")
--   </pre>
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>.
foldr1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

-- | <i>O(n)</i> A monadic version of <a>foldl'</a>.
foldlM' :: Monad m => (a -> Char -> m a) -> a -> Text -> m a

-- | <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> satisfies the predicate
--   <tt>p</tt>.
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> satisfy the predicate
--   <tt>p</tt>.
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.
maximum :: HasCallStack => Text -> Char

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

-- | O(n) Test whether <a>Text</a> contains only ASCII code-points (i.e.
--   only U+0000 through U+007F).
--   
--   This is a more efficient version of <tt><a>all</a>
--   <a>isAscii</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; isAscii ""
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abc\NUL"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abcd€"
--   False
--   </pre>
--   
--   <pre>
--   isAscii t == all (&lt; '\x80') t
--   </pre>
isAscii :: Text -> Bool

-- | <i>O(n)</i> <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   list of successive reduced values from the left. 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. 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)

-- | <tt><a>repeat</a> x</tt> is an infinite <a>Text</a>, with <tt>x</tt>
--   the value of every element.
repeat :: Char -> 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

-- | <a>cycle</a> ties a finite, non-empty <a>Text</a> into a circular one,
--   or equivalently, the infinite repetition of the original <a>Text</a>.
cycle :: HasCallStack => Text -> Text

-- | <tt><a>iterate</a> f x</tt> returns an infinite <a>Text</a> of
--   repeated applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
iterate :: (Char -> Char) -> Char -> 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.
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>.
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>.
takeWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>takeWhileEnd</a>, applied to a predicate <tt>p</tt> and
--   a <a>Text</a>, returns the longest suffix (possibly empty) of elements
--   that satisfy <tt>p</tt>. Examples:
--   
--   <pre>
--   takeWhileEnd (=='o') "foo" == "oo"
--   </pre>
takeWhileEnd :: (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>.
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 satisfy 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 satisfy the
--   predicate <tt>p</tt> from both the beginning and end of <tt>t</tt>.
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 text.
--   
--   <pre>
--   &gt;&gt;&gt; T.span (=='0') "000AB"
--   ("000","AB")
--   </pre>
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(length of prefix)</i> <a>spanM</a>, applied to a monadic
--   predicate <tt>p</tt>, a text <tt>t</tt>, returns a pair <tt>(t1,
--   t2)</tt> where <tt>t1</tt> is the longest prefix of <tt>t</tt> whose
--   elements satisfy <tt>p</tt>, and <tt>t2</tt> is the remainder of the
--   text.
--   
--   <pre>
--   &gt;&gt;&gt; T.spanM (\c -&gt; state $ \i -&gt; (fromEnum c == i, i+1)) "abcefg" `runState` 97
--   (("abc","efg"),101)
--   </pre>
--   
--   <a>span</a> is <a>spanM</a> specialized to <a>Identity</a>:
--   
--   <pre>
--   -- for all p :: Char -&gt; Bool
--   <a>span</a> p = <a>runIdentity</a> . <a>spanM</a> (<a>pure</a> . p)
--   </pre>
spanM :: Monad m => (Char -> m Bool) -> Text -> m (Text, Text)

-- | <i>O(length of suffix)</i> <a>spanEndM</a>, applied to a monadic
--   predicate <tt>p</tt>, a text <tt>t</tt>, returns a pair <tt>(t1,
--   t2)</tt> where <tt>t2</tt> is the longest suffix of <tt>t</tt> whose
--   elements satisfy <tt>p</tt>, and <tt>t1</tt> is the remainder of the
--   text.
--   
--   <pre>
--   &gt;&gt;&gt; T.spanEndM (\c -&gt; state $ \i -&gt; (fromEnum c == i, i-1)) "tuvxyz" `runState` 122
--   (("tuv","xyz"),118)
--   </pre>
--   
--   <pre>
--   <a>spanEndM</a> p . <a>reverse</a> = fmap (<a>bimap</a> <a>reverse</a> <a>reverse</a>) . <a>spanM</a> p
--   </pre>
spanEndM :: Monad m => (Char -> m Bool) -> Text -> m (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 :: HasCallStack => 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 :: HasCallStack => 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>.
--   
--   <pre>
--   &gt;&gt;&gt; T.break (=='c') "180cm"
--   ("180","cm")
--   </pre>
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 initial segments of the given <a>Text</a>,
--   shortest first.
initsNE :: Text -> NonEmpty Text

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

-- | <i>O(n)</i> Return all final segments of the given <a>Text</a>,
--   longest first.
tailsNE :: Text -> NonEmpty 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 :: HasCallStack => 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 characters <tt>'\n'</tt> (LF, line feed). The resulting
--   strings do not contain newlines.
--   
--   <a>lines</a> <b>does not</b> treat <tt>'\r'</tt> (CR, carriage return)
--   as a newline character.
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> if and only if the first is a prefix of the
--   second.
isPrefixOf :: Text -> Text -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two <a>Text</a>s and
--   returns <a>True</a> if and only if 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> if and only if 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)</i> The <a>elem</a> function takes a character and a
--   <a>Text</a>, and returns <a>True</a> if the element is found in the
--   given <a>Text</a>, or <a>False</a> otherwise.
elem :: Char -> Text -> Bool

-- | <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 :: HasCallStack => 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 :: HasCallStack => 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 :: HasCallStack => 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

-- | Convert a value to lazy <a>Text</a>.
show :: Show a => a -> Text
instance Data.Binary.Class.Binary Data.Text.Internal.Lazy.Text
instance GHC.Internal.Data.Data.Data Data.Text.Internal.Lazy.Text
instance GHC.Classes.Eq Data.Text.Internal.Lazy.Text
instance GHC.Internal.IsList.IsList Data.Text.Internal.Lazy.Text
instance GHC.Internal.Data.String.IsString Data.Text.Internal.Lazy.Text
instance Language.Haskell.TH.Syntax.Lift Data.Text.Internal.Lazy.Text
instance GHC.Internal.Base.Monoid Data.Text.Internal.Lazy.Text
instance Control.DeepSeq.NFData Data.Text.Internal.Lazy.Text
instance GHC.Classes.Ord Data.Text.Internal.Lazy.Text
instance Text.Printf.PrintfArg Data.Text.Internal.Lazy.Text
instance GHC.Internal.Read.Read Data.Text.Internal.Lazy.Text
instance GHC.Internal.Base.Semigroup Data.Text.Internal.Lazy.Text
instance GHC.Internal.Show.Show Data.Text.Internal.Lazy.Text


-- | Functions used frequently when reading textual data.
module Data.Text.Lazy.Read

-- | Read some text. If the read succeeds, return its value and the
--   remaining text, otherwise an error message.
type Reader a = Text -> Either String (a, Text)

-- | Read a decimal integer. The input must begin with at least one decimal
--   digit, and is consumed until a non-digit or end of string is reached.
--   
--   This function does not handle leading sign characters. If you need to
--   handle signed input, use <tt><a>signed</a> <a>decimal</a></tt>.
--   
--   <i>Note</i>: For fixed-width integer types, this function does not
--   attempt to detect overflow, so a sufficiently long input may give
--   incorrect results. If you are worried about overflow, use
--   <a>Integer</a> for your result type.
decimal :: Integral a => Reader a

-- | Read a hexadecimal integer, consisting of an optional leading
--   <tt>"0x"</tt> followed by at least one hexadecimal 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


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

-- | Print a <tt>Stream Char</tt>.
hPutStream :: Handle -> Stream Char -> IO ()

-- | Write a string to a handle.
hPutStr :: Handle -> Text -> IO ()

-- | Write a string to a handle, followed by a newline.
hPutStrLn :: Handle -> Text -> IO ()


-- | Efficient locale-sensitive support for lazy text I/O.
--   
--   The functions in this module obey the runtime system's locale,
--   character set encoding, and line ending conversion settings.
--   
--   If you know in advance that you will be working with data that has a
--   specific encoding (e.g. UTF-8), and your application is highly
--   performance sensitive, you may find that it is faster to perform I/O
--   with bytestrings and to encode and decode yourself than to use the
--   functions in this module.
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>.
--   
--   Beware that this function (similarly to <a>readFile</a>) is
--   locale-dependent. Unexpected system locale may cause your application
--   to read corrupted data or throw runtime exceptions about "invalid
--   argument (invalid byte sequence)" or "invalid argument (invalid
--   character)". This is also slow, because GHC first converts an entire
--   input to UTF-32, which is afterwards converted to UTF-8.
--   
--   If your data is UTF-8, using <a>decodeUtf8</a> <a>.</a>
--   <a>readFile</a> is a much faster and safer alternative.
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 to 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 ()


-- | <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
type LazyTextBuilder = 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>
--   
--   Performs replacement on invalid scalar values:
--   
--   <pre>
--   &gt;&gt;&gt; fromString "\55555"
--   "\65533"
--   </pre>
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 GHC.Classes.Eq Data.Text.Internal.Builder.Builder
instance GHC.Internal.Data.String.IsString Data.Text.Internal.Builder.Builder
instance GHC.Internal.Base.Monoid Data.Text.Internal.Builder.Builder
instance GHC.Classes.Ord Data.Text.Internal.Builder.Builder
instance GHC.Internal.Base.Semigroup Data.Text.Internal.Builder.Builder
instance GHC.Internal.Show.Show Data.Text.Internal.Builder.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 <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. Or,
--   equivalently, prefer
--   
--   <pre>
--   singleton 'a' &lt;&gt; singleton 'b' &lt;&gt; singleton 'c'
--   </pre>
--   
--   since the <a>&lt;&gt;</a> 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
type LazyTextBuilder = 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>
--   
--   Performs replacement on invalid scalar values:
--   
--   <pre>
--   &gt;&gt;&gt; fromString "\55555"
--   "\65533"
--   </pre>
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
infixr 4 <>

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

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


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

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

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

-- | Standard decimal notation.
Fixed :: FPFormat

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

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

-- | Encode a signed <a>RealFloat</a> according to <a>FPFormat</a> and
--   optionally requested precision.
--   
--   This corresponds to the <tt>show{E,F,G}Float</tt> operations provided
--   by <tt>base</tt>'s <a>Numeric</a> module.
--   
--   <b>NOTE</b>: The functions in <tt>base-4.12</tt> changed the
--   serialisation in case of a <tt>Just 0</tt> precision; this version of
--   <tt>text</tt> still provides the serialisation as implemented in
--   <tt>base-4.11</tt>. The next major version of <tt>text</tt> will
--   switch to the more correct <tt>base-4.12</tt> serialisation.
formatRealFloat :: RealFloat a => FPFormat -> Maybe Int -> a -> Builder
instance GHC.Internal.Enum.Bounded Data.Text.Lazy.Builder.RealFloat.FPFormat
instance GHC.Internal.Enum.Enum Data.Text.Lazy.Builder.RealFloat.FPFormat
instance GHC.Internal.Read.Read Data.Text.Lazy.Builder.RealFloat.FPFormat
instance GHC.Internal.Show.Show Data.Text.Lazy.Builder.RealFloat.FPFormat


-- | Efficient UTF-8 support for text I/O. Unlike <tt>Data.Text.IO</tt>,
--   these functions do not depend on the locale and do not do line ending
--   conversion.
module Data.Text.IO.Utf8

-- | 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 to the end of a file.
appendFile :: FilePath -> Text -> IO ()

-- | Read the remaining contents of a <a>Handle</a> as a string.
hGetContents :: Handle -> IO Text

-- | Read a single line from a handle.
hGetLine :: Handle -> IO Text

-- | Write a string to a handle.
hPutStr :: Handle -> Text -> IO ()

-- | Write a string to a handle, followed by a newline.
hPutStrLn :: Handle -> Text -> IO ()

-- | The <a>interact</a> function takes a function of type <tt>Text -&gt;
--   Text</tt> as its argument. The entire input from the standard input
--   device is passed to this function as its argument, and the resulting
--   string is output on the standard output device.
interact :: (Text -> Text) -> IO ()

-- | Read all user input on <tt>stdin</tt> as a single string.
getContents :: IO Text

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

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

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


-- | Efficient locale-sensitive support for text I/O.
--   
--   The functions in this module obey the runtime system's locale,
--   character set encoding, and line ending conversion settings.
--   
--   If you want to do I/O using the UTF-8 encoding, use
--   <tt>Data.Text.IO.Utf8</tt>, which is faster than this module.
--   
--   If you know in advance that you will be working with data that has a
--   specific encoding, and your application is highly performance
--   sensitive, you may find that it is faster to perform I/O with
--   bytestrings and to encode and decode yourself than to use the
--   functions in this module.
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>.
--   
--   Beware that this function (similarly to <a>readFile</a>) is
--   locale-dependent. Unexpected system locale may cause your application
--   to read corrupted data or throw runtime exceptions about "invalid
--   argument (invalid byte sequence)" or "invalid argument (invalid
--   character)". This is also slow, because GHC first converts an entire
--   input to UTF-32, which is afterwards converted to UTF-8.
--   
--   If your data is UTF-8, using <a>decodeUtf8</a> <a>.</a>
--   <a>readFile</a> is a much faster and safer alternative.
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 to 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 ()