-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A standard library for Haskell
--   
--   See README and Haddocks at <a>https://www.stackage.org/package/rio</a>
@package rio
@version 0.1.21.0


-- | Lazy <tt>ByteString</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.ByteString.Lazy.Partial as BL'
--   </pre>
module RIO.ByteString.Lazy.Partial

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty.
head :: ByteString -> Word8

-- | <i>O(n/c)</i> Extract the last element of a ByteString, which must be
--   finite and non-empty.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty.
tail :: ByteString -> ByteString

-- | <i>O(n/c)</i> Return all the elements of a <a>ByteString</a> except
--   the last one.
init :: ByteString -> ByteString

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a>
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a>
minimum :: ByteString -> Word8


-- | Strict <tt>ByteString</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.ByteString.Partial as B'
--   </pre>
module RIO.ByteString.Partial

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   ByteString.
head :: ByteString -> Word8

-- | <i>O(1)</i> Extract the last element of a ByteString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty ByteString.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   ByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: ByteString -> ByteString

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s. An
--   exception will be thrown in the case of an empty ByteString.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty ByteString.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s An
--   exception will be thrown in the case of an empty ByteString.
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
minimum :: ByteString -> Word8


-- | Unicode <tt>Char</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Char as C
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.Char.Partial</a>
module RIO.Char

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <a>ord</a> and
--   <a>chr</a>).
data Char

-- | Selects control characters, which are the non-printing characters of
--   the Latin-1 subset of Unicode.
isControl :: Char -> Bool

-- | Returns <a>True</a> for any Unicode space character, and the control
--   characters <tt>\t</tt>, <tt>\n</tt>, <tt>\r</tt>, <tt>\f</tt>,
--   <tt>\v</tt>.
isSpace :: Char -> Bool

-- | Selects lower-case alphabetic Unicode characters (letters).
isLower :: Char -> Bool

-- | Selects upper-case or title-case alphabetic Unicode characters
--   (letters). Title case is used by a small number of letter ligatures
--   like the single-character form of <i>Lj</i>.
isUpper :: Char -> Bool

-- | Selects alphabetic Unicode characters (lower-case, upper-case and
--   title-case letters, plus letters of caseless scripts and modifiers
--   letters). This function is equivalent to <a>isLetter</a>.
isAlpha :: Char -> Bool

-- | Selects alphabetic or numeric Unicode characters.
--   
--   Note that numeric digits outside the ASCII range, as well as numeric
--   characters which aren't digits, are selected by this function but not
--   by <a>isDigit</a>. Such characters may be part of identifiers but are
--   not used by the printer and reader to represent numbers.
isAlphaNum :: Char -> Bool

-- | Selects printable Unicode characters (letters, numbers, marks,
--   punctuation, symbols and spaces).
isPrint :: Char -> Bool

-- | Selects ASCII digits, i.e. <tt>'0'</tt>..<tt>'9'</tt>.
isDigit :: Char -> Bool

-- | Selects ASCII octal digits, i.e. <tt>'0'</tt>..<tt>'7'</tt>.
isOctDigit :: Char -> Bool

-- | Selects ASCII hexadecimal digits, i.e. <tt>'0'</tt>..<tt>'9'</tt>,
--   <tt>'a'</tt>..<tt>'f'</tt>, <tt>'A'</tt>..<tt>'F'</tt>.
isHexDigit :: Char -> Bool

-- | Selects alphabetic Unicode characters (lower-case, upper-case and
--   title-case letters, plus letters of caseless scripts and modifiers
--   letters). This function is equivalent to <a>isAlpha</a>.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>UppercaseLetter</a></li>
--   <li><a>LowercaseLetter</a></li>
--   <li><a>TitlecaseLetter</a></li>
--   <li><a>ModifierLetter</a></li>
--   <li><a>OtherLetter</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Letter".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isLetter 'a'
--   True
--   
--   &gt;&gt;&gt; isLetter 'A'
--   True
--   
--   &gt;&gt;&gt; isLetter 'λ'
--   True
--   
--   &gt;&gt;&gt; isLetter '0'
--   False
--   
--   &gt;&gt;&gt; isLetter '%'
--   False
--   
--   &gt;&gt;&gt; isLetter '♥'
--   False
--   
--   &gt;&gt;&gt; isLetter '\31'
--   False
--   </pre>
--   
--   Ensure that <a>isLetter</a> and <a>isAlpha</a> are equivalent.
--   
--   <pre>
--   &gt;&gt;&gt; let chars = [(chr 0)..]
--   
--   &gt;&gt;&gt; let letters = map isLetter chars
--   
--   &gt;&gt;&gt; let alphas = map isAlpha chars
--   
--   &gt;&gt;&gt; letters == alphas
--   True
--   </pre>
isLetter :: Char -> Bool

-- | Selects Unicode mark characters, for example accents and the like,
--   which combine with preceding characters.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>NonSpacingMark</a></li>
--   <li><a>SpacingCombiningMark</a></li>
--   <li><a>EnclosingMark</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Mark".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isMark 'a'
--   False
--   
--   &gt;&gt;&gt; isMark '0'
--   False
--   </pre>
--   
--   Combining marks such as accent characters usually need to follow
--   another character before they become printable:
--   
--   <pre>
--   &gt;&gt;&gt; map isMark "ò"
--   [False,True]
--   </pre>
--   
--   Puns are not necessarily supported:
--   
--   <pre>
--   &gt;&gt;&gt; isMark '✓'
--   False
--   </pre>
isMark :: Char -> Bool

-- | Selects Unicode numeric characters, including digits from various
--   scripts, Roman numerals, et cetera.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>DecimalNumber</a></li>
--   <li><a>LetterNumber</a></li>
--   <li><a>OtherNumber</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Number".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isNumber 'a'
--   False
--   
--   &gt;&gt;&gt; isNumber '%'
--   False
--   
--   &gt;&gt;&gt; isNumber '3'
--   True
--   </pre>
--   
--   ASCII <tt>'0'</tt> through <tt>'9'</tt> are all numbers:
--   
--   <pre>
--   &gt;&gt;&gt; and $ map isNumber ['0'..'9']
--   True
--   </pre>
--   
--   Unicode Roman numerals are "numbers" as well:
--   
--   <pre>
--   &gt;&gt;&gt; isNumber 'Ⅸ'
--   True
--   </pre>
isNumber :: Char -> Bool

-- | Selects Unicode punctuation characters, including various kinds of
--   connectors, brackets and quotes.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>ConnectorPunctuation</a></li>
--   <li><a>DashPunctuation</a></li>
--   <li><a>OpenPunctuation</a></li>
--   <li><a>ClosePunctuation</a></li>
--   <li><a>InitialQuote</a></li>
--   <li><a>FinalQuote</a></li>
--   <li><a>OtherPunctuation</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Punctuation".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isPunctuation 'a'
--   False
--   
--   &gt;&gt;&gt; isPunctuation '7'
--   False
--   
--   &gt;&gt;&gt; isPunctuation '♥'
--   False
--   
--   &gt;&gt;&gt; isPunctuation '"'
--   True
--   
--   &gt;&gt;&gt; isPunctuation '?'
--   True
--   
--   &gt;&gt;&gt; isPunctuation '—'
--   True
--   </pre>
isPunctuation :: Char -> Bool

-- | Selects Unicode symbol characters, including mathematical and currency
--   symbols.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>MathSymbol</a></li>
--   <li><a>CurrencySymbol</a></li>
--   <li><a>ModifierSymbol</a></li>
--   <li><a>OtherSymbol</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Symbol".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isSymbol 'a'
--   False
--   
--   &gt;&gt;&gt; isSymbol '6'
--   False
--   
--   &gt;&gt;&gt; isSymbol '='
--   True
--   </pre>
--   
--   The definition of "math symbol" may be a little counter-intuitive
--   depending on one's background:
--   
--   <pre>
--   &gt;&gt;&gt; isSymbol '+'
--   True
--   
--   &gt;&gt;&gt; isSymbol '-'
--   False
--   </pre>
isSymbol :: Char -> Bool

-- | Selects Unicode space and separator characters.
--   
--   This function returns <a>True</a> if its argument has one of the
--   following <a>GeneralCategory</a>s, or <a>False</a> otherwise:
--   
--   <ul>
--   <li><a>Space</a></li>
--   <li><a>LineSeparator</a></li>
--   <li><a>ParagraphSeparator</a></li>
--   </ul>
--   
--   These classes are defined in the <a>Unicode Character Database</a>,
--   part of the Unicode standard. The same document defines what is and is
--   not a "Separator".
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isSeparator 'a'
--   False
--   
--   &gt;&gt;&gt; isSeparator '6'
--   False
--   
--   &gt;&gt;&gt; isSeparator ' '
--   True
--   </pre>
--   
--   Warning: newlines and tab characters are not considered separators.
--   
--   <pre>
--   &gt;&gt;&gt; isSeparator '\n'
--   False
--   
--   &gt;&gt;&gt; isSeparator '\t'
--   False
--   </pre>
--   
--   But some more exotic characters are (like HTML's <tt>&amp;nbsp;</tt>):
--   
--   <pre>
--   &gt;&gt;&gt; isSeparator '\160'
--   True
--   </pre>
isSeparator :: Char -> Bool

-- | Selects the first 128 characters of the Unicode character set,
--   corresponding to the ASCII character set.
isAscii :: Char -> Bool

-- | Selects the first 256 characters of the Unicode character set,
--   corresponding to the ISO 8859-1 (Latin-1) character set.
isLatin1 :: Char -> Bool

-- | Selects ASCII upper-case letters, i.e. characters satisfying both
--   <a>isAscii</a> and <a>isUpper</a>.
isAsciiUpper :: Char -> Bool

-- | Selects ASCII lower-case letters, i.e. characters satisfying both
--   <a>isAscii</a> and <a>isLower</a>.
isAsciiLower :: Char -> Bool

-- | Unicode General Categories (column 2 of the UnicodeData table) in the
--   order they are listed in the Unicode standard (the Unicode Character
--   Database, in particular).
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; :t OtherLetter
--   OtherLetter :: GeneralCategory
--   </pre>
--   
--   <a>Eq</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; UppercaseLetter == UppercaseLetter
--   True
--   
--   &gt;&gt;&gt; UppercaseLetter == LowercaseLetter
--   False
--   </pre>
--   
--   <a>Ord</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; NonSpacingMark &lt;= MathSymbol
--   True
--   </pre>
--   
--   <a>Enum</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; enumFromTo ModifierLetter SpacingCombiningMark
--   [ModifierLetter,OtherLetter,NonSpacingMark,SpacingCombiningMark]
--   </pre>
--   
--   <a>Read</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; read "DashPunctuation" :: GeneralCategory
--   DashPunctuation
--   
--   &gt;&gt;&gt; read "17" :: GeneralCategory
--   *** Exception: Prelude.read: no parse
--   </pre>
--   
--   <a>Show</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; show EnclosingMark
--   "EnclosingMark"
--   </pre>
--   
--   <a>Bounded</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; minBound :: GeneralCategory
--   UppercaseLetter
--   
--   &gt;&gt;&gt; maxBound :: GeneralCategory
--   NotAssigned
--   </pre>
--   
--   <a>Ix</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ix ( index )
--   
--   &gt;&gt;&gt; index (OtherLetter,Control) FinalQuote
--   12
--   
--   &gt;&gt;&gt; index (OtherLetter,Control) Format
--   *** Exception: Error in array index
--   </pre>
data GeneralCategory

-- | Lu: Letter, Uppercase
UppercaseLetter :: GeneralCategory

-- | Ll: Letter, Lowercase
LowercaseLetter :: GeneralCategory

-- | Lt: Letter, Titlecase
TitlecaseLetter :: GeneralCategory

-- | Lm: Letter, Modifier
ModifierLetter :: GeneralCategory

-- | Lo: Letter, Other
OtherLetter :: GeneralCategory

-- | Mn: Mark, Non-Spacing
NonSpacingMark :: GeneralCategory

-- | Mc: Mark, Spacing Combining
SpacingCombiningMark :: GeneralCategory

-- | Me: Mark, Enclosing
EnclosingMark :: GeneralCategory

-- | Nd: Number, Decimal
DecimalNumber :: GeneralCategory

-- | Nl: Number, Letter
LetterNumber :: GeneralCategory

-- | No: Number, Other
OtherNumber :: GeneralCategory

-- | Pc: Punctuation, Connector
ConnectorPunctuation :: GeneralCategory

-- | Pd: Punctuation, Dash
DashPunctuation :: GeneralCategory

-- | Ps: Punctuation, Open
OpenPunctuation :: GeneralCategory

-- | Pe: Punctuation, Close
ClosePunctuation :: GeneralCategory

-- | Pi: Punctuation, Initial quote
InitialQuote :: GeneralCategory

-- | Pf: Punctuation, Final quote
FinalQuote :: GeneralCategory

-- | Po: Punctuation, Other
OtherPunctuation :: GeneralCategory

-- | Sm: Symbol, Math
MathSymbol :: GeneralCategory

-- | Sc: Symbol, Currency
CurrencySymbol :: GeneralCategory

-- | Sk: Symbol, Modifier
ModifierSymbol :: GeneralCategory

-- | So: Symbol, Other
OtherSymbol :: GeneralCategory

-- | Zs: Separator, Space
Space :: GeneralCategory

-- | Zl: Separator, Line
LineSeparator :: GeneralCategory

-- | Zp: Separator, Paragraph
ParagraphSeparator :: GeneralCategory

-- | Cc: Other, Control
Control :: GeneralCategory

-- | Cf: Other, Format
Format :: GeneralCategory

-- | Cs: Other, Surrogate
Surrogate :: GeneralCategory

-- | Co: Other, Private Use
PrivateUse :: GeneralCategory

-- | Cn: Other, Not Assigned
NotAssigned :: GeneralCategory

-- | The Unicode general category of the character. This relies on the
--   <a>Enum</a> instance of <a>GeneralCategory</a>, which must remain in
--   the same order as the categories are presented in the Unicode
--   standard.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; generalCategory 'a'
--   LowercaseLetter
--   
--   &gt;&gt;&gt; generalCategory 'A'
--   UppercaseLetter
--   
--   &gt;&gt;&gt; generalCategory '0'
--   DecimalNumber
--   
--   &gt;&gt;&gt; generalCategory '%'
--   OtherPunctuation
--   
--   &gt;&gt;&gt; generalCategory '♥'
--   OtherSymbol
--   
--   &gt;&gt;&gt; generalCategory '\31'
--   Control
--   
--   &gt;&gt;&gt; generalCategory ' '
--   Space
--   </pre>
generalCategory :: Char -> GeneralCategory

-- | Convert a letter to the corresponding upper-case letter, if any. Any
--   other character is returned unchanged.
toUpper :: Char -> Char

-- | Convert a letter to the corresponding lower-case letter, if any. Any
--   other character is returned unchanged.
toLower :: Char -> Char

-- | Convert a letter to the corresponding title-case or upper-case letter,
--   if any. (Title case differs from upper case only for a small number of
--   ligature letters.) Any other character is returned unchanged.
toTitle :: Char -> Char

-- | The <a>fromEnum</a> method restricted to the type <a>Char</a>.
ord :: Char -> Int

-- | Convert a character to a string using only printable characters, using
--   Haskell source-language escape conventions. For example:
--   
--   <pre>
--   showLitChar '\n' s  =  "\\n" ++ s
--   </pre>
showLitChar :: Char -> ShowS

-- | Read a string representation of a character, using Haskell
--   source-language escape conventions. For example:
--   
--   <pre>
--   lexLitChar  "\\nHello"  =  [("\\n", "Hello")]
--   </pre>
lexLitChar :: ReadS String

-- | Read a string representation of a character, using Haskell
--   source-language escape conventions, and convert it to the character
--   that it encodes. For example:
--   
--   <pre>
--   readLitChar "\\nHello"  =  [('\n', "Hello")]
--   </pre>
readLitChar :: ReadS Char


-- | Unicode <tt>Char</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Char.Partial as C'
--   </pre>
module RIO.Char.Partial

-- | Convert a single digit <a>Char</a> to the corresponding <a>Int</a>.
--   This function fails unless its argument satisfies <a>isHexDigit</a>,
--   but recognises both upper- and lower-case hexadecimal digits (that is,
--   <tt>'0'</tt>..<tt>'9'</tt>, <tt>'a'</tt>..<tt>'f'</tt>,
--   <tt>'A'</tt>..<tt>'F'</tt>).
--   
--   <h4><b>Examples</b></h4>
--   
--   Characters <tt>'0'</tt> through <tt>'9'</tt> are converted properly to
--   <tt>0..9</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; map digitToInt ['0'..'9']
--   [0,1,2,3,4,5,6,7,8,9]
--   </pre>
--   
--   Both upper- and lower-case <tt>'A'</tt> through <tt>'F'</tt> are
--   converted as well, to <tt>10..15</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; map digitToInt ['a'..'f']
--   [10,11,12,13,14,15]
--   
--   &gt;&gt;&gt; map digitToInt ['A'..'F']
--   [10,11,12,13,14,15]
--   </pre>
--   
--   Anything else throws an exception:
--   
--   <pre>
--   &gt;&gt;&gt; digitToInt 'G'
--   *** Exception: Char.digitToInt: not a digit 'G'
--   
--   &gt;&gt;&gt; digitToInt '♥'
--   *** Exception: Char.digitToInt: not a digit '\9829'
--   </pre>
digitToInt :: Char -> Int

-- | Convert an <a>Int</a> in the range <tt>0</tt>..<tt>15</tt> to the
--   corresponding single digit <a>Char</a>. This function fails on other
--   inputs, and generates lower-case hexadecimal digits.
intToDigit :: Int -> Char

-- | The <a>toEnum</a> method restricted to the type <a>Char</a>.
chr :: Int -> Char

module RIO.Directory


-- | <h2>Rationale</h2>
--   
--   This module offers functions to handle files that offer better
--   durability and/or atomicity.
--   
--   See <a>UnliftIO.IO.File</a> for the rationale behind this module,
--   since all of the functions were moved upstream and are now simply
--   re-exported from here.
module RIO.File

-- | Unlifted version of <a>withBinaryFile</a>.
withBinaryFile :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m a) -> m a

-- | Lifted version of <a>writeFile</a>
writeBinaryFile :: MonadIO m => FilePath -> ByteString -> m ()

-- | Perform an action on a new or existing file at the destination file
--   path. If previously the file existed at the supplied file path then:
--   
--   <ul>
--   <li>in case of <a>WriteMode</a> it will be overwritten</li>
--   <li>upon <a>ReadWriteMode</a> or <a>AppendMode</a> files contents will
--   be copied over into a temporary file, thus making sure no corruption
--   can happen to an existing file upon any failures, even catastrophic
--   one, yet its contents are availble for modification.</li>
--   <li>There is nothing atomic about <a>ReadMode</a>, so no special
--   treatment there.</li>
--   </ul>
--   
--   It is similar to <a>withBinaryFileDurableAtomic</a>, but without the
--   durability part. It means that all modification can still disappear
--   after it has been succesfully written due to some extreme event like
--   an abrupt power loss, but the contents will not be corrupted in case
--   when the file write did not end successfully.
--   
--   The same performance caveats apply as for
--   <a>withBinaryFileDurableAtomic</a> due to making a copy of the content
--   of existing files during non-truncating writes.
--   
--   <b>Important</b> - Do not close the handle, otherwise it will result
--   in <tt>invalid argument (Bad file descriptor)</tt> exception
--   
--   <b>Note</b> - on Linux operating system and only with supported file
--   systems an anonymous temporary file will be used while working on the
--   file (see <tt>O_TMPFILE</tt> in <tt>man openat</tt>). In case when
--   such feature is not available or not supported a temporary file
--   ".target-file-nameXXX.ext.tmp", where XXX is some random number, will
--   be created alongside the target file in the same directory
withBinaryFileAtomic :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Same as <a>writeBinaryFileDurableAtomic</a>, except it does not
--   guarantee durability.
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function behaves the same as <a>writeBinaryFile</a> on Windows
--   platforms.
writeBinaryFileAtomic :: MonadIO m => FilePath -> ByteString -> m ()

-- | Opens a file with the following guarantees:
--   
--   <ul>
--   <li>It successfully closes the file in case of an asynchronous
--   exception</li>
--   <li>It reliably saves the file in the correct directory; including
--   edge case situations like a different device being mounted to the
--   current directory, or the current directory being renamed to some
--   other name while the file is being used.</li>
--   <li>It ensures durability by executing an <tt>fsync()</tt> call before
--   closing the file handle</li>
--   </ul>
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function behaves the same as <a>withBinaryFile</a> on Windows
--   platforms.
withBinaryFileDurable :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Similar to <a>writeBinaryFile</a>, but it also ensures that changes
--   executed to the file are guaranteed to be durable. It internally uses
--   <tt>fsync()</tt> and makes sure it synchronizes the file on disk.
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function behaves the same as <a>writeBinaryFile</a> on Windows
--   platforms.
writeBinaryFileDurable :: MonadIO m => FilePath -> ByteString -> m ()

-- | After a file is closed, this function opens it again and executes
--   <tt>fsync()</tt> internally on both the file and the directory that
--   contains it. Note that this function is intended to work around the
--   non-durability of existing file APIs, as opposed to being necessary
--   for the API functions provided in this module.
--   
--   <a>The effectiveness of calling this function is debatable</a>, as it
--   relies on internal implementation details at the Kernel level that
--   might change. We argue that, despite this fact, calling this function
--   may bring benefits in terms of durability.
--   
--   This function does not provide the same guarantee as if you would open
--   and modify a file using <a>withBinaryFileDurable</a> or
--   <a>writeBinaryFileDurable</a>, since they ensure that the
--   <tt>fsync()</tt> is called before the file is closed, so if possible
--   use those instead.
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function is a noop on Windows platforms.
ensureFileDurable :: MonadIO m => FilePath -> m ()

-- | Opens a file with the following guarantees:
--   
--   <ul>
--   <li>It successfully closes the file in case of an asynchronous
--   exception</li>
--   <li>It reliably saves the file in the correct directory; including
--   edge case situations like a different device being mounted to the
--   current directory, or the current directory being renamed to some
--   other name while the file is being used.</li>
--   <li>It ensures durability by executing an <tt>fsync()</tt> call before
--   closing the file handle</li>
--   <li>It keeps all changes in a temporary file, and after it is closed
--   it atomically moves the temporary file to the original filepath, in
--   case of catastrophic failure, the original file stays unaffected.</li>
--   </ul>
--   
--   If you do not need durability but only atomicity, use
--   <a>withBinaryFileAtomic</a> instead, which is faster as it does not
--   perform <tt>fsync()</tt>.
--   
--   <b>Important</b> - Make sure not to close the <a>Handle</a>, it will
--   be closed for you, otherwise it will result in <tt>invalid argument
--   (Bad file descriptor)</tt> exception.
--   
--   <h3>Performance Considerations</h3>
--   
--   When using a writable but non-truncating <a>IOMode</a> (i.e.
--   <a>ReadWriteMode</a> and <a>AppendMode</a>), this function performs a
--   copy operation of the specified input file to guarantee the original
--   file is intact in case of a catastrophic failure (no partial writes).
--   This approach may be prohibitive in scenarios where the input file is
--   expected to be large in size.
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function behaves the same as <a>withBinaryFile</a> on Windows
--   platforms.
withBinaryFileDurableAtomic :: MonadUnliftIO m => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Similar to <a>writeBinaryFile</a>, but it also guarantes that changes
--   executed to the file are durable, also, in case of failure, the
--   modified file is never going to get corrupted. It internally uses
--   <tt>fsync()</tt> and makes sure it synchronizes the file on disk.
--   
--   <h3>Cross-Platform support</h3>
--   
--   This function behaves the same as <a>writeBinaryFile</a> on Windows
--   platforms.
writeBinaryFileDurableAtomic :: MonadIO m => FilePath -> ByteString -> m ()

module RIO.FilePath

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Combine two paths with a path separator. If the second path starts
--   with a path separator or a drive letter, then it returns the second.
--   The intention is that <tt>readFile (dir <a>&lt;/&gt;</a> file)</tt>
--   will access the same file as <tt>setCurrentDirectory dir; readFile
--   file</tt>.
--   
--   <pre>
--   Posix:   "/directory" &lt;/&gt; "file.ext" == "/directory/file.ext"
--   Windows: "/directory" &lt;/&gt; "file.ext" == "/directory\\file.ext"
--            "directory" &lt;/&gt; "/file.ext" == "/file.ext"
--   Valid x =&gt; (takeDirectory x &lt;/&gt; takeFileName x) `equalFilePath` x
--   </pre>
--   
--   Combined:
--   
--   <pre>
--   Posix:   "/" &lt;/&gt; "test" == "/test"
--   Posix:   "home" &lt;/&gt; "bob" == "home/bob"
--   Posix:   "x:" &lt;/&gt; "foo" == "x:/foo"
--   Windows: "C:\\foo" &lt;/&gt; "bar" == "C:\\foo\\bar"
--   Windows: "home" &lt;/&gt; "bob" == "home\\bob"
--   </pre>
--   
--   Not combined:
--   
--   <pre>
--   Posix:   "home" &lt;/&gt; "/bob" == "/bob"
--   Windows: "home" &lt;/&gt; "C:\\bob" == "C:\\bob"
--   </pre>
--   
--   Not combined (tricky):
--   
--   On Windows, if a filepath starts with a single slash, it is relative
--   to the root of the current drive. In [1], this is (confusingly)
--   referred to as an absolute path. The current behavior of
--   <a>&lt;/&gt;</a> is to never combine these forms.
--   
--   <pre>
--   Windows: "home" &lt;/&gt; "/bob" == "/bob"
--   Windows: "home" &lt;/&gt; "\\bob" == "\\bob"
--   Windows: "C:\\home" &lt;/&gt; "\\bob" == "\\bob"
--   </pre>
--   
--   On Windows, from [1]: "If a file name begins with only a disk
--   designator but not the backslash after the colon, it is interpreted as
--   a relative path to the current directory on the drive with the
--   specified letter." The current behavior of <a>&lt;/&gt;</a> is to
--   never combine these forms.
--   
--   <pre>
--   Windows: "D:\\foo" &lt;/&gt; "C:bar" == "C:bar"
--   Windows: "C:\\foo" &lt;/&gt; "C:bar" == "C:bar"
--   </pre>
(</>) :: FilePath -> FilePath -> FilePath
infixr 5 </>

-- | Contract a filename, based on a relative path. Note that the resulting
--   path will never introduce <tt>..</tt> paths, as the presence of
--   symlinks means <tt>../b</tt> may not reach <tt>a/b</tt> if it starts
--   from <tt>a/c</tt>. For a worked example see <a>this blog post</a>.
--   
--   The corresponding <tt>makeAbsolute</tt> function can be found in
--   <tt>System.Directory</tt>.
--   
--   <pre>
--            makeRelative "/directory" "/directory/file.ext" == "file.ext"
--            Valid x =&gt; makeRelative (takeDirectory x) x `equalFilePath` takeFileName x
--            makeRelative x x == "."
--            Valid x y =&gt; equalFilePath x y || (isRelative x &amp;&amp; makeRelative y x == x) || equalFilePath (y &lt;/&gt; makeRelative y x) x
--   Windows: makeRelative "C:\\Home" "c:\\home\\bob" == "bob"
--   Windows: makeRelative "C:\\Home" "c:/home/bob" == "bob"
--   Windows: makeRelative "C:\\Home" "D:\\Home\\Bob" == "D:\\Home\\Bob"
--   Windows: makeRelative "C:\\Home" "C:Home\\Bob" == "C:Home\\Bob"
--   Windows: makeRelative "/Home" "/home/bob" == "bob"
--   Windows: makeRelative "/" "//" == "//"
--   Posix:   makeRelative "/Home" "/home/bob" == "/home/bob"
--   Posix:   makeRelative "/home/" "/home/bob/foo/bar" == "bob/foo/bar"
--   Posix:   makeRelative "/fred" "bob" == "bob"
--   Posix:   makeRelative "/file/test" "/file/test/fred" == "fred"
--   Posix:   makeRelative "/file/test" "/file/test/fred/" == "fred/"
--   Posix:   makeRelative "some/path" "some/path/a/b/c" == "a/b/c"
--   </pre>
makeRelative :: FilePath -> FilePath -> FilePath

-- | Remove any trailing path separators
--   
--   <pre>
--   dropTrailingPathSeparator "file/test/" == "file/test"
--             dropTrailingPathSeparator "/" == "/"
--   Windows:  dropTrailingPathSeparator "\\" == "\\"
--   Posix:    not (hasTrailingPathSeparator (dropTrailingPathSeparator x)) || isDrive x
--   </pre>
dropTrailingPathSeparator :: FilePath -> FilePath

-- | Normalise a file
--   
--   <ul>
--   <li>// outside of the drive can be made blank</li>
--   <li>/ -&gt; <a>pathSeparator</a></li>
--   <li>./ -&gt; ""</li>
--   </ul>
--   
--   <pre>
--   Posix:   normalise "/file/\\test////" == "/file/\\test/"
--   Posix:   normalise "/file/./test" == "/file/test"
--   Posix:   normalise "/test/file/../bob/fred/" == "/test/file/../bob/fred/"
--   Posix:   normalise "../bob/fred/" == "../bob/fred/"
--   Posix:   normalise "./bob/fred/" == "bob/fred/"
--   Windows: normalise "c:\\file/bob\\" == "C:\\file\\bob\\"
--   Windows: normalise "c:\\" == "C:\\"
--   Windows: normalise "C:.\\" == "C:"
--   Windows: normalise "\\\\server\\test" == "\\\\server\\test"
--   Windows: normalise "//server/test" == "\\\\server\\test"
--   Windows: normalise "c:/file" == "C:\\file"
--   Windows: normalise "/file" == "\\file"
--   Windows: normalise "\\" == "\\"
--   Windows: normalise "/./" == "\\"
--            normalise "." == "."
--   Posix:   normalise "./" == "./"
--   Posix:   normalise "./." == "./"
--   Posix:   normalise "/./" == "/"
--   Posix:   normalise "/" == "/"
--   Posix:   normalise "bob/fred/." == "bob/fred/"
--   Posix:   normalise "//home" == "/home"
--   </pre>
normalise :: FilePath -> FilePath

-- | <pre>
--   not . <a>isRelative</a>
--   </pre>
--   
--   <pre>
--   isAbsolute x == not (isRelative x)
--   </pre>
isAbsolute :: FilePath -> Bool

-- | Is a path relative, or is it fixed to the root?
--   
--   <pre>
--   Windows: isRelative "path\\test" == True
--   Windows: isRelative "c:\\test" == False
--   Windows: isRelative "c:test" == True
--   Windows: isRelative "c:\\" == False
--   Windows: isRelative "c:/" == False
--   Windows: isRelative "c:" == True
--   Windows: isRelative "\\\\foo" == False
--   Windows: isRelative "\\\\?\\foo" == False
--   Windows: isRelative "\\\\?\\UNC\\foo" == False
--   Windows: isRelative "/foo" == True
--   Windows: isRelative "\\foo" == True
--   Posix:   isRelative "test/path" == True
--   Posix:   isRelative "/test" == False
--   Posix:   isRelative "/" == False
--   </pre>
--   
--   According to [1]:
--   
--   <ul>
--   <li>"A UNC name of any format [is never relative]."</li>
--   <li>"You cannot use the "\?" prefix with a relative path."</li>
--   </ul>
isRelative :: FilePath -> Bool

-- | Take a FilePath and make it valid; does not change already valid
--   FilePaths.
--   
--   <pre>
--   isValid (makeValid x)
--   isValid x ==&gt; makeValid x == x
--   makeValid "" == "_"
--   makeValid "file\0name" == "file_name"
--   Windows: makeValid "c:\\already\\/valid" == "c:\\already\\/valid"
--   Windows: makeValid "c:\\test:of_test" == "c:\\test_of_test"
--   Windows: makeValid "test*" == "test_"
--   Windows: makeValid "c:\\test\\nul" == "c:\\test\\nul_"
--   Windows: makeValid "c:\\test\\prn.txt" == "c:\\test\\prn_.txt"
--   Windows: makeValid "c:\\test/prn.txt" == "c:\\test/prn_.txt"
--   Windows: makeValid "c:\\nul\\file" == "c:\\nul_\\file"
--   Windows: makeValid "\\\\\\foo" == "\\\\drive"
--   Windows: makeValid "\\\\?\\D:file" == "\\\\?\\D:\\file"
--   Windows: makeValid "nul .txt" == "nul _.txt"
--   </pre>
makeValid :: FilePath -> FilePath

-- | Is a FilePath valid, i.e. could you create a file like it? This
--   function checks for invalid names, and invalid characters, but does
--   not check if length limits are exceeded, as these are typically
--   filesystem dependent.
--   
--   <pre>
--            isValid "" == False
--            isValid "\0" == False
--   Posix:   isValid "/random_ path:*" == True
--   Posix:   isValid x == not (null x)
--   Windows: isValid "c:\\test" == True
--   Windows: isValid "c:\\test:of_test" == False
--   Windows: isValid "test*" == False
--   Windows: isValid "c:\\test\\nul" == False
--   Windows: isValid "c:\\test\\prn.txt" == False
--   Windows: isValid "c:\\nul\\file" == False
--   Windows: isValid "\\\\" == False
--   Windows: isValid "\\\\\\foo" == False
--   Windows: isValid "\\\\?\\D:file" == False
--   Windows: isValid "foo\tbar" == False
--   Windows: isValid "nul .txt" == False
--   Windows: isValid " nul.txt" == True
--   </pre>
isValid :: FilePath -> Bool

-- | Equality of two <a>FilePath</a>s. If you call
--   <tt>System.Directory.canonicalizePath</tt> first this has a much
--   better chance of working. Note that this doesn't follow symlinks or
--   DOSNAM~1s.
--   
--   <pre>
--            x == y ==&gt; equalFilePath x y
--            normalise x == normalise y ==&gt; equalFilePath x y
--            equalFilePath "foo" "foo/"
--            not (equalFilePath "foo" "/foo")
--   Posix:   not (equalFilePath "foo" "FOO")
--   Windows: equalFilePath "foo" "FOO"
--   Windows: not (equalFilePath "C:" "C:/")
--   </pre>
equalFilePath :: FilePath -> FilePath -> Bool

-- | Join path elements back together.
--   
--   <pre>
--   joinPath ["/","directory/","file.ext"] == "/directory/file.ext"
--   Valid x =&gt; joinPath (splitPath x) == x
--   joinPath [] == ""
--   Posix: joinPath ["test","file","path"] == "test/file/path"
--   </pre>
joinPath :: [FilePath] -> FilePath

-- | Just as <a>splitPath</a>, but don't add the trailing slashes to each
--   element.
--   
--   <pre>
--            splitDirectories "/directory/file.ext" == ["/","directory","file.ext"]
--            splitDirectories "test/file" == ["test","file"]
--            splitDirectories "/test/file" == ["/","test","file"]
--   Windows: splitDirectories "C:\\test\\file" == ["C:\\", "test", "file"]
--            Valid x =&gt; joinPath (splitDirectories x) `equalFilePath` x
--            splitDirectories "" == []
--   Windows: splitDirectories "C:\\test\\\\\\file" == ["C:\\", "test", "file"]
--            splitDirectories "/test///file" == ["/","test","file"]
--   </pre>
splitDirectories :: FilePath -> [FilePath]

-- | Split a path by the directory separator.
--   
--   <pre>
--   splitPath "/directory/file.ext" == ["/","directory/","file.ext"]
--   concat (splitPath x) == x
--   splitPath "test//item/" == ["test//","item/"]
--   splitPath "test/item/file" == ["test/","item/","file"]
--   splitPath "" == []
--   Windows: splitPath "c:\\test\\path" == ["c:\\","test\\","path"]
--   Posix:   splitPath "/file/test" == ["/","file/","test"]
--   </pre>
splitPath :: FilePath -> [FilePath]

-- | An alias for <a>&lt;/&gt;</a>.
combine :: FilePath -> FilePath -> FilePath

-- | Set the directory, keeping the filename the same.
--   
--   <pre>
--   replaceDirectory "root/file.ext" "/directory/" == "/directory/file.ext"
--   Valid x =&gt; replaceDirectory x (takeDirectory x) `equalFilePath` x
--   </pre>
replaceDirectory :: FilePath -> String -> FilePath

-- | Get the directory name, move up one level.
--   
--   <pre>
--             takeDirectory "/directory/other.ext" == "/directory"
--             takeDirectory x `isPrefixOf` x || takeDirectory x == "."
--             takeDirectory "foo" == "."
--             takeDirectory "/" == "/"
--             takeDirectory "/foo" == "/"
--             takeDirectory "/foo/bar/baz" == "/foo/bar"
--             takeDirectory "/foo/bar/baz/" == "/foo/bar/baz"
--             takeDirectory "foo/bar/baz" == "foo/bar"
--   Windows:  takeDirectory "foo\\bar" == "foo"
--   Windows:  takeDirectory "foo\\bar\\\\" == "foo\\bar"
--   Windows:  takeDirectory "C:\\" == "C:\\"
--   </pre>
takeDirectory :: FilePath -> FilePath

-- | Add a trailing file path separator if one is not already present.
--   
--   <pre>
--   hasTrailingPathSeparator (addTrailingPathSeparator x)
--   hasTrailingPathSeparator x ==&gt; addTrailingPathSeparator x == x
--   Posix:    addTrailingPathSeparator "test/rest" == "test/rest/"
--   </pre>
addTrailingPathSeparator :: FilePath -> FilePath

-- | Is an item either a directory or the last character a path separator?
--   
--   <pre>
--   hasTrailingPathSeparator "test" == False
--   hasTrailingPathSeparator "test/" == True
--   </pre>
hasTrailingPathSeparator :: FilePath -> Bool

-- | Set the base name.
--   
--   <pre>
--   replaceBaseName "/directory/other.ext" "file" == "/directory/file.ext"
--   replaceBaseName "file/test.txt" "bob" == "file/bob.txt"
--   replaceBaseName "fred" "bill" == "bill"
--   replaceBaseName "/dave/fred/bob.gz.tar" "new" == "/dave/fred/new.tar"
--   Valid x =&gt; replaceBaseName x (takeBaseName x) == x
--   </pre>
replaceBaseName :: FilePath -> String -> FilePath

-- | Get the base name, without an extension or path.
--   
--   <pre>
--   takeBaseName "/directory/file.ext" == "file"
--   takeBaseName "file/test.txt" == "test"
--   takeBaseName "dave.ext" == "dave"
--   takeBaseName "" == ""
--   takeBaseName "test" == "test"
--   takeBaseName (addTrailingPathSeparator x) == ""
--   takeBaseName "file/file.tar.gz" == "file.tar"
--   </pre>
takeBaseName :: FilePath -> String

-- | Get the file name.
--   
--   <pre>
--   takeFileName "/directory/file.ext" == "file.ext"
--   takeFileName "test/" == ""
--   takeFileName x `isSuffixOf` x
--   takeFileName x == snd (splitFileName x)
--   Valid x =&gt; takeFileName (replaceFileName x "fred") == "fred"
--   Valid x =&gt; takeFileName (x &lt;/&gt; "fred") == "fred"
--   Valid x =&gt; isRelative (takeFileName x)
--   </pre>
takeFileName :: FilePath -> FilePath

-- | Drop the filename. Unlike <a>takeDirectory</a>, this function will
--   leave a trailing path separator on the directory.
--   
--   <pre>
--   dropFileName "/directory/file.ext" == "/directory/"
--   dropFileName x == fst (splitFileName x)
--   </pre>
dropFileName :: FilePath -> FilePath

-- | Set the filename.
--   
--   <pre>
--   replaceFileName "/directory/other.txt" "file.ext" == "/directory/file.ext"
--   Valid x =&gt; replaceFileName x (takeFileName x) == x
--   </pre>
replaceFileName :: FilePath -> String -> FilePath

-- | Split a filename into directory and file. <a>&lt;/&gt;</a> is the
--   inverse. The first component will often end with a trailing slash.
--   
--   <pre>
--   splitFileName "/directory/file.ext" == ("/directory/","file.ext")
--   Valid x =&gt; uncurry (&lt;/&gt;) (splitFileName x) == x || fst (splitFileName x) == "./"
--   Valid x =&gt; isValid (fst (splitFileName x))
--   splitFileName "file/bob.txt" == ("file/", "bob.txt")
--   splitFileName "file/" == ("file/", "")
--   splitFileName "bob" == ("./", "bob")
--   Posix:   splitFileName "/" == ("/","")
--   Windows: splitFileName "c:" == ("c:","")
--   </pre>
splitFileName :: FilePath -> (String, String)

-- | Is an element a drive
--   
--   <pre>
--   Posix:   isDrive "/" == True
--   Posix:   isDrive "/foo" == False
--   Windows: isDrive "C:\\" == True
--   Windows: isDrive "C:\\foo" == False
--            isDrive "" == False
--   </pre>
isDrive :: FilePath -> Bool

-- | Does a path have a drive.
--   
--   <pre>
--   not (hasDrive x) == null (takeDrive x)
--   Posix:   hasDrive "/foo" == True
--   Windows: hasDrive "C:\\foo" == True
--   Windows: hasDrive "C:foo" == True
--            hasDrive "foo" == False
--            hasDrive "" == False
--   </pre>
hasDrive :: FilePath -> Bool

-- | Delete the drive, if it exists.
--   
--   <pre>
--   dropDrive x == snd (splitDrive x)
--   </pre>
dropDrive :: FilePath -> FilePath

-- | Get the drive from a filepath.
--   
--   <pre>
--   takeDrive x == fst (splitDrive x)
--   </pre>
takeDrive :: FilePath -> FilePath

-- | Join a drive and the rest of the path.
--   
--   <pre>
--   Valid x =&gt; uncurry joinDrive (splitDrive x) == x
--   Windows: joinDrive "C:" "foo" == "C:foo"
--   Windows: joinDrive "C:\\" "bar" == "C:\\bar"
--   Windows: joinDrive "\\\\share" "foo" == "\\\\share\\foo"
--   Windows: joinDrive "/:" "foo" == "/:\\foo"
--   </pre>
joinDrive :: FilePath -> FilePath -> FilePath

-- | Split a path into a drive and a path. On Posix, / is a Drive.
--   
--   <pre>
--   uncurry (++) (splitDrive x) == x
--   Windows: splitDrive "file" == ("","file")
--   Windows: splitDrive "c:/file" == ("c:/","file")
--   Windows: splitDrive "c:\\file" == ("c:\\","file")
--   Windows: splitDrive "\\\\shared\\test" == ("\\\\shared\\","test")
--   Windows: splitDrive "\\\\shared" == ("\\\\shared","")
--   Windows: splitDrive "\\\\?\\UNC\\shared\\file" == ("\\\\?\\UNC\\shared\\","file")
--   Windows: splitDrive "\\\\?\\UNCshared\\file" == ("\\\\?\\","UNCshared\\file")
--   Windows: splitDrive "\\\\?\\d:\\file" == ("\\\\?\\d:\\","file")
--   Windows: splitDrive "/d" == ("","/d")
--   Posix:   splitDrive "/test" == ("/","test")
--   Posix:   splitDrive "//test" == ("//","test")
--   Posix:   splitDrive "test/file" == ("","test/file")
--   Posix:   splitDrive "file" == ("","file")
--   </pre>
splitDrive :: FilePath -> (FilePath, FilePath)

-- | Replace all extensions of a file with a new extension. Note that
--   <a>replaceExtension</a> and <a>addExtension</a> both work for adding
--   multiple extensions, so only required when you need to drop all
--   extensions first.
--   
--   <pre>
--   replaceExtensions "file.fred.bob" "txt" == "file.txt"
--   replaceExtensions "file.fred.bob" "tar.gz" == "file.tar.gz"
--   </pre>
replaceExtensions :: FilePath -> String -> FilePath

-- | Get all extensions.
--   
--   <pre>
--   takeExtensions "/directory/path.ext" == ".ext"
--   takeExtensions "file.tar.gz" == ".tar.gz"
--   </pre>
takeExtensions :: FilePath -> String

-- | Drop all extensions.
--   
--   <pre>
--   dropExtensions "/directory/path.ext" == "/directory/path"
--   dropExtensions "file.tar.gz" == "file"
--   not $ hasExtension $ dropExtensions x
--   not $ any isExtSeparator $ takeFileName $ dropExtensions x
--   </pre>
dropExtensions :: FilePath -> FilePath

-- | Split on all extensions.
--   
--   <pre>
--   splitExtensions "/directory/path.ext" == ("/directory/path",".ext")
--   splitExtensions "file.tar.gz" == ("file",".tar.gz")
--   uncurry (++) (splitExtensions x) == x
--   Valid x =&gt; uncurry addExtension (splitExtensions x) == x
--   splitExtensions "file.tar.gz" == ("file",".tar.gz")
--   </pre>
splitExtensions :: FilePath -> (FilePath, String)

-- | Drop the given extension from a FilePath, and the <tt>"."</tt>
--   preceding it. Returns <a>Nothing</a> if the FilePath does not have the
--   given extension, or <a>Just</a> and the part before the extension if
--   it does.
--   
--   This function can be more predictable than <a>dropExtensions</a>,
--   especially if the filename might itself contain <tt>.</tt> characters.
--   
--   <pre>
--   stripExtension "hs.o" "foo.x.hs.o" == Just "foo.x"
--   stripExtension "hi.o" "foo.x.hs.o" == Nothing
--   dropExtension x == fromJust (stripExtension (takeExtension x) x)
--   dropExtensions x == fromJust (stripExtension (takeExtensions x) x)
--   stripExtension ".c.d" "a.b.c.d"  == Just "a.b"
--   stripExtension ".c.d" "a.b..c.d" == Just "a.b."
--   stripExtension "baz"  "foo.bar"  == Nothing
--   stripExtension "bar"  "foobar"   == Nothing
--   stripExtension ""     x          == Just x
--   </pre>
stripExtension :: String -> FilePath -> Maybe FilePath

-- | Does the given filename have the specified extension?
--   
--   <pre>
--   "png" `isExtensionOf` "/directory/file.png" == True
--   ".png" `isExtensionOf` "/directory/file.png" == True
--   ".tar.gz" `isExtensionOf` "bar/foo.tar.gz" == True
--   "ar.gz" `isExtensionOf` "bar/foo.tar.gz" == False
--   "png" `isExtensionOf` "/directory/file.png.jpg" == False
--   "csv/table.csv" `isExtensionOf` "/data/csv/table.csv" == False
--   </pre>
isExtensionOf :: String -> FilePath -> Bool

-- | Does the given filename have an extension?
--   
--   <pre>
--   hasExtension "/directory/path.ext" == True
--   hasExtension "/directory/path" == False
--   null (takeExtension x) == not (hasExtension x)
--   </pre>
hasExtension :: FilePath -> Bool

-- | Add an extension, even if there is already one there, equivalent to
--   <a>&lt;.&gt;</a>.
--   
--   <pre>
--   addExtension "/directory/path" "ext" == "/directory/path.ext"
--   addExtension "file.txt" "bib" == "file.txt.bib"
--   addExtension "file." ".bib" == "file..bib"
--   addExtension "file" ".bib" == "file.bib"
--   addExtension "/" "x" == "/.x"
--   addExtension x "" == x
--   Valid x =&gt; takeFileName (addExtension (addTrailingPathSeparator x) "ext") == ".ext"
--   Windows: addExtension "\\\\share" ".txt" == "\\\\share\\.txt"
--   </pre>
addExtension :: FilePath -> String -> FilePath

-- | Remove last extension, and the "." preceding it.
--   
--   <pre>
--   dropExtension "/directory/path.ext" == "/directory/path"
--   dropExtension x == fst (splitExtension x)
--   </pre>
dropExtension :: FilePath -> FilePath

-- | Add an extension, even if there is already one there, equivalent to
--   <a>addExtension</a>.
--   
--   <pre>
--   "/directory/path" &lt;.&gt; "ext" == "/directory/path.ext"
--   "/directory/path" &lt;.&gt; ".ext" == "/directory/path.ext"
--   </pre>
(<.>) :: FilePath -> String -> FilePath
infixr 7 <.>

-- | Set the extension of a file, overwriting one if already present,
--   equivalent to <a>-&lt;.&gt;</a>.
--   
--   <pre>
--   replaceExtension "/directory/path.txt" "ext" == "/directory/path.ext"
--   replaceExtension "/directory/path.txt" ".ext" == "/directory/path.ext"
--   replaceExtension "file.txt" ".bob" == "file.bob"
--   replaceExtension "file.txt" "bob" == "file.bob"
--   replaceExtension "file" ".bob" == "file.bob"
--   replaceExtension "file.txt" "" == "file"
--   replaceExtension "file.fred.bob" "txt" == "file.fred.txt"
--   replaceExtension x y == addExtension (dropExtension x) y
--   </pre>
replaceExtension :: FilePath -> String -> FilePath

-- | Remove the current extension and add another, equivalent to
--   <a>replaceExtension</a>.
--   
--   <pre>
--   "/directory/path.txt" -&lt;.&gt; "ext" == "/directory/path.ext"
--   "/directory/path.txt" -&lt;.&gt; ".ext" == "/directory/path.ext"
--   "foo.o" -&lt;.&gt; "c" == "foo.c"
--   </pre>
(-<.>) :: FilePath -> String -> FilePath
infixr 7 -<.>

-- | Get the extension of a file, returns <tt>""</tt> for no extension,
--   <tt>.ext</tt> otherwise.
--   
--   <pre>
--   takeExtension "/directory/path.ext" == ".ext"
--   takeExtension x == snd (splitExtension x)
--   Valid x =&gt; takeExtension (addExtension x "ext") == ".ext"
--   Valid x =&gt; takeExtension (replaceExtension x "ext") == ".ext"
--   </pre>
takeExtension :: FilePath -> String

-- | Split on the extension. <a>addExtension</a> is the inverse.
--   
--   <pre>
--   splitExtension "/directory/path.ext" == ("/directory/path",".ext")
--   uncurry (++) (splitExtension x) == x
--   Valid x =&gt; uncurry addExtension (splitExtension x) == x
--   splitExtension "file.txt" == ("file",".txt")
--   splitExtension "file" == ("file","")
--   splitExtension "file/file.txt" == ("file/file",".txt")
--   splitExtension "file.txt/boris" == ("file.txt/boris","")
--   splitExtension "file.txt/boris.ext" == ("file.txt/boris",".ext")
--   splitExtension "file/path.txt.bob.fred" == ("file/path.txt.bob",".fred")
--   splitExtension "file/path.txt/" == ("file/path.txt/","")
--   </pre>
splitExtension :: FilePath -> (String, String)

-- | Take a string, split it on the <a>searchPathSeparator</a> character.
--   Blank items are ignored on Windows, and converted to <tt>.</tt> on
--   Posix. On Windows path elements are stripped of quotes.
--   
--   Follows the recommendations in
--   <a>http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html</a>
--   
--   <pre>
--   Posix:   splitSearchPath "File1:File2:File3"  == ["File1","File2","File3"]
--   Posix:   splitSearchPath "File1::File2:File3" == ["File1",".","File2","File3"]
--   Windows: splitSearchPath "File1;File2;File3"  == ["File1","File2","File3"]
--   Windows: splitSearchPath "File1;;File2;File3" == ["File1","File2","File3"]
--   Windows: splitSearchPath "File1;\"File2\";File3" == ["File1","File2","File3"]
--   </pre>
splitSearchPath :: String -> [FilePath]

-- | Is the character an extension character?
--   
--   <pre>
--   isExtSeparator a == (a == extSeparator)
--   </pre>
isExtSeparator :: Char -> Bool

-- | File extension character
--   
--   <pre>
--   extSeparator == '.'
--   </pre>
extSeparator :: Char

-- | Is the character a file separator?
--   
--   <pre>
--   isSearchPathSeparator a == (a == searchPathSeparator)
--   </pre>
isSearchPathSeparator :: Char -> Bool

-- | The character that is used to separate the entries in the $PATH
--   environment variable.
--   
--   <pre>
--   Windows: searchPathSeparator == ';'
--   Posix:   searchPathSeparator == ':'
--   </pre>
searchPathSeparator :: Char

-- | Rather than using <tt>(== <a>pathSeparator</a>)</tt>, use this. Test
--   if something is a path separator.
--   
--   <pre>
--   isPathSeparator a == (a `elem` pathSeparators)
--   </pre>
isPathSeparator :: Char -> Bool

-- | The list of all possible separators.
--   
--   <pre>
--   Windows: pathSeparators == ['\\', '/']
--   Posix:   pathSeparators == ['/']
--   pathSeparator `elem` pathSeparators
--   </pre>
pathSeparators :: [Char]

-- | The character that separates directories. In the case where more than
--   one character is possible, <a>pathSeparator</a> is the 'ideal' one.
--   
--   <pre>
--   Windows: pathSeparator == '\\'
--   Posix:   pathSeparator ==  '/'
--   isPathSeparator pathSeparator
--   </pre>
pathSeparator :: Char

-- | Lifted version of <a>getSearchPath</a>
getSearchPath :: MonadIO m => m [FilePath]


-- | Strict <tt>Map</tt> with hashed keys. Import as:
--   
--   <pre>
--   import qualified RIO.HashMap as HM
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.HashMap.Partial</a>
module RIO.HashMap

-- | A map from keys to values. A map cannot contain duplicate keys; each
--   key can map to at most one value.
data HashMap k v

-- | &lt;math&gt; Construct an empty map.
empty :: HashMap k v

-- | &lt;math&gt; Construct a map with a single element.
singleton :: Hashable k => k -> v -> HashMap k v

-- | &lt;math&gt; Return <a>True</a> if this map is empty, <a>False</a>
--   otherwise.
null :: HashMap k v -> Bool

-- | &lt;math&gt; Return the number of key-value mappings in this map.
size :: HashMap k v -> Int

-- | &lt;math&gt; Return <a>True</a> if the specified key is present in the
--   map, <a>False</a> otherwise.
member :: (Eq k, Hashable k) => k -> HashMap k a -> Bool

-- | &lt;math&gt; Return the value to which the specified key is mapped, or
--   <a>Nothing</a> if this map contains no mapping for the key.
lookup :: (Eq k, Hashable k) => k -> HashMap k v -> Maybe v

-- | &lt;math&gt; Return the value to which the specified key is mapped, or
--   the default value if this map contains no mapping for the key.
--   
--   DEPRECATED: lookupDefault is deprecated as of version 0.2.11, replaced
--   by <a>findWithDefault</a>.
lookupDefault :: (Eq k, Hashable k) => v -> k -> HashMap k v -> v

-- | &lt;math&gt; Associate the specified value with the specified key in
--   this map. If this map previously contained a mapping for the key, the
--   old value is replaced.
insert :: (Eq k, Hashable k) => k -> v -> HashMap k v -> HashMap k v

-- | &lt;math&gt; Associate the value with the key in this map. If this map
--   previously contained a mapping for the key, the old value is replaced
--   by the result of applying the given function to the new and old value.
--   Example:
--   
--   <pre>
--   insertWith f k v map
--     where f new old = new + old
--   </pre>
insertWith :: (Eq k, Hashable k) => (v -> v -> v) -> k -> v -> HashMap k v -> HashMap k v

-- | &lt;math&gt; Remove the mapping for the specified key from this map if
--   present.
delete :: (Eq k, Hashable k) => k -> HashMap k v -> HashMap k v

-- | &lt;math&gt; Adjust the value tied to a given key in this map only if
--   it is present. Otherwise, leave the map alone.
adjust :: (Eq k, Hashable k) => (v -> v) -> k -> HashMap k v -> HashMap k v

-- | &lt;math&gt; The expression <tt>(<a>update</a> f k map)</tt> updates
--   the value <tt>x</tt> at <tt>k</tt> (if it is in the map). If <tt>(f
--   x)</tt> is <a>Nothing</a>, the element is deleted. If it is
--   <tt>(<a>Just</a> y)</tt>, the key <tt>k</tt> is bound to the new value
--   <tt>y</tt>.
update :: (Eq k, Hashable k) => (a -> Maybe a) -> k -> HashMap k a -> HashMap k a

-- | &lt;math&gt; The expression <tt>(<a>alter</a> f k map)</tt> alters the
--   value <tt>x</tt> at <tt>k</tt>, or absence thereof.
--   
--   <a>alter</a> can be used to insert, delete, or update a value in a
--   map. In short:
--   
--   <pre>
--   <tt>lookup</tt> k (<a>alter</a> f k m) = f (<tt>lookup</tt> k m)
--   </pre>
alter :: (Eq k, Hashable k) => (Maybe v -> Maybe v) -> k -> HashMap k v -> HashMap k v

-- | &lt;math&gt; The union of two maps. If a key occurs in both maps, the
--   mapping from the first will be the mapping in the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; union (fromList [(1,'a'),(2,'b')]) (fromList [(2,'c'),(3,'d')])
--   fromList [(1,'a'),(2,'b'),(3,'d')]
--   </pre>
union :: Eq k => HashMap k v -> HashMap k v -> HashMap k v

-- | &lt;math&gt; The union of two maps. If a key occurs in both maps, the
--   provided function (first argument) will be used to compute the result.
unionWith :: Eq k => (v -> v -> v) -> HashMap k v -> HashMap k v -> HashMap k v

-- | &lt;math&gt; The union of two maps. If a key occurs in both maps, the
--   provided function (first argument) will be used to compute the result.
unionWithKey :: Eq k => (k -> v -> v -> v) -> HashMap k v -> HashMap k v -> HashMap k v

-- | Construct a set containing all elements from a list of sets.
unions :: Eq k => [HashMap k v] -> HashMap k v

-- | &lt;math&gt; Transform this map by applying a function to every value.
map :: (v1 -> v2) -> HashMap k v1 -> HashMap k v2

-- | &lt;math&gt; Transform this map by applying a function to every value.
mapWithKey :: (k -> v1 -> v2) -> HashMap k v1 -> HashMap k v2

-- | &lt;math&gt; Perform an <a>Applicative</a> action for each key-value
--   pair in a <a>HashMap</a> and produce a <a>HashMap</a> of all the
--   results. Each <a>HashMap</a> will be strict in all its values.
--   
--   <pre>
--   traverseWithKey f = fmap (<a>map</a> id) . <a>Data.HashMap.Lazy</a>.<a>traverseWithKey</a> f
--   </pre>
--   
--   Note: the order in which the actions occur is unspecified. In
--   particular, when the map contains hash collisions, the order in which
--   the actions associated with the keys involved will depend in an
--   unspecified way on their insertion order.
traverseWithKey :: Applicative f => (k -> v1 -> f v2) -> HashMap k v1 -> f (HashMap k v2)

-- | &lt;math&gt; Difference of two maps. Return elements of the first map
--   not existing in the second.
difference :: (Eq k, Hashable k) => HashMap k v -> HashMap k w -> HashMap k v

-- | &lt;math&gt; Difference with a combining function. When two equal keys
--   are encountered, the combining function is applied to the values of
--   these keys. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
differenceWith :: (Eq k, Hashable k) => (v -> w -> Maybe v) -> HashMap k v -> HashMap k w -> HashMap k v

-- | &lt;math&gt; Intersection of two maps. Return elements of the first
--   map for keys existing in the second.
intersection :: Eq k => HashMap k v -> HashMap k w -> HashMap k v

-- | &lt;math&gt; Intersection of two maps. If a key occurs in both maps
--   the provided function is used to combine the values from the two maps.
intersectionWith :: Eq k => (v1 -> v2 -> v3) -> HashMap k v1 -> HashMap k v2 -> HashMap k v3

-- | &lt;math&gt; Intersection of two maps. If a key occurs in both maps
--   the provided function is used to combine the values from the two maps.
intersectionWithKey :: Eq k => (k -> v1 -> v2 -> v3) -> HashMap k v1 -> HashMap k v2 -> HashMap k v3

-- | &lt;math&gt; Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the left-identity
--   of the operator). Each application of the operator is evaluated before
--   using the result in the next application. This function is strict in
--   the starting value.
foldl' :: (a -> v -> a) -> a -> HashMap k v -> a

-- | &lt;math&gt; Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the left-identity
--   of the operator). Each application of the operator is evaluated before
--   using the result in the next application. This function is strict in
--   the starting value.
foldlWithKey' :: (a -> k -> v -> a) -> a -> HashMap k v -> a

-- | &lt;math&gt; Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
foldr :: (v -> a -> a) -> a -> HashMap k v -> a

-- | &lt;math&gt; Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
foldrWithKey :: (k -> v -> a -> a) -> a -> HashMap k v -> a

-- | &lt;math&gt; Filter this map by retaining only elements which values
--   satisfy a predicate.
filter :: (v -> Bool) -> HashMap k v -> HashMap k v

-- | &lt;math&gt; Filter this map by retaining only elements satisfying a
--   predicate.
filterWithKey :: (k -> v -> Bool) -> HashMap k v -> HashMap k v

-- | &lt;math&gt; Transform this map by applying a function to every value
--   and retaining only some of them.
mapMaybe :: (v1 -> Maybe v2) -> HashMap k v1 -> HashMap k v2

-- | &lt;math&gt; Transform this map by applying a function to every value
--   and retaining only some of them.
mapMaybeWithKey :: (k -> v1 -> Maybe v2) -> HashMap k v1 -> HashMap k v2

-- | &lt;math&gt; Return a list of this map's keys. The list is produced
--   lazily.
keys :: HashMap k v -> [k]

-- | &lt;math&gt; Return a list of this map's values. The list is produced
--   lazily.
elems :: HashMap k v -> [v]

-- | &lt;math&gt; Return a list of this map's elements. The list is
--   produced lazily. The order of its elements is unspecified.
toList :: HashMap k v -> [(k, v)]

-- | &lt;math&gt; Construct a map with the supplied mappings. If the list
--   contains duplicate mappings, the later mappings take precedence.
fromList :: (Eq k, Hashable k) => [(k, v)] -> HashMap k v

-- | &lt;math&gt; Construct a map from a list of elements. Uses the
--   provided function <tt>f</tt> to merge duplicate entries with <tt>(f
--   newVal oldVal)</tt>.
--   
--   <h3>Examples</h3>
--   
--   Given a list <tt>xs</tt>, create a map with the number of occurrences
--   of each element in <tt>xs</tt>:
--   
--   <pre>
--   let xs = ['a', 'b', 'a']
--   in fromListWith (+) [ (x, 1) | x &lt;- xs ]
--   
--   = fromList [('a', 2), ('b', 1)]
--   </pre>
--   
--   Given a list of key-value pairs <tt>xs :: [(k, v)]</tt>, group all
--   values by their keys and return a <tt>HashMap k [v]</tt>.
--   
--   <pre>
--   let xs = ('a', 1), ('b', 2), ('a', 3)]
--   in fromListWith (++) [ (k, [v]) | (k, v) &lt;- xs ]
--   
--   = fromList [('a', [3, 1]), ('b', [2])]
--   </pre>
--   
--   Note that the lists in the resulting map contain elements in reverse
--   order from their occurrences in the original list.
--   
--   More generally, duplicate entries are accumulated as follows; this
--   matters when <tt>f</tt> is not commutative or not associative.
--   
--   <pre>
--   fromListWith f [(k, a), (k, b), (k, c), (k, d)]
--   = fromList [(k, f d (f c (f b a)))]
--   </pre>
fromListWith :: (Eq k, Hashable k) => (v -> v -> v) -> [(k, v)] -> HashMap k v


-- | Strict <tt>HashMap</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.HashMap.Partial as HM'
--   </pre>
module RIO.HashMap.Partial

-- | &lt;math&gt; Return the value to which the specified key is mapped.
--   Calls <a>error</a> if this map contains no mapping for the key.
(!) :: (Eq k, Hashable k, HasCallStack) => HashMap k v -> k -> v
infixl 9 !


-- | <tt>Set</tt> with hashed members. Import as:
--   
--   <pre>
--   import qualified RIO.HashSet as HS
--   </pre>
module RIO.HashSet

-- | A set of values. A set cannot contain duplicate values.
data HashSet a

-- | &lt;math&gt; Construct an empty set.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.empty
--   fromList []
--   </pre>
empty :: HashSet a

-- | &lt;math&gt; Construct a set with a single element.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.singleton 1
--   fromList [1]
--   </pre>
singleton :: Hashable a => a -> HashSet a

-- | &lt;math&gt; Construct a set containing all elements from both sets.
--   
--   To obtain good performance, the smaller set must be presented as the
--   first argument.
--   
--   <pre>
--   &gt;&gt;&gt; union (fromList [1,2]) (fromList [2,3])
--   fromList [1,2,3]
--   </pre>
union :: Eq a => HashSet a -> HashSet a -> HashSet a

-- | Construct a set containing all elements from a list of sets.
unions :: Eq a => [HashSet a] -> HashSet a

-- | &lt;math&gt; Return <a>True</a> if this set is empty, <a>False</a>
--   otherwise.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.null HashSet.empty
--   True
--   
--   &gt;&gt;&gt; HashSet.null (HashSet.singleton 1)
--   False
--   </pre>
null :: HashSet a -> Bool

-- | &lt;math&gt; Return the number of elements in this set.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.size HashSet.empty
--   0
--   
--   &gt;&gt;&gt; HashSet.size (HashSet.fromList [1,2,3])
--   3
--   </pre>
size :: HashSet a -> Int

-- | &lt;math&gt; Return <a>True</a> if the given value is present in this
--   set, <a>False</a> otherwise.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.member 1 (Hashset.fromList [1,2,3])
--   True
--   
--   &gt;&gt;&gt; HashSet.member 1 (Hashset.fromList [4,5,6])
--   False
--   </pre>
member :: (Eq a, Hashable a) => a -> HashSet a -> Bool

-- | &lt;math&gt; Add the specified value to this set.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.insert 1 HashSet.empty
--   fromList [1]
--   </pre>
insert :: (Eq a, Hashable a) => a -> HashSet a -> HashSet a

-- | &lt;math&gt; Remove the specified value from this set if present.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.delete 1 (HashSet.fromList [1,2,3])
--   fromList [2,3]
--   
--   &gt;&gt;&gt; HashSet.delete 1 (HashSet.fromList [4,5,6])
--   fromList [4,5,6]
--   </pre>
delete :: (Eq a, Hashable a) => a -> HashSet a -> HashSet a

-- | &lt;math&gt; Transform this set by applying a function to every value.
--   The resulting set may be smaller than the source.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.map show (HashSet.fromList [1,2,3])
--   HashSet.fromList ["1","2","3"]
--   </pre>
map :: (Hashable b, Eq b) => (a -> b) -> HashSet a -> HashSet b

-- | &lt;math&gt; Difference of two sets. Return elements of the first set
--   not existing in the second.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.difference (HashSet.fromList [1,2,3]) (HashSet.fromList [2,3,4])
--   fromList [1]
--   </pre>
difference :: (Eq a, Hashable a) => HashSet a -> HashSet a -> HashSet a

-- | &lt;math&gt; Intersection of two sets. Return elements present in both
--   the first set and the second.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.intersection (HashSet.fromList [1,2,3]) (HashSet.fromList [2,3,4])
--   fromList [2,3]
--   </pre>
intersection :: Eq a => HashSet a -> HashSet a -> HashSet a

-- | &lt;math&gt; Reduce this set by applying a binary operator to all
--   elements, using the given starting value (typically the left-identity
--   of the operator). Each application of the operator is evaluated before
--   before using the result in the next application. This function is
--   strict in the starting value.
foldl' :: (a -> b -> a) -> a -> HashSet b -> a

-- | &lt;math&gt; Reduce this set by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
foldr :: (b -> a -> a) -> a -> HashSet b -> a

-- | &lt;math&gt; Filter this set by retaining only elements satisfying a
--   predicate.
filter :: (a -> Bool) -> HashSet a -> HashSet a

-- | &lt;math&gt; Return a list of this set's elements. The list is
--   produced lazily.
toList :: HashSet a -> [a]

-- | &lt;math&gt; Construct a set from a list of elements.
fromList :: (Eq a, Hashable a) => [a] -> HashSet a

-- | &lt;math&gt; Convert to set to the equivalent <a>HashMap</a> with
--   <tt>()</tt> values.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.toMap (HashSet.singleton 1)
--   fromList [(1,())]
--   </pre>
toMap :: HashSet a -> HashMap a ()

-- | &lt;math&gt; Convert from the equivalent <a>HashMap</a> with
--   <tt>()</tt> values.
--   
--   <pre>
--   &gt;&gt;&gt; HashSet.fromMap (HashMap.singleton 1 ())
--   fromList [1]
--   </pre>
fromMap :: HashMap a () -> HashSet a


-- | Extra utilities from <tt>microlens</tt>.
--   
--   @since: 0.1.16.0
module RIO.Lens

-- | A <tt>SimpleFold s a</tt> extracts several <tt>a</tt>s from
--   <tt>s</tt>; so, it's pretty much the same thing as <tt>(s -&gt;
--   [a])</tt>, but you can use it with lens operators.
--   
--   The actual <tt>Fold</tt> from lens is more general:
--   
--   <pre>
--   type Fold s a =
--     forall f. (Contravariant f, Applicative f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   There are several functions in lens that accept lens's <tt>Fold</tt>
--   but won't accept <a>SimpleFold</a>; I'm aware of
--   <tt><a>takingWhile</a></tt>, <tt><a>droppingWhile</a></tt>,
--   <tt><a>backwards</a></tt>, <tt><a>foldByOf</a></tt>,
--   <tt><a>foldMapByOf</a></tt>. For this reason, try not to export
--   <a>SimpleFold</a>s if at all possible. <a>microlens-contra</a>
--   provides a fully lens-compatible <tt>Fold</tt>.
--   
--   Lens users: you can convert a <a>SimpleFold</a> to <tt>Fold</tt> by
--   applying <tt>folded . toListOf</tt> to it.
type SimpleFold s a = forall r. Monoid r => Getting r s a

-- | <a>toListOf</a> is a synonym for (<a>^..</a>).
toListOf :: Getting (Endo [a]) s a -> s -> [a]

-- | <a>has</a> checks whether a getter (any getter, including lenses,
--   traversals, and folds) returns at least 1 value.
--   
--   Checking whether a list is non-empty:
--   
--   <pre>
--   &gt;&gt;&gt; has each []
--   False
--   </pre>
--   
--   You can also use it with e.g. <a>_Left</a> (and other 0-or-1
--   traversals) as a replacement for <a>isNothing</a>, <a>isJust</a> and
--   other <tt>isConstructorName</tt> functions:
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Left 1)
--   True
--   </pre>
has :: Getting Any s a -> s -> Bool

-- | Gives access to the 1st field of a tuple (up to 5-tuples).
--   
--   Getting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4,5) ^. _1
--   1
--   </pre>
--   
--   Setting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3) &amp; _1 .~ 10
--   (10,2,3)
--   </pre>
--   
--   Note that this lens is lazy, and can set fields even of
--   <a>undefined</a>:
--   
--   <pre>
--   &gt;&gt;&gt; set _1 10 undefined :: (Int, Int)
--   (10,*** Exception: Prelude.undefined
--   </pre>
--   
--   This is done to avoid violating a lens law stating that you can get
--   back what you put:
--   
--   <pre>
--   &gt;&gt;&gt; view _1 . set _1 10 $ (undefined :: (Int, Int))
--   10
--   </pre>
--   
--   The implementation (for 2-tuples) is:
--   
--   <pre>
--   <a>_1</a> f t = (,) <a>&lt;$&gt;</a> f    (<a>fst</a> t)
--                <a>&lt;*&gt;</a> <a>pure</a> (<a>snd</a> t)
--   </pre>
--   
--   or, alternatively,
--   
--   <pre>
--   <a>_1</a> f ~(a,b) = (\a' -&gt; (a',b)) <a>&lt;$&gt;</a> f a
--   </pre>
--   
--   (where <tt>~</tt> means a <a>lazy pattern</a>).
--   
--   <a>_2</a>, <a>_3</a>, <a>_4</a>, and <a>_5</a> are also available (see
--   below).
_1 :: Field1 s t a b => Lens s t a b
_2 :: Field2 s t a b => Lens s t a b
_3 :: Field3 s t a b => Lens s t a b
_4 :: Field4 s t a b => Lens s t a b
_5 :: Field5 s t a b => Lens s t a b

-- | This lens lets you read, write, or delete elements in
--   <tt>Map</tt>-like structures. It returns <a>Nothing</a> when the value
--   isn't found, just like <tt>lookup</tt>:
--   
--   <pre>
--   Data.Map.lookup k m = m <a>^.</a> at k
--   </pre>
--   
--   However, it also lets you insert and delete values by setting the
--   value to <tt><a>Just</a> value</tt> or <a>Nothing</a>:
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>.~</a> Just a
--   
--   Data.Map.delete k m = m <a>&amp;</a> at k <a>.~</a> Nothing
--   </pre>
--   
--   Or you could use (<a>?~</a>) instead of (<a>.~</a>):
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>?~</a> a
--   </pre>
--   
--   Note that <a>at</a> doesn't work for arrays or lists. You can't delete
--   an arbitrary element from an array (what would be left in its place?),
--   and you can't set an arbitrary element in a list because if the index
--   is out of list's bounds, you'd have to somehow fill the stretch
--   between the last element and the element you just inserted (i.e.
--   <tt>[1,2,3] &amp; at 10 .~ 5</tt> is undefined). If you want to modify
--   an already existing value in an array or list, you should use
--   <a>ix</a> instead.
--   
--   <a>at</a> is often used with <a>non</a>. See the documentation of
--   <a>non</a> for examples.
--   
--   Note that <a>at</a> isn't strict for <tt>Map</tt>, even if you're
--   using <tt>Data.Map.Strict</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Map.Strict.size (Data.Map.Strict.empty &amp; at 1 .~ Just undefined)
--   1
--   </pre>
--   
--   The reason for such behavior is that there's actually no “strict
--   <tt>Map</tt>” type; <tt>Data.Map.Strict</tt> just provides some strict
--   functions for ordinary <tt>Map</tt>s.
--   
--   This package doesn't actually provide any instances for <a>at</a>, but
--   there are instances for <tt>Map</tt> and <tt>IntMap</tt> in
--   <a>microlens-ghc</a> and an instance for <tt>HashMap</tt> in
--   <a>microlens-platform</a>.
at :: At m => Index m -> Lens' m (Maybe (IxValue m))

-- | <a>lens</a> creates a <a>Lens</a> from a getter and a setter. The
--   resulting lens isn't the most effective one (because of having to
--   traverse the structure twice when modifying), but it shouldn't matter
--   much.
--   
--   A (partial) lens for list indexing:
--   
--   <pre>
--   ix :: Int -&gt; <a>Lens'</a> [a] a
--   ix i = <a>lens</a> (<a>!!</a> i)                                   -- getter
--               (\s b -&gt; take i s ++ b : drop (i+1) s)   -- setter
--   </pre>
--   
--   Usage:
--   
--   <pre>
--   &gt;&gt;&gt; [1..9] <a>^.</a> ix 3
--   4
--   
--   &gt;&gt;&gt; [1..9] &amp; ix 3 <a>%~</a> negate
--   [1,2,3,-4,5,6,7,8,9]
--   </pre>
--   
--   When getting, the setter is completely unused; when setting, the
--   getter is unused. Both are used only when the value is being modified.
--   For instance, here we define a lens for the 1st element of a list, but
--   instead of a legitimate getter we use <a>undefined</a>. Then we use
--   the resulting lens for <i>setting</i> and it works, which proves that
--   the getter wasn't used:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &amp; lens undefined (\s b -&gt; b : tail s) .~ 10
--   [10,2,3]
--   </pre>
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b

-- | <a>non</a> lets you “relabel” a <a>Maybe</a> by equating
--   <a>Nothing</a> to an arbitrary value (which you can choose):
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^. non 0
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Nothing ^. non 0
--   0
--   </pre>
--   
--   The most useful thing about <a>non</a> is that relabeling also works
--   in other direction. If you try to <a>set</a> the “forbidden” value,
--   it'll be turned to <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 .~ 0
--   Nothing
--   </pre>
--   
--   Setting anything else works just fine:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 .~ 5
--   Just 5
--   </pre>
--   
--   Same happens if you try to modify a value:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 %~ subtract 1
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 %~ (+ 1)
--   Just 2
--   </pre>
--   
--   <a>non</a> is often useful when combined with <a>at</a>. For instance,
--   if you have a map of songs and their playcounts, it makes sense not to
--   store songs with 0 plays in the map; <a>non</a> can act as a filter
--   that wouldn't pass such entries.
--   
--   Decrease playcount of a song to 0, and it'll be gone:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Soon",1),("Yesterday",3)] &amp; at "Soon" . non 0 %~ subtract 1
--   fromList [("Yesterday",3)]
--   </pre>
--   
--   Try to add a song with 0 plays, and it won't be added:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Yesterday",3)] &amp; at "Soon" . non 0 .~ 0
--   fromList [("Yesterday",3)]
--   </pre>
--   
--   But it will be added if you set any other number:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Yesterday",3)] &amp; at "Soon" . non 0 .~ 1
--   fromList [("Soon",1),("Yesterday",3)]
--   </pre>
--   
--   <a>non</a> is also useful when working with nested maps. Here a nested
--   map is created when it's missing:
--   
--   <pre>
--   &gt;&gt;&gt; Map.empty &amp; at "Dez Mona" . non Map.empty . at "Soon" .~ Just 1
--   fromList [("Dez Mona",fromList [("Soon",1)])]
--   </pre>
--   
--   and here it is deleted when its last entry is deleted (notice that
--   <a>non</a> is used twice here):
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Dez Mona",fromList [("Soon",1)])] &amp; at "Dez Mona" . non Map.empty . at "Soon" . non 0 %~ subtract 1
--   fromList []
--   </pre>
--   
--   To understand the last example better, observe the flow of values in
--   it:
--   
--   <ul>
--   <li>the map goes into <tt>at "Dez Mona"</tt></li>
--   <li>the nested map (wrapped into <tt>Just</tt>) goes into <tt>non
--   Map.empty</tt></li>
--   <li><tt>Just</tt> is unwrapped and the nested map goes into <tt>at
--   "Soon"</tt></li>
--   <li><tt>Just 1</tt> is unwrapped by <tt>non 0</tt></li>
--   </ul>
--   
--   Then the final value – i.e. 1 – is modified by <tt>subtract 1</tt> and
--   the result (which is 0) starts flowing backwards:
--   
--   <ul>
--   <li><tt>non 0</tt> sees the 0 and produces a <tt>Nothing</tt></li>
--   <li><tt>at "Soon"</tt> sees <tt>Nothing</tt> and deletes the
--   corresponding value from the map</li>
--   <li>the resulting empty map is passed to <tt>non Map.empty</tt>, which
--   sees that it's empty and thus produces <tt>Nothing</tt></li>
--   <li><tt>at "Dez Mona"</tt> sees <tt>Nothing</tt> and removes the key
--   from the map</li>
--   </ul>
non :: Eq a => a -> Lens' (Maybe a) a

-- | <a>singular</a> turns a traversal into a lens that behaves like a
--   single-element traversal:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] ^. singular each
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &amp; singular each %~ negate
--   [-1,2,3]
--   </pre>
--   
--   If there is nothing to return, it'll throw an error:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^. singular each
--   *** Exception: Lens.Micro.singular: empty traversal
--   </pre>
--   
--   However, it won't fail if you are merely setting the value:
--   
--   <pre>
--   &gt;&gt;&gt; [] &amp; singular each %~ negate
--   </pre>
singular :: HasCallStack => Traversal s t a a -> Lens s t a a

-- | <a>failing</a> lets you chain traversals together; if the 1st
--   traversal fails, the 2nd traversal will be used.
--   
--   <pre>
--   &gt;&gt;&gt; ([1,2],[3]) &amp; failing (_1.each) (_2.each) .~ 0
--   ([0,0],[3])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ([],[3]) &amp; failing (_1.each) (_2.each) .~ 0
--   ([],[0])
--   </pre>
--   
--   Note that the resulting traversal won't be valid unless either both
--   traversals don't touch each others' elements, or both traversals
--   return exactly the same results. To see an example of how
--   <a>failing</a> can generate invalid traversals, see <a>this
--   Stackoverflow question</a>.
failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b
infixl 5 `failing`

-- | <a>filtered</a> is a traversal that filters elements “passing” through
--   it:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) ^.. each
--   [1,2,3,4]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) ^.. each . filtered even
--   [2,4]
--   </pre>
--   
--   It also can be used to modify elements selectively:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) &amp; each . filtered even %~ (*100)
--   (1,200,3,400)
--   </pre>
--   
--   The implementation of <a>filtered</a> is very simple. Consider this
--   traversal, which always “traverses” just the value it's given:
--   
--   <pre>
--   id :: <a>Traversal'</a> a a
--   id f s = f s
--   </pre>
--   
--   And this traversal, which traverses nothing (in other words,
--   <i>doesn't</i> traverse the value it's given):
--   
--   <pre>
--   ignored :: <a>Traversal'</a> a a
--   ignored f s = <a>pure</a> s
--   </pre>
--   
--   And now combine them into a traversal that conditionally traverses the
--   value it's given, and you get <a>filtered</a>:
--   
--   <pre>
--   filtered :: (a -&gt; Bool) -&gt; <a>Traversal'</a> a a
--   filtered p f s = if p s then f s else <a>pure</a> s
--   </pre>
--   
--   By the way, note that <a>filtered</a> can generate illegal traversals
--   – sometimes this can bite you. In particular, an optimisation that
--   should be safe becomes unsafe. (To the best of my knowledge, this
--   optimisation never happens automatically. If you just use
--   <a>filtered</a> to modify/view something, you're safe. If you don't
--   define any traversals that use <a>filtered</a>, you're safe too.)
--   
--   Let's use <tt>evens</tt> as an example:
--   
--   <pre>
--   evens = <a>filtered</a> <a>even</a>
--   </pre>
--   
--   If <tt>evens</tt> was a legal traversal, you'd be able to fuse several
--   applications of <tt>evens</tt> like this:
--   
--   <pre>
--   <a>over</a> evens f <a>.</a> <a>over</a> evens g = <a>over</a> evens (f <a>.</a> g)
--   </pre>
--   
--   Unfortunately, in case of <tt>evens</tt> this isn't a correct
--   optimisation:
--   
--   <ul>
--   <li>the left-side variant applies <tt>g</tt> to all even numbers, and
--   then applies <tt>f</tt> to all even numbers that are left after
--   <tt>f</tt> (because <tt>f</tt> might've turned some even numbers into
--   odd ones)</li>
--   <li>the right-side variant applies <tt>f</tt> and <tt>g</tt> to all
--   even numbers</li>
--   </ul>
--   
--   Of course, when you are careful and know what you're doing, you won't
--   try to make such an optimisation. However, if you export an illegal
--   traversal created with <a>filtered</a> and someone tries to use it,
--   they might mistakenly assume that it's legal, do the optimisation, and
--   silently get an incorrect result.
--   
--   If you are using <a>filtered</a> with some another traversal that
--   doesn't overlap with -whatever the predicate checks-, the resulting
--   traversal will be legal. For instance, here the predicate looks at the
--   1st element of a tuple, but the resulting traversal only gives you
--   access to the 2nd:
--   
--   <pre>
--   pairedWithEvens :: <a>Traversal</a> [(Int, a)] [(Int, b)] a b
--   pairedWithEvens = <a>each</a> <a>.</a> <a>filtered</a> (<a>even</a> <a>.</a> <a>fst</a>) <a>.</a> <a>_2</a>
--   </pre>
--   
--   Since you can't do anything with the 1st components through this
--   traversal, the following holds for any <tt>f</tt> and <tt>g</tt>:
--   
--   <pre>
--   <a>over</a> pairedWithEvens f <a>.</a> <a>over</a> pairedWithEvens g = <a>over</a> pairedWithEvens (f <a>.</a> g)
--   </pre>
filtered :: (a -> Bool) -> Traversal' a a

-- | <a>both</a> traverses both fields of a tuple. Unlike
--   <tt><a>both</a></tt> from lens, it only works for pairs – not for
--   triples or <a>Either</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") ^. both
--   "string"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") &amp; both %~ reverse
--   ("rts","gni")
--   </pre>
both :: Traversal (a, a) (b, b) a b

-- | <a>traversed</a> traverses any <a>Traversable</a> container (list,
--   vector, <tt>Map</tt>, <a>Maybe</a>, you name it):
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^.. traversed
--   [1]
--   </pre>
--   
--   <a>traversed</a> is the same as <a>traverse</a>, but can be faster
--   thanks to magic rewrite rules.
traversed :: forall (f :: Type -> Type) a b. Traversable f => Traversal (f a) (f b) a b

-- | <a>each</a> tries to be a universal <a>Traversal</a> – it behaves like
--   <a>traversed</a> in most situations, but also adds support for e.g.
--   tuples with same-typed values:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) &amp; each %~ succ
--   (2,3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ["x", "y", "z"] ^. each
--   "xyz"
--   </pre>
--   
--   However, note that <a>each</a> doesn't work on <i>every</i> instance
--   of <a>Traversable</a>. If you have a <a>Traversable</a> which isn't
--   supported by <a>each</a>, you can use <a>traversed</a> instead.
--   Personally, I like using <a>each</a> instead of <a>traversed</a>
--   whenever possible – it's shorter and more descriptive.
--   
--   You can use <a>each</a> with these things:
--   
--   <pre>
--   <a>each</a> :: <a>Traversal</a> [a] [b] a b
--   
--   <a>each</a> :: <a>Traversal</a> (<a>Maybe</a> a) (<a>Maybe</a> b) a b
--   <a>each</a> :: <a>Traversal</a> (<a>Either</a> a a) (<a>Either</a> b b) a b  -- since 0.4.11
--   
--   <a>each</a> :: <a>Traversal</a> (a,a) (b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a) (b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a) (b,b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a,a) (b,b,b,b,b) a b
--   
--   <a>each</a> :: (<a>RealFloat</a> a, <a>RealFloat</a> b) =&gt; <a>Traversal</a> (<a>Complex</a> a) (<a>Complex</a> b) a b
--   </pre>
--   
--   You can also use <a>each</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
each :: Each s t a b => Traversal s t a b

-- | This traversal lets you access (and update) an arbitrary element in a
--   list, array, <tt>Map</tt>, etc. (If you want to insert or delete
--   elements as well, look at <a>at</a>.)
--   
--   An example for lists:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] &amp; ix 3 .~ 10
--   [0,1,2,10,4,5]
--   </pre>
--   
--   You can use it for getting, too:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 3
--   Just 3
--   </pre>
--   
--   Of course, the element may not be present (which means that you can
--   use <a>ix</a> as a safe variant of (<a>!!</a>)):
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 10
--   Nothing
--   </pre>
--   
--   Another useful instance is the one for functions – it lets you modify
--   their outputs for specific inputs. For instance, here's <a>maximum</a>
--   that returns 0 when the list is empty (instead of throwing an
--   exception):
--   
--   <pre>
--   maximum0 = <a>maximum</a> <a>&amp;</a> <a>ix</a> [] <a>.~</a> 0
--   </pre>
--   
--   The following instances are provided in this package:
--   
--   <pre>
--   <a>ix</a> :: <a>Int</a> -&gt; <a>Traversal'</a> [a] a
--   
--   <a>ix</a> :: <a>Int</a> -&gt; <a>Traversal'</a> (NonEmpty a) a
--   
--   <a>ix</a> :: (<a>Eq</a> e) =&gt; e -&gt; <a>Traversal'</a> (e -&gt; a) a
--   </pre>
--   
--   You can also use <a>ix</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
ix :: Ixed m => Index m -> Traversal' m (IxValue m)

-- | <a>_head</a> traverses the 1st element of something (usually a list,
--   but can also be a <tt>Seq</tt>, etc):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^? _head
--   Just 1
--   </pre>
--   
--   It can be used to modify too, as in this example where the 1st letter
--   of a sentence is capitalised:
--   
--   <pre>
--   &gt;&gt;&gt; "mary had a little lamb." &amp; _head %~ toTitle
--   "Mary had a little lamb."
--   </pre>
--   
--   The reason it's a traversal and not a lens is that there's nothing to
--   traverse when the list is empty:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^? _head
--   Nothing
--   </pre>
--   
--   This package only lets you use <a>_head</a> on lists, but if you use
--   <a>microlens-ghc</a> you get instances for <tt>ByteString</tt> and
--   <tt>Seq</tt>, and if you use <a>microlens-platform</a> you
--   additionally get instances for <tt>Text</tt> and <tt>Vector</tt>.
_head :: Cons s s a a => Traversal' s a

-- | <a>_tail</a> gives you access to the tail of a list (or <tt>Seq</tt>,
--   etc):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^? _tail
--   Just [2,3,4,5]
--   </pre>
--   
--   You can modify the tail as well:
--   
--   <pre>
--   &gt;&gt;&gt; [4,1,2,3] &amp; _tail %~ reverse
--   [4,3,2,1]
--   </pre>
--   
--   Since lists are monoids, you can use <a>_tail</a> with plain
--   (<a>^.</a>) (and then it'll return an empty list if you give it an
--   empty list):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^. _tail
--   [2,3,4,5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [] ^. _tail
--   []
--   </pre>
--   
--   If you want to traverse each <i>element</i> of the tail, use
--   <a>_tail</a> with <a>each</a>:
--   
--   <pre>
--   &gt;&gt;&gt; "I HATE CAPS." &amp; _tail.each %~ toLower
--   "I hate caps."
--   </pre>
--   
--   This package only lets you use <a>_tail</a> on lists, but if you use
--   <a>microlens-ghc</a> you get instances for <tt>ByteString</tt> and
--   <tt>Seq</tt>, and if you use <a>microlens-platform</a> you
--   additionally get instances for <tt>Text</tt> and <tt>Vector</tt>.
_tail :: Cons s s a a => Traversal' s s

-- | <a>_init</a> gives you access to all-but-the-last elements of the
--   list:
--   
--   <pre>
--   &gt;&gt;&gt; "Hello." ^. _init
--   "Hello"
--   </pre>
--   
--   See documentation for <a>_tail</a>, as <a>_init</a> and <a>_tail</a>
--   are pretty similar.
_init :: Snoc s s a a => Traversal' s s

-- | <a>_last</a> gives you access to the last element of the list:
--   
--   <pre>
--   &gt;&gt;&gt; "Hello." ^? _last
--   '.'
--   </pre>
--   
--   See documentation for <a>_head</a>, as <a>_last</a> and <a>_head</a>
--   are pretty similar.
_last :: Snoc s s a a => Traversal' s a

-- | <a>_Left</a> targets the value contained in an <a>Either</a>, provided
--   it's a <a>Left</a>.
--   
--   Gathering all <tt>Left</tt>s in a structure (like the <a>lefts</a>
--   function, but not necessarily just for lists):
--   
--   <pre>
--   &gt;&gt;&gt; [Left 1, Right 'c', Left 3] ^.. each._Left
--   [1,3]
--   </pre>
--   
--   Checking whether an <a>Either</a> is a <a>Left</a> (like
--   <a>isLeft</a>):
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Left 1)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Right 1)
--   False
--   </pre>
--   
--   Extracting a value (if you're sure it's a <a>Left</a>):
--   
--   <pre>
--   &gt;&gt;&gt; Left 1 ^?! _Left
--   1
--   </pre>
--   
--   Mapping over all <a>Left</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; (each._Left %~ map toUpper) [Left "foo", Right "bar"]
--   [Left "FOO",Right "bar"]
--   </pre>
--   
--   Implementation:
--   
--   <pre>
--   <a>_Left</a> f (Left a)  = <a>Left</a> <a>&lt;$&gt;</a> f a
--   <a>_Left</a> _ (Right b) = <a>pure</a> (<a>Right</a> b)
--   </pre>
_Left :: Traversal (Either a b) (Either a' b) a a'

-- | <a>_Right</a> targets the value contained in an <a>Either</a>,
--   provided it's a <a>Right</a>.
--   
--   See documentation for <a>_Left</a>.
_Right :: Traversal (Either a b) (Either a b') b b'

-- | <a>_Just</a> targets the value contained in a <a>Maybe</a>, provided
--   it's a <a>Just</a>.
--   
--   See documentation for <a>_Left</a> (as these 2 are pretty similar). In
--   particular, it can be used to write these:
--   
--   <ul>
--   <li>Unsafely extracting a value from a <a>Just</a>:</li>
--   </ul>
--   
--   <pre>
--   <a>fromJust</a> = (<a>^?!</a> <a>_Just</a>)
--   
--   </pre>
--   
--   <ul>
--   <li>Checking whether a value is a <a>Just</a>:</li>
--   </ul>
--   
--   <pre>
--   <a>isJust</a> = <a>has</a> <a>_Just</a>
--   
--   </pre>
--   
--   <ul>
--   <li>Converting a <a>Maybe</a> to a list (empty or consisting of a
--   single element):</li>
--   </ul>
--   
--   <pre>
--   <a>maybeToList</a> = (<a>^..</a> <a>_Just</a>)
--   
--   </pre>
--   
--   <ul>
--   <li>Gathering all <a>Just</a>s in a list:</li>
--   </ul>
--   
--   <pre>
--   <a>catMaybes</a> = (<a>^..</a> <a>each</a> <a>.</a> <a>_Just</a>)
--   
--   </pre>
_Just :: Traversal (Maybe a) (Maybe a') a a'

-- | <a>_Nothing</a> targets a <tt>()</tt> if the <a>Maybe</a> is a
--   <a>Nothing</a>, and doesn't target anything otherwise:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^.. _Nothing
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Nothing ^.. _Nothing
--   [()]
--   </pre>
--   
--   It's not particularly useful (unless you want to use <tt><a>has</a>
--   <a>_Nothing</a></tt> as a replacement for <a>isNothing</a>), and
--   provided mainly for consistency.
--   
--   Implementation:
--   
--   <pre>
--   <a>_Nothing</a> f Nothing = <a>const</a> <a>Nothing</a> <a>&lt;$&gt;</a> f ()
--   <a>_Nothing</a> _ j       = <a>pure</a> j
--   </pre>
_Nothing :: Traversal' (Maybe a) ()


-- | <tt>List</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.List as L
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.List.Partial</a>
module RIO.List

-- | Append two lists, i.e.,
--   
--   <pre>
--   [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
--   [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--   </pre>
--   
--   If the first list is not finite, the result is the first list.
(++) :: [a] -> [a] -> [a]
infixr 5 ++

-- | &lt;math&gt;. Decompose a list into its head and tail. If the list is
--   empty, returns <a>Nothing</a>. If the list is non-empty, returns
--   <tt><a>Just</a> (x, xs)</tt>, where <tt>x</tt> is the head of the list
--   and <tt>xs</tt> its tail.
uncons :: [a] -> Maybe (a, [a])

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Returns the size/length of a finite structure as an <a>Int</a>. The
--   default implementation is optimized for structures that are similar to
--   cons-lists, because there is no general way to do better.
length :: Foldable t => t a -> Int

headMaybe :: [a] -> Maybe a

lastMaybe :: [a] -> Maybe a

tailMaybe :: [a] -> Maybe [a]

initMaybe :: [a] -> Maybe [a]

-- | &lt;math&gt;. <a>map</a> <tt>f xs</tt> is the list obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>, i.e.,
--   
--   <pre>
--   map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
--   map f [x1, x2, ...] == [f x1, f x2, ...]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (+1) [1, 2, 3]
--   </pre>
map :: (a -> b) -> [a] -> [b]

-- | <a>reverse</a> <tt>xs</tt> returns the elements of <tt>xs</tt> in
--   reverse order. <tt>xs</tt> must be finite.
reverse :: [a] -> [a]

-- | &lt;math&gt;. The <a>intersperse</a> function takes an element and a
--   list and `intersperses' that element between the elements of the list.
--   For example,
--   
--   <pre>
--   &gt;&gt;&gt; intersperse ',' "abcde"
--   "a,b,c,d,e"
--   </pre>
intersperse :: a -> [a] -> [a]

-- | <a>intercalate</a> <tt>xs xss</tt> is equivalent to <tt>(<a>concat</a>
--   (<a>intersperse</a> xs xss))</tt>. It inserts the list <tt>xs</tt> in
--   between the lists in <tt>xss</tt> and concatenates the result.
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["Lorem", "ipsum", "dolor"]
--   "Lorem, ipsum, dolor"
--   </pre>
intercalate :: [a] -> [[a]] -> [a]

-- | The <a>transpose</a> function transposes the rows and columns of its
--   argument. For example,
--   
--   <pre>
--   &gt;&gt;&gt; transpose [[1,2,3],[4,5,6]]
--   [[1,4],[2,5],[3,6]]
--   </pre>
--   
--   If some of the rows are shorter than the following rows, their
--   elements are skipped:
--   
--   <pre>
--   &gt;&gt;&gt; transpose [[10,11],[20],[],[30,31,32]]
--   [[10,20,30],[11,31],[32]]
--   </pre>
transpose :: [[a]] -> [[a]]

-- | The <a>subsequences</a> function returns the list of all subsequences
--   of the argument.
--   
--   <pre>
--   &gt;&gt;&gt; subsequences "abc"
--   ["","a","b","ab","c","ac","bc","abc"]
--   </pre>
subsequences :: [a] -> [[a]]

-- | The <a>permutations</a> function returns the list of all permutations
--   of the argument.
--   
--   <pre>
--   &gt;&gt;&gt; permutations "abc"
--   ["abc","bac","cba","bca","cab","acb"]
--   </pre>
permutations :: [a] -> [[a]]

-- | Left-associative fold of a structure.
--   
--   In the case of lists, <a>foldl</a>, when applied to a binary operator,
--   a starting value (typically the left-identity of the operator), and a
--   list, reduces the list using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   </pre>
--   
--   Note that to produce the outermost application of the operator the
--   entire input list must be traversed. This means that <a>foldl'</a>
--   will diverge if given an infinite list.
--   
--   Also note that if you want an efficient left-fold, you probably want
--   to use <a>foldl'</a> instead of <a>foldl</a>. The reason for this is
--   that latter does not force the "inner" results (e.g. <tt>z `f` x1</tt>
--   in the above example) before applying them to the operator (e.g. to
--   <tt>(`f` x2)</tt>). This results in a thunk chain &lt;math&gt;
--   elements long, which then must be evaluated from the outside-in.
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldl f z = <a>foldl</a> f z . <a>toList</a>
--   </pre>
foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b

-- | Left-associative fold of a structure but with strict application of
--   the operator.
--   
--   This ensures that each step of the fold is forced to weak head normal
--   form before being applied, avoiding the collection of thunks that
--   would otherwise occur. This is often what you want to strictly reduce
--   a finite list to a single, monolithic result (e.g. <a>length</a>).
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldl' f z = <a>foldl'</a> f z . <a>toList</a>
--   </pre>
foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b

-- | Right-associative fold of a structure.
--   
--   In the case of lists, <a>foldr</a>, when applied to a binary operator,
--   a starting value (typically the right-identity of the operator), and a
--   list, reduces the list using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--   </pre>
--   
--   Note that, since the head of the resulting expression is produced by
--   an application of the operator to the first element of the list,
--   <a>foldr</a> can produce a terminating expression from an infinite
--   list.
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldr f z = <a>foldr</a> f z . <a>toList</a>
--   </pre>
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b

-- | The concatenation of all the elements of a container of lists.
concat :: Foldable t => t [a] -> [a]

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => (a -> Bool) -> t a -> Bool

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => (a -> Bool) -> t a -> Bool

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

maximumMaybe :: (Ord a, Foldable t) => t a -> Maybe a

minimumMaybe :: (Ord a, Foldable t) => t a -> Maybe a

maximumByMaybe :: Foldable t => (a -> a -> Ordering) -> t a -> Maybe a

minimumByMaybe :: Foldable t => (a -> a -> Ordering) -> t a -> Maybe a

-- | &lt;math&gt;. <a>scanl</a> is similar to <a>foldl</a>, but returns a
--   list of successive reduced values from the left:
--   
--   <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 :: (b -> a -> b) -> b -> [a] -> [b]

-- | &lt;math&gt;. A strictly accumulating version of <a>scanl</a>
scanl' :: (b -> a -> b) -> b -> [a] -> [b]

-- | &lt;math&gt;. <a>scanr</a> is the right-to-left dual of <a>scanl</a>.
--   Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs.
--   </pre>
scanr :: (a -> b -> b) -> b -> [a] -> [b]

-- | &lt;math&gt;. <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (a -> a -> a) -> [a] -> [a]

-- | &lt;math&gt;. <a>scanr1</a> is a variant of <a>scanr</a> that has no
--   starting value argument.
scanr1 :: (a -> a -> a) -> [a] -> [a]

-- | The <a>mapAccumL</a> function behaves like a combination of
--   <a>fmap</a> and <a>foldl</a>; it applies a function to each element of
--   a structure, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   structure.
mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)

-- | The <a>mapAccumR</a> function behaves like a combination of
--   <a>fmap</a> and <a>foldr</a>; it applies a function to each element of
--   a structure, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   structure.
mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)

-- | <a>iterate</a> <tt>f x</tt> returns an infinite list of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
--   
--   Note that <a>iterate</a> is lazy, potentially leading to thunk
--   build-up if the consumer doesn't force each iterate. See
--   <a>iterate'</a> for a strict variant of this function.
iterate :: (a -> a) -> a -> [a]

-- | <a>repeat</a> <tt>x</tt> is an infinite list, with <tt>x</tt> the
--   value of every element.
repeat :: a -> [a]

-- | <a>replicate</a> <tt>n x</tt> is a list of length <tt>n</tt> with
--   <tt>x</tt> the value of every element. It is an instance of the more
--   general <a>genericReplicate</a>, in which <tt>n</tt> may be of any
--   integral type.
replicate :: Int -> a -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: [a] -> [a]

-- | The <a>unfoldr</a> function is a `dual' to <a>foldr</a>: while
--   <a>foldr</a> reduces a list to a summary value, <a>unfoldr</a> builds
--   a list from a seed value. The function takes the element and returns
--   <a>Nothing</a> if it is done producing the list or returns <a>Just</a>
--   <tt>(a,b)</tt>, in which case, <tt>a</tt> is a prepended to the list
--   and <tt>b</tt> is used as the next element in a recursive call. For
--   example,
--   
--   <pre>
--   iterate f == unfoldr (\x -&gt; Just (x, f x))
--   </pre>
--   
--   In some cases, <a>unfoldr</a> can undo a <a>foldr</a> operation:
--   
--   <pre>
--   unfoldr f' (foldr f z xs) == xs
--   </pre>
--   
--   if the following holds:
--   
--   <pre>
--   f' (f x y) = Just (x,y)
--   f' z       = Nothing
--   </pre>
--   
--   A simple use of unfoldr:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr (\b -&gt; if b == 0 then Nothing else Just (b, b-1)) 10
--   [10,9,8,7,6,5,4,3,2,1]
--   </pre>
unfoldr :: (b -> Maybe (a, b)) -> b -> [a]

-- | <a>take</a> <tt>n</tt>, applied to a list <tt>xs</tt>, returns the
--   prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt> itself if
--   <tt>n &gt; <a>length</a> xs</tt>:
--   
--   <pre>
--   take 5 "Hello World!" == "Hello"
--   take 3 [1,2,3,4,5] == [1,2,3]
--   take 3 [1,2] == [1,2]
--   take 3 [] == []
--   take (-1) [1,2] == []
--   take 0 [1,2] == []
--   </pre>
--   
--   It is an instance of the more general <a>genericTake</a>, in which
--   <tt>n</tt> may be of any integral type.
take :: Int -> [a] -> [a]

-- | <a>drop</a> <tt>n xs</tt> returns the suffix of <tt>xs</tt> after the
--   first <tt>n</tt> elements, or <tt>[]</tt> if <tt>n &gt; <a>length</a>
--   xs</tt>:
--   
--   <pre>
--   drop 6 "Hello World!" == "World!"
--   drop 3 [1,2,3,4,5] == [4,5]
--   drop 3 [1,2] == []
--   drop 3 [] == []
--   drop (-1) [1,2] == [1,2]
--   drop 0 [1,2] == [1,2]
--   </pre>
--   
--   It is an instance of the more general <a>genericDrop</a>, in which
--   <tt>n</tt> may be of any integral type.
drop :: Int -> [a] -> [a]

-- | <a>splitAt</a> <tt>n xs</tt> returns a tuple where first element is
--   <tt>xs</tt> prefix of length <tt>n</tt> and second element is the
--   remainder of the list:
--   
--   <pre>
--   splitAt 6 "Hello World!" == ("Hello ","World!")
--   splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
--   splitAt 1 [1,2,3] == ([1],[2,3])
--   splitAt 3 [1,2,3] == ([1,2,3],[])
--   splitAt 4 [1,2,3] == ([1,2,3],[])
--   splitAt 0 [1,2,3] == ([],[1,2,3])
--   splitAt (-1) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   It is equivalent to <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt> when
--   <tt>n</tt> is not <tt>_|_</tt> (<tt>splitAt _|_ xs = _|_</tt>).
--   <a>splitAt</a> is an instance of the more general
--   <a>genericSplitAt</a>, in which <tt>n</tt> may be of any integral
--   type.
splitAt :: Int -> [a] -> ([a], [a])

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: (a -> Bool) -> [a] -> [a]

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: (a -> Bool) -> [a] -> [a]

-- | The <a>dropWhileEnd</a> function drops the largest suffix of a list in
--   which the given predicate holds for all elements. For example:
--   
--   <pre>
--   &gt;&gt;&gt; dropWhileEnd isSpace "foo\n"
--   "foo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dropWhileEnd isSpace "foo bar"
--   "foo bar"
--   </pre>
--   
--   <pre>
--   dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined
--   </pre>
dropWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: (a -> Bool) -> [a] -> ([a], [a])

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (a -> Bool) -> [a] -> ([a], [a])

-- | &lt;math&gt;. The <a>stripPrefix</a> function drops the given prefix
--   from a list. It returns <a>Nothing</a> if the list did not start with
--   the prefix given, or <a>Just</a> the list after the prefix, if it
--   does.
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "foo" "foobar"
--   Just "bar"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "foo" "foo"
--   Just ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "foo" "barfoo"
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "foo" "barfoobaz"
--   Nothing
--   </pre>
stripPrefix :: Eq a => [a] -> [a] -> Maybe [a]

-- | Remove the suffix from the given list, if present
stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]

-- | Drop prefix if present, otherwise return original list.
dropPrefix :: Eq a => [a] -> [a] -> [a]

-- | Drop prefix if present, otherwise return original list.
dropSuffix :: Eq a => [a] -> [a] -> [a]

-- | The <a>group</a> function takes a list and returns a list of lists
--   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>
--   &gt;&gt;&gt; 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 :: Eq a => [a] -> [[a]]

-- | The <a>inits</a> function returns all initial segments of the
--   argument, shortest first. For example,
--   
--   <pre>
--   &gt;&gt;&gt; inits "abc"
--   ["","a","ab","abc"]
--   </pre>
--   
--   Note that <a>inits</a> has the following strictness property:
--   <tt>inits (xs ++ _|_) = inits xs ++ _|_</tt>
--   
--   In particular, <tt>inits _|_ = [] : _|_</tt>
inits :: [a] -> [[a]]

-- | &lt;math&gt;. The <a>tails</a> function returns all final segments of
--   the argument, longest first. For example,
--   
--   <pre>
--   &gt;&gt;&gt; tails "abc"
--   ["abc","bc","c",""]
--   </pre>
--   
--   Note that <a>tails</a> has the following strictness property:
--   <tt>tails _|_ = _|_ : _|_</tt>
tails :: [a] -> [[a]]

-- | &lt;math&gt;. The <a>isPrefixOf</a> function takes two lists and
--   returns <a>True</a> iff the first list is a prefix of the second.
--   
--   <pre>
--   &gt;&gt;&gt; "Hello" `isPrefixOf` "Hello World!"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello" `isPrefixOf` "Wello Horld!"
--   False
--   </pre>
isPrefixOf :: Eq a => [a] -> [a] -> Bool

-- | The <a>isSuffixOf</a> function takes two lists and returns <a>True</a>
--   iff the first list is a suffix of the second. The second list must be
--   finite.
--   
--   <pre>
--   &gt;&gt;&gt; "ld!" `isSuffixOf` "Hello World!"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; "World" `isSuffixOf` "Hello World!"
--   False
--   </pre>
isSuffixOf :: Eq a => [a] -> [a] -> Bool

-- | The <a>isInfixOf</a> function takes two lists and returns <a>True</a>
--   iff the first list is contained, wholly and intact, anywhere within
--   the second.
--   
--   <pre>
--   &gt;&gt;&gt; isInfixOf "Haskell" "I really like Haskell."
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isInfixOf "Ial" "I really like Haskell."
--   False
--   </pre>
isInfixOf :: Eq a => [a] -> [a] -> Bool

-- | The <a>isSubsequenceOf</a> function takes two lists and returns
--   <a>True</a> if all the elements of the first list occur, in order, in
--   the second. The elements do not have to occur consecutively.
--   
--   <tt><a>isSubsequenceOf</a> x y</tt> is equivalent to <tt><a>elem</a> x
--   (<a>subsequences</a> y)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; isSubsequenceOf "GHC" "The Glorious Haskell Compiler"
--   True
--   
--   &gt;&gt;&gt; isSubsequenceOf ['a','d'..'z'] ['a'..'z']
--   True
--   
--   &gt;&gt;&gt; isSubsequenceOf [1..10] [10,9..0]
--   False
--   </pre>
isSubsequenceOf :: Eq a => [a] -> [a] -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `elem`

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | &lt;math&gt;. <a>lookup</a> <tt>key assocs</tt> looks up a key in an
--   association list.
--   
--   <pre>
--   &gt;&gt;&gt; lookup 2 [(1, "first"), (2, "second"), (3, "third")]
--   Just "second"
--   </pre>
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | The <a>find</a> function takes a predicate and a structure and returns
--   the leftmost element of the structure matching the predicate, or
--   <a>Nothing</a> if there is no such element.
find :: Foldable t => (a -> Bool) -> t a -> Maybe a

-- | &lt;math&gt;. <a>filter</a>, applied to a predicate and a list,
--   returns the list of those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; filter odd [1, 2, 3]
--   [1,3]
--   </pre>
filter :: (a -> Bool) -> [a] -> [a]

-- | The <a>partition</a> function takes a predicate a list and returns the
--   pair of lists of elements which do and do not satisfy the predicate,
--   respectively; i.e.,
--   
--   <pre>
--   partition p xs == (filter p xs, filter (not . p) xs)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; partition (`elem` "aeiou") "Hello World!"
--   ("eoo","Hll Wrld!")
--   </pre>
partition :: (a -> Bool) -> [a] -> ([a], [a])

-- | The <a>elemIndex</a> function returns the index of the first element
--   in the given list which is equal (by <a>==</a>) to the query element,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 4 [0..]
--   Just 4
--   </pre>
elemIndex :: Eq a => a -> [a] -> Maybe Int

-- | The <a>elemIndices</a> function extends <a>elemIndex</a>, by returning
--   the indices of all elements equal to the query element, in ascending
--   order.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndices 'o' "Hello World"
--   [4,7]
--   </pre>
elemIndices :: Eq a => a -> [a] -> [Int]

-- | The <a>findIndex</a> function takes a predicate and a list and returns
--   the index of the first element in the list satisfying the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex isSpace "Hello World!"
--   Just 5
--   </pre>
findIndex :: (a -> Bool) -> [a] -> Maybe Int

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
--   
--   <pre>
--   &gt;&gt;&gt; findIndices (`elem` "aeiou") "Hello World!"
--   [1,4,7]
--   </pre>
findIndices :: (a -> Bool) -> [a] -> [Int]

-- | &lt;math&gt;. <a>zip</a> takes two lists and returns a list of
--   corresponding pairs.
--   
--   <pre>
--   zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]
--   </pre>
--   
--   If one input list is short, excess elements of the longer list are
--   discarded:
--   
--   <pre>
--   zip [1] ['a', 'b'] = [(1, 'a')]
--   zip [1, 2] ['a'] = [(1, 'a')]
--   </pre>
--   
--   <a>zip</a> is right-lazy:
--   
--   <pre>
--   zip [] _|_ = []
--   zip _|_ [] = _|_
--   </pre>
--   
--   <a>zip</a> is capable of list fusion, but it is restricted to its
--   first list argument and its resulting list.
zip :: [a] -> [b] -> [(a, b)]

-- | <a>zip3</a> takes three lists and returns a list of triples, analogous
--   to <a>zip</a>. It is capable of list fusion, but it is restricted to
--   its first list argument and its resulting list.
zip3 :: [a] -> [b] -> [c] -> [(a, b, c)]

-- | The <a>zip4</a> function takes four lists and returns a list of
--   quadruples, analogous to <a>zip</a>. It is capable of list fusion, but
--   it is restricted to its first list argument and its resulting list.
zip4 :: [a] -> [b] -> [c] -> [d] -> [(a, b, c, d)]

-- | The <a>zip5</a> function takes five lists and returns a list of
--   five-tuples, analogous to <a>zip</a>. It is capable of list fusion,
--   but it is restricted to its first list argument and its resulting
--   list.
zip5 :: [a] -> [b] -> [c] -> [d] -> [e] -> [(a, b, c, d, e)]

-- | The <a>zip6</a> function takes six lists and returns a list of
--   six-tuples, analogous to <a>zip</a>. It is capable of list fusion, but
--   it is restricted to its first list argument and its resulting list.
zip6 :: [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [(a, b, c, d, e, f)]

-- | The <a>zip7</a> function takes seven lists and returns a list of
--   seven-tuples, analogous to <a>zip</a>. It is capable of list fusion,
--   but it is restricted to its first list argument and its resulting
--   list.
zip7 :: [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g] -> [(a, b, c, d, e, f, g)]

-- | &lt;math&gt;. <a>zipWith</a> generalises <a>zip</a> by zipping with
--   the function given as the first argument, instead of a tupling
--   function. For example, <tt><a>zipWith</a> (+)</tt> is applied to two
--   lists to produce the list of corresponding sums:
--   
--   <pre>
--   &gt;&gt;&gt; zipWith (+) [1, 2, 3] [4, 5, 6]
--   [5,7,9]
--   </pre>
--   
--   <a>zipWith</a> is right-lazy:
--   
--   <pre>
--   zipWith f [] _|_ = []
--   </pre>
--   
--   <a>zipWith</a> is capable of list fusion, but it is restricted to its
--   first list argument and its resulting list.
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]

-- | The <a>zipWith3</a> function takes a function which combines three
--   elements, as well as three lists and returns a list of their
--   point-wise combination, analogous to <a>zipWith</a>. It is capable of
--   list fusion, but it is restricted to its first list argument and its
--   resulting list.
zipWith3 :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]

-- | The <a>zipWith4</a> function takes a function which combines four
--   elements, as well as four lists and returns a list of their point-wise
--   combination, analogous to <a>zipWith</a>. It is capable of list
--   fusion, but it is restricted to its first list argument and its
--   resulting list.
zipWith4 :: (a -> b -> c -> d -> e) -> [a] -> [b] -> [c] -> [d] -> [e]

-- | The <a>zipWith5</a> function takes a function which combines five
--   elements, as well as five lists and returns a list of their point-wise
--   combination, analogous to <a>zipWith</a>. It is capable of list
--   fusion, but it is restricted to its first list argument and its
--   resulting list.
zipWith5 :: (a -> b -> c -> d -> e -> f) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f]

-- | The <a>zipWith6</a> function takes a function which combines six
--   elements, as well as six lists and returns a list of their point-wise
--   combination, analogous to <a>zipWith</a>. It is capable of list
--   fusion, but it is restricted to its first list argument and its
--   resulting list.
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g]

-- | The <a>zipWith7</a> function takes a function which combines seven
--   elements, as well as seven lists and returns a list of their
--   point-wise combination, analogous to <a>zipWith</a>. It is capable of
--   list fusion, but it is restricted to its first list argument and its
--   resulting list.
zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g] -> [h]

-- | <a>unzip</a> transforms a list of pairs into a list of first
--   components and a list of second components.
unzip :: [(a, b)] -> ([a], [b])

-- | The <a>unzip3</a> function takes a list of triples and returns three
--   lists, analogous to <a>unzip</a>.
unzip3 :: [(a, b, c)] -> ([a], [b], [c])

-- | The <a>unzip4</a> function takes a list of quadruples and returns four
--   lists, analogous to <a>unzip</a>.
unzip4 :: [(a, b, c, d)] -> ([a], [b], [c], [d])

-- | The <a>unzip5</a> function takes a list of five-tuples and returns
--   five lists, analogous to <a>unzip</a>.
unzip5 :: [(a, b, c, d, e)] -> ([a], [b], [c], [d], [e])

-- | The <a>unzip6</a> function takes a list of six-tuples and returns six
--   lists, analogous to <a>unzip</a>.
unzip6 :: [(a, b, c, d, e, f)] -> ([a], [b], [c], [d], [e], [f])

-- | The <a>unzip7</a> function takes a list of seven-tuples and returns
--   seven lists, analogous to <a>unzip</a>.
unzip7 :: [(a, b, c, d, e, f, g)] -> ([a], [b], [c], [d], [e], [f], [g])

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | <a>linesCR</a> breaks a <a>String</a> up into a list of <a>String</a>s
--   at newline <a>Char</a>s. It is very similar to <a>lines</a>, but it
--   also removes any trailing <tt>'r'</tt> <a>Char</a>s. The resulting
--   <a>String</a> values do not contain newlines or trailing <tt>'r'</tt>
--   characters.
linesCR :: String -> [String]

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | &lt;math&gt;. The <a>nub</a> function removes duplicate elements from
--   a list. In particular, it keeps only the first occurrence of each
--   element. (The name <a>nub</a> means `essence'.) It is a special case
--   of <a>nubBy</a>, which allows the programmer to supply their own
--   equality test.
--   
--   <pre>
--   &gt;&gt;&gt; nub [1,2,3,4,3,2,1,2,4,3,5]
--   [1,2,3,4,5]
--   </pre>
nub :: Eq a => [a] -> [a]

-- | &lt;math&gt;. <a>delete</a> <tt>x</tt> removes the first occurrence of
--   <tt>x</tt> from its list argument. For example,
--   
--   <pre>
--   &gt;&gt;&gt; delete 'a' "banana"
--   "bnana"
--   </pre>
--   
--   It is a special case of <a>deleteBy</a>, which allows the programmer
--   to supply their own equality test.
delete :: Eq a => a -> [a] -> [a]

-- | The <a>\\</a> function is list difference (non-associative). In the
--   result of <tt>xs</tt> <a>\\</a> <tt>ys</tt>, the first occurrence of
--   each element of <tt>ys</tt> in turn (if any) has been removed from
--   <tt>xs</tt>. Thus
--   
--   <pre>
--   (xs ++ ys) \\ xs == ys.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello World!" \\ "ell W"
--   "Hoorld!"
--   </pre>
--   
--   It is a special case of <a>deleteFirstsBy</a>, which allows the
--   programmer to supply their own equality test.
(\\) :: Eq a => [a] -> [a] -> [a]
infix 5 \\

-- | The <a>union</a> function returns the list union of the two lists. For
--   example,
--   
--   <pre>
--   &gt;&gt;&gt; "dog" `union` "cow"
--   "dogcw"
--   </pre>
--   
--   Duplicates, and elements of the first list, are removed from the the
--   second list, but if the first list contains duplicates, so will the
--   result. It is a special case of <a>unionBy</a>, which allows the
--   programmer to supply their own equality test.
union :: Eq a => [a] -> [a] -> [a]

-- | The <a>intersect</a> function takes the list intersection of two
--   lists. For example,
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3,4] `intersect` [2,4,6,8]
--   [2,4]
--   </pre>
--   
--   If the first list contains duplicates, so will the result.
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,2,3,4] `intersect` [6,4,4,2]
--   [2,2,4]
--   </pre>
--   
--   It is a special case of <a>intersectBy</a>, which allows the
--   programmer to supply their own equality test. If the element is found
--   in both the first and the second list, the element from the first list
--   will be used.
intersect :: Eq a => [a] -> [a] -> [a]

-- | The <a>sort</a> function implements a stable sorting algorithm. It is
--   a special case of <a>sortBy</a>, which allows the programmer to supply
--   their own comparison function.
--   
--   Elements are arranged from lowest to highest, keeping duplicates in
--   the order they appeared in the input.
--   
--   <pre>
--   &gt;&gt;&gt; sort [1,6,4,3,2,5]
--   [1,2,3,4,5,6]
--   </pre>
sort :: Ord a => [a] -> [a]

-- | Sort a list by comparing the results of a key function applied to each
--   element. <tt>sortOn f</tt> is equivalent to <tt>sortBy (comparing
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list. This is called the
--   decorate-sort-undecorate paradigm, or Schwartzian transform.
--   
--   Elements are arranged from from lowest to highest, keeping duplicates
--   in the order they appeared in the input.
--   
--   <pre>
--   &gt;&gt;&gt; sortOn fst [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--   </pre>
sortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | &lt;math&gt;. The <a>insert</a> function takes an element and a list
--   and inserts the element into the list at the first position where it
--   is less than or equal to the next element. In particular, if the list
--   is sorted before the call, the result will also be sorted. It is a
--   special case of <a>insertBy</a>, which allows the programmer to supply
--   their own comparison function.
--   
--   <pre>
--   &gt;&gt;&gt; insert 4 [1,2,3,5,6,7]
--   [1,2,3,4,5,6,7]
--   </pre>
insert :: Ord a => a -> [a] -> [a]

-- | The <a>nubBy</a> function behaves just like <a>nub</a>, except it uses
--   a user-supplied equality predicate instead of the overloaded <a>==</a>
--   function.
--   
--   <pre>
--   &gt;&gt;&gt; nubBy (\x y -&gt; mod x 3 == mod y 3) [1,2,4,5,6]
--   [1,2,6]
--   </pre>
nubBy :: (a -> a -> Bool) -> [a] -> [a]

-- | &lt;math&gt;. The <a>deleteBy</a> function behaves like <a>delete</a>,
--   but takes a user-supplied equality predicate.
--   
--   <pre>
--   &gt;&gt;&gt; deleteBy (&lt;=) 4 [1..10]
--   [1,2,3,5,6,7,8,9,10]
--   </pre>
deleteBy :: (a -> a -> Bool) -> a -> [a] -> [a]

-- | The <a>deleteFirstsBy</a> function takes a predicate and two lists and
--   returns the first list with the first occurrence of each element of
--   the second list removed.
deleteFirstsBy :: (a -> a -> Bool) -> [a] -> [a] -> [a]

-- | The <a>unionBy</a> function is the non-overloaded version of
--   <a>union</a>.
unionBy :: (a -> a -> Bool) -> [a] -> [a] -> [a]

-- | The <a>intersectBy</a> function is the non-overloaded version of
--   <a>intersect</a>.
intersectBy :: (a -> a -> Bool) -> [a] -> [a] -> [a]

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

-- | The <a>sortBy</a> function is the non-overloaded version of
--   <a>sort</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sortBy (\(a,_) (b,_) -&gt; compare a b) [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--   </pre>
sortBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | &lt;math&gt;. The non-overloaded version of <a>insert</a>.
insertBy :: (a -> a -> Ordering) -> a -> [a] -> [a]

-- | &lt;math&gt;. The <a>genericLength</a> function is an overloaded
--   version of <a>length</a>. In particular, instead of returning an
--   <a>Int</a>, it returns any type which is an instance of <a>Num</a>. It
--   is, however, less efficient than <a>length</a>.
--   
--   <pre>
--   &gt;&gt;&gt; genericLength [1, 2, 3] :: Int
--   3
--   
--   &gt;&gt;&gt; genericLength [1, 2, 3] :: Float
--   3.0
--   </pre>
genericLength :: Num i => [a] -> i

-- | The <a>genericTake</a> function is an overloaded version of
--   <a>take</a>, which accepts any <a>Integral</a> value as the number of
--   elements to take.
genericTake :: Integral i => i -> [a] -> [a]

-- | The <a>genericDrop</a> function is an overloaded version of
--   <a>drop</a>, which accepts any <a>Integral</a> value as the number of
--   elements to drop.
genericDrop :: Integral i => i -> [a] -> [a]

-- | The <a>genericSplitAt</a> function is an overloaded version of
--   <a>splitAt</a>, which accepts any <a>Integral</a> value as the
--   position at which to split.
genericSplitAt :: Integral i => i -> [a] -> ([a], [a])

-- | The <a>genericIndex</a> function is an overloaded version of
--   <a>!!</a>, which accepts any <a>Integral</a> value as the index.
genericIndex :: Integral i => [a] -> i -> a

-- | The <a>genericReplicate</a> function is an overloaded version of
--   <a>replicate</a>, which accepts any <a>Integral</a> value as the
--   number of repetitions to make.
genericReplicate :: Integral i => i -> a -> [a]


-- | <tt>List</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.List.Partial as L'
--   </pre>
module RIO.List.Partial

-- | &lt;math&gt;. Extract the first element of a list, which must be
--   non-empty.
head :: [a] -> a

-- | &lt;math&gt;. Extract the last element of a list, which must be finite
--   and non-empty.
last :: [a] -> a

-- | &lt;math&gt;. Extract the elements after the head of a list, which
--   must be non-empty.
tail :: [a] -> [a]

-- | &lt;math&gt;. Return all the elements of a list except the last one.
--   The list must be non-empty.
init :: [a] -> [a]

-- | A variant of <a>foldl</a> that has no base case, and thus may only be
--   applied to non-empty structures.
--   
--   <pre>
--   <a>foldl1</a> f = <a>foldl1</a> f . <a>toList</a>
--   </pre>
foldl1 :: Foldable t => (a -> a -> a) -> t a -> a

-- | A strict version of <a>foldl1</a>
foldl1' :: (a -> a -> a) -> [a] -> a

-- | A variant of <a>foldr</a> that has no base case, and thus may only be
--   applied to non-empty structures.
--   
--   <pre>
--   <a>foldr1</a> f = <a>foldr1</a> f . <a>toList</a>
--   </pre>
foldr1 :: Foldable t => (a -> a -> a) -> t a -> a

-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a

-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a

-- | The largest element of a non-empty structure with respect to the given
--   comparison function.
maximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a

-- | The least element of a non-empty structure with respect to the given
--   comparison function.
minimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a

-- | &lt;math&gt;. <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (a -> a -> a) -> [a] -> [a]

-- | &lt;math&gt;. <a>scanr1</a> is a variant of <a>scanr</a> that has no
--   starting value argument.
scanr1 :: (a -> a -> a) -> [a] -> [a]

-- | List index (subscript) operator, starting from 0. It is an instance of
--   the more general <a>genericIndex</a>, which takes an index of any
--   integral type.
(!!) :: [a] -> Int -> a
infixl 9 !!


-- | Strict <tt>Map</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Map as Map
--   </pre>
--   
--   This module does not export any partial or unchecked functions. For
--   those, see <a>RIO.Map.Partial</a> and <a>RIO.Map.Unchecked</a>
module RIO.Map

-- | A Map from keys <tt>k</tt> to values <tt>a</tt>.
--   
--   The <a>Semigroup</a> operation for <a>Map</a> is <a>union</a>, which
--   prefers values from the left operand. If <tt>m1</tt> maps a key
--   <tt>k</tt> to a value <tt>a1</tt>, and <tt>m2</tt> maps the same key
--   to a different value <tt>a2</tt>, then their union <tt>m1 &lt;&gt;
--   m2</tt> maps <tt>k</tt> to <tt>a1</tt>.
data Map k a

-- | <i>O(log n)</i>. Find the value at a key. Returns <a>Nothing</a> when
--   the element can not be found.
--   
--   <pre>
--   fromList [(5, 'a'), (3, 'b')] !? 1 == Nothing
--   </pre>
--   
--   <pre>
--   fromList [(5, 'a'), (3, 'b')] !? 5 == Just 'a'
--   </pre>
(!?) :: Ord k => Map k a -> k -> Maybe a
infixl 9 !?

-- | Same as <a>difference</a>.
(\\) :: Ord k => Map k a -> Map k b -> Map k a
infixl 9 \\

-- | <i>O(1)</i>. Is the map empty?
--   
--   <pre>
--   Data.Map.null (empty)           == True
--   Data.Map.null (singleton 1 'a') == False
--   </pre>
null :: Map k a -> Bool

-- | <i>O(1)</i>. The number of elements in the map.
--   
--   <pre>
--   size empty                                   == 0
--   size (singleton 1 'a')                       == 1
--   size (fromList([(1,'a'), (2,'c'), (3,'b')])) == 3
--   </pre>
size :: Map k a -> Int

-- | <i>O(log n)</i>. Is the key a member of the map? See also
--   <a>notMember</a>.
--   
--   <pre>
--   member 5 (fromList [(5,'a'), (3,'b')]) == True
--   member 1 (fromList [(5,'a'), (3,'b')]) == False
--   </pre>
member :: Ord k => k -> Map k a -> Bool

-- | <i>O(log n)</i>. Is the key not a member of the map? See also
--   <a>member</a>.
--   
--   <pre>
--   notMember 5 (fromList [(5,'a'), (3,'b')]) == False
--   notMember 1 (fromList [(5,'a'), (3,'b')]) == True
--   </pre>
notMember :: Ord k => k -> Map k a -> Bool

-- | <i>O(log n)</i>. Lookup the value at a key in the map.
--   
--   The function will return the corresponding value as <tt>(<a>Just</a>
--   value)</tt>, or <a>Nothing</a> if the key isn't in the map.
--   
--   An example of using <tt>lookup</tt>:
--   
--   <pre>
--   import Prelude hiding (lookup)
--   import Data.Map
--   
--   employeeDept = fromList([("John","Sales"), ("Bob","IT")])
--   deptCountry = fromList([("IT","USA"), ("Sales","France")])
--   countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")])
--   
--   employeeCurrency :: String -&gt; Maybe String
--   employeeCurrency name = do
--       dept &lt;- lookup name employeeDept
--       country &lt;- lookup dept deptCountry
--       lookup country countryCurrency
--   
--   main = do
--       putStrLn $ "John's currency: " ++ (show (employeeCurrency "John"))
--       putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete"))
--   </pre>
--   
--   The output of this program:
--   
--   <pre>
--   John's currency: Just "Euro"
--   Pete's currency: Nothing
--   </pre>
lookup :: Ord k => k -> Map k a -> Maybe a

-- | <i>O(log n)</i>. The expression <tt>(<a>findWithDefault</a> def k
--   map)</tt> returns the value at key <tt>k</tt> or returns default value
--   <tt>def</tt> when the key is not in the map.
--   
--   <pre>
--   findWithDefault 'x' 1 (fromList [(5,'a'), (3,'b')]) == 'x'
--   findWithDefault 'x' 5 (fromList [(5,'a'), (3,'b')]) == 'a'
--   </pre>
findWithDefault :: Ord k => a -> k -> Map k a -> a

-- | <i>O(log n)</i>. Find largest key smaller than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLT 3 (fromList [(3,'a'), (5,'b')]) == Nothing
--   lookupLT 4 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a')
--   </pre>
lookupLT :: Ord k => k -> Map k v -> Maybe (k, v)

-- | <i>O(log n)</i>. Find smallest key greater than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGT 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b')
--   lookupGT 5 (fromList [(3,'a'), (5,'b')]) == Nothing
--   </pre>
lookupGT :: Ord k => k -> Map k v -> Maybe (k, v)

-- | <i>O(log n)</i>. Find largest key smaller or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLE 2 (fromList [(3,'a'), (5,'b')]) == Nothing
--   lookupLE 4 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a')
--   lookupLE 5 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b')
--   </pre>
lookupLE :: Ord k => k -> Map k v -> Maybe (k, v)

-- | <i>O(log n)</i>. Find smallest key greater or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGE 3 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a')
--   lookupGE 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b')
--   lookupGE 6 (fromList [(3,'a'), (5,'b')]) == Nothing
--   </pre>
lookupGE :: Ord k => k -> Map k v -> Maybe (k, v)

-- | <i>O(1)</i>. The empty map.
--   
--   <pre>
--   empty      == fromList []
--   size empty == 0
--   </pre>
empty :: Map k a

-- | <i>O(1)</i>. A map with a single element.
--   
--   <pre>
--   singleton 1 'a'        == fromList [(1, 'a')]
--   size (singleton 1 'a') == 1
--   </pre>
singleton :: k -> a -> Map k a

-- | <i>O(log n)</i>. Insert a new key and value in the map. If the key is
--   already present in the map, the associated value is replaced with the
--   supplied value. <a>insert</a> is equivalent to <tt><a>insertWith</a>
--   <a>const</a></tt>.
--   
--   <pre>
--   insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')]
--   insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')]
--   insert 5 'x' empty                         == singleton 5 'x'
--   </pre>
insert :: Ord k => k -> a -> Map k a -> Map k a

-- | <i>O(log n)</i>. Insert with a function, combining new value and old
--   value. <tt><a>insertWith</a> f key value mp</tt> will insert the pair
--   (key, value) into <tt>mp</tt> if key does not exist in the map. If the
--   key does exist, the function will insert the pair <tt>(key, f
--   new_value old_value)</tt>.
--   
--   <pre>
--   insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")]
--   insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
--   insertWith (++) 5 "xxx" empty                         == singleton 5 "xxx"
--   </pre>
insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a

-- | <i>O(log n)</i>. Insert with a function, combining key, new value and
--   old value. <tt><a>insertWithKey</a> f key value mp</tt> will insert
--   the pair (key, value) into <tt>mp</tt> if key does not exist in the
--   map. If the key does exist, the function will insert the pair
--   <tt>(key,f key new_value old_value)</tt>. Note that the key passed to
--   f is the same key passed to <a>insertWithKey</a>.
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")]
--   insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
--   insertWithKey f 5 "xxx" empty                         == singleton 5 "xxx"
--   </pre>
insertWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a

-- | <i>O(log n)</i>. Combines insert operation with old value retrieval.
--   The expression (<tt><a>insertLookupWithKey</a> f k x map</tt>) is a
--   pair where the first element is equal to (<tt><a>lookup</a> k
--   map</tt>) and the second element equal to (<tt><a>insertWithKey</a> f
--   k x map</tt>).
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")])
--   insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a"), (7, "xxx")])
--   insertLookupWithKey f 5 "xxx" empty                         == (Nothing,  singleton 5 "xxx")
--   </pre>
--   
--   This is how to define <tt>insertLookup</tt> using
--   <tt>insertLookupWithKey</tt>:
--   
--   <pre>
--   let insertLookup kx x t = insertLookupWithKey (\_ a _ -&gt; a) kx x t
--   insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")])
--   insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a"), (7, "x")])
--   </pre>
insertLookupWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> (Maybe a, Map k a)

-- | <i>O(log n)</i>. Delete a key and its value from the map. When the key
--   is not a member of the map, the original map is returned.
--   
--   <pre>
--   delete 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   delete 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   delete 5 empty                         == empty
--   </pre>
delete :: Ord k => k -> Map k a -> Map k a

-- | <i>O(log n)</i>. Update a value at a specific key with the result of
--   the provided function. When the key is not a member of the map, the
--   original map is returned.
--   
--   <pre>
--   adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")]
--   adjust ("new " ++) 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   adjust ("new " ++) 7 empty                         == empty
--   </pre>
adjust :: Ord k => (a -> a) -> k -> Map k a -> Map k a

-- | <i>O(log n)</i>. Adjust a value at a specific key. When the key is not
--   a member of the map, the original map is returned.
--   
--   <pre>
--   let f key x = (show key) ++ ":new " ++ x
--   adjustWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")]
--   adjustWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   adjustWithKey f 7 empty                         == empty
--   </pre>
adjustWithKey :: Ord k => (k -> a -> a) -> k -> Map k a -> Map k a

-- | <i>O(log n)</i>. The expression (<tt><a>update</a> f k map</tt>)
--   updates the value <tt>x</tt> at <tt>k</tt> (if it is in the map). If
--   (<tt>f x</tt>) is <a>Nothing</a>, the element is deleted. If it is
--   (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the new value
--   <tt>y</tt>.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   update f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")]
--   update f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   update f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   </pre>
update :: Ord k => (a -> Maybe a) -> k -> Map k a -> Map k a

-- | <i>O(log n)</i>. The expression (<tt><a>updateWithKey</a> f k
--   map</tt>) updates the value <tt>x</tt> at <tt>k</tt> (if it is in the
--   map). If (<tt>f k x</tt>) is <a>Nothing</a>, the element is deleted.
--   If it is (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the
--   new value <tt>y</tt>.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")]
--   updateWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   updateWithKey f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   </pre>
updateWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> Map k a

-- | <i>O(log n)</i>. Lookup and update. See also <a>updateWithKey</a>. The
--   function returns changed value, if it is updated. Returns the original
--   key value if the map entry is deleted.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateLookupWithKey f 5 (fromList [(5,"a"), (3,"b")]) == (Just "5:new a", fromList [(3, "b"), (5, "5:new a")])
--   updateLookupWithKey f 7 (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a")])
--   updateLookupWithKey f 3 (fromList [(5,"a"), (3,"b")]) == (Just "b", singleton 5 "a")
--   </pre>
updateLookupWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> (Maybe a, Map k a)

-- | <i>O(log n)</i>. The expression (<tt><a>alter</a> f k map</tt>) alters
--   the value <tt>x</tt> at <tt>k</tt>, or absence thereof. <a>alter</a>
--   can be used to insert, delete, or update a value in a <a>Map</a>. In
--   short : <tt><a>lookup</a> k (<a>alter</a> f k m) = f (<a>lookup</a> k
--   m)</tt>.
--   
--   <pre>
--   let f _ = Nothing
--   alter f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")]
--   alter f 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   
--   let f _ = Just "c"
--   alter f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "c")]
--   alter f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "c")]
--   </pre>
--   
--   Note that <tt><a>adjust</a> = alter . fmap</tt>.
alter :: Ord k => (Maybe a -> Maybe a) -> k -> Map k a -> Map k a

-- | <i>O(log n)</i>. The expression (<tt><a>alterF</a> f k map</tt>)
--   alters the value <tt>x</tt> at <tt>k</tt>, or absence thereof.
--   <a>alterF</a> can be used to inspect, insert, delete, or update a
--   value in a <a>Map</a>. In short: <tt><a>lookup</a> k &lt;$&gt;
--   <a>alterF</a> f k m = f (<a>lookup</a> k m)</tt>.
--   
--   Example:
--   
--   <pre>
--   interactiveAlter :: Int -&gt; Map Int String -&gt; IO (Map Int String)
--   interactiveAlter k m = alterF f k m where
--     f Nothing = do
--        putStrLn $ show k ++
--            " was not found in the map. Would you like to add it?"
--        getUserResponse1 :: IO (Maybe String)
--     f (Just old) = do
--        putStrLn $ "The key is currently bound to " ++ show old ++
--            ". Would you like to change or delete it?"
--        getUserResponse2 :: IO (Maybe String)
--   </pre>
--   
--   <a>alterF</a> is the most general operation for working with an
--   individual key that may or may not be in a given map. When used with
--   trivial functors like <a>Identity</a> and <a>Const</a>, it is often
--   slightly slower than more specialized combinators like <a>lookup</a>
--   and <a>insert</a>. However, when the functor is non-trivial and key
--   comparison is not particularly cheap, it is the fastest way.
--   
--   Note on rewrite rules:
--   
--   This module includes GHC rewrite rules to optimize <a>alterF</a> for
--   the <a>Const</a> and <a>Identity</a> functors. In general, these rules
--   improve performance. The sole exception is that when using
--   <a>Identity</a>, deleting a key that is already absent takes longer
--   than it would without the rules. If you expect this to occur a very
--   large fraction of the time, you might consider using a private copy of
--   the <a>Identity</a> type.
--   
--   Note: <a>alterF</a> is a flipped version of the <tt>at</tt> combinator
--   from <tt>Control.Lens.At</tt>.
alterF :: (Functor f, Ord k) => (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression (<tt><a>union</a>
--   t1 t2</tt>) takes the left-biased union of <tt>t1</tt> and
--   <tt>t2</tt>. It prefers <tt>t1</tt> when duplicate keys are
--   encountered, i.e. (<tt><a>union</a> == <a>unionWith</a>
--   <a>const</a></tt>).
--   
--   <pre>
--   union (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "a"), (7, "C")]
--   </pre>
union :: Ord k => Map k a -> Map k a -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function.
--   
--   <pre>
--   unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")]
--   </pre>
unionWith :: Ord k => (a -> a -> a) -> Map k a -> Map k a -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function.
--   
--   <pre>
--   let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value
--   unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")]
--   </pre>
unionWithKey :: Ord k => (k -> a -> a -> a) -> Map k a -> Map k a -> Map k a

-- | The union of a list of maps: (<tt><a>unions</a> == <a>foldl</a>
--   <a>union</a> <a>empty</a></tt>).
--   
--   <pre>
--   unions [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])]
--       == fromList [(3, "b"), (5, "a"), (7, "C")]
--   unions [(fromList [(5, "A3"), (3, "B3")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "a"), (3, "b")])]
--       == fromList [(3, "B3"), (5, "A3"), (7, "C")]
--   </pre>
unions :: (Foldable f, Ord k) => f (Map k a) -> Map k a

-- | The union of a list of maps, with a combining operation:
--   (<tt><a>unionsWith</a> f == <a>foldl</a> (<a>unionWith</a> f)
--   <a>empty</a></tt>).
--   
--   <pre>
--   unionsWith (++) [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])]
--       == fromList [(3, "bB3"), (5, "aAA3"), (7, "C")]
--   </pre>
unionsWith :: (Foldable f, Ord k) => (a -> a -> a) -> f (Map k a) -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two maps. Return
--   elements of the first map not existing in the second map.
--   
--   <pre>
--   difference (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 3 "b"
--   </pre>
difference :: Ord k => Map k a -> Map k b -> Map k a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the values
--   of these keys. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   <pre>
--   let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
--   differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")])
--       == singleton 3 "b:B"
--   </pre>
differenceWith :: Ord k => (a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the key and
--   both values. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   <pre>
--   let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing
--   differenceWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (10, "C")])
--       == singleton 3 "3:b|B"
--   </pre>
differenceWithKey :: Ord k => (k -> a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection of two maps. Return
--   data in the first map for the keys existing in both maps.
--   (<tt><a>intersection</a> m1 m2 == <a>intersectionWith</a> <a>const</a>
--   m1 m2</tt>).
--   
--   <pre>
--   intersection (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "a"
--   </pre>
intersection :: Ord k => Map k a -> Map k b -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   <pre>
--   intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA"
--   </pre>
intersectionWith :: Ord k => (a -> b -> c) -> Map k a -> Map k b -> Map k c

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   <pre>
--   let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar
--   intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A"
--   </pre>
intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c

-- | <i>O(n+m)</i>. An unsafe universal combining function.
--   
--   WARNING: This function can produce corrupt maps and its results may
--   depend on the internal structures of its inputs. Users should prefer
--   <a>merge</a> or <a>mergeA</a>.
--   
--   When <a>mergeWithKey</a> is given three arguments, it is inlined to
--   the call site. You should therefore use <a>mergeWithKey</a> only to
--   define custom combining functions. For example, you could define
--   <a>unionWithKey</a>, <a>differenceWithKey</a> and
--   <a>intersectionWithKey</a> as
--   
--   <pre>
--   myUnionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -&gt; Just (f k x1 x2)) id id m1 m2
--   myDifferenceWithKey f m1 m2 = mergeWithKey f id (const empty) m1 m2
--   myIntersectionWithKey f m1 m2 = mergeWithKey (\k x1 x2 -&gt; Just (f k x1 x2)) (const empty) (const empty) m1 m2
--   </pre>
--   
--   When calling <tt><a>mergeWithKey</a> combine only1 only2</tt>, a
--   function combining two <a>Map</a>s is created, such that
--   
--   <ul>
--   <li>if a key is present in both maps, it is passed with both
--   corresponding values to the <tt>combine</tt> function. Depending on
--   the result, the key is either present in the result with specified
--   value, or is left out;</li>
--   <li>a nonempty subtree present only in the first map is passed to
--   <tt>only1</tt> and the output is added to the result;</li>
--   <li>a nonempty subtree present only in the second map is passed to
--   <tt>only2</tt> and the output is added to the result.</li>
--   </ul>
--   
--   The <tt>only1</tt> and <tt>only2</tt> methods <i>must return a map
--   with a subset (possibly empty) of the keys of the given map</i>. The
--   values can be modified arbitrarily. Most common variants of
--   <tt>only1</tt> and <tt>only2</tt> are <a>id</a> and <tt><a>const</a>
--   <a>empty</a></tt>, but for example <tt><a>map</a> f</tt> or
--   <tt><a>filterWithKey</a> f</tt> could be used for any <tt>f</tt>.
mergeWithKey :: Ord k => (k -> a -> b -> Maybe c) -> (Map k a -> Map k c) -> (Map k b -> Map k c) -> Map k a -> Map k b -> Map k c

-- | <i>O(n)</i>. Map a function over all values in the map.
--   
--   <pre>
--   map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")]
--   </pre>
map :: (a -> b) -> Map k a -> Map k b

-- | <i>O(n)</i>. Map a function over all values in the map.
--   
--   <pre>
--   let f key x = (show key) ++ ":" ++ x
--   mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")]
--   </pre>
mapWithKey :: (k -> a -> b) -> Map k a -> Map k b

-- | <i>O(n)</i>. <tt><a>traverseWithKey</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse</a> ((k, v) -&gt; (v' -&gt; v' `seq` (k,v'))
--   <a>$</a> f k v) (<a>toList</a> m)</tt> That is, it behaves much like a
--   regular <a>traverse</a> except that the traversing function also has
--   access to the key associated with a value and the values are forced
--   before they are installed in the result map.
--   
--   <pre>
--   traverseWithKey (\k v -&gt; if odd k then Just (succ v) else Nothing) (fromList [(1, 'a'), (5, 'e')]) == Just (fromList [(1, 'b'), (5, 'f')])
--   traverseWithKey (\k v -&gt; if odd k then Just (succ v) else Nothing) (fromList [(2, 'c')])           == Nothing
--   </pre>
traverseWithKey :: Applicative t => (k -> a -> t b) -> Map k a -> t (Map k b)

-- | <i>O(n)</i>. Traverse keys/values and collect the <a>Just</a> results.
traverseMaybeWithKey :: Applicative f => (k -> a -> f (Maybe b)) -> Map k a -> f (Map k b)

-- | <i>O(n)</i>. The function <a>mapAccum</a> threads an accumulating
--   argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a b = (a ++ b, b ++ "X")
--   mapAccum f "Everything: " (fromList [(5,"a"), (3,"b")]) == ("Everything: ba", fromList [(3, "bX"), (5, "aX")])
--   </pre>
mapAccum :: (a -> b -> (a, c)) -> a -> Map k b -> (a, Map k c)

-- | <i>O(n)</i>. The function <a>mapAccumWithKey</a> threads an
--   accumulating argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
--   mapAccumWithKey f "Everything:" (fromList [(5,"a"), (3,"b")]) == ("Everything: 3-b 5-a", fromList [(3, "bX"), (5, "aX")])
--   </pre>
mapAccumWithKey :: (a -> k -> b -> (a, c)) -> a -> Map k b -> (a, Map k c)

-- | <i>O(n)</i>. The function <a>mapAccumRWithKey</a> threads an
--   accumulating argument through the map in descending order of keys.
mapAccumRWithKey :: (a -> k -> b -> (a, c)) -> a -> Map k b -> (a, Map k c)

-- | <i>O(n*log n)</i>. <tt><a>mapKeys</a> f s</tt> is the map obtained by
--   applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the value at the
--   greatest of the original keys is retained.
--   
--   <pre>
--   mapKeys (+ 1) (fromList [(5,"a"), (3,"b")])                        == fromList [(4, "b"), (6, "a")]
--   mapKeys (\ _ -&gt; 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "c"
--   mapKeys (\ _ -&gt; 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "c"
--   </pre>
mapKeys :: Ord k2 => (k1 -> k2) -> Map k1 a -> Map k2 a

-- | <i>O(n*log n)</i>. <tt><a>mapKeysWith</a> c f s</tt> is the map
--   obtained by applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the associated values
--   will be combined using <tt>c</tt>. The value at the greater of the two
--   original keys is used as the first argument to <tt>c</tt>.
--   
--   <pre>
--   mapKeysWith (++) (\ _ -&gt; 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "cdab"
--   mapKeysWith (++) (\ _ -&gt; 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "cdab"
--   </pre>
mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1 -> k2) -> Map k1 a -> Map k2 a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>elems</a></tt>.
--   
--   For example,
--   
--   <pre>
--   elems map = foldr (:) [] map
--   </pre>
--   
--   <pre>
--   let f a len = len + (length a)
--   foldr f 0 (fromList [(5,"a"), (3,"bbb")]) == 4
--   </pre>
foldr :: (a -> b -> b) -> b -> Map k a -> b

-- | <i>O(n)</i>. Fold the values in the map using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>elems</a></tt>.
--   
--   For example,
--   
--   <pre>
--   elems = reverse . foldl (flip (:)) []
--   </pre>
--   
--   <pre>
--   let f len a = len + (length a)
--   foldl f 0 (fromList [(5,"a"), (3,"bbb")]) == 4
--   </pre>
foldl :: (a -> b -> a) -> a -> Map k b -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   right-associative binary operator, such that <tt><a>foldrWithKey</a> f
--   z == <a>foldr</a> (<a>uncurry</a> f) z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keys map = foldrWithKey (\k x ks -&gt; k:ks) [] map
--   </pre>
--   
--   <pre>
--   let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")"
--   foldrWithKey f "Map: " (fromList [(5,"a"), (3,"b")]) == "Map: (5:a)(3:b)"
--   </pre>
foldrWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   left-associative binary operator, such that <tt><a>foldlWithKey</a> f
--   z == <a>foldl</a> (\z' (kx, x) -&gt; f z' kx x) z .
--   <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keys = reverse . foldlWithKey (\ks k x -&gt; k:ks) []
--   </pre>
--   
--   <pre>
--   let f result k a = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")"
--   foldlWithKey f "Map: " (fromList [(5,"a"), (3,"b")]) == "Map: (3:b)(5:a)"
--   </pre>
foldlWithKey :: (a -> k -> b -> a) -> a -> Map k b -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   monoid, such that
--   
--   <pre>
--   <a>foldMapWithKey</a> f = <a>fold</a> . <a>mapWithKey</a> f
--   </pre>
--   
--   This can be an asymptotically faster than <a>foldrWithKey</a> or
--   <a>foldlWithKey</a> for some monoids.
foldMapWithKey :: Monoid m => (k -> a -> m) -> Map k a -> m

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> Map k a -> b

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> Map k b -> a

-- | <i>O(n)</i>. A strict version of <a>foldrWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldrWithKey' :: (k -> a -> b -> b) -> b -> Map k a -> b

-- | <i>O(n)</i>. A strict version of <a>foldlWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldlWithKey' :: (a -> k -> b -> a) -> a -> Map k b -> a

-- | <i>O(n)</i>. Return all elements of the map in the ascending order of
--   their keys. Subject to list fusion.
--   
--   <pre>
--   elems (fromList [(5,"a"), (3,"b")]) == ["b","a"]
--   elems empty == []
--   </pre>
elems :: Map k a -> [a]

-- | <i>O(n)</i>. Return all keys of the map in ascending order. Subject to
--   list fusion.
--   
--   <pre>
--   keys (fromList [(5,"a"), (3,"b")]) == [3,5]
--   keys empty == []
--   </pre>
keys :: Map k a -> [k]

-- | <i>O(n)</i>. An alias for <a>toAscList</a>. Return all key/value pairs
--   in the map in ascending key order. Subject to list fusion.
--   
--   <pre>
--   assocs (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")]
--   assocs empty == []
--   </pre>
assocs :: Map k a -> [(k, a)]

-- | <i>O(n)</i>. The set of all keys of the map.
--   
--   <pre>
--   keysSet (fromList [(5,"a"), (3,"b")]) == Data.Set.fromList [3,5]
--   keysSet empty == Data.Set.empty
--   </pre>
keysSet :: Map k a -> Set k

-- | <i>O(n)</i>. Build a map from a set of keys and a function which for
--   each key computes its value.
--   
--   <pre>
--   fromSet (\k -&gt; replicate k 'a') (Data.Set.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")]
--   fromSet undefined Data.Set.empty == empty
--   </pre>
fromSet :: (k -> a) -> Set k -> Map k a

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs. Subject to
--   list fusion.
--   
--   <pre>
--   toList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")]
--   toList empty == []
--   </pre>
toList :: Map k a -> [(k, a)]

-- | <i>O(n*log n)</i>. Build a map from a list of key/value pairs. See
--   also <a>fromAscList</a>. If the list contains more than one value for
--   the same key, the last value for the key is retained.
--   
--   If the keys of the list are ordered, linear-time implementation is
--   used, with the performance equal to <a>fromDistinctAscList</a>.
--   
--   <pre>
--   fromList [] == empty
--   fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")]
--   fromList [(5,"c"), (3,"b"), (5, "a")] == fromList [(5,"a"), (3,"b")]
--   </pre>
fromList :: Ord k => [(k, a)] -> Map k a

-- | <i>O(n*log n)</i>. Build a map from a list of key/value pairs with a
--   combining function. See also <a>fromAscListWith</a>.
--   
--   <pre>
--   fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")]
--   fromListWith (++) [] == empty
--   </pre>
fromListWith :: Ord k => (a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n*log n)</i>. Build a map from a list of key/value pairs with a
--   combining function. See also <a>fromAscListWithKey</a>.
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ a1 ++ a2
--   fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "3ab"), (5, "5a5ba")]
--   fromListWithKey f [] == empty
--   </pre>
fromListWithKey :: Ord k => (k -> a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in ascending order. Subject to list fusion.
--   
--   <pre>
--   toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")]
--   </pre>
toAscList :: Map k a -> [(k, a)]

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in descending order. Subject to list fusion.
--   
--   <pre>
--   toDescList (fromList [(5,"a"), (3,"b")]) == [(5,"a"), (3,"b")]
--   </pre>
toDescList :: Map k a -> [(k, a)]

-- | <i>O(n)</i>. Filter all values that satisfy the predicate.
--   
--   <pre>
--   filter (&gt; "a") (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   filter (&gt; "x") (fromList [(5,"a"), (3,"b")]) == empty
--   filter (&lt; "a") (fromList [(5,"a"), (3,"b")]) == empty
--   </pre>
filter :: (a -> Bool) -> Map k a -> Map k a

-- | <i>O(n)</i>. Filter all keys/values that satisfy the predicate.
--   
--   <pre>
--   filterWithKey (\k _ -&gt; k &gt; 4) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   </pre>
filterWithKey :: (k -> a -> Bool) -> Map k a -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Restrict a <a>Map</a> to only
--   those keys found in a <a>Set</a>.
--   
--   <pre>
--   m `restrictKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`member`</a> s) m
--   m `restrictKeys` s = m <a>`intersection`</a> <a>fromSet</a> (const ()) s
--   </pre>
restrictKeys :: Ord k => Map k a -> Set k -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Remove all keys in a <a>Set</a>
--   from a <a>Map</a>.
--   
--   <pre>
--   m `withoutKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`notMember`</a> s) m
--   m `withoutKeys` s = m <a>`difference`</a> <a>fromSet</a> (const ()) s
--   </pre>
withoutKeys :: Ord k => Map k a -> Set k -> Map k a

-- | <i>O(n)</i>. Partition the map according to a predicate. The first map
--   contains all elements that satisfy the predicate, the second all
--   elements that fail the predicate. See also <a>split</a>.
--   
--   <pre>
--   partition (&gt; "a") (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a")
--   partition (&lt; "x") (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty)
--   partition (&gt; "x") (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")])
--   </pre>
partition :: (a -> Bool) -> Map k a -> (Map k a, Map k a)

-- | <i>O(n)</i>. Partition the map according to a predicate. The first map
--   contains all elements that satisfy the predicate, the second all
--   elements that fail the predicate. See also <a>split</a>.
--   
--   <pre>
--   partitionWithKey (\ k _ -&gt; k &gt; 3) (fromList [(5,"a"), (3,"b")]) == (singleton 5 "a", singleton 3 "b")
--   partitionWithKey (\ k _ -&gt; k &lt; 7) (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty)
--   partitionWithKey (\ k _ -&gt; k &gt; 7) (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")])
--   </pre>
partitionWithKey :: (k -> a -> Bool) -> Map k a -> (Map k a, Map k a)

-- | <i>O(log n)</i>. Take while a predicate on the keys holds. The user is
--   responsible for ensuring that for all keys <tt>j</tt> and <tt>k</tt>
--   in the map, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See note at
--   <a>spanAntitone</a>.
--   
--   <pre>
--   takeWhileAntitone p = <a>fromDistinctAscList</a> . <a>takeWhile</a> (p . fst) . <a>toList</a>
--   takeWhileAntitone p = <a>filterWithKey</a> (k _ -&gt; p k)
--   </pre>
takeWhileAntitone :: (k -> Bool) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Drop while a predicate on the keys holds. The user is
--   responsible for ensuring that for all keys <tt>j</tt> and <tt>k</tt>
--   in the map, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See note at
--   <a>spanAntitone</a>.
--   
--   <pre>
--   dropWhileAntitone p = <a>fromDistinctAscList</a> . <a>dropWhile</a> (p . fst) . <a>toList</a>
--   dropWhileAntitone p = <a>filterWithKey</a> (k -&gt; not (p k))
--   </pre>
dropWhileAntitone :: (k -> Bool) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Divide a map at the point where a predicate on the
--   keys stops holding. The user is responsible for ensuring that for all
--   keys <tt>j</tt> and <tt>k</tt> in the map, <tt>j &lt; k ==&gt; p j
--   &gt;= p k</tt>.
--   
--   <pre>
--   spanAntitone p xs = (<a>takeWhileAntitone</a> p xs, <a>dropWhileAntitone</a> p xs)
--   spanAntitone p xs = partitionWithKey (k _ -&gt; p k) xs
--   </pre>
--   
--   Note: if <tt>p</tt> is not actually antitone, then
--   <tt>spanAntitone</tt> will split the map at some <i>unspecified</i>
--   point where the predicate switches from holding to not holding (where
--   the predicate is seen to hold before the first key and to fail after
--   the last key).
spanAntitone :: (k -> Bool) -> Map k a -> (Map k a, Map k a)

-- | <i>O(n)</i>. Map values and collect the <a>Just</a> results.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a"
--   </pre>
mapMaybe :: (a -> Maybe b) -> Map k a -> Map k b

-- | <i>O(n)</i>. Map keys/values and collect the <a>Just</a> results.
--   
--   <pre>
--   let f k _ = if k &lt; 5 then Just ("key : " ++ (show k)) else Nothing
--   mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3"
--   </pre>
mapMaybeWithKey :: (k -> a -> Maybe b) -> Map k a -> Map k b

-- | <i>O(n)</i>. Map values and separate the <a>Left</a> and <a>Right</a>
--   results.
--   
--   <pre>
--   let f a = if a &lt; "c" then Left a else Right a
--   mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
--       == (fromList [(3,"b"), (5,"a")], fromList [(1,"x"), (7,"z")])
--   
--   mapEither (\ a -&gt; Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
--       == (empty, fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
--   </pre>
mapEither :: (a -> Either b c) -> Map k a -> (Map k b, Map k c)

-- | <i>O(n)</i>. Map keys/values and separate the <a>Left</a> and
--   <a>Right</a> results.
--   
--   <pre>
--   let f k a = if k &lt; 5 then Left (k * 2) else Right (a ++ a)
--   mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
--       == (fromList [(1,2), (3,6)], fromList [(5,"aa"), (7,"zz")])
--   
--   mapEitherWithKey (\_ a -&gt; Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
--       == (empty, fromList [(1,"x"), (3,"b"), (5,"a"), (7,"z")])
--   </pre>
mapEitherWithKey :: (k -> a -> Either b c) -> Map k a -> (Map k b, Map k c)

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> k map</tt>) is a
--   pair <tt>(map1,map2)</tt> where the keys in <tt>map1</tt> are smaller
--   than <tt>k</tt> and the keys in <tt>map2</tt> larger than <tt>k</tt>.
--   Any key equal to <tt>k</tt> is found in neither <tt>map1</tt> nor
--   <tt>map2</tt>.
--   
--   <pre>
--   split 2 (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3,"b"), (5,"a")])
--   split 3 (fromList [(5,"a"), (3,"b")]) == (empty, singleton 5 "a")
--   split 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a")
--   split 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", empty)
--   split 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], empty)
--   </pre>
split :: Ord k => k -> Map k a -> (Map k a, Map k a)

-- | <i>O(log n)</i>. The expression (<tt><a>splitLookup</a> k map</tt>)
--   splits a map just like <a>split</a> but also returns <tt><a>lookup</a>
--   k map</tt>.
--   
--   <pre>
--   splitLookup 2 (fromList [(5,"a"), (3,"b")]) == (empty, Nothing, fromList [(3,"b"), (5,"a")])
--   splitLookup 3 (fromList [(5,"a"), (3,"b")]) == (empty, Just "b", singleton 5 "a")
--   splitLookup 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Nothing, singleton 5 "a")
--   splitLookup 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Just "a", empty)
--   splitLookup 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], Nothing, empty)
--   </pre>
splitLookup :: Ord k => k -> Map k a -> (Map k a, Maybe a, Map k a)

-- | <i>O(1)</i>. Decompose a map into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a map in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first submap less than all elements in the second, and so on).
--   
--   Examples:
--   
--   <pre>
--   splitRoot (fromList (zip [1..6] ['a'..])) ==
--     [fromList [(1,'a'),(2,'b'),(3,'c')],fromList [(4,'d')],fromList [(5,'e'),(6,'f')]]
--   </pre>
--   
--   <pre>
--   splitRoot empty == []
--   </pre>
--   
--   Note that the current implementation does not return more than three
--   submaps, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: Map k b -> [Map k b]

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. This function is defined as
--   (<tt><a>isSubmapOf</a> = <a>isSubmapOfBy</a> (==)</tt>).
isSubmapOf :: (Ord k, Eq a) => Map k a -> Map k a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression
--   (<tt><a>isSubmapOfBy</a> f t1 t2</tt>) returns <a>True</a> if all keys
--   in <tt>t1</tt> are in tree <tt>t2</tt>, and when <tt>f</tt> returns
--   <a>True</a> when applied to their respective values. For example, the
--   following expressions are all <a>True</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (fromList [('a',1)]) (fromList [('a',1),('b',2)])
--   isSubmapOfBy (&lt;=) (fromList [('a',1)]) (fromList [('a',1),('b',2)])
--   isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1),('b',2)])
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (fromList [('a',2)]) (fromList [('a',1),('b',2)])
--   isSubmapOfBy (&lt;)  (fromList [('a',1)]) (fromList [('a',1),('b',2)])
--   isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1)])
--   </pre>
--   
--   Note that <tt>isSubmapOfBy (_ _ -&gt; True) m1 m2</tt> tests whether
--   all the keys in <tt>m1</tt> are also keys in <tt>m2</tt>.
isSubmapOfBy :: Ord k => (a -> b -> Bool) -> Map k a -> Map k b -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). Defined as (<tt><a>isProperSubmapOf</a> =
--   <a>isProperSubmapOfBy</a> (==)</tt>).
isProperSubmapOf :: (Ord k, Eq a) => Map k a -> Map k a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). The expression (<tt><a>isProperSubmapOfBy</a> f
--   m1 m2</tt>) returns <a>True</a> when <tt>keys m1</tt> and <tt>keys
--   m2</tt> are not equal, all keys in <tt>m1</tt> are in <tt>m2</tt>, and
--   when <tt>f</tt> returns <a>True</a> when applied to their respective
--   values. For example, the following expressions are all <a>True</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
--   isProperSubmapOfBy (&lt;=) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
--   isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
--   isProperSubmapOfBy (&lt;)  (fromList [(1,1)])       (fromList [(1,1),(2,2)])
--   </pre>
isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> Map k a -> Map k b -> Bool

-- | <i>O(log n)</i>. Lookup the <i>index</i> of a key, which is its
--   zero-based index in the sequence sorted by keys. The index is a number
--   from <i>0</i> up to, but not including, the <a>size</a> of the map.
--   
--   <pre>
--   isJust (lookupIndex 2 (fromList [(5,"a"), (3,"b")]))   == False
--   fromJust (lookupIndex 3 (fromList [(5,"a"), (3,"b")])) == 0
--   fromJust (lookupIndex 5 (fromList [(5,"a"), (3,"b")])) == 1
--   isJust (lookupIndex 6 (fromList [(5,"a"), (3,"b")]))   == False
--   </pre>
lookupIndex :: Ord k => k -> Map k a -> Maybe Int

-- | <i>O(log n)</i>. Retrieve an element by its <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   <pre>
--   elemAt 0 (fromList [(5,"a"), (3,"b")]) == (3,"b")
--   elemAt 1 (fromList [(5,"a"), (3,"b")]) == (5, "a")
--   elemAt 2 (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   </pre>
elemAt :: Int -> Map k a -> (k, a)

-- | <i>O(log n)</i>. Delete the element at <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   <pre>
--   deleteAt 0  (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   deleteAt 1  (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   deleteAt 2 (fromList [(5,"a"), (3,"b")])     Error: index out of range
--   deleteAt (-1) (fromList [(5,"a"), (3,"b")])  Error: index out of range
--   </pre>
deleteAt :: Int -> Map k a -> Map k a

-- | Take a given number of entries in key order, beginning with the
--   smallest keys.
--   
--   <pre>
--   take n = <a>fromDistinctAscList</a> . <a>take</a> n . <a>toAscList</a>
--   </pre>
take :: Int -> Map k a -> Map k a

-- | Drop a given number of entries in key order, beginning with the
--   smallest keys.
--   
--   <pre>
--   drop n = <a>fromDistinctAscList</a> . <a>drop</a> n . <a>toAscList</a>
--   </pre>
drop :: Int -> Map k a -> Map k a

-- | <i>O(log n)</i>. Split a map at a particular index.
--   
--   <pre>
--   splitAt !n !xs = (<a>take</a> n xs, <a>drop</a> n xs)
--   </pre>
splitAt :: Int -> Map k a -> (Map k a, Map k a)

-- | <i>O(log n)</i>. The minimal key of the map. Returns <a>Nothing</a> if
--   the map is empty.
--   
--   <pre>
--   lookupMin (fromList [(5,"a"), (3,"b")]) == Just (3,"b")
--   lookupMin empty = Nothing
--   </pre>
lookupMin :: Map k a -> Maybe (k, a)

-- | <i>O(log n)</i>. The maximal key of the map. Returns <a>Nothing</a> if
--   the map is empty.
--   
--   <pre>
--   lookupMax (fromList [(5,"a"), (3,"b")]) == Just (5,"a")
--   lookupMax empty = Nothing
--   </pre>
lookupMax :: Map k a -> Maybe (k, a)

-- | <i>O(log n)</i>. Delete the minimal key. Returns an empty map if the
--   map is empty.
--   
--   <pre>
--   deleteMin (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(5,"a"), (7,"c")]
--   deleteMin empty == empty
--   </pre>
deleteMin :: Map k a -> Map k a

-- | <i>O(log n)</i>. Delete the maximal key. Returns an empty map if the
--   map is empty.
--   
--   <pre>
--   deleteMax (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(3,"b"), (5,"a")]
--   deleteMax empty == empty
--   </pre>
deleteMax :: Map k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the minimal key.
--   
--   <pre>
--   updateMin (\ a -&gt; Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")]
--   updateMin (\ _ -&gt; Nothing)         (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   </pre>
updateMin :: (a -> Maybe a) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the maximal key.
--   
--   <pre>
--   updateMax (\ a -&gt; Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")]
--   updateMax (\ _ -&gt; Nothing)         (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   </pre>
updateMax :: (a -> Maybe a) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the minimal key.
--   
--   <pre>
--   updateMinWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")]
--   updateMinWithKey (\ _ _ -&gt; Nothing)                     (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   </pre>
updateMinWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the maximal key.
--   
--   <pre>
--   updateMaxWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")]
--   updateMaxWithKey (\ _ _ -&gt; Nothing)                     (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   </pre>
updateMaxWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a

-- | <i>O(log n)</i>. Retrieves the value associated with minimal key of
--   the map, and the map stripped of that element, or <a>Nothing</a> if
--   passed an empty map.
--   
--   <pre>
--   minView (fromList [(5,"a"), (3,"b")]) == Just ("b", singleton 5 "a")
--   minView empty == Nothing
--   </pre>
minView :: Map k a -> Maybe (a, Map k a)

-- | <i>O(log n)</i>. Retrieves the value associated with maximal key of
--   the map, and the map stripped of that element, or <a>Nothing</a> if
--   passed an empty map.
--   
--   <pre>
--   maxView (fromList [(5,"a"), (3,"b")]) == Just ("a", singleton 3 "b")
--   maxView empty == Nothing
--   </pre>
maxView :: Map k a -> Maybe (a, Map k a)

-- | <i>O(log n)</i>. Retrieves the minimal (key,value) pair of the map,
--   and the map stripped of that element, or <a>Nothing</a> if passed an
--   empty map.
--   
--   <pre>
--   minViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((3,"b"), singleton 5 "a")
--   minViewWithKey empty == Nothing
--   </pre>
minViewWithKey :: Map k a -> Maybe ((k, a), Map k a)

-- | <i>O(log n)</i>. Retrieves the maximal (key,value) pair of the map,
--   and the map stripped of that element, or <a>Nothing</a> if passed an
--   empty map.
--   
--   <pre>
--   maxViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((5,"a"), singleton 3 "b")
--   maxViewWithKey empty == Nothing
--   </pre>
maxViewWithKey :: Map k a -> Maybe ((k, a), Map k a)

-- | This function has moved to <a>showTree</a>.
showTree :: Whoops "showTree has moved to Data.Map.Internal.Debug.showTree." => Map k a -> String

-- | This function has moved to <a>showTreeWith</a>.
showTreeWith :: Whoops "showTreeWith has moved to Data.Map.Internal.Debug.showTreeWith." => (k -> a -> String) -> Bool -> Bool -> Map k a -> String

-- | <i>O(n)</i>. Test if the internal map structure is valid.
--   
--   <pre>
--   valid (fromAscList [(3,"b"), (5,"a")]) == True
--   valid (fromAscList [(5,"a"), (3,"b")]) == False
--   </pre>
valid :: Ord k => Map k a -> Bool


-- | Strict <tt>Map</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Map.Partial as Map'
--   </pre>
module RIO.Map.Partial

-- | <i>O(log n)</i>. Find the value at a key. Calls <a>error</a> when the
--   element can not be found.
--   
--   <pre>
--   fromList [(5,'a'), (3,'b')] ! 1    Error: element not in the map
--   fromList [(5,'a'), (3,'b')] ! 5 == 'a'
--   </pre>
(!) :: Ord k => Map k a -> k -> a
infixl 9 !

-- | <i>O(log n)</i>. Retrieve an element by its <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   <pre>
--   elemAt 0 (fromList [(5,"a"), (3,"b")]) == (3,"b")
--   elemAt 1 (fromList [(5,"a"), (3,"b")]) == (5, "a")
--   elemAt 2 (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   </pre>
elemAt :: Int -> Map k a -> (k, a)

-- | <i>O(log n)</i>. Delete the element at <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   <pre>
--   deleteAt 0  (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   deleteAt 1  (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   deleteAt 2 (fromList [(5,"a"), (3,"b")])     Error: index out of range
--   deleteAt (-1) (fromList [(5,"a"), (3,"b")])  Error: index out of range
--   </pre>
deleteAt :: Int -> Map k a -> Map k a

-- | <i>O(log n)</i>. Return the <i>index</i> of a key, which is its
--   zero-based index in the sequence sorted by keys. The index is a number
--   from <i>0</i> up to, but not including, the <a>size</a> of the map.
--   Calls <a>error</a> when the key is not a <a>member</a> of the map.
--   
--   <pre>
--   findIndex 2 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map
--   findIndex 3 (fromList [(5,"a"), (3,"b")]) == 0
--   findIndex 5 (fromList [(5,"a"), (3,"b")]) == 1
--   findIndex 6 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map
--   </pre>
findIndex :: Ord k => k -> Map k a -> Int

-- | <i>O(log n)</i>. Update the element at <i>index</i>. Calls
--   <a>error</a> when an invalid index is used.
--   
--   <pre>
--   updateAt (\ _ _ -&gt; Just "x") 0    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")]
--   updateAt (\ _ _ -&gt; Just "x") 1    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "x")]
--   updateAt (\ _ _ -&gt; Just "x") 2    (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   updateAt (\ _ _ -&gt; Just "x") (-1) (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   updateAt (\_ _  -&gt; Nothing)  0    (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
--   updateAt (\_ _  -&gt; Nothing)  1    (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
--   updateAt (\_ _  -&gt; Nothing)  2    (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   updateAt (\_ _  -&gt; Nothing)  (-1) (fromList [(5,"a"), (3,"b")])    Error: index out of range
--   </pre>
updateAt :: (k -> a -> Maybe a) -> Int -> Map k a -> Map k a

-- | <i>O(log n)</i>. The minimal key of the map. Calls <a>error</a> if the
--   map is empty.
--   
--   <pre>
--   findMin (fromList [(5,"a"), (3,"b")]) == (3,"b")
--   findMin empty                            Error: empty map has no minimal element
--   </pre>
findMin :: Map k a -> (k, a)
findMax :: Map k a -> (k, a)

-- | <i>O(log n)</i>. Delete and find the minimal element.
--   
--   <pre>
--   deleteFindMin (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((3,"b"), fromList[(5,"a"), (10,"c")])
--   deleteFindMin empty                                      Error: can not return the minimal element of an empty map
--   </pre>
deleteFindMin :: Map k a -> ((k, a), Map k a)

-- | <i>O(log n)</i>. Delete and find the maximal element.
--   
--   <pre>
--   deleteFindMax (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((10,"c"), fromList [(3,"b"), (5,"a")])
--   deleteFindMax empty                                      Error: can not return the maximal element of an empty map
--   </pre>
deleteFindMax :: Map k a -> ((k, a), Map k a)


-- | This module contains functions from <a>Data.Map.Strict</a> that have
--   unchecked preconditions on their input. If these preconditions are not
--   satisfied, the data structure may end up in an invalid state and other
--   operations may misbehave. Import as:
--   
--   <pre>
--   import qualified RIO.Map.Unchecked as Map'
--   </pre>
module RIO.Map.Unchecked

-- | <i>O(n)</i>. <tt><a>mapKeysMonotonic</a> f s == <a>mapKeys</a> f
--   s</tt>, but works only when <tt>f</tt> is strictly monotonic. That is,
--   for any values <tt>x</tt> and <tt>y</tt>, if <tt>x</tt> &lt;
--   <tt>y</tt> then <tt>f x</tt> &lt; <tt>f y</tt>. <i>The precondition is
--   not checked.</i> Semi-formally, we have:
--   
--   <pre>
--   and [x &lt; y ==&gt; f x &lt; f y | x &lt;- ls, y &lt;- ls]
--                       ==&gt; mapKeysMonotonic f s == mapKeys f s
--       where ls = keys s
--   </pre>
--   
--   This means that <tt>f</tt> maps distinct original keys to distinct
--   resulting keys. This function has better performance than
--   <a>mapKeys</a>.
--   
--   <pre>
--   mapKeysMonotonic (\ k -&gt; k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
--   valid (mapKeysMonotonic (\ k -&gt; k * 2) (fromList [(5,"a"), (3,"b")])) == True
--   valid (mapKeysMonotonic (\ _ -&gt; 1)     (fromList [(5,"a"), (3,"b")])) == False
--   </pre>
mapKeysMonotonic :: (k1 -> k2) -> Map k1 a -> Map k2 a

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in ascending order. Subject to list fusion.
--   
--   <pre>
--   toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")]
--   </pre>
toAscList :: Map k a -> [(k, a)]

-- | <i>O(n)</i>. Build a map from an ascending list in linear time. <i>The
--   precondition (input list is ascending) is not checked.</i>
--   
--   <pre>
--   fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
--   fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
--   valid (fromAscList [(3,"b"), (5,"a"), (5,"b")]) == True
--   valid (fromAscList [(5,"a"), (3,"b"), (5,"b")]) == False
--   </pre>
fromAscList :: Eq k => [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from an ascending list in linear time with a
--   combining function for equal keys. <i>The precondition (input list is
--   ascending) is not checked.</i>
--   
--   <pre>
--   fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
--   valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
--   valid (fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False
--   </pre>
fromAscListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from an ascending list in linear time with a
--   combining function for equal keys. <i>The precondition (input list is
--   ascending) is not checked.</i>
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
--   fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
--   valid (fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")]) == True
--   valid (fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]) == False
--   </pre>
fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from an ascending list of distinct elements
--   in linear time. <i>The precondition is not checked.</i>
--   
--   <pre>
--   fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
--   valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
--   valid (fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")]) == False
--   </pre>
fromDistinctAscList :: [(k, a)] -> Map k a

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in descending order. Subject to list fusion.
--   
--   <pre>
--   toDescList (fromList [(5,"a"), (3,"b")]) == [(5,"a"), (3,"b")]
--   </pre>
toDescList :: Map k a -> [(k, a)]

-- | <i>O(n)</i>. Build a map from a descending list in linear time. <i>The
--   precondition (input list is descending) is not checked.</i>
--   
--   <pre>
--   fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
--   fromDescList [(5,"a"), (5,"b"), (3,"a")] == fromList [(3, "b"), (5, "b")]
--   valid (fromDescList [(5,"a"), (5,"b"), (3,"b")]) == True
--   valid (fromDescList [(5,"a"), (3,"b"), (5,"b")]) == False
--   </pre>
fromDescList :: Eq k => [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from a descending list in linear time with a
--   combining function for equal keys. <i>The precondition (input list is
--   descending) is not checked.</i>
--   
--   <pre>
--   fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
--   valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
--   valid (fromDescListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False
--   </pre>
fromDescListWith :: Eq k => (a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from a descending list in linear time with a
--   combining function for equal keys. <i>The precondition (input list is
--   descending) is not checked.</i>
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
--   fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
--   valid (fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")]) == True
--   valid (fromDescListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]) == False
--   </pre>
fromDescListWithKey :: Eq k => (k -> a -> a -> a) -> [(k, a)] -> Map k a

-- | <i>O(n)</i>. Build a map from a descending list of distinct elements
--   in linear time. <i>The precondition is not checked.</i>
--   
--   <pre>
--   fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
--   valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True
--   valid (fromDistinctDescList [(5,"a"), (3,"b"), (3,"a")]) == False
--   </pre>
fromDistinctDescList :: [(k, a)] -> Map k a


-- | <tt>NonEmpty</tt> list. Import as:
--   
--   <pre>
--   import qualified RIO.NonEmpty as NE
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.NonEmpty.Partial</a>
module RIO.NonEmpty

-- | Non-empty (and non-strict) list type.
data NonEmpty a
(:|) :: a -> [a] -> NonEmpty a
infixr 5 :|

-- | Map a function over a <a>NonEmpty</a> stream.
map :: (a -> b) -> NonEmpty a -> NonEmpty b

-- | 'intersperse x xs' alternates elements of the list with copies of
--   <tt>x</tt>.
--   
--   <pre>
--   intersperse 0 (1 :| [2,3]) == 1 :| [0,2,0,3]
--   </pre>
intersperse :: a -> NonEmpty a -> NonEmpty a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a stream of
--   successive reduced values from the left:
--   
--   <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 :: Foldable f => (b -> a -> b) -> b -> f a -> NonEmpty b

-- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>. Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs.
--   </pre>
scanr :: Foldable f => (a -> b -> b) -> b -> f a -> NonEmpty b

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == x1 :| [x1 `f` x2, x1 `f` (x2 `f` x3), ...]
--   </pre>
scanl1 :: (a -> a -> a) -> NonEmpty a -> NonEmpty a

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (a -> a -> a) -> NonEmpty a -> NonEmpty a

-- | <a>transpose</a> for <a>NonEmpty</a>, behaves the same as
--   <a>transpose</a> The rows/columns need not be the same length, in
--   which case &gt; transpose . transpose /= id
transpose :: NonEmpty (NonEmpty a) -> NonEmpty (NonEmpty a)

-- | <a>sortBy</a> for <a>NonEmpty</a>, behaves the same as <a>sortBy</a>
sortBy :: (a -> a -> Ordering) -> NonEmpty a -> NonEmpty a

-- | <a>sortWith</a> for <a>NonEmpty</a>, behaves the same as:
--   
--   <pre>
--   sortBy . comparing
--   </pre>
sortWith :: Ord o => (a -> o) -> NonEmpty a -> NonEmpty a

-- | Number of elements in <a>NonEmpty</a> list.
length :: NonEmpty a -> Int

-- | Extract the first element of the stream.
head :: NonEmpty a -> a

-- | Extract the possibly-empty tail of the stream.
tail :: NonEmpty a -> [a]

-- | Extract the last element of the stream.
last :: NonEmpty a -> a

-- | Extract everything except the last element of the stream.
init :: NonEmpty a -> [a]

-- | Prepend an element to the stream.
(<|) :: a -> NonEmpty a -> NonEmpty a
infixr 5 <|

-- | Synonym for <a>&lt;|</a>.
cons :: a -> NonEmpty a -> NonEmpty a

-- | <a>uncons</a> produces the first element of the stream, and a stream
--   of the remaining elements, if any.
uncons :: NonEmpty a -> (a, Maybe (NonEmpty a))

-- | The <a>unfoldr</a> function is analogous to <a>Data.List</a>'s
--   <a>unfoldr</a> operation.
unfoldr :: (a -> (b, Maybe a)) -> a -> NonEmpty b

-- | Sort a stream.
sort :: Ord a => NonEmpty a -> NonEmpty a

-- | <a>reverse</a> a finite NonEmpty stream.
reverse :: NonEmpty a -> NonEmpty a

-- | The <a>inits</a> function takes a stream <tt>xs</tt> and returns all
--   the finite prefixes of <tt>xs</tt>.
inits :: Foldable f => f a -> NonEmpty [a]

-- | The <a>tails</a> function takes a stream <tt>xs</tt> and returns all
--   the suffixes of <tt>xs</tt>.
tails :: Foldable f => f a -> NonEmpty [a]

-- | <tt><a>iterate</a> f x</tt> produces the infinite sequence of repeated
--   applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   iterate f x = x :| [f x, f (f x), ..]
--   </pre>
iterate :: (a -> a) -> a -> NonEmpty a

-- | <tt><a>repeat</a> x</tt> returns a constant stream, where all elements
--   are equal to <tt>x</tt>.
repeat :: a -> NonEmpty a

-- | <tt><a>cycle</a> xs</tt> returns the infinite repetition of
--   <tt>xs</tt>:
--   
--   <pre>
--   cycle (1 :| [2,3]) = 1 :| [2,3,1,2,3,...]
--   </pre>
cycle :: NonEmpty a -> NonEmpty a

-- | <tt><a>insert</a> x xs</tt> inserts <tt>x</tt> into the last position
--   in <tt>xs</tt> where it is still less than or equal to the next
--   element. In particular, if the list is sorted beforehand, the result
--   will also be sorted.
insert :: (Foldable f, Ord a) => a -> f a -> NonEmpty a

-- | <tt><a>some1</a> x</tt> sequences <tt>x</tt> one or more times.
some1 :: Alternative f => f a -> f (NonEmpty a)

-- | <tt><a>take</a> n xs</tt> returns the first <tt>n</tt> elements of
--   <tt>xs</tt>.
take :: Int -> NonEmpty a -> [a]

-- | <tt><a>drop</a> n xs</tt> drops the first <tt>n</tt> elements off the
--   front of the sequence <tt>xs</tt>.
drop :: Int -> NonEmpty a -> [a]

-- | <tt><a>splitAt</a> n xs</tt> returns a pair consisting of the prefix
--   of <tt>xs</tt> of length <tt>n</tt> and the remaining stream
--   immediately following this prefix.
--   
--   <pre>
--   'splitAt' n xs == ('take' n xs, 'drop' n xs)
--   xs == ys ++ zs where (ys, zs) = 'splitAt' n xs
--   </pre>
splitAt :: Int -> NonEmpty a -> ([a], [a])

-- | <tt><a>takeWhile</a> p xs</tt> returns the longest prefix of the
--   stream <tt>xs</tt> for which the predicate <tt>p</tt> holds.
takeWhile :: (a -> Bool) -> NonEmpty a -> [a]

-- | <tt><a>dropWhile</a> p xs</tt> returns the suffix remaining after
--   <tt><a>takeWhile</a> p xs</tt>.
dropWhile :: (a -> Bool) -> NonEmpty a -> [a]

-- | <tt><a>span</a> p xs</tt> returns the longest prefix of <tt>xs</tt>
--   that satisfies <tt>p</tt>, together with the remainder of the stream.
--   
--   <pre>
--   'span' p xs == ('takeWhile' p xs, 'dropWhile' p xs)
--   xs == ys ++ zs where (ys, zs) = 'span' p xs
--   </pre>
span :: (a -> Bool) -> NonEmpty a -> ([a], [a])

-- | The <tt><a>break</a> p</tt> function is equivalent to <tt><a>span</a>
--   (not . p)</tt>.
break :: (a -> Bool) -> NonEmpty a -> ([a], [a])

-- | <tt><a>filter</a> p xs</tt> removes any elements from <tt>xs</tt> that
--   do not satisfy <tt>p</tt>.
filter :: (a -> Bool) -> NonEmpty a -> [a]

-- | The <a>partition</a> function takes a predicate <tt>p</tt> and a
--   stream <tt>xs</tt>, and returns a pair of lists. The first list
--   corresponds to the elements of <tt>xs</tt> for which <tt>p</tt> holds;
--   the second corresponds to the elements of <tt>xs</tt> for which
--   <tt>p</tt> does not hold.
--   
--   <pre>
--   'partition' p xs = ('filter' p xs, 'filter' (not . p) xs)
--   </pre>
partition :: (a -> Bool) -> NonEmpty a -> ([a], [a])

-- | The <a>group</a> function takes a stream and returns a list of streams
--   such that flattening the resulting list is equal to the argument.
--   Moreover, each stream in the resulting list contains only equal
--   elements. For example, in list notation:
--   
--   <pre>
--   'group' $ 'cycle' "Mississippi"
--     = "M" : "i" : "ss" : "i" : "ss" : "i" : "pp" : "i" : "M" : "i" : ...
--   </pre>
group :: (Foldable f, Eq a) => f a -> [NonEmpty a]

-- | <a>groupBy</a> operates like <a>group</a>, but uses the provided
--   equality predicate instead of <a>==</a>.
groupBy :: Foldable f => (a -> a -> Bool) -> f a -> [NonEmpty a]

-- | <a>groupWith</a> operates like <a>group</a>, but uses the provided
--   projection when comparing for equality
groupWith :: (Foldable f, Eq b) => (a -> b) -> f a -> [NonEmpty a]

-- | <a>groupAllWith</a> operates like <a>groupWith</a>, but sorts the list
--   first so that each equivalence class has, at most, one list in the
--   output
groupAllWith :: Ord b => (a -> b) -> [a] -> [NonEmpty a]

-- | <a>group1</a> operates like <a>group</a>, but uses the knowledge that
--   its input is non-empty to produce guaranteed non-empty output.
group1 :: Eq a => NonEmpty a -> NonEmpty (NonEmpty a)

-- | <a>groupBy1</a> is to <a>group1</a> as <a>groupBy</a> is to
--   <a>group</a>.
groupBy1 :: (a -> a -> Bool) -> NonEmpty a -> NonEmpty (NonEmpty a)

-- | <a>groupWith1</a> is to <a>group1</a> as <a>groupWith</a> is to
--   <a>group</a>
groupWith1 :: Eq b => (a -> b) -> NonEmpty a -> NonEmpty (NonEmpty a)

-- | <a>groupAllWith1</a> is to <a>groupWith1</a> as <a>groupAllWith</a> is
--   to <a>groupWith</a>
groupAllWith1 :: Ord b => (a -> b) -> NonEmpty a -> NonEmpty (NonEmpty a)

-- | The <a>isPrefixOf</a> function returns <a>True</a> if the first
--   argument is a prefix of the second.
isPrefixOf :: Eq a => [a] -> NonEmpty a -> Bool

-- | The <a>nub</a> function removes duplicate elements from a list. In
--   particular, it keeps only the first occurrence of each element. (The
--   name <a>nub</a> means 'essence'.) It is a special case of
--   <a>nubBy</a>, which allows the programmer to supply their own
--   inequality test.
nub :: Eq a => NonEmpty a -> NonEmpty a

-- | The <a>nubBy</a> function behaves just like <a>nub</a>, except it uses
--   a user-supplied equality predicate instead of the overloaded <a>==</a>
--   function.
nubBy :: (a -> a -> Bool) -> NonEmpty a -> NonEmpty a

-- | The <a>zip</a> function takes two streams and returns a stream of
--   corresponding pairs.
zip :: NonEmpty a -> NonEmpty b -> NonEmpty (a, b)

-- | The <a>zipWith</a> function generalizes <a>zip</a>. Rather than
--   tupling the elements, the elements are combined using the function
--   passed as the first argument.
zipWith :: (a -> b -> c) -> NonEmpty a -> NonEmpty b -> NonEmpty c

-- | The <a>unzip</a> function is the inverse of the <a>zip</a> function.
unzip :: Functor f => f (a, b) -> (f a, f b)

-- | <a>nonEmpty</a> efficiently turns a normal list into a <a>NonEmpty</a>
--   stream, producing <a>Nothing</a> if the input is empty.
nonEmpty :: [a] -> Maybe (NonEmpty a)

-- | Convert a stream to a normal list efficiently.
toList :: NonEmpty a -> [a]

-- | Compute n-ary logic exclusive OR operation on <a>NonEmpty</a> list.
xor :: NonEmpty Bool -> Bool


-- | <tt>NonEmpty</tt> list partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.NonEmpty.Partial as NE'
--   </pre>
module RIO.NonEmpty.Partial

-- | <tt>xs !! n</tt> returns the element of the stream <tt>xs</tt> at
--   index <tt>n</tt>. Note that the head of the stream has index 0.
--   
--   <i>Beware</i>: a negative or out-of-bounds index will cause an error.
(!!) :: NonEmpty a -> Int -> a
infixl 9 !!

-- | Converts a normal list to a <a>NonEmpty</a> stream.
--   
--   Raises an error if given an empty list.
fromList :: [a] -> NonEmpty a


-- | Partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Partial as RIO'
--   </pre>
module RIO.Partial

-- | The <a>fromJust</a> function extracts the element out of a <a>Just</a>
--   and throws an error if its argument is <a>Nothing</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromJust (Just 1)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 2 * (fromJust (Just 10))
--   20
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 2 * (fromJust Nothing)
--   *** Exception: Maybe.fromJust: Nothing
--   </pre>
fromJust :: HasCallStack => Maybe a -> a

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

module RIO.Prelude.Types
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <a>ord</a> and
--   <a>chr</a>).
data Char

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
--   
--   See <a>Data.List</a> for operations on lists.
type String = [Char]

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | 8-bit signed integer type
data Int8

-- | 16-bit signed integer type
data Int16

-- | 32-bit signed integer type
data Int32

-- | 64-bit signed integer type
data Int64

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | 8-bit unsigned integer type
data Word8

-- | 16-bit unsigned integer type
data Word16

-- | 32-bit unsigned integer type
data Word32

-- | 64-bit unsigned integer type
data Word64

-- | Arbitrary precision integers. In contrast with fixed-size integral
--   types such as <a>Int</a>, the <a>Integer</a> type represents the
--   entire infinite range of integers.
--   
--   For more information about this type's representation, see the
--   comments in its implementation.
data Integer

-- | Type representing arbitrary-precision non-negative integers.
--   
--   <pre>
--   &gt;&gt;&gt; 2^100 :: Natural
--   1267650600228229401496703205376
--   </pre>
--   
--   Operations whose result would be negative <tt><a>throw</a>
--   (<a>Underflow</a> :: <a>ArithException</a>)</tt>,
--   
--   <pre>
--   &gt;&gt;&gt; -1 :: Natural
--   *** Exception: arithmetic underflow
--   </pre>
data Natural

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | Non-empty (and non-strict) list type.
data NonEmpty a
(:|) :: a -> [a] -> NonEmpty a
infixr 5 :|

-- | <a>Proxy</a> is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, <tt><a>Proxy</a> :: <a>Proxy</a> a</tt> is a safer
--   alternative to the <tt><a>undefined</a> :: a</tt> idiom.
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy (Void, Int -&gt; Int)
--   Proxy
--   </pre>
--   
--   Proxy can even hold types of higher kinds,
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Either
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Functor
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy complicatedStructure
--   Proxy
--   </pre>
data Proxy (t :: k)
Proxy :: Proxy (t :: k)

-- | Uninhabited data type
data Void

-- | The <a>Const</a> functor.
newtype Const a (b :: k)
Const :: a -> Const a (b :: k)
[getConst] :: Const a (b :: k) -> a

-- | Identity functor and monad. (a non-strict monad)
newtype Identity a
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <a>&gt;&gt;</a> and <a>&gt;&gt;=</a>
--   operations from the <a>Monad</a> class.
data IO a

-- | The strict <a>ST</a> monad. The <a>ST</a> monad allows for destructive
--   updates, but is escapable (unlike IO). A computation of type
--   <tt><a>ST</a> s a</tt> returns a value of type <tt>a</tt>, and execute
--   in "thread" <tt>s</tt>. The <tt>s</tt> parameter is either
--   
--   <ul>
--   <li>an uninstantiated type variable (inside invocations of
--   <a>runST</a>), or</li>
--   <li><a>RealWorld</a> (inside invocations of <a>stToIO</a>).</li>
--   </ul>
--   
--   It serves to keep the internal states of different invocations of
--   <a>runST</a> separate from each other and from invocations of
--   <a>stToIO</a>.
--   
--   The <a>&gt;&gt;=</a> and <a>&gt;&gt;</a> operations are strict in the
--   state (though not in values stored in the state). For example,
--   
--   <pre>
--   <a>runST</a> (writeSTRef _|_ v &gt;&gt;= f) = _|_
--   </pre>
data ST s a

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   The Haskell Report defines no laws for <a>Eq</a>. However, <a>==</a>
--   is customarily expected to implement an equivalence relationship where
--   two values comparing equal are indistinguishable by "public"
--   functions, with a "public" function being one not allowing to see
--   implementation details. For example, for a type representing
--   non-normalised natural numbers modulo 100, a "public" function doesn't
--   make the difference between 1 and 201. It is expected to have the
--   following properties:
--   
--   <ul>
--   <li><i><b>Reflexivity</b></i> <tt>x == x</tt> = <a>True</a></li>
--   <li><i><b>Symmetry</b></i> <tt>x == y</tt> = <tt>y == x</tt></li>
--   <li><i><b>Transitivity</b></i> if <tt>x == y &amp;&amp; y == z</tt> =
--   <a>True</a>, then <tt>x == z</tt> = <a>True</a></li>
--   <li><i><b>Substitutivity</b></i> if <tt>x == y</tt> = <a>True</a> and
--   <tt>f</tt> is a "public" function whose return type is an instance of
--   <a>Eq</a>, then <tt>f x == f y</tt> = <a>True</a></li>
--   <li><i><b>Negation</b></i> <tt>x /= y</tt> = <tt>not (x ==
--   y)</tt></li>
--   </ul>
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   The Haskell Report defines no laws for <a>Ord</a>. However,
--   <a>&lt;=</a> is customarily expected to implement a non-strict partial
--   order and have the following properties:
--   
--   <ul>
--   <li><i><b>Transitivity</b></i> if <tt>x &lt;= y &amp;&amp; y &lt;=
--   z</tt> = <a>True</a>, then <tt>x &lt;= z</tt> = <a>True</a></li>
--   <li><i><b>Reflexivity</b></i> <tt>x &lt;= x</tt> = <a>True</a></li>
--   <li><i><b>Antisymmetry</b></i> if <tt>x &lt;= y &amp;&amp; y &lt;=
--   x</tt> = <a>True</a>, then <tt>x == y</tt> = <a>True</a></li>
--   </ul>
--   
--   Note that the following operator interactions are expected to hold:
--   
--   <ol>
--   <li><tt>x &gt;= y</tt> = <tt>y &lt;= x</tt></li>
--   <li><tt>x &lt; y</tt> = <tt>x &lt;= y &amp;&amp; x /= y</tt></li>
--   <li><tt>x &gt; y</tt> = <tt>y &lt; x</tt></li>
--   <li><tt>x &lt; y</tt> = <tt>compare x y == LT</tt></li>
--   <li><tt>x &gt; y</tt> = <tt>compare x y == GT</tt></li>
--   <li><tt>x == y</tt> = <tt>compare x y == EQ</tt></li>
--   <li><tt>min x y == if x &lt;= y then x else y</tt> = <a>True</a></li>
--   <li><tt>max x y == if x &gt;= y then x else y</tt> = <a>True</a></li>
--   </ol>
--   
--   Note that (7.) and (8.) do <i>not</i> require <a>min</a> and
--   <a>max</a> to return either of their arguments. The result is merely
--   required to <i>equal</i> one of the arguments in terms of <a>(==)</a>.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | Class for string-like datastructures; used by the overloaded string
--   extension (-XOverloadedStrings in GHC).
class IsString a

-- | Basic numeric class.
--   
--   The Haskell Report defines no laws for <a>Num</a>. However,
--   <tt>(<a>+</a>)</tt> and <tt>(<a>*</a>)</tt> are customarily expected
--   to define a ring and have the following properties:
--   
--   <ul>
--   <li><i><b>Associativity of <tt>(<a>+</a>)</tt></b></i> <tt>(x + y) +
--   z</tt> = <tt>x + (y + z)</tt></li>
--   <li><i><b>Commutativity of <tt>(<a>+</a>)</tt></b></i> <tt>x + y</tt>
--   = <tt>y + x</tt></li>
--   <li><i><b><tt><a>fromInteger</a> 0</tt> is the additive
--   identity</b></i> <tt>x + fromInteger 0</tt> = <tt>x</tt></li>
--   <li><i><b><a>negate</a> gives the additive inverse</b></i> <tt>x +
--   negate x</tt> = <tt>fromInteger 0</tt></li>
--   <li><i><b>Associativity of <tt>(<a>*</a>)</tt></b></i> <tt>(x * y) *
--   z</tt> = <tt>x * (y * z)</tt></li>
--   <li><i><b><tt><a>fromInteger</a> 1</tt> is the multiplicative
--   identity</b></i> <tt>x * fromInteger 1</tt> = <tt>x</tt> and
--   <tt>fromInteger 1 * x</tt> = <tt>x</tt></li>
--   <li><i><b>Distributivity of <tt>(<a>*</a>)</tt> with respect to
--   <tt>(<a>+</a>)</tt></b></i> <tt>a * (b + c)</tt> = <tt>(a * b) + (a *
--   c)</tt> and <tt>(b + c) * a</tt> = <tt>(b * a) + (c * a)</tt></li>
--   </ul>
--   
--   Note that it <i>isn't</i> customarily expected that a type instance of
--   both <a>Num</a> and <a>Ord</a> implement an ordered ring. Indeed, in
--   <tt>base</tt> only <a>Integer</a> and <a>Rational</a> do.
class Num a

-- | Fractional numbers, supporting real division.
--   
--   The Haskell Report defines no laws for <a>Fractional</a>. However,
--   <tt>(<a>+</a>)</tt> and <tt>(<a>*</a>)</tt> are customarily expected
--   to define a division ring and have the following properties:
--   
--   <ul>
--   <li><i><b><a>recip</a> gives the multiplicative inverse</b></i> <tt>x
--   * recip x</tt> = <tt>recip x * x</tt> = <tt>fromInteger 1</tt></li>
--   </ul>
--   
--   Note that it <i>isn't</i> customarily expected that a type instance of
--   <a>Fractional</a> implement a field. However, all instances in
--   <tt>base</tt> do.
class Num a => Fractional a

-- | Trigonometric and hyperbolic functions and related functions.
--   
--   The Haskell Report defines no laws for <a>Floating</a>. However,
--   <tt>(<a>+</a>)</tt>, <tt>(<a>*</a>)</tt> and <a>exp</a> are
--   customarily expected to define an exponential field and have the
--   following properties:
--   
--   <ul>
--   <li><tt>exp (a + b)</tt> = <tt>exp a * exp b</tt></li>
--   <li><tt>exp (fromInteger 0)</tt> = <tt>fromInteger 1</tt></li>
--   </ul>
class Fractional a => Floating a
class (Num a, Ord a) => Real a

-- | Integral numbers, supporting integer division.
--   
--   The Haskell Report defines no laws for <a>Integral</a>. However,
--   <a>Integral</a> instances are customarily expected to define a
--   Euclidean domain and have the following properties for the
--   <a>div</a>/<a>mod</a> and <a>quot</a>/<a>rem</a> pairs, given suitable
--   Euclidean functions <tt>f</tt> and <tt>g</tt>:
--   
--   <ul>
--   <li><tt>x</tt> = <tt>y * quot x y + rem x y</tt> with <tt>rem x y</tt>
--   = <tt>fromInteger 0</tt> or <tt>g (rem x y)</tt> &lt; <tt>g
--   y</tt></li>
--   <li><tt>x</tt> = <tt>y * div x y + mod x y</tt> with <tt>mod x y</tt>
--   = <tt>fromInteger 0</tt> or <tt>f (mod x y)</tt> &lt; <tt>f
--   y</tt></li>
--   </ul>
--   
--   An example of a suitable Euclidean function, for <a>Integer</a>'s
--   instance, is <a>abs</a>.
class (Real a, Enum a) => Integral a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | A type <tt>f</tt> is a Functor if it provides a function <tt>fmap</tt>
--   which, given any types <tt>a</tt> and <tt>b</tt> lets you apply any
--   function from <tt>(a -&gt; b)</tt> to turn an <tt>f a</tt> into an
--   <tt>f b</tt>, preserving the structure of <tt>f</tt>. Furthermore
--   <tt>f</tt> needs to adhere to the following:
--   
--   <ul>
--   <li><i>Identity</i> <tt><a>fmap</a> <a>id</a> == <a>id</a></tt></li>
--   <li><i>Composition</i> <tt><a>fmap</a> (f . g) == <a>fmap</a> f .
--   <a>fmap</a> g</tt></li>
--   </ul>
--   
--   Note, that the second law follows from the free theorem of the type
--   <a>fmap</a> and the first law, so you need only check that the former
--   condition holds.
class Functor (f :: Type -> Type)

-- | A bifunctor is a type constructor that takes two type arguments and is
--   a functor in <i>both</i> arguments. That is, unlike with
--   <a>Functor</a>, a type constructor such as <a>Either</a> does not need
--   to be partially applied for a <a>Bifunctor</a> instance, and the
--   methods in this class permit mapping functions over the <a>Left</a>
--   value or the <a>Right</a> value, or both at the same time.
--   
--   Formally, the class <a>Bifunctor</a> represents a bifunctor from
--   <tt>Hask</tt> -&gt; <tt>Hask</tt>.
--   
--   Intuitively it is a bifunctor where both the first and second
--   arguments are covariant.
--   
--   You can define a <a>Bifunctor</a> by either defining <a>bimap</a> or
--   by defining both <a>first</a> and <a>second</a>.
--   
--   If you supply <a>bimap</a>, you should ensure that:
--   
--   <pre>
--   <a>bimap</a> <a>id</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply <a>first</a> and <a>second</a>, ensure:
--   
--   <pre>
--   <a>first</a> <a>id</a> ≡ <a>id</a>
--   <a>second</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply both, you should also ensure:
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   These ensure by parametricity:
--   
--   <pre>
--   <a>bimap</a>  (f <a>.</a> g) (h <a>.</a> i) ≡ <a>bimap</a> f h <a>.</a> <a>bimap</a> g i
--   <a>first</a>  (f <a>.</a> g) ≡ <a>first</a>  f <a>.</a> <a>first</a>  g
--   <a>second</a> (f <a>.</a> g) ≡ <a>second</a> f <a>.</a> <a>second</a> g
--   </pre>
class Bifunctor (p :: Type -> Type -> Type)

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: Type -> Type)

-- | <a>Bifoldable</a> identifies foldable structures with two different
--   varieties of elements (as opposed to <a>Foldable</a>, which has one
--   variety of element). Common examples are <a>Either</a> and
--   <tt>(,)</tt>:
--   
--   <pre>
--   instance Bifoldable Either where
--     bifoldMap f _ (Left  a) = f a
--     bifoldMap _ g (Right b) = g b
--   
--   instance Bifoldable (,) where
--     bifoldr f g z (a, b) = f a (g b z)
--   </pre>
--   
--   A minimal <a>Bifoldable</a> definition consists of either
--   <a>bifoldMap</a> or <a>bifoldr</a>. When defining more than this
--   minimal set, one should ensure that the following identities hold:
--   
--   <pre>
--   <a>bifold</a> ≡ <a>bifoldMap</a> <a>id</a> <a>id</a>
--   <a>bifoldMap</a> f g ≡ <a>bifoldr</a> (<a>mappend</a> . f) (<a>mappend</a> . g) <a>mempty</a>
--   <a>bifoldr</a> f g z t ≡ <a>appEndo</a> (<a>bifoldMap</a> (Endo . f) (Endo . g) t) z
--   </pre>
--   
--   If the type is also a <a>Bifunctor</a> instance, it should satisfy:
--   
--   <pre>
--   <a>bifoldMap</a> f g ≡ <a>bifold</a> . <a>bimap</a> f g
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   <a>bifoldMap</a> f g . <a>bimap</a> h i ≡ <a>bifoldMap</a> (f . h) (g . i)
--   </pre>
class Bifoldable (p :: Type -> Type -> Type)

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt></li>
--   </ul>
class Semigroup a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following:
--   
--   <ul>
--   <li><i>Right identity</i> <tt>x <a>&lt;&gt;</a> <a>mempty</a> =
--   x</tt></li>
--   <li><i>Left identity</i> <tt><a>mempty</a> <a>&lt;&gt;</a> x =
--   x</tt></li>
--   <li><i>Associativity</i> <tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) =
--   (x <a>&lt;&gt;</a> y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a>
--   law)</li>
--   <li><i>Concatenation</i> <tt><a>mconcat</a> = <a>foldr</a>
--   (<a>&lt;&gt;</a>) <a>mempty</a></tt></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <a>Sum</a> and <a>Product</a>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <a>&lt;$&gt;</a> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i>Identity</i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a> v =
--   v</pre></li>
--   <li><i>Composition</i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i>Homomorphism</i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i>Interchange</i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>m1 <a>&lt;*&gt;</a> m2 = m1 <a>&gt;&gt;=</a> (x1 -&gt; m2
--   <a>&gt;&gt;=</a> (x2 -&gt; <a>return</a> (x1 x2)))</pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: Type -> Type)

-- | A monoid on applicative functors.
--   
--   If defined, <a>some</a> and <a>many</a> should be the least solutions
--   of the equations:
--   
--   <ul>
--   <li><pre><a>some</a> v = (:) <a>&lt;$&gt;</a> v <a>&lt;*&gt;</a>
--   <a>many</a> v</pre></li>
--   <li><pre><a>many</a> v = <a>some</a> v <a>&lt;|&gt;</a> <a>pure</a>
--   []</pre></li>
--   </ul>
class Applicative f => Alternative (f :: Type -> Type)

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i>Naturality</i> <tt>t . <a>traverse</a> f = <a>traverse</a> (t .
--   f)</tt> for every applicative transformation <tt>t</tt></li>
--   <li><i>Identity</i> <tt><a>traverse</a> <a>Identity</a> =
--   <a>Identity</a></tt></li>
--   <li><i>Composition</i> <tt><a>traverse</a> (<a>Compose</a> .
--   <a>fmap</a> g . f) = <a>Compose</a> . <a>fmap</a> (<a>traverse</a> g)
--   . <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i>Naturality</i> <tt>t . <a>sequenceA</a> = <a>sequenceA</a> .
--   <a>fmap</a> t</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i>Identity</i> <tt><a>sequenceA</a> . <a>fmap</a> <a>Identity</a>
--   = <a>Identity</a></tt></li>
--   <li><i>Composition</i> <tt><a>sequenceA</a> . <a>fmap</a>
--   <a>Compose</a> = <a>Compose</a> . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <pre>
--   t (<a>pure</a> x) = <a>pure</a> x
--   t (f <a>&lt;*&gt;</a> x) = t f <a>&lt;*&gt;</a> t x
--   </pre>
--   
--   and the identity functor <a>Identity</a> and composition functors
--   <a>Compose</a> are from <a>Data.Functor.Identity</a> and
--   <a>Data.Functor.Compose</a>.
--   
--   A result of the naturality law is a purity law for <a>traverse</a>
--   
--   <pre>
--   <a>traverse</a> <a>pure</a> = <a>pure</a>
--   </pre>
--   
--   (The naturality law is implied by parametricity and thus so is the
--   purity law [1, p15].)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
--   
--   References: [1] The Essence of the Iterator Pattern, Jeremy Gibbons
--   and Bruno C. d. S. Oliveira
class (Functor t, Foldable t) => Traversable (t :: Type -> Type)

-- | <a>Bitraversable</a> identifies bifunctorial data structures whose
--   elements can be traversed in order, performing <a>Applicative</a> or
--   <a>Monad</a> actions at each element, and collecting a result
--   structure with the same shape.
--   
--   As opposed to <a>Traversable</a> data structures, which have one
--   variety of element on which an action can be performed,
--   <a>Bitraversable</a> data structures have two such varieties of
--   elements.
--   
--   A definition of <a>bitraverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i>Naturality</i> <tt><a>bitraverse</a> (t . f) (t . g) ≡ t .
--   <a>bitraverse</a> f g</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i>Identity</i> <tt><a>bitraverse</a> <a>Identity</a>
--   <a>Identity</a> ≡ <a>Identity</a></tt></li>
--   <li><i>Composition</i> <tt><a>Compose</a> . <a>fmap</a>
--   (<a>bitraverse</a> g1 g2) . <a>bitraverse</a> f1 f2 ≡
--   <a>bitraverse</a> (<a>Compose</a> . <a>fmap</a> g1 . f1)
--   (<a>Compose</a> . <a>fmap</a> g2 . f2)</tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (<a>Applicative</a> f, <a>Applicative</a> g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations:
--   
--   <pre>
--   t (<a>pure</a> x) = <a>pure</a> x
--   t (f <a>&lt;*&gt;</a> x) = t f <a>&lt;*&gt;</a> t x
--   </pre>
--   
--   and the identity functor <a>Identity</a> and composition functors
--   <a>Compose</a> are from <a>Data.Functor.Identity</a> and
--   <a>Data.Functor.Compose</a>.
--   
--   Some simple examples are <a>Either</a> and <tt>(,)</tt>:
--   
--   <pre>
--   instance Bitraversable Either where
--     bitraverse f _ (Left x) = Left &lt;$&gt; f x
--     bitraverse _ g (Right y) = Right &lt;$&gt; g y
--   
--   instance Bitraversable (,) where
--     bitraverse f g (x, y) = (,) &lt;$&gt; f x &lt;*&gt; g y
--   </pre>
--   
--   <a>Bitraversable</a> relates to its superclasses in the following
--   ways:
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>runIdentity</a> . <a>bitraverse</a> (<a>Identity</a> . f) (<a>Identity</a> . g)
--   <a>bifoldMap</a> f g = <a>getConst</a> . <a>bitraverse</a> (<a>Const</a> . f) (<a>Const</a> . g)
--   </pre>
--   
--   These are available as <a>bimapDefault</a> and <a>bifoldMapDefault</a>
--   respectively.
class (Bifunctor t, Bifoldable t) => Bitraversable (t :: Type -> Type -> Type)

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following:
--   
--   <ul>
--   <li><i>Left identity</i> <tt><a>return</a> a <a>&gt;&gt;=</a> k = k
--   a</tt></li>
--   <li><i>Right identity</i> <tt>m <a>&gt;&gt;=</a> <a>return</a> =
--   m</tt></li>
--   <li><i>Associativity</i> <tt>m <a>&gt;&gt;=</a> (\x -&gt; k x
--   <a>&gt;&gt;=</a> h) = (m <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a>
--   h</tt></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>m1 <a>&lt;*&gt;</a> m2 = m1 <a>&gt;&gt;=</a> (x1 -&gt; m2
--   <a>&gt;&gt;=</a> (x2 -&gt; <a>return</a> (x1 x2)))</pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: Type -> Type)

-- | Monads that also support choice and failure.
class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type)

-- | A class for categories. Instances should satisfy the laws
--   
--   <ul>
--   <li><i>Right identity</i> <tt>f <a>.</a> <a>id</a> = f</tt></li>
--   <li><i>Left identity</i> <tt><a>id</a> <a>.</a> f = f</tt></li>
--   <li><i>Associativity</i> <tt>f <a>.</a> (g <a>.</a> h) = (f <a>.</a>
--   g) <a>.</a> h</tt></li>
--   </ul>
class Category (cat :: k -> k -> Type)

-- | The basic arrow class.
--   
--   Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>arr</a> id = <a>id</a></pre></li>
--   <li><pre><a>arr</a> (f &gt;&gt;&gt; g) = <a>arr</a> f &gt;&gt;&gt;
--   <a>arr</a> g</pre></li>
--   <li><pre><a>first</a> (<a>arr</a> f) = <a>arr</a> (<a>first</a>
--   f)</pre></li>
--   <li><pre><a>first</a> (f &gt;&gt;&gt; g) = <a>first</a> f &gt;&gt;&gt;
--   <a>first</a> g</pre></li>
--   <li><pre><a>first</a> f &gt;&gt;&gt; <a>arr</a> <a>fst</a> =
--   <a>arr</a> <a>fst</a> &gt;&gt;&gt; f</pre></li>
--   <li><pre><a>first</a> f &gt;&gt;&gt; <a>arr</a> (<a>id</a> *** g) =
--   <a>arr</a> (<a>id</a> *** g) &gt;&gt;&gt; <a>first</a> f</pre></li>
--   <li><pre><a>first</a> (<a>first</a> f) &gt;&gt;&gt; <a>arr</a> assoc =
--   <a>arr</a> assoc &gt;&gt;&gt; <a>first</a> f</pre></li>
--   </ul>
--   
--   where
--   
--   <pre>
--   assoc ((a,b),c) = (a,(b,c))
--   </pre>
--   
--   The other combinators have sensible default definitions, which may be
--   overridden for efficiency.
class Category a => Arrow (a :: Type -> Type -> Type)

-- | When a value is bound in <tt>do</tt>-notation, the pattern on the left
--   hand side of <tt>&lt;-</tt> might not match. In this case, this class
--   provides a function to recover.
--   
--   A <a>Monad</a> without a <a>MonadFail</a> instance may only be used in
--   conjunction with pattern that always match, such as newtypes, tuples,
--   data types with only a single data constructor, and irrefutable
--   patterns (<tt>~pat</tt>).
--   
--   Instances of <a>MonadFail</a> should satisfy the following law:
--   <tt>fail s</tt> should be a left zero for <a>&gt;&gt;=</a>,
--   
--   <pre>
--   fail s &gt;&gt;= f  =  fail s
--   </pre>
--   
--   If your <a>Monad</a> is also <a>MonadPlus</a>, a popular definition is
--   
--   <pre>
--   fail _ = mzero
--   </pre>
class Monad m => MonadFail (m :: Type -> Type)

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | The <a>Data</a> class comprehends a fundamental primitive
--   <a>gfoldl</a> for folding over constructor applications, say terms.
--   This primitive can be instantiated in several ways to map over the
--   immediate subterms of a term; see the <tt>gmap</tt> combinators later
--   in this class. Indeed, a generic programmer does not necessarily need
--   to use the ingenious gfoldl primitive but rather the intuitive
--   <tt>gmap</tt> combinators. The <a>gfoldl</a> primitive is completed by
--   means to query top-level constructors, to turn constructor
--   representations into proper terms, and to list all possible datatype
--   constructors. This completion allows us to serve generic programming
--   scenarios like read, show, equality, term generation.
--   
--   The combinators <a>gmapT</a>, <a>gmapQ</a>, <a>gmapM</a>, etc are all
--   provided with default definitions in terms of <a>gfoldl</a>, leaving
--   open the opportunity to provide datatype-specific definitions. (The
--   inclusion of the <tt>gmap</tt> combinators as members of class
--   <a>Data</a> allows the programmer or the compiler to derive
--   specialised, and maybe more efficient code per datatype. <i>Note</i>:
--   <a>gfoldl</a> is more higher-order than the <tt>gmap</tt> combinators.
--   This is subject to ongoing benchmarking experiments. It might turn out
--   that the <tt>gmap</tt> combinators will be moved out of the class
--   <a>Data</a>.)
--   
--   Conceptually, the definition of the <tt>gmap</tt> combinators in terms
--   of the primitive <a>gfoldl</a> requires the identification of the
--   <a>gfoldl</a> function arguments. Technically, we also need to
--   identify the type constructor <tt>c</tt> for the construction of the
--   result type from the folded term type.
--   
--   In the definition of <tt>gmapQ</tt><i>x</i> combinators, we use
--   phantom type constructors for the <tt>c</tt> in the type of
--   <a>gfoldl</a> because the result type of a query does not involve the
--   (polymorphic) type of the term argument. In the definition of
--   <a>gmapQl</a> we simply use the plain constant type constructor
--   because <a>gfoldl</a> is left-associative anyway and so it is readily
--   suited to fold a left-associative binary operation over the immediate
--   subterms. In the definition of gmapQr, extra effort is needed. We use
--   a higher-order accumulation trick to mediate between left-associative
--   constructor application vs. right-associative binary operation (e.g.,
--   <tt>(:)</tt>). When the query is meant to compute a value of type
--   <tt>r</tt>, then the result type withing generic folding is <tt>r
--   -&gt; r</tt>. So the result of folding is a function to which we
--   finally pass the right unit.
--   
--   With the <tt>-XDeriveDataTypeable</tt> option, GHC can generate
--   instances of the <a>Data</a> class automatically. For example, given
--   the declaration
--   
--   <pre>
--   data T a b = C1 a b | C2 deriving (Typeable, Data)
--   </pre>
--   
--   GHC will generate an instance that is equivalent to
--   
--   <pre>
--   instance (Data a, Data b) =&gt; Data (T a b) where
--       gfoldl k z (C1 a b) = z C1 `k` a `k` b
--       gfoldl k z C2       = z C2
--   
--       gunfold k z c = case constrIndex c of
--                           1 -&gt; k (k (z C1))
--                           2 -&gt; z C2
--   
--       toConstr (C1 _ _) = con_C1
--       toConstr C2       = con_C2
--   
--       dataTypeOf _ = ty_T
--   
--   con_C1 = mkConstr ty_T "C1" [] Prefix
--   con_C2 = mkConstr ty_T "C2" [] Prefix
--   ty_T   = mkDataType "Module.T" [con_C1, con_C2]
--   </pre>
--   
--   This is suitable for datatypes that are exported transparently.
class Typeable a => Data a

-- | Left-associative fold operation for constructor applications.
--   
--   The type of <a>gfoldl</a> is a headache, but operationally it is a
--   simple generalisation of a list fold.
--   
--   The default definition for <a>gfoldl</a> is <tt><a>const</a>
--   <a>id</a></tt>, which is suitable for abstract datatypes with no
--   substructures.
gfoldl :: Data a => (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. () => g -> c g) -> a -> c a

-- | Unfolding constructor applications
gunfold :: Data a => (forall b r. Data b => c (b -> r) -> c r) -> (forall r. () => r -> c r) -> Constr -> c a

-- | Obtaining the constructor from a given datum. For proper terms, this
--   is meant to be the top-level constructor. Primitive datatypes are here
--   viewed as potentially infinite sets of values (i.e., constructors).
toConstr :: Data a => a -> Constr

-- | The outer type constructor of the type
dataTypeOf :: Data a => a -> DataType

-- | Mediate types and unary type constructors.
--   
--   In <a>Data</a> instances of the form
--   
--   <pre>
--   instance (Data a, ...) =&gt; Data (T a)
--   </pre>
--   
--   <a>dataCast1</a> should be defined as <a>gcast1</a>.
--   
--   The default definition is <tt><a>const</a> <a>Nothing</a></tt>, which
--   is appropriate for instances of other forms.
dataCast1 :: (Data a, Typeable t) => (forall d. Data d => c (t d)) -> Maybe (c a)

-- | Mediate types and binary type constructors.
--   
--   In <a>Data</a> instances of the form
--   
--   <pre>
--   instance (Data a, Data b, ...) =&gt; Data (T a b)
--   </pre>
--   
--   <a>dataCast2</a> should be defined as <a>gcast2</a>.
--   
--   The default definition is <tt><a>const</a> <a>Nothing</a></tt>, which
--   is appropriate for instances of other forms.
dataCast2 :: (Data a, Typeable t) => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c a)

-- | A generic transformation that maps over the immediate subterms
--   
--   The default definition instantiates the type constructor <tt>c</tt> in
--   the type of <a>gfoldl</a> to an identity datatype constructor, using
--   the isomorphism pair as injection and projection.
gmapT :: Data a => (forall b. Data b => b -> b) -> a -> a

-- | A generic query with a left-associative binary operator
gmapQl :: Data a => (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> a -> r

-- | A generic query with a right-associative binary operator
gmapQr :: forall r r'. Data a => (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> a -> r

-- | A generic query that processes the immediate subterms and returns a
--   list of results. The list is given in the same order as originally
--   specified in the declaration of the data constructors.
gmapQ :: Data a => (forall d. Data d => d -> u) -> a -> [u]

-- | A generic query that processes one child by index (zero-based)
gmapQi :: Data a => Int -> (forall d. Data d => d -> u) -> a -> u

-- | A generic monadic transformation that maps over the immediate subterms
--   
--   The default definition instantiates the type constructor <tt>c</tt> in
--   the type of <a>gfoldl</a> to the monad datatype constructor, defining
--   injection and projection using <a>return</a> and <a>&gt;&gt;=</a>.
gmapM :: (Data a, Monad m) => (forall d. Data d => d -> m d) -> a -> m a

-- | Transformation of at least one immediate subterm does not fail
gmapMp :: (Data a, MonadPlus m) => (forall d. Data d => d -> m d) -> a -> m a

-- | Transformation of one immediate subterm with success
gmapMo :: (Data a, MonadPlus m) => (forall d. Data d => d -> m d) -> a -> m a

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class Generic a

-- | The member functions of this class facilitate writing values of
--   primitive types to raw memory (which may have been allocated with the
--   above mentioned routines) and reading values from blocks of raw
--   memory. The class, furthermore, includes support for computing the
--   storage requirements and alignment restrictions of storable types.
--   
--   Memory addresses are represented as values of type <tt><a>Ptr</a>
--   a</tt>, for some <tt>a</tt> which is an instance of class
--   <a>Storable</a>. The type argument to <a>Ptr</a> helps provide some
--   valuable type safety in FFI code (you can't mix pointers of different
--   types without an explicit cast), while helping the Haskell type system
--   figure out which marshalling method is needed for a given pointer.
--   
--   All marshalling between Haskell and a foreign language ultimately
--   boils down to translating Haskell data structures into the binary
--   representation of a corresponding data structure of the foreign
--   language and vice versa. To code this marshalling in Haskell, it is
--   necessary to manipulate primitive data types stored in unstructured
--   memory blocks. The class <a>Storable</a> facilitates this manipulation
--   on all types for which it is instantiated, which are the standard
--   basic types of Haskell, the fixed size <tt>Int</tt> types
--   (<a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>), the fixed
--   size <tt>Word</tt> types (<a>Word8</a>, <a>Word16</a>, <a>Word32</a>,
--   <a>Word64</a>), <a>StablePtr</a>, all types from
--   <a>Foreign.C.Types</a>, as well as <a>Ptr</a>.
class Storable a

-- | Any type that you wish to throw or catch as an exception must be an
--   instance of the <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving Show
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make an exception type for a particular frontend compiler exception
--   
--   data MismatchedParentheses = MismatchedParentheses
--       deriving Show
--   
--   instance Exception MismatchedParentheses where
--       toException   = frontendExceptionToException
--       fromException = frontendExceptionFromException
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable e, Show e) => Exception e

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | A class of types that can be fully evaluated.
class NFData a

-- | The class of monad transformers. Instances should satisfy the
--   following laws, which state that <a>lift</a> is a monad
--   transformation:
--   
--   <ul>
--   <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>lift</a> (m &gt;&gt;= f) = <a>lift</a> m &gt;&gt;=
--   (<a>lift</a> . f)</pre></li>
--   </ul>
class MonadTrans (t :: Type -> Type -> Type -> Type)

-- | See examples in <a>Control.Monad.Reader</a>. Note, the partially
--   applied function type <tt>(-&gt;) r</tt> is a simple reader monad. See
--   the <tt>instance</tt> declaration below.
class Monad m => MonadReader r (m :: Type -> Type) | m -> r

-- | The parameterizable reader monad.
--   
--   Computations are functions of a shared environment.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
type Reader r = ReaderT r Identity

-- | The reader monad transformer, which adds a read-only environment to
--   the given monad.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
newtype ReaderT r (m :: Type -> Type) a
ReaderT :: (r -> m a) -> ReaderT r (m :: Type -> Type) a

-- | A class for monads in which exceptions may be thrown.
--   
--   Instances should obey the following law:
--   
--   <pre>
--   throwM e &gt;&gt; x = throwM e
--   </pre>
--   
--   In other words, throwing an exception short-circuits the rest of the
--   monadic computation.
class Monad m => MonadThrow (m :: Type -> Type)

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString
type LByteString = ByteString

-- | <a>Builder</a>s denote sequences of bytes. They are <a>Monoid</a>s
--   where <a>mempty</a> is the zero-length sequence and <a>mappend</a> is
--   concatenation, which runs in <i>O(1)</i>.
data Builder

-- | A compact representation of a <a>Word8</a> vector.
--   
--   It has a lower memory overhead than a <a>ByteString</a> and does not
--   contribute to heap fragmentation. It can be converted to or from a
--   <a>ByteString</a> (at the cost of copying the string data). It
--   supports very few other operations.
--   
--   It is suitable for use as an internal representation for code that
--   needs to keep many short strings in memory, but it <i>should not</i>
--   be used as an interchange type. That is, it should not generally be
--   used in public APIs. The <a>ByteString</a> type is usually more
--   suitable for use in interfaces; it is more flexible and it supports a
--   wide range of operations.
data ShortByteString

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

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

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

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

-- | Boxed vectors, supporting efficient slicing.
data Vector a
type UVector = Vector
class (Vector Vector a, MVector MVector a) => Unbox a
type SVector = Vector
type GVector = Vector

-- | A map of integers to values <tt>a</tt>.
data IntMap a

-- | A Map from keys <tt>k</tt> to values <tt>a</tt>.
--   
--   The <a>Semigroup</a> operation for <a>Map</a> is <a>union</a>, which
--   prefers values from the left operand. If <tt>m1</tt> maps a key
--   <tt>k</tt> to a value <tt>a1</tt>, and <tt>m2</tt> maps the same key
--   to a different value <tt>a2</tt>, then their union <tt>m1 &lt;&gt;
--   m2</tt> maps <tt>k</tt> to <tt>a1</tt>.
data Map k a

-- | A set of integers.
data IntSet

-- | A set of values <tt>a</tt>.
data Set a

-- | General-purpose finite sequences.
data Seq a

-- | The class of types that can be converted to a hash value.
--   
--   Minimal implementation: <a>hashWithSalt</a>.
--   
--   <i>Note:</i> the hash is not guaranteed to be stable across library
--   versions, operating systems or architectures. For stable hashing use
--   named hashes: SHA256, CRC32 etc.
--   
--   If you are looking for <a>Hashable</a> instance in <tt>time</tt>
--   package, check <a>time-compat</a>
class Eq a => Hashable a

-- | A map from keys to values. A map cannot contain duplicate keys; each
--   key can map to at most one value.
data HashMap k v

-- | A set of values. A set cannot contain duplicate values.
data HashSet a

-- | Class of monads which can perform primitive state-transformer actions.
class Monad m => PrimMonad (m :: Type -> Type) where {
    
    -- | State token type.
    type family PrimState (m :: Type -> Type);
}

module RIO.Prelude

-- | Boolean "or", lazy in the second argument
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "and", lazy in the second argument
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "not"
not :: Bool -> Bool

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Case analysis for the <a>Bool</a> type. <tt><a>bool</a> x y p</tt>
--   evaluates to <tt>x</tt> when <tt>p</tt> is <a>False</a>, and evaluates
--   to <tt>y</tt> when <tt>p</tt> is <a>True</a>.
--   
--   This is equivalent to <tt>if p then y else x</tt>; that is, one can
--   think of it as an if-then-else construct with its arguments reordered.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; bool "foo" "bar" True
--   "bar"
--   
--   &gt;&gt;&gt; bool "foo" "bar" False
--   "foo"
--   </pre>
--   
--   Confirm that <tt><a>bool</a> x y p</tt> and <tt>if p then y else
--   x</tt> are equivalent:
--   
--   <pre>
--   &gt;&gt;&gt; let p = True; x = "bar"; y = "foo"
--   
--   &gt;&gt;&gt; bool x y p == if p then y else x
--   True
--   
--   &gt;&gt;&gt; let p = False
--   
--   &gt;&gt;&gt; bool x y p == if p then y else x
--   True
--   </pre>
bool :: a -> a -> Bool -> a

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <a>readMaybe</a>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <a>show</a> to a <tt>Maybe Int</tt>. If we have <tt>Just n</tt>,
--   we want to show the underlying <a>Int</a> <tt>n</tt>. But if we have
--   <a>Nothing</a>, we return the empty string instead of (for example)
--   "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: b -> (a -> b) -> Maybe a -> b

-- | The <a>fromMaybe</a> function takes a default value and and
--   <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
--   the default values; otherwise, it returns the value contained in the
--   <a>Maybe</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" Nothing
--   ""
--   </pre>
--   
--   Read an integer from a string using <a>readMaybe</a>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
--   5
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "")
--   0
--   </pre>
fromMaybe :: a -> Maybe a -> a

-- | Get a <a>First</a> value with a default fallback
fromFirst :: a -> First a -> a

-- | The <a>isJust</a> function returns <a>True</a> iff its argument is of
--   the form <tt>Just _</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just ())
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isJust Nothing
--   False
--   </pre>
--   
--   Only the outer constructor is taken into consideration:
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just Nothing)
--   True
--   </pre>
isJust :: Maybe a -> Bool

-- | The <a>isNothing</a> function returns <a>True</a> iff its argument is
--   <a>Nothing</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just 3)
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just ())
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing Nothing
--   True
--   </pre>
--   
--   Only the outer constructor is taken into consideration:
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just Nothing)
--   False
--   </pre>
isNothing :: Maybe a -> Bool

-- | The <a>listToMaybe</a> function returns <a>Nothing</a> on an empty
--   list or <tt><a>Just</a> a</tt> where <tt>a</tt> is the first element
--   of the list.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe []
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe [9]
--   Just 9
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe [1,2,3]
--   Just 1
--   </pre>
--   
--   Composing <a>maybeToList</a> with <a>listToMaybe</a> should be the
--   identity on singleton/empty lists:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList $ listToMaybe [5]
--   [5]
--   
--   &gt;&gt;&gt; maybeToList $ listToMaybe []
--   []
--   </pre>
--   
--   But not on lists with more than one element:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList $ listToMaybe [1,2,3]
--   [1]
--   </pre>
listToMaybe :: [a] -> Maybe a

-- | The <a>maybeToList</a> function returns an empty list when given
--   <a>Nothing</a> or a singleton list when given <a>Just</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList (Just 7)
--   [7]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList Nothing
--   []
--   </pre>
--   
--   One can use <a>maybeToList</a> to avoid pattern matching when combined
--   with a function that (safely) works on lists:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; sum $ maybeToList (readMaybe "3")
--   3
--   
--   &gt;&gt;&gt; sum $ maybeToList (readMaybe "")
--   0
--   </pre>
maybeToList :: Maybe a -> [a]

-- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and
--   returns a list of all the <a>Just</a> values.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; catMaybes [Just 1, Nothing, Just 3]
--   [1,3]
--   </pre>
--   
--   When constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
--   be used to return all of the "success" results (if the list is the
--   result of a <a>map</a>, then <a>mapMaybe</a> would be more
--   appropriate):
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [Just 1,Nothing,Just 3]
--   
--   &gt;&gt;&gt; catMaybes $ [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [1,3]
--   </pre>
catMaybes :: [Maybe a] -> [a]

-- | The <a>mapMaybe</a> function is a version of <a>map</a> which can
--   throw out elements. In particular, the functional argument returns
--   something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>,
--   no element is added on to the result list. If it is <tt><a>Just</a>
--   b</tt>, then <tt>b</tt> is included in the result list.
--   
--   <h4><b>Examples</b></h4>
--   
--   Using <tt><a>mapMaybe</a> f x</tt> is a shortcut for
--   <tt><a>catMaybes</a> $ <a>map</a> f x</tt> in most cases:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; let readMaybeInt = readMaybe :: String -&gt; Maybe Int
--   
--   &gt;&gt;&gt; mapMaybe readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--   
--   &gt;&gt;&gt; catMaybes $ map readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--   </pre>
--   
--   If we map the <a>Just</a> constructor, the entire list should be
--   returned:
--   
--   <pre>
--   &gt;&gt;&gt; mapMaybe Just [1,2,3]
--   [1,2,3]
--   </pre>
mapMaybe :: (a -> Maybe b) -> [a] -> [b]

-- | Applicative <a>mapMaybe</a>.
mapMaybeA :: Applicative f => (a -> f (Maybe b)) -> [a] -> f [b]

-- | Monadic <a>mapMaybe</a>.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]

-- | <pre>
--   <a>forMaybeA</a> <a>==</a> <a>flip</a> <a>mapMaybeA</a>
--   </pre>
forMaybeA :: Applicative f => [a] -> (a -> f (Maybe b)) -> f [b]

-- | <pre>
--   <a>forMaybeM</a> <a>==</a> <a>flip</a> <a>mapMaybeM</a>
--   </pre>
forMaybeM :: Monad m => [a] -> (a -> m (Maybe b)) -> m [b]

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <a>length</a> function (if we have a <a>String</a>) or the "times-two"
--   function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: (a -> c) -> (b -> c) -> Either a b -> c

-- | Return the contents of a <a>Left</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft 1 (Left 3)
--   3
--   
--   &gt;&gt;&gt; fromLeft 1 (Right "foo")
--   1
--   </pre>
fromLeft :: a -> Either a b -> a

-- | Return the contents of a <a>Right</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromRight 1 (Right 3)
--   3
--   
--   &gt;&gt;&gt; fromRight 1 (Left "foo")
--   1
--   </pre>
fromRight :: b -> Either a b -> b

-- | Return <a>True</a> if the given value is a <a>Left</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isLeft (Left "foo")
--   True
--   
--   &gt;&gt;&gt; isLeft (Right 3)
--   False
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isLeft</a> to write a very simple error-reporting function that
--   does absolutely nothing in the case of success, and outputs "ERROR" if
--   any error occurred.
--   
--   This example shows how <a>isLeft</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isLeft e) $ putStrLn "ERROR"
--   
--   &gt;&gt;&gt; report (Right 1)
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   ERROR
--   </pre>
isLeft :: Either a b -> Bool

-- | Return <a>True</a> if the given value is a <a>Right</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isRight (Left "foo")
--   False
--   
--   &gt;&gt;&gt; isRight (Right 3)
--   True
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isRight</a> to write a very simple reporting function that only
--   outputs "SUCCESS" when a computation has succeeded.
--   
--   This example shows how <a>isRight</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isRight e) $ putStrLn "SUCCESS"
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   
--   &gt;&gt;&gt; report (Right 1)
--   SUCCESS
--   </pre>
isRight :: Either a b -> Bool

-- | Apply a function to a <a>Left</a> constructor
mapLeft :: (a1 -> a2) -> Either a1 b -> Either a2 b

-- | Extracts from a list of <a>Either</a> all the <a>Left</a> elements.
--   All the <a>Left</a> elements are extracted in order.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; lefts list
--   ["foo","bar","baz"]
--   </pre>
lefts :: [Either a b] -> [a]

-- | Partitions a list of <a>Either</a> into two lists. All the <a>Left</a>
--   elements are extracted, in order, to the first component of the
--   output. Similarly the <a>Right</a> elements are extracted to the
--   second component of the output.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; partitionEithers list
--   (["foo","bar","baz"],[3,7])
--   </pre>
--   
--   The pair returned by <tt><a>partitionEithers</a> x</tt> should be the
--   same pair as <tt>(<a>lefts</a> x, <a>rights</a> x)</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; partitionEithers list == (lefts list, rights list)
--   True
--   </pre>
partitionEithers :: [Either a b] -> ([a], [b])

-- | Extracts from a list of <a>Either</a> all the <a>Right</a> elements.
--   All the <a>Right</a> elements are extracted in order.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; rights list
--   [3,7]
--   </pre>
rights :: [Either a b] -> [b]

-- | Extract the first component of a pair.
fst :: (a, b) -> a

-- | Extract the second component of a pair.
snd :: (a, b) -> b

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: ((a, b) -> c) -> a -> b -> c

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: (a -> b -> c) -> (a, b) -> c
(==) :: Eq a => a -> a -> Bool
infix 4 ==
(/=) :: Eq a => a -> a -> Bool
infix 4 /=
(<) :: Ord a => a -> a -> Bool
infix 4 <
(<=) :: Ord a => a -> a -> Bool
infix 4 <=
(>) :: Ord a => a -> a -> Bool
infix 4 >
(>=) :: Ord a => a -> a -> Bool
infix 4 >=
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a
compare :: Ord a => a -> a -> Ordering

-- | <pre>
--   comparing p x y = compare (p x) (p y)
--   </pre>
--   
--   Useful combinator for use in conjunction with the <tt>xxxBy</tt>
--   family of functions from <a>Data.List</a>, for example:
--   
--   <pre>
--   ... sortBy (comparing fst) ...
--   </pre>
comparing :: Ord a => (b -> a) -> b -> b -> Ordering

-- | The <a>Down</a> type allows you to reverse sort order conveniently. A
--   value of type <tt><a>Down</a> a</tt> contains a value of type
--   <tt>a</tt> (represented as <tt><a>Down</a> a</tt>). If <tt>a</tt> has
--   an <tt><a>Ord</a></tt> instance associated with it then comparing two
--   values thus wrapped will give you the opposite of their normal sort
--   order. This is particularly useful when sorting in generalised list
--   comprehensions, as in: <tt>then sortWith by <a>Down</a> x</tt>
newtype Down a
Down :: a -> Down a

[getDown] :: Down a -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int
minBound :: Bounded a => a
maxBound :: Bounded a => a
(+) :: Num a => a -> a -> a
infixl 6 +
(-) :: Num a => a -> a -> a
infixl 6 -
(*) :: Num a => a -> a -> a
infixl 7 *

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a
infixl 7 `quot`

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a
infixl 7 `rem`

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a
infixl 7 `div`

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a
infixl 7 `mod`

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer
even :: Integral a => a -> Bool
odd :: Integral a => a -> Bool

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | Fractional division.
(/) :: Fractional a => a -> a -> a
infixl 7 /

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | Reciprocal fraction.
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
infixr 8 **
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><a>uncurry</a> <a>encodeFloat</a> (<a>decodeFloat</a> x) = x</tt>.
--   <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Reverse order of bytes in <a>Word16</a>.
byteSwap16 :: Word16 -> Word16

-- | Reverse order of bytes in <a>Word32</a>.
byteSwap32 :: Word32 -> Word32

-- | Reverse order of bytes in <a>Word64</a>.
byteSwap64 :: Word64 -> Word64

-- | An associative operation.
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &lt;&gt; [4,5,6]
--   [1,2,3,4,5,6]
--   </pre>
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
sappend :: Semigroup s => s -> s -> s

-- | Identity of <a>mappend</a>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello world" &lt;&gt; mempty
--   "Hello world"
--   </pre>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = (<a>&lt;&gt;</a>)</tt> since
--   <i>base-4.11.0.0</i>. Should it be implemented manually, since
--   <a>mappend</a> is a synonym for (<a>&lt;&gt;</a>), it is expected that
--   the two functions are defined the same way. In a future GHC release
--   <a>mappend</a> will be removed from <a>Monoid</a>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
--   
--   <pre>
--   &gt;&gt;&gt; mconcat ["Hello", " ", "Haskell", "!"]
--   "Hello Haskell!"
--   </pre>
mconcat :: Monoid a => [a] -> a

-- | Using <tt>ApplicativeDo</tt>: '<tt><a>fmap</a> f as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      pure (f a)
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
fmap :: Functor f => (a -> b) -> f a -> f b

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <a>$</a>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <a>$</a> is function application, <a>&lt;$&gt;</a> is function
--   application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><a>Maybe</a> <a>Int</a></tt> to a <tt><a>Maybe</a>
--   <a>String</a></tt> using <a>show</a>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><a>Either</a> <a>Int</a> <a>Int</a></tt> to an
--   <tt><a>Either</a> <a>Int</a></tt> <a>String</a> using <a>show</a>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <a>even</a> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => (a -> b) -> f a -> f b
infixl 4 <$>

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>a <a>&lt;$</a> bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do bs
--      pure a
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
(<$) :: Functor f => a -> f b -> f a
infixl 4 <$

-- | Flipped version of <a>&lt;$</a>.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>as <a>$&gt;</a> b</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do as
--      pure b
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><a>Maybe</a> <a>Int</a></tt> with a
--   constant <a>String</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Nothing $&gt; "foo"
--   Nothing
--   
--   &gt;&gt;&gt; Just 90210 $&gt; "foo"
--   Just "foo"
--   </pre>
--   
--   Replace the contents of an <tt><a>Either</a> <a>Int</a>
--   <a>Int</a></tt> with a constant <a>String</a>, resulting in an
--   <tt><a>Either</a> <a>Int</a> <a>String</a></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Left 8675309 $&gt; "foo"
--   Left 8675309
--   
--   &gt;&gt;&gt; Right 8675309 $&gt; "foo"
--   Right "foo"
--   </pre>
--   
--   Replace each element of a list with a constant <a>String</a>:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] $&gt; "foo"
--   ["foo","foo","foo"]
--   </pre>
--   
--   Replace the second element of a pair with a constant <a>String</a>:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) $&gt; "foo"
--   (1,"foo")
--   </pre>
($>) :: Functor f => f a -> b -> f b
infixl 4 $>

-- | <tt><a>void</a> value</tt> discards or ignores the result of
--   evaluation, such as the return value of an <a>IO</a> action.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>void</a> as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do as
--      pure ()
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><a>Maybe</a> <a>Int</a></tt> with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void Nothing
--   Nothing
--   
--   &gt;&gt;&gt; void (Just 3)
--   Just ()
--   </pre>
--   
--   Replace the contents of an <tt><a>Either</a> <a>Int</a>
--   <a>Int</a></tt> with unit, resulting in an <tt><a>Either</a>
--   <a>Int</a> <tt>()</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; void (Left 8675309)
--   Left 8675309
--   
--   &gt;&gt;&gt; void (Right 8675309)
--   Right ()
--   </pre>
--   
--   Replace every element of a list with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void [1,2,3]
--   [(),(),()]
--   </pre>
--   
--   Replace the second element of a pair with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void (1,2)
--   (1,())
--   </pre>
--   
--   Discard the result of an <a>IO</a> action:
--   
--   <pre>
--   &gt;&gt;&gt; mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   &gt;&gt;&gt; void $ mapM print [1,2]
--   1
--   2
--   </pre>
void :: Functor f => f a -> f ()

-- | Flipped version of <a>&lt;$&gt;</a>.
--   
--   <pre>
--   (<a>&lt;&amp;&gt;</a>) = <a>flip</a> <a>fmap</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   Apply <tt>(+1)</tt> to a list, a <a>Just</a> and a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Just 2 &lt;&amp;&gt; (+1)
--   Just 3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &lt;&amp;&gt; (+1)
--   [2,3,4]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Right 3 &lt;&amp;&gt; (+1)
--   Right 4
--   </pre>
(<&>) :: Functor f => f a -> (a -> b) -> f b
infixl 1 <&>

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>fs <a>&lt;*&gt;</a> as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do f &lt;- fs
--      a &lt;- as
--      pure (f a)
--   </pre>
(<*>) :: Applicative f => f (a -> b) -> f a -> f b
infixl 4 <*>

-- | Sequence actions, discarding the value of the second argument.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt>as <a>&lt;*</a> bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      bs
--      pure a
--   </pre>
(<*) :: Applicative f => f a -> f b -> f a
infixl 4 <*

-- | Sequence actions, discarding the value of the first argument.
--   
--   '<tt>as <a>*&gt;</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do as
--      bs
--   </pre>
--   
--   This is a tad complicated for our <tt>ApplicativeDo</tt> extension
--   which will give it a <tt>Monad</tt> constraint. For an
--   <tt>Applicative</tt> constraint we write it of the form
--   
--   <pre>
--   do _ &lt;- as
--      b &lt;- bs
--      pure b
--   </pre>
(*>) :: Applicative f => f a -> f b -> f b
infixl 4 *>

-- | Lift a function to actions. This function may be used as a value for
--   <a>fmap</a> in a <a>Functor</a> instance.
--   
--   | Using <tt>ApplicativeDo</tt>: '<tt><a>liftA</a> f as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      pure (f a)
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint, weaker than
--   <tt>Applicative</tt>.
liftA :: Applicative f => (a -> b) -> f a -> f b

-- | Lift a binary function to actions.
--   
--   Some functors support an implementation of <a>liftA2</a> that is more
--   efficient than the default one. In particular, if <a>fmap</a> is an
--   expensive operation, it is likely better to use <a>liftA2</a> than to
--   <a>fmap</a> over the structure and then use <a>&lt;*&gt;</a>.
--   
--   This became a typeclass method in 4.10.0.0. Prior to that, it was a
--   function defined in terms of <a>&lt;*&gt;</a> and <a>fmap</a>.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>liftA2</a> f as bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      b &lt;- bs
--      pure (f a b)
--   </pre>
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c

-- | Lift a ternary function to actions.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>liftA3</a> f as bs cs</tt>' can
--   be understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      b &lt;- bs
--      c &lt;- cs
--      pure (f a b c)
--   </pre>
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d

-- | Repeat an action indefinitely.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>forever</a> as</tt>' can be
--   understood as the pseudo-<tt>do</tt> expression
--   
--   <pre>
--   do as
--      as
--      ..
--   </pre>
--   
--   with <tt>as</tt> repeating.
--   
--   <h4><b>Examples</b></h4>
--   
--   A common use of <a>forever</a> is to process input from network
--   sockets, <a>Handle</a>s, and channels (e.g. <a>MVar</a> and
--   <a>Chan</a>).
--   
--   For example, here is how we might implement an <a>echo server</a>,
--   using <a>forever</a> both to listen for client connections on a
--   network socket and to echo client input on client connection handles:
--   
--   <pre>
--   echoServer :: Socket -&gt; IO ()
--   echoServer socket = <a>forever</a> $ do
--     client &lt;- accept socket
--     <a>forkFinally</a> (echo client) (\_ -&gt; hClose client)
--     where
--       echo :: Handle -&gt; IO ()
--       echo client = <a>forever</a> $
--         hGetLine client &gt;&gt;= hPutStrLn client
--   </pre>
forever :: Applicative f => f a -> f b

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and ignore the results. For a version that doesn't
--   ignore the results see <a>traverse</a>.
traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f ()

-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
--   version that doesn't ignore the results see <a>for</a>.
--   
--   <pre>
--   &gt;&gt;&gt; for_ [1..4] print
--   1
--   2
--   3
--   4
--   </pre>
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()

-- | Evaluate each action in the structure from left to right, and ignore
--   the results. For a version that doesn't ignore the results see
--   <a>sequenceA</a>.
sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f ()

-- | This generalizes the list-based <a>filter</a> function.
filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: Applicative m => Int -> m a -> m ()

-- | The <a>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary
--   applicative functors.
zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]

-- | <a>zipWithM_</a> is the extension of <a>zipWithM</a> which ignores the
--   final result.
zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | The <a>join</a> function is the conventional monad join operator. It
--   is used to remove one level of monadic structure, projecting its bound
--   argument into the outer level.
--   
--   '<tt><a>join</a> bss</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do bs &lt;- bss
--      bs
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   A common use of <a>join</a> is to run an <a>IO</a> computation
--   returned from an <a>STM</a> transaction, since <a>STM</a> transactions
--   can't perform <a>IO</a> directly. Recall that
--   
--   <pre>
--   <a>atomically</a> :: STM a -&gt; IO a
--   </pre>
--   
--   is used to run <a>STM</a> transactions atomically. So, by specializing
--   the types of <a>atomically</a> and <a>join</a> to
--   
--   <pre>
--   <a>atomically</a> :: STM (IO b) -&gt; IO (IO b)
--   <a>join</a>       :: IO (IO b)  -&gt; IO b
--   </pre>
--   
--   we can compose them as
--   
--   <pre>
--   <a>join</a> . <a>atomically</a> :: STM (IO b) -&gt; IO b
--   </pre>
--   
--   to run an <a>STM</a> transaction and the <a>IO</a> action it returns.
join :: Monad m => m (m a) -> m a
fail :: MonadFail m => String -> m a

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
--   
--   '<tt>as <a>&gt;&gt;=</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do a &lt;- as
--      bs a
--   </pre>
(>>=) :: Monad m => m a -> (a -> m b) -> m b
infixl 1 >>=

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
--   
--   '<tt>as <a>&gt;&gt;</a> bs</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do as
--      bs
--   </pre>
(>>) :: Monad m => m a -> m b -> m b
infixl 1 >>

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<

-- | Left-to-right composition of Kleisli arrows.
--   
--   '<tt>(bs <a>&gt;=&gt;</a> cs) a</tt>' can be understood as the
--   <tt>do</tt> expression
--   
--   <pre>
--   do b &lt;- bs a
--      cs b
--   </pre>
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
infixr 1 >=>

-- | Right-to-left composition of Kleisli arrows.
--   <tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped.
--   
--   Note how this operator resembles function composition
--   <tt>(<a>.</a>)</tt>:
--   
--   <pre>
--   (.)   ::            (b -&gt;   c) -&gt; (a -&gt;   b) -&gt; a -&gt;   c
--   (&lt;=&lt;) :: Monad m =&gt; (b -&gt; m c) -&gt; (a -&gt; m b) -&gt; a -&gt; m c
--   </pre>
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
infixr 1 <=<

-- | Strict version of <a>&lt;$&gt;</a>.
(<$!>) :: Monad m => (a -> b) -> m a -> m b
infixl 4 <$!>

-- | Promote a function to a monad.
liftM :: Monad m => (a1 -> r) -> m a1 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right. For example,
--   
--   <pre>
--   liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--   liftM2 (+) (Just 1) Nothing = Nothing
--   </pre>
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r

-- | Run the second value if the first value returns <a>True</a>
whenM :: Monad m => m Bool -> m () -> m ()

-- | Run the second value if the first value returns <a>False</a>
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()

-- | <a>forM_</a> is <a>mapM_</a> with its arguments flipped. For a version
--   that doesn't ignore the results see <a>forM</a>.
--   
--   As of base 4.8.0.0, <a>forM_</a> is just <a>for_</a>, specialized to
--   <a>Monad</a>.
forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()

-- | The <a>foldM</a> function is analogous to <a>foldl</a>, except that
--   its result is encapsulated in a monad. Note that <a>foldM</a> works
--   from left-to-right over the list arguments. This could be an issue
--   where <tt>(<a>&gt;&gt;</a>)</tt> and the `folded function' are not
--   commutative.
--   
--   <pre>
--   foldM f a1 [x1, x2, ..., xm]
--   
--   ==
--   
--   do
--     a2 &lt;- f a1 x1
--     a3 &lt;- f a2 x2
--     ...
--     f am xm
--   </pre>
--   
--   If right-to-left evaluation is required, the input list should be
--   reversed.
--   
--   Note: <a>foldM</a> is the same as <a>foldlM</a>
foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b

-- | Like <a>foldM</a>, but discards the result.
foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()

-- | Right-associative fold of a structure.
--   
--   In the case of lists, <a>foldr</a>, when applied to a binary operator,
--   a starting value (typically the right-identity of the operator), and a
--   list, reduces the list using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--   </pre>
--   
--   Note that, since the head of the resulting expression is produced by
--   an application of the operator to the first element of the list,
--   <a>foldr</a> can produce a terminating expression from an infinite
--   list.
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldr f z = <a>foldr</a> f z . <a>toList</a>
--   </pre>
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b

-- | Left-associative fold of a structure but with strict application of
--   the operator.
--   
--   This ensures that each step of the fold is forced to weak head normal
--   form before being applied, avoiding the collection of thunks that
--   would otherwise occur. This is often what you want to strictly reduce
--   a finite list to a single, monolithic result (e.g. <a>length</a>).
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldl' f z = <a>foldl'</a> f z . <a>toList</a>
--   </pre>
foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b

-- | Combine the elements of a structure using a monoid.
fold :: (Foldable t, Monoid m) => t m -> m

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m

-- | Extend <a>foldMap</a> to allow side effects.
--   
--   Internally, this is implemented using a strict left fold. This is used
--   for performance reasons. It also necessitates that this function has a
--   <tt>Monad</tt> constraint and not just an <tt>Applicative</tt>
--   constraint. For more information, see
--   <a>https://github.com/commercialhaskell/rio/pull/99#issuecomment-394179757</a>.
foldMapM :: (Monad m, Monoid w, Foldable t) => (a -> m w) -> t a -> m w

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `elem`

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Returns the size/length of a finite structure as an <a>Int</a>. The
--   default implementation is optimized for structures that are similar to
--   cons-lists, because there is no general way to do better.
length :: Foldable t => t a -> Int

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => (a -> Bool) -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => (a -> Bool) -> t a -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | List of elements of a structure, from left to right.
toList :: Foldable t => t a -> [a]

-- | The concatenation of all the elements of a container of lists.
concat :: Foldable t => t [a] -> [a]

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)

-- | <a>for</a> is <a>traverse</a> with its arguments flipped. For a
--   version that ignores the results see <a>for_</a>.
for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)

-- | Evaluate each action in the structure from left to right, and collect
--   the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)

-- | <a>forM</a> is <a>mapM</a> with its arguments flipped. For a version
--   that ignores the results see <a>forM_</a>.
forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)

-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
infixl 3 <|>

-- | One or more.
some :: Alternative f => f a -> f [a]

-- | Zero or more.
many :: Alternative f => f a -> f [a]

-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)

-- | The sum of a collection of actions, generalizing <a>concat</a>.
--   
--   <pre>
--   &gt;&gt;&gt; asum [Just "Hello", Nothing, Just "World"]
--   Just "Hello"
--   </pre>
asum :: (Foldable t, Alternative f) => t (f a) -> f a

-- | Conditional failure of <a>Alternative</a> computations. Defined by
--   
--   <pre>
--   guard True  = <a>pure</a> ()
--   guard False = <a>empty</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   Common uses of <a>guard</a> include conditionally signaling an error
--   in an error monad and conditionally rejecting the current choice in an
--   <a>Alternative</a>-based parser.
--   
--   As an example of signaling an error in the error monad <a>Maybe</a>,
--   consider a safe division function <tt>safeDiv x y</tt> that returns
--   <a>Nothing</a> when the denominator <tt>y</tt> is zero and
--   <tt><a>Just</a> (x `div` y)</tt> otherwise. For example:
--   
--   <pre>
--   &gt;&gt;&gt; safeDiv 4 0
--   Nothing
--   &gt;&gt;&gt; safeDiv 4 2
--   Just 2
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using guards, but not <a>guard</a>:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y | y /= 0    = Just (x `div` y)
--               | otherwise = Nothing
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using <a>guard</a> and <a>Monad</a>
--   <tt>do</tt>-notation:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y = do
--     guard (y /= 0)
--     return (x `div` y)
--   </pre>
guard :: Alternative f => Bool -> f ()

-- | Conditional execution of <a>Applicative</a> expressions. For example,
--   
--   <pre>
--   when debug (putStrLn "Debugging")
--   </pre>
--   
--   will output the string <tt>Debugging</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()

-- | The reverse of <a>when</a>.
unless :: Applicative f => Bool -> f () -> f ()

-- | Map over both arguments at the same time.
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) ('j', 3)
--   ('J',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Left 'j')
--   Left 'J'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Right 3)
--   Right 4
--   </pre>
bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d

-- | Map covariantly over the first argument.
--   
--   <pre>
--   <a>first</a> f ≡ <a>bimap</a> f <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper ('j', 3)
--   ('J',3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper (Left 'j')
--   Left 'J'
--   </pre>
first :: Bifunctor p => (a -> b) -> p a c -> p b c

-- | Map covariantly over the second argument.
--   
--   <pre>
--   <a>second</a> ≡ <a>bimap</a> <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) ('j', 3)
--   ('j',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) (Right 3)
--   Right 4
--   </pre>
second :: Bifunctor p => (b -> c) -> p a b -> p a c

-- | Combines the elements of a structure using a monoid.
--   
--   <pre>
--   <a>bifold</a> ≡ <a>bifoldMap</a> <a>id</a> <a>id</a>
--   </pre>
bifold :: (Bifoldable p, Monoid m) => p m m -> m

-- | Combines the elements of a structure, given ways of mapping them to a
--   common monoid.
--   
--   <pre>
--   <a>bifoldMap</a> f g
--        ≡ <a>bifoldr</a> (<a>mappend</a> . f) (<a>mappend</a> . g) <a>mempty</a>
--   </pre>
bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m

-- | Combines the elements of a structure in a right associative manner.
--   Given a hypothetical function <tt>toEitherList :: p a b -&gt; [Either
--   a b]</tt> yielding a list of all elements of a structure in order, the
--   following would hold:
--   
--   <pre>
--   <a>bifoldr</a> f g z ≡ <a>foldr</a> (<a>either</a> f g) z . toEitherList
--   </pre>
bifoldr :: Bifoldable p => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c

-- | Combines the elements of a structure in a left associative manner.
--   Given a hypothetical function <tt>toEitherList :: p a b -&gt; [Either
--   a b]</tt> yielding a list of all elements of a structure in order, the
--   following would hold:
--   
--   <pre>
--   <a>bifoldl</a> f g z
--        ≡ <a>foldl</a> (acc -&gt; <a>either</a> (f acc) (g acc)) z . toEitherList
--   </pre>
--   
--   Note that if you want an efficient left-fold, you probably want to use
--   <a>bifoldl'</a> instead of <a>bifoldl</a>. The reason is that the
--   latter does not force the "inner" results, resulting in a thunk chain
--   which then must be evaluated from the outside-in.
bifoldl :: Bifoldable p => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c

-- | As <a>bifoldr</a>, but strict in the result of the reduction functions
--   at each step.
bifoldr' :: Bifoldable t => (a -> c -> c) -> (b -> c -> c) -> c -> t a b -> c

-- | A variant of <a>bifoldr</a> that has no base case, and thus may only
--   be applied to non-empty structures.
bifoldr1 :: Bifoldable t => (a -> a -> a) -> t a a -> a

-- | Right associative monadic bifold over a structure.
bifoldrM :: (Bifoldable t, Monad m) => (a -> c -> m c) -> (b -> c -> m c) -> c -> t a b -> m c

-- | As <a>bifoldl</a>, but strict in the result of the reduction functions
--   at each step.
--   
--   This ensures that each step of the bifold is forced to weak head
--   normal form before being applied, avoiding the collection of thunks
--   that would otherwise occur. This is often what you want to strictly
--   reduce a finite structure to a single, monolithic result (e.g.,
--   <a>bilength</a>).
bifoldl' :: Bifoldable t => (a -> b -> a) -> (a -> c -> a) -> a -> t b c -> a

-- | A variant of <a>bifoldl</a> that has no base case, and thus may only
--   be applied to non-empty structures.
bifoldl1 :: Bifoldable t => (a -> a -> a) -> t a a -> a

-- | Left associative monadic bifold over a structure.
bifoldlM :: (Bifoldable t, Monad m) => (a -> b -> m a) -> (a -> c -> m a) -> a -> t b c -> m a

-- | Map each element of a structure using one of two actions, evaluate
--   these actions from left to right, and ignore the results. For a
--   version that doesn't ignore the results, see <a>bitraverse</a>.
bitraverse_ :: (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f ()

-- | As <a>bitraverse_</a>, but with the structure as the primary argument.
--   For a version that doesn't ignore the results, see <a>bifor</a>.
--   
--   <pre>
--   &gt;&gt;&gt; &gt; bifor_ ('a', "bc") print (print . reverse)
--   'a'
--   "cb"
--   </pre>
bifor_ :: (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f ()

-- | Evaluate each action in the structure from left to right, and ignore
--   the results. For a version that doesn't ignore the results, see
--   <a>bisequence</a>.
bisequence_ :: (Bifoldable t, Applicative f) => t (f a) (f b) -> f ()

-- | The sum of a collection of actions, generalizing <a>biconcat</a>.
biasum :: (Bifoldable t, Alternative f) => t (f a) (f a) -> f a

-- | Collects the list of elements of a structure, from left to right.
biList :: Bifoldable t => t a a -> [a]

-- | Test whether the structure is empty.
binull :: Bifoldable t => t a b -> Bool

-- | Returns the size/length of a finite structure as an <a>Int</a>.
bilength :: Bifoldable t => t a b -> Int

-- | Does the element occur in the structure?
bielem :: (Bifoldable t, Eq a) => a -> t a a -> Bool

-- | The largest element of a non-empty structure.
bimaximum :: (Bifoldable t, Ord a) => t a a -> a

-- | The least element of a non-empty structure.
biminimum :: (Bifoldable t, Ord a) => t a a -> a

-- | The <a>bisum</a> function computes the sum of the numbers of a
--   structure.
bisum :: (Bifoldable t, Num a) => t a a -> a

-- | The <a>biproduct</a> function computes the product of the numbers of a
--   structure.
biproduct :: (Bifoldable t, Num a) => t a a -> a

-- | Reduces a structure of lists to the concatenation of those lists.
biconcat :: Bifoldable t => t [a] [a] -> [a]

-- | Given a means of mapping the elements of a structure to lists,
--   computes the concatenation of all such lists in order.
biconcatMap :: Bifoldable t => (a -> [c]) -> (b -> [c]) -> t a b -> [c]

-- | <a>biand</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
biand :: Bifoldable t => t Bool Bool -> Bool

-- | <a>bior</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
bior :: Bifoldable t => t Bool Bool -> Bool

-- | Determines whether any element of the structure satisfies its
--   appropriate predicate argument.
biany :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool

-- | Determines whether all elements of the structure satisfy their
--   appropriate predicate argument.
biall :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool

-- | The largest element of a non-empty structure with respect to the given
--   comparison function.
bimaximumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a

-- | The least element of a non-empty structure with respect to the given
--   comparison function.
biminimumBy :: Bifoldable t => (a -> a -> Ordering) -> t a a -> a

-- | <a>binotElem</a> is the negation of <a>bielem</a>.
binotElem :: (Bifoldable t, Eq a) => a -> t a a -> Bool

-- | The <a>bifind</a> function takes a predicate and a structure and
--   returns the leftmost element of the structure matching the predicate,
--   or <a>Nothing</a> if there is no such element.
bifind :: Bifoldable t => (a -> Bool) -> t a a -> Maybe a

-- | Evaluates the relevant functions at each element in the structure,
--   running the action, and builds a new structure with the same shape,
--   using the results produced from sequencing the actions.
--   
--   <pre>
--   <a>bitraverse</a> f g ≡ <a>bisequenceA</a> . <a>bimap</a> f g
--   </pre>
--   
--   For a version that ignores the results, see <a>bitraverse_</a>.
bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)

-- | Sequences all the actions in a structure, building a new structure
--   with the same shape using the results of the actions. For a version
--   that ignores the results, see <a>bisequence_</a>.
--   
--   <pre>
--   <a>bisequence</a> ≡ <a>bitraverse</a> <a>id</a> <a>id</a>
--   </pre>
bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b)

-- | <a>bifor</a> is <a>bitraverse</a> with the structure as the first
--   argument. For a version that ignores the results, see <a>bifor_</a>.
bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)

-- | The <a>bimapAccumL</a> function behaves like a combination of
--   <a>bimap</a> and <a>bifoldl</a>; it traverses a structure from left to
--   right, threading a state of type <tt>a</tt> and using the given
--   actions to compute new elements for the structure.
bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)

-- | The <a>bimapAccumR</a> function behaves like a combination of
--   <a>bimap</a> and <a>bifoldl</a>; it traverses a structure from right
--   to left, threading a state of type <tt>a</tt> and using the given
--   actions to compute new elements for the structure.
bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e)

-- | The identity of <a>mplus</a>. It should also satisfy the equations
--   
--   <pre>
--   mzero &gt;&gt;= f  =  mzero
--   v &gt;&gt; mzero   =  mzero
--   </pre>
--   
--   The default definition is
--   
--   <pre>
--   mzero = <a>empty</a>
--   </pre>
mzero :: MonadPlus m => m a

-- | An associative operation. The default definition is
--   
--   <pre>
--   mplus = (<a>&lt;|&gt;</a>)
--   </pre>
mplus :: MonadPlus m => m a -> m a -> m a

-- | The sum of a collection of actions, generalizing <a>concat</a>. As of
--   base 4.8.0.0, <a>msum</a> is just <a>asum</a>, specialized to
--   <a>MonadPlus</a>.
msum :: (Foldable t, MonadPlus m) => t (m a) -> m a

-- | Direct <a>MonadPlus</a> equivalent of <a>filter</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   The <a>filter</a> function is just <a>mfilter</a> specialized to the
--   list monad:
--   
--   <pre>
--   <a>filter</a> = ( <a>mfilter</a> :: (a -&gt; Bool) -&gt; [a] -&gt; [a] )
--   </pre>
--   
--   An example using <a>mfilter</a> with the <a>Maybe</a> monad:
--   
--   <pre>
--   &gt;&gt;&gt; mfilter odd (Just 1)
--   Just 1
--   &gt;&gt;&gt; mfilter odd (Just 2)
--   Nothing
--   </pre>
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a

-- | Fanout: send the input to both argument arrows and combine their
--   output.
--   
--   The default definition may be overridden with a more efficient version
--   if desired.
(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')
infixr 3 &&&

-- | Split the input between the two argument arrows and combine their
--   output. Note that this is in general not a functor.
--   
--   The default definition may be overridden with a more efficient version
--   if desired.
(***) :: Arrow a => a b c -> a b' c' -> a (b, b') (c, c')
infixr 3 ***

-- | Left-to-right composition
(>>>) :: forall k cat (a :: k) (b :: k) (c :: k). Category cat => cat a b -> cat b c -> cat a c
infixr 1 >>>

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: a -> a

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: a -> b -> a

-- | Function composition.
(.) :: (b -> c) -> (a -> b) -> a -> c
infixr 9 .

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
--   
--   Note that <tt>(<a>$</a>)</tt> is levity-polymorphic in its result
--   type, so that <tt>foo <a>$</a> True</tt> where <tt>foo :: Bool -&gt;
--   Int#</tt> is well-typed.
($) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 5 &amp; (+1) &amp; show
--   "6"
--   </pre>
(&) :: a -> (a -> b) -> b
infixl 1 &

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: (a -> b -> c) -> b -> a -> c

-- | <tt><a>fix</a> f</tt> is the least fixed point of the function
--   <tt>f</tt>, i.e. the least defined <tt>x</tt> such that <tt>f x =
--   x</tt>.
--   
--   For example, we can write the factorial function using direct
--   recursion as
--   
--   <pre>
--   &gt;&gt;&gt; let fac n = if n &lt;= 1 then 1 else n * fac (n-1) in fac 5
--   120
--   </pre>
--   
--   This uses the fact that Haskell’s <tt>let</tt> introduces recursive
--   bindings. We can rewrite this definition using <a>fix</a>,
--   
--   <pre>
--   &gt;&gt;&gt; fix (\rec n -&gt; if n &lt;= 1 then 1 else n * rec (n-1)) 5
--   120
--   </pre>
--   
--   Instead of making a recursive call, we introduce a dummy parameter
--   <tt>rec</tt>; when used within <a>fix</a>, this parameter then refers
--   to <a>fix</a>’s argument, hence the recursion is reintroduced.
fix :: (a -> a) -> a

-- | <tt><a>on</a> b u x y</tt> runs the binary function <tt>b</tt>
--   <i>on</i> the results of applying unary function <tt>u</tt> to two
--   arguments <tt>x</tt> and <tt>y</tt>. From the opposite perspective, it
--   transforms two inputs and combines the outputs.
--   
--   <pre>
--   ((+) `<a>on</a>` f) x y = f x + f y
--   </pre>
--   
--   Typical usage: <tt><a>sortBy</a> (<a>compare</a> `on`
--   <a>fst</a>)</tt>.
--   
--   Algebraic properties:
--   
--   <ul>
--   <li><pre>(*) `on` <a>id</a> = (*) -- (if (*) ∉ {⊥, <a>const</a>
--   ⊥})</pre></li>
--   <li><pre>((*) `on` f) `on` g = (*) `on` (f . g)</pre></li>
--   <li><pre><a>flip</a> on f . <a>flip</a> on g = <a>flip</a> on (g .
--   f)</pre></li>
--   </ul>
on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
infixl 0 `on`

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b
infixr 0 $!

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: forall (r :: RuntimeRep) a (b :: TYPE r). a -> b -> b
infixr 0 `seq`

-- | <a>error</a> stops execution and displays an error message.
error :: forall (r :: RuntimeRep) (a :: TYPE r). HasCallStack => [Char] -> a

-- | A special case of <a>error</a>. It is expected that compilers will
--   recognize this and insert error messages which are more appropriate to
--   the context in which <a>undefined</a> appears.
undefined :: forall (r :: RuntimeRep) (a :: TYPE r). HasCallStack => a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: a -> a -> a

-- | Helper function to force an action to run in <a>IO</a>. Especially
--   useful for overly general contexts, like hspec tests.
asIO :: IO a -> IO a

-- | Append two lists, i.e.,
--   
--   <pre>
--   [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
--   [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--   </pre>
--   
--   If the first list is not finite, the result is the first list.
(++) :: [a] -> [a] -> [a]
infixr 5 ++

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (a -> Bool) -> [a] -> ([a], [a])

-- | <a>drop</a> <tt>n xs</tt> returns the suffix of <tt>xs</tt> after the
--   first <tt>n</tt> elements, or <tt>[]</tt> if <tt>n &gt; <a>length</a>
--   xs</tt>:
--   
--   <pre>
--   drop 6 "Hello World!" == "World!"
--   drop 3 [1,2,3,4,5] == [4,5]
--   drop 3 [1,2] == []
--   drop 3 [] == []
--   drop (-1) [1,2] == [1,2]
--   drop 0 [1,2] == [1,2]
--   </pre>
--   
--   It is an instance of the more general <a>genericDrop</a>, in which
--   <tt>n</tt> may be of any integral type.
drop :: Int -> [a] -> [a]

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: (a -> Bool) -> [a] -> [a]

-- | &lt;math&gt;. <a>filter</a>, applied to a predicate and a list,
--   returns the list of those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; filter odd [1, 2, 3]
--   [1,3]
--   </pre>
filter :: (a -> Bool) -> [a] -> [a]

-- | &lt;math&gt;. <a>lookup</a> <tt>key assocs</tt> looks up a key in an
--   association list.
--   
--   <pre>
--   &gt;&gt;&gt; lookup 2 [(1, "first"), (2, "second"), (3, "third")]
--   Just "second"
--   </pre>
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | &lt;math&gt;. <a>map</a> <tt>f xs</tt> is the list obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>, i.e.,
--   
--   <pre>
--   map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
--   map f [x1, x2, ...] == [f x1, f x2, ...]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (+1) [1, 2, 3]
--   </pre>
map :: (a -> b) -> [a] -> [b]

-- | <a>replicate</a> <tt>n x</tt> is a list of length <tt>n</tt> with
--   <tt>x</tt> the value of every element. It is an instance of the more
--   general <a>genericReplicate</a>, in which <tt>n</tt> may be of any
--   integral type.
replicate :: Int -> a -> [a]

-- | <a>reverse</a> <tt>xs</tt> returns the elements of <tt>xs</tt> in
--   reverse order. <tt>xs</tt> must be finite.
reverse :: [a] -> [a]

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: (a -> Bool) -> [a] -> ([a], [a])

-- | <a>take</a> <tt>n</tt>, applied to a list <tt>xs</tt>, returns the
--   prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt> itself if
--   <tt>n &gt; <a>length</a> xs</tt>:
--   
--   <pre>
--   take 5 "Hello World!" == "Hello"
--   take 3 [1,2,3,4,5] == [1,2,3]
--   take 3 [1,2] == [1,2]
--   take 3 [] == []
--   take (-1) [1,2] == []
--   take 0 [1,2] == []
--   </pre>
--   
--   It is an instance of the more general <a>genericTake</a>, in which
--   <tt>n</tt> may be of any integral type.
take :: Int -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: (a -> Bool) -> [a] -> [a]

-- | &lt;math&gt;. <a>zip</a> takes two lists and returns a list of
--   corresponding pairs.
--   
--   <pre>
--   zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]
--   </pre>
--   
--   If one input list is short, excess elements of the longer list are
--   discarded:
--   
--   <pre>
--   zip [1] ['a', 'b'] = [(1, 'a')]
--   zip [1, 2] ['a'] = [(1, 'a')]
--   </pre>
--   
--   <a>zip</a> is right-lazy:
--   
--   <pre>
--   zip [] _|_ = []
--   zip _|_ [] = _|_
--   </pre>
--   
--   <a>zip</a> is capable of list fusion, but it is restricted to its
--   first list argument and its resulting list.
zip :: [a] -> [b] -> [(a, b)]

-- | &lt;math&gt;. <a>zipWith</a> generalises <a>zip</a> by zipping with
--   the function given as the first argument, instead of a tupling
--   function. For example, <tt><a>zipWith</a> (+)</tt> is applied to two
--   lists to produce the list of corresponding sums:
--   
--   <pre>
--   &gt;&gt;&gt; zipWith (+) [1, 2, 3] [4, 5, 6]
--   [5,7,9]
--   </pre>
--   
--   <a>zipWith</a> is right-lazy:
--   
--   <pre>
--   zipWith f [] _|_ = []
--   </pre>
--   
--   <a>zipWith</a> is capable of list fusion, but it is restricted to its
--   first list argument and its resulting list.
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]

-- | Strip out duplicates
nubOrd :: Ord a => [a] -> [a]
fromString :: IsString a => String -> a

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | Parse a string using the <a>Read</a> instance. Succeeds if there is
--   exactly one valid result.
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "123" :: Maybe Int
--   Just 123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "hello" :: Maybe Int
--   Nothing
--   </pre>
readMaybe :: Read a => String -> Maybe a

-- | the deep analogue of <a>$!</a>. In the expression <tt>f $!! x</tt>,
--   <tt>x</tt> is fully evaluated before the function <tt>f</tt> is
--   applied to it.
($!!) :: NFData a => (a -> b) -> a -> b
infixr 0 $!!

-- | <a>rnf</a> should reduce its argument to normal form (that is, fully
--   evaluate all sub-components), and then return <tt>()</tt>.
--   
--   <h3><a>Generic</a> <a>NFData</a> deriving</h3>
--   
--   Starting with GHC 7.2, you can automatically derive instances for
--   types possessing a <a>Generic</a> instance.
--   
--   Note: <a>Generic1</a> can be auto-derived starting with GHC 7.4
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics (Generic, Generic1)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1)
--   
--   instance NFData a =&gt; NFData (Foo a)
--   instance NFData1 Foo
--   
--   data Colour = Red | Green | Blue
--                 deriving Generic
--   
--   instance NFData Colour
--   </pre>
--   
--   Starting with GHC 7.10, the example above can be written more
--   concisely by enabling the new <tt>DeriveAnyClass</tt> extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1, NFData, NFData1)
--   
--   data Colour = Red | Green | Blue
--                 deriving (Generic, NFData)
--   </pre>
--   
--   <h3>Compatibility with previous <tt>deepseq</tt> versions</h3>
--   
--   Prior to version 1.4.0.0, the default implementation of the <a>rnf</a>
--   method was defined as
--   
--   <pre>
--   <a>rnf</a> a = <a>seq</a> a ()
--   </pre>
--   
--   However, starting with <tt>deepseq-1.4.0.0</tt>, the default
--   implementation is based on <tt>DefaultSignatures</tt> allowing for
--   more accurate auto-derived <a>NFData</a> instances. If you need the
--   previously used exact default <a>rnf</a> method implementation
--   semantics, use
--   
--   <pre>
--   instance NFData Colour where rnf x = seq x ()
--   </pre>
--   
--   or alternatively
--   
--   <pre>
--   instance NFData Colour where rnf = rwhnf
--   </pre>
--   
--   or
--   
--   <pre>
--   {-# LANGUAGE BangPatterns #-}
--   instance NFData Colour where rnf !_ = ()
--   </pre>
rnf :: NFData a => a -> ()

-- | <a>deepseq</a>: fully evaluates the first argument, before returning
--   the second.
--   
--   The name <a>deepseq</a> is used to illustrate the relationship to
--   <a>seq</a>: where <a>seq</a> is shallow in the sense that it only
--   evaluates the top level of its argument, <a>deepseq</a> traverses the
--   entire data structure evaluating it completely.
--   
--   <a>deepseq</a> can be useful for forcing pending exceptions,
--   eradicating space leaks, or forcing lazy I/O to happen. It is also
--   useful in conjunction with parallel Strategies (see the
--   <tt>parallel</tt> package).
--   
--   There is no guarantee about the ordering of evaluation. The
--   implementation may evaluate the components of the structure in any
--   order or in parallel. To impose an actual order on evaluation, use
--   <tt>pseq</tt> from <a>Control.Parallel</a> in the <tt>parallel</tt>
--   package.
deepseq :: NFData a => a -> b -> b

-- | a variant of <a>deepseq</a> that is useful in some circumstances:
--   
--   <pre>
--   force x = x `deepseq` x
--   </pre>
--   
--   <tt>force x</tt> fully evaluates <tt>x</tt>, and then returns it. Note
--   that <tt>force x</tt> only performs evaluation when the value of
--   <tt>force x</tt> itself is demanded, so essentially it turns shallow
--   evaluation into deep evaluation.
--   
--   <a>force</a> can be conveniently used in combination with
--   <tt>ViewPatterns</tt>:
--   
--   <pre>
--   {-# LANGUAGE BangPatterns, ViewPatterns #-}
--   import Control.DeepSeq
--   
--   someFun :: ComplexData -&gt; SomeResult
--   someFun (force -&gt; !arg) = {- 'arg' will be fully evaluated -}
--   </pre>
--   
--   Another useful application is to combine <a>force</a> with
--   <a>evaluate</a> in order to force deep evaluation relative to other
--   <a>IO</a> operations:
--   
--   <pre>
--   import Control.Exception (evaluate)
--   import Control.DeepSeq
--   
--   main = do
--     result &lt;- evaluate $ force $ pureComputation
--     {- 'result' will be fully evaluated at this point -}
--     return ()
--   </pre>
--   
--   Finally, here's an exception safe variant of the <tt>readFile'</tt>
--   example:
--   
--   <pre>
--   readFile' :: FilePath -&gt; IO String
--   readFile' fn = bracket (openFile fn ReadMode) hClose $ \h -&gt;
--                          evaluate . force =&lt;&lt; hGetContents h
--   </pre>
force :: NFData a => a -> a

-- | Since <a>Void</a> values logically don't exist, this witnesses the
--   logical reasoning tool of "ex falso quodlibet".
--   
--   <pre>
--   &gt;&gt;&gt; let x :: Either Void Int; x = Right 5
--   
--   &gt;&gt;&gt; :{
--   case x of
--       Right r -&gt; r
--       Left l  -&gt; absurd l
--   :}
--   5
--   </pre>
absurd :: Void -> a

-- | Lift a computation from the argument monad to the constructed monad.
lift :: (MonadTrans t, Monad m) => m a -> t m a

-- | Retrieves the monad environment.
ask :: MonadReader r m => m r

-- | Retrieves a function of the current environment.
asks :: MonadReader r m => (r -> a) -> m a

-- | Executes a computation in a modified environment.
local :: MonadReader r m => (r -> r) -> m a -> m a

-- | Runs a <tt>Reader</tt> and extracts the final value from it. (The
--   inverse of <a>reader</a>.)
runReader :: Reader r a -> r -> a
runReaderT :: ReaderT r m a -> r -> m a
toStrictBytes :: LByteString -> ByteString
fromStrictBytes :: ByteString -> LByteString

-- | <i>O(n)</i>. Convert a <a>ByteString</a> into a
--   <a>ShortByteString</a>.
--   
--   This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a
--   <a>ByteString</a>.
fromShort :: ShortByteString -> ByteString
tshow :: Show a => a -> Text
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 UTF-8 encoded text.
--   
--   <b>NOTE</b>: The replacement character returned by
--   <a>OnDecodeError</a> MUST be within the BMP plane; surrogate code
--   points will automatically be remapped to the replacement char
--   <tt>U+FFFD</tt> (<i>since 0.11.3.0</i>), whereas code points beyond
--   the BMP will throw an <a>error</a> (<i>since 1.2.3.1</i>); For earlier
--   versions of <tt>text</tt> using those unsupported code points would
--   result in undefined behavior.
decodeUtf8With :: OnDecodeError -> ByteString -> Text

-- | Encode text using UTF-8 encoding.
encodeUtf8 :: Text -> ByteString

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

-- | Replace an invalid input byte with the Unicode replacement character
--   U+FFFD.
lenientDecode :: OnDecodeError

-- | Execute a primitive operation.
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a

-- | Return the value computed by a state thread. The <tt>forall</tt>
--   ensures that the internal state used by the <a>ST</a> computation is
--   inaccessible to the rest of the program.
runST :: (forall s. () => ST s a) -> a

module RIO.Deque

-- | A double-ended queue supporting any underlying vector type and any
--   monad.
--   
--   This implements a circular double-ended queue with exponential growth.
data Deque v s a

-- | A <a>Deque</a> specialized to unboxed vectors.
type UDeque = Deque MVector

-- | A <a>Deque</a> specialized to storable vectors.
type SDeque = Deque MVector

-- | A <a>Deque</a> specialized to boxed vectors.
type BDeque = Deque MVector

-- | Create a new, empty <a>Deque</a>
newDeque :: (MVector v a, PrimMonad m) => m (Deque v (PrimState m) a)

-- | <i>O(1)</i> - Get the number of elements that is currently in the
--   <a>Deque</a>
getDequeSize :: PrimMonad m => Deque v (PrimState m) a -> m Int

-- | Pop the first value from the beginning of the <a>Deque</a>
popFrontDeque :: (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (Maybe a)

-- | Pop the first value from the end of the <a>Deque</a>
popBackDeque :: (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (Maybe a)

-- | Push a new value to the beginning of the <a>Deque</a>
pushFrontDeque :: (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> a -> m ()

-- | Push a new value to the end of the <a>Deque</a>
pushBackDeque :: (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> a -> m ()

-- | Fold over a <a>Deque</a>, starting at the beginning. Does not modify
--   the <a>Deque</a>.
foldlDeque :: (MVector v a, PrimMonad m) => (acc -> a -> m acc) -> acc -> Deque v (PrimState m) a -> m acc

-- | Fold over a <a>Deque</a>, starting at the end. Does not modify the
--   <a>Deque</a>.
foldrDeque :: (MVector v a, PrimMonad m) => (a -> acc -> m acc) -> acc -> Deque v (PrimState m) a -> m acc

-- | Convert a <a>Deque</a> into a list. Does not modify the <a>Deque</a>.
dequeToList :: (MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m [a]

-- | Convert to an immutable vector of any type. If resulting pure vector
--   corresponds to the mutable one used by the <a>Deque</a>, it will be
--   more efficient to use <a>freezeDeque</a> instead.
--   
--   <h4><b>Example</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; import qualified RIO.Vector.Unboxed as U
--   
--   &gt;&gt;&gt; import qualified RIO.Vector.Storable as S
--   
--   &gt;&gt;&gt; d &lt;- newDeque @U.MVector @Int
--   
--   &gt;&gt;&gt; mapM_ (pushFrontDeque d) [0..10]
--   
--   &gt;&gt;&gt; dequeToVector @S.Vector d
--   [10,9,8,7,6,5,4,3,2,1,0]
--   </pre>
dequeToVector :: (Vector v' a, MVector v a, PrimMonad m) => Deque v (PrimState m) a -> m (v' a)

-- | Yield an immutable copy of the underlying mutable vector. The
--   difference from <a>dequeToVector</a> is that the the copy will be
--   performed with a more efficient <tt>memcpy</tt>, rather than element
--   by element. The downside is that the resulting vector type must be the
--   one that corresponds to the mutable one that is used in the
--   <a>Deque</a>.
--   
--   <h4><b>Example</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; import qualified RIO.Vector.Unboxed as U
--   
--   &gt;&gt;&gt; d &lt;- newDeque @U.MVector @Int
--   
--   &gt;&gt;&gt; mapM_ (pushFrontDeque d) [0..10]
--   
--   &gt;&gt;&gt; freezeDeque @U.Vector d
--   [10,9,8,7,6,5,4,3,2,1,0]
--   </pre>
freezeDeque :: (Vector v a, PrimMonad m) => Deque (Mutable v) (PrimState m) a -> m (v a)

-- | Helper function to assist with type inference, forcing usage of an
--   unboxed vector.
asUDeque :: UDeque s a -> UDeque s a

-- | Helper function to assist with type inference, forcing usage of a
--   storable vector.
asSDeque :: SDeque s a -> SDeque s a

-- | Helper function to assist with type inference, forcing usage of a
--   boxed vector.
asBDeque :: BDeque s a -> BDeque s a


-- | Interacting with external processes.
--   
--   This module provides a layer on top of <a>System.Process.Typed</a>,
--   with the following additions:
--   
--   <ul>
--   <li>For efficiency, it will cache <tt>PATH</tt> lookups.</li>
--   <li>For convenience, you can set the working directory and env vars
--   overrides in a <a>RIO</a> environment instead of on the individual
--   calls to the process.</li>
--   <li>Built-in support for logging at the debug level.</li>
--   </ul>
--   
--   In order to switch over to this API, the main idea is:
--   
--   <ul>
--   <li>Like most of the rio library, you need to create an environment
--   value (this time <a>ProcessContext</a>), and include it in your
--   <a>RIO</a> environment. See <a>mkProcessContext</a>.</li>
--   <li>Instead of using the <a>proc</a> function from
--   <a>System.Process.Typed</a> for creating a <a>ProcessConfig</a>, use
--   the locally defined <a>proc</a> function, which will handle overriding
--   environment variables, looking up paths, performing logging, etc.</li>
--   </ul>
--   
--   Once you have your <a>ProcessConfig</a>, use the standard functions
--   from <a>Typed</a> (reexported here for convenient) for running the
--   <a>ProcessConfig</a>.
module RIO.Process

-- | Context in which to run processes.
data ProcessContext

-- | Get the <a>ProcessContext</a> from the environment.
class HasProcessContext env
processContextL :: HasProcessContext env => Lens' env ProcessContext

-- | The environment variable map
type EnvVars = Map Text Text

-- | Create a new <a>ProcessContext</a> from the given environment variable
--   map.
mkProcessContext :: MonadIO m => EnvVars -> m ProcessContext

-- | Same as <a>mkProcessContext</a> but uses the system environment (from
--   <a>getEnvironment</a>).
mkDefaultProcessContext :: MonadIO m => m ProcessContext

-- | Modify the environment variables of a <a>ProcessContext</a>. This will
--   not change the working directory.
--   
--   Note that this requires <a>MonadIO</a>, as it will create a new
--   <a>IORef</a> for the cache.
modifyEnvVars :: MonadIO m => ProcessContext -> (EnvVars -> EnvVars) -> m ProcessContext

-- | Use <a>modifyEnvVars</a> to create a new <a>ProcessContext</a>, and
--   then use it in the provided action.
withModifyEnvVars :: (HasProcessContext env, MonadReader env m, MonadIO m) => (EnvVars -> EnvVars) -> m a -> m a

-- | Look into the <a>ProcessContext</a> and return the specified
--   environmet variable if one is available.
lookupEnvFromContext :: (MonadReader env m, HasProcessContext env) => Text -> m (Maybe Text)

-- | Set the working directory to be used by child processes.
withWorkingDir :: (HasProcessContext env, MonadReader env m, MonadIO m) => FilePath -> m a -> m a

-- | Override the working directory processes run in. <tt>Nothing</tt>
--   means the current process's working directory.
workingDirL :: HasProcessContext env => Lens' env (Maybe FilePath)

-- | Get the environment variables. We cannot provide a <tt>Lens</tt> here,
--   since updating the environment variables requires an <tt>IO</tt>
--   action to allocate a new <tt>IORef</tt> for holding the executable
--   path cache.
envVarsL :: HasProcessContext env => SimpleGetter env EnvVars

-- | Get the <a>EnvVars</a> as an associated list of <a>String</a>s.
--   
--   Useful for interacting with other libraries.
envVarsStringsL :: HasProcessContext env => SimpleGetter env [(String, String)]

-- | Get the list of directories searched for executables (the
--   <tt>PATH</tt>).
--   
--   Similar to <tt>envVarMapL</tt>, this cannot be a full <tt>Lens</tt>.
exeSearchPathL :: HasProcessContext env => SimpleGetter env [FilePath]

-- | Reset the executable cache.
resetExeCache :: (MonadIO m, MonadReader env m, HasProcessContext env) => m ()

-- | Provide a <a>ProcessConfig</a> based on the <a>ProcessContext</a> in
--   scope. Deals with resolving the full path, setting the child process's
--   environment variables, setting the working directory, and wrapping the
--   call with <a>withProcessTimeLog</a> for debugging output.
--   
--   This is intended to be analogous to the <tt>proc</tt> function
--   provided by the <tt>System.Process.Typed</tt> module, but has a
--   different type signature to (1) allow it to perform <tt>IO</tt>
--   actions for looking up paths, and (2) allow logging and timing of the
--   running action.
proc :: (HasProcessContext env, HasLogFunc env, MonadReader env m, MonadIO m, HasCallStack) => FilePath -> [String] -> (ProcessConfig () () () -> m a) -> m a

-- | Same as <a>withProcess</a>, but generalized to <a>MonadUnliftIO</a>.

-- | <i>Deprecated: Please consider using withProcessWait, or instead use
--   withProcessTerm</i>
withProcess :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcess_</a>, but generalized to <a>MonadUnliftIO</a>.

-- | <i>Deprecated: Please consider using withProcessWait, or instead use
--   withProcessTerm</i>
withProcess_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcessWait</a>, but generalized to
--   <a>MonadUnliftIO</a>.
withProcessWait :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcessWait_</a>, but generalized to
--   <a>MonadUnliftIO</a>.
withProcessWait_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcessTerm</a>, but generalized to
--   <a>MonadUnliftIO</a>.
withProcessTerm :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcessTerm_</a>, but generalized to
--   <a>MonadUnliftIO</a>.
withProcessTerm_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Execute a process within the configured environment.
--   
--   Execution will not return, because either:
--   
--   1) On non-windows, execution is taken over by execv of the
--   sub-process. This allows signals to be propagated (#527)
--   
--   2) On windows, an <a>ExitCode</a> exception will be thrown.
exec :: (HasProcessContext env, HasLogFunc env) => String -> [String] -> RIO env b

-- | Like <a>exec</a>, but does not use <tt>execv</tt> on non-windows. This
--   way, there is a sub-process, which is helpful in some cases
--   (<a>https://github.com/commercialhaskell/stack/issues/1306</a>).
--   
--   This function only exits by throwing <a>ExitCode</a>.
execSpawn :: (HasProcessContext env, HasLogFunc env) => String -> [String] -> RIO env a

-- | A convenience environment combining a <a>LogFunc</a> and a
--   <a>ProcessContext</a>
data LoggedProcessContext
LoggedProcessContext :: ProcessContext -> LogFunc -> LoggedProcessContext

-- | Run an action using a <a>LoggedProcessContext</a> with default
--   settings and no logging.
withProcessContextNoLogging :: MonadIO m => RIO LoggedProcessContext a -> m a

-- | Exception type which may be generated in this module.
--   
--   <i>NOTE</i> Other exceptions may be thrown by underlying libraries!
data ProcessException
NoPathFound :: ProcessException
ExecutableNotFound :: String -> [FilePath] -> ProcessException
ExecutableNotFoundAt :: FilePath -> ProcessException
PathsInvalidInPath :: [FilePath] -> ProcessException

-- | Check if the given executable exists on the given PATH.
doesExecutableExist :: (MonadIO m, MonadReader env m, HasProcessContext env) => String -> m Bool

-- | Find the complete path for the given executable name.
--   
--   On POSIX systems, filenames that match but are not exectuables are
--   excluded.
--   
--   On Windows systems, the executable names tried, in turn, are the
--   supplied name (only if it has an extension) and that name extended by
--   each of the <a>exeExtensions</a>. Also, this function may behave
--   differently from <a>findExecutable</a>. The latter excludes as
--   executables filenames without a <tt>.bat</tt>, <tt>.cmd</tt>,
--   <tt>.com</tt> or <tt>.exe</tt> extension (case-insensitive).
findExecutable :: (MonadIO m, MonadReader env m, HasProcessContext env) => String -> m (Either ProcessException FilePath)

-- | Get the filename extensions for executable files, including the dot
--   (if any).
--   
--   On POSIX systems, this is <tt>[""]</tt>.
--   
--   On Windows systems, the list is determined by the value of the
--   <tt>PATHEXT</tt> environment variable, if it present in the
--   environment. If the variable is absent, this is its default value on a
--   Windows system. This function may, therefore, behave differently from
--   <a>exeExtension</a>, which returns only <tt>".exe"</tt>.
exeExtensions :: (MonadIO m, MonadReader env m, HasProcessContext env) => m [String]

-- | Augment the PATH environment variable with the given extra paths,
--   which are prepended (as in: they take precedence).
augmentPath :: [FilePath] -> Maybe Text -> Either ProcessException Text

-- | Apply <a>augmentPath</a> on the PATH value in the given
--   <a>EnvVars</a>.
augmentPathMap :: [FilePath] -> EnvVars -> Either ProcessException EnvVars

-- | Show a process arg including speechmarks when necessary. Just for
--   debugging purposes, not functionally important.
showProcessArgDebug :: String -> Text

-- | An abstract configuration for a process, which can then be launched
--   into an actual running <tt>Process</tt>. Takes three type parameters,
--   providing the types of standard input, standard output, and standard
--   error, respectively.
--   
--   There are three ways to construct a value of this type:
--   
--   <ul>
--   <li>With the <a>proc</a> smart constructor, which takes a command name
--   and a list of arguments.</li>
--   <li>With the <a>shell</a> smart constructor, which takes a shell
--   string</li>
--   <li>With the <a>IsString</a> instance via OverloadedStrings. If you
--   provide it a string with no spaces (e.g., <tt>"date"</tt>), it will
--   treat it as a raw command with no arguments (e.g., <tt>proc "date"
--   []</tt>). If it has spaces, it will use <tt>shell</tt>.</li>
--   </ul>
--   
--   In all cases, the default for all three streams is to inherit the
--   streams from the parent process. For other settings, see the
--   <a>setters below</a> for default values.
--   
--   Once you have a <tt>ProcessConfig</tt> you can launch a process from
--   it using the functions in the section <a>Launch a process</a>.
data ProcessConfig stdin stdout stderr

-- | A specification for how to create one of the three standard child
--   streams, <tt>stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt>. A
--   <a>StreamSpec</a> can be thought of as containing
--   
--   <ol>
--   <li>A type safe version of <a>StdStream</a> from
--   <a>System.Process</a>. This determines whether the stream should be
--   inherited from the parent process, piped to or from a <a>Handle</a>,
--   etc.</li>
--   <li>A means of accessing the stream as a value of type <tt>a</tt></li>
--   <li>A cleanup action which will be run on the stream once the process
--   terminates</li>
--   </ol>
--   
--   To create a <tt>StreamSpec</tt> see the section <a>Stream specs</a>.
data StreamSpec (streamType :: StreamType) a

-- | Whether a stream is an input stream or output stream. Note that this
--   is from the perspective of the <i>child process</i>, so that a child's
--   standard input stream is an <tt>STInput</tt>, even though the parent
--   process will be writing to it.
data StreamType
STInput :: StreamType
STOutput :: StreamType

-- | A running process. The three type parameters provide the type of the
--   standard input, standard output, and standard error streams.
--   
--   To interact with a <tt>Process</tt> use the functions from the section
--   <a>Interact with a process</a>.
data Process stdin stdout stderr

-- | Set the child's standard input stream to the given <a>StreamSpec</a>.
--   
--   Default: <a>inherit</a>
setStdin :: StreamSpec 'STInput stdin -> ProcessConfig stdin0 stdout stderr -> ProcessConfig stdin stdout stderr

-- | Set the child's standard output stream to the given <a>StreamSpec</a>.
--   
--   Default: <a>inherit</a>
setStdout :: StreamSpec 'STOutput stdout -> ProcessConfig stdin stdout0 stderr -> ProcessConfig stdin stdout stderr

-- | Set the child's standard error stream to the given <a>StreamSpec</a>.
--   
--   Default: <a>inherit</a>
setStderr :: StreamSpec 'STOutput stderr -> ProcessConfig stdin stdout stderr0 -> ProcessConfig stdin stdout stderr

-- | Should we close all file descriptors besides stdin, stdout, and
--   stderr? See <a>close_fds</a> for more information.
--   
--   Default: False
setCloseFds :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Should we create a new process group?
--   
--   Default: False
setCreateGroup :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Delegate handling of Ctrl-C to the child. For more information, see
--   <a>delegate_ctlc</a>.
--   
--   Default: False
setDelegateCtlc :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Detach console on Windows, see <a>detach_console</a>.
--   
--   Default: False
setDetachConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Create new console on Windows, see <a>create_new_console</a>.
--   
--   Default: False
setCreateNewConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Set a new session with the POSIX <tt>setsid</tt> syscall, does nothing
--   on non-POSIX. See <a>new_session</a>.
--   
--   Default: False
setNewSession :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Set the child process's group ID with the POSIX <tt>setgid</tt>
--   syscall, does nothing on non-POSIX. See <a>child_group</a>.
--   
--   Default: False
setChildGroup :: GroupID -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Set the child process's user ID with the POSIX <tt>setuid</tt>
--   syscall, does nothing on non-POSIX. See <a>child_user</a>.
--   
--   Default: False
setChildUser :: UserID -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | Create a new <a>StreamSpec</a> from the given <a>StdStream</a> and a
--   helper function. This function:
--   
--   <ul>
--   <li>Takes as input the raw <tt>Maybe Handle</tt> returned by the
--   <a>createProcess</a> function. The handle will be <tt>Just</tt>
--   <a>Handle</a> if the <a>StdStream</a> argument is <a>CreatePipe</a>
--   and <tt>Nothing</tt> otherwise. See <a>createProcess</a> for more
--   details.</li>
--   <li>Returns the actual stream value <tt>a</tt>, as well as a cleanup
--   function to be run when calling <tt>stopProcess</tt>.</li>
--   </ul>
--   
--   If making a <a>StreamSpec</a> with <a>CreatePipe</a>, prefer
--   <a>mkPipeStreamSpec</a>, which encodes the invariant that a
--   <a>Handle</a> is created.
mkStreamSpec :: forall a (streamType :: StreamType). StdStream -> (ProcessConfig () () () -> Maybe Handle -> IO (a, IO ())) -> StreamSpec streamType a

-- | A stream spec which simply inherits the stream of the parent process.
inherit :: forall (anyStreamType :: StreamType). StreamSpec anyStreamType ()

-- | A stream spec which will close the stream for the child process. You
--   usually do not want to use this, as it will leave the corresponding
--   file descriptor unassigned and hence available for re-use in the child
--   process. Prefer <a>nullStream</a> unless you're certain you want this
--   behavior.
closed :: forall (anyStreamType :: StreamType). StreamSpec anyStreamType ()

-- | An input stream spec which sets the input to the given
--   <a>ByteString</a>. A separate thread will be forked to write the
--   contents to the child process.
byteStringInput :: ByteString -> StreamSpec 'STInput ()

-- | Capture the output of a process in a <a>ByteString</a>.
--   
--   This function will fork a separate thread to consume all input from
--   the process, and will only make the results available when the
--   underlying <a>Handle</a> is closed. As this is provided as an
--   <a>STM</a> action, you can either check if the result is available, or
--   block until it's ready.
--   
--   In the event of any exception occurring when reading from the
--   <a>Handle</a>, the <a>STM</a> action will throw a
--   <a>ByteStringOutputException</a>.
byteStringOutput :: StreamSpec 'STOutput (STM ByteString)

-- | Create a new pipe between this process and the child, and return a
--   <a>Handle</a> to communicate with the child.
createPipe :: forall (anyStreamType :: StreamType). StreamSpec anyStreamType Handle

-- | Use the provided <a>Handle</a> for the child process, and when the
--   process exits, do <i>not</i> close it. This is useful if, for example,
--   you want to have multiple processes write to the same log file
--   sequentially.
useHandleOpen :: forall (anyStreamType :: StreamType). Handle -> StreamSpec anyStreamType ()

-- | Use the provided <a>Handle</a> for the child process, and when the
--   process exits, close it. If you have no reason to keep the
--   <a>Handle</a> open, you should use this over <a>useHandleOpen</a>.
useHandleClose :: forall (anyStreamType :: StreamType). Handle -> StreamSpec anyStreamType ()

-- | Launch a process based on the given <a>ProcessConfig</a>. You should
--   ensure that you call <a>stopProcess</a> on the result. It's usually
--   better to use one of the functions in this module which ensures
--   <a>stopProcess</a> is called, such as <a>withProcessWait</a>.
startProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m (Process stdin stdout stderr)

-- | Close a process and release any resources acquired. This will ensure
--   <a>terminateProcess</a> is called, wait for the process to actually
--   exit, and then close out resources allocated for the streams. In the
--   event of any cleanup exceptions being thrown this will throw an
--   exception.
stopProcess :: MonadIO m => Process stdin stdout stderr -> m ()

-- | Run a process, capture its standard output and error as a
--   <a>ByteString</a>, wait for it to complete, and then return its exit
--   code, output, and error.
--   
--   Note that any previously used <a>setStdout</a> or <a>setStderr</a>
--   will be overridden.
readProcess :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ExitCode, ByteString, ByteString)

-- | Same as <a>readProcess</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stdout and stderr.
readProcess_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ByteString, ByteString)

-- | Run the given process, wait for it to exit, and returns its
--   <a>ExitCode</a>.
runProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m ExitCode

-- | Same as <a>runProcess</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
runProcess_ :: MonadIO m => ProcessConfig stdin stdout stderr -> m ()

-- | Same as <a>readProcess</a>, but only read the stdout of the process.
--   Original settings for stderr remain.
readProcessStdout :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m (ExitCode, ByteString)

-- | Same as <a>readProcessStdout</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stdout.
readProcessStdout_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m ByteString

-- | Same as <a>readProcess</a>, but only read the stderr of the process.
--   Original settings for stdout remain.
readProcessStderr :: MonadIO m => ProcessConfig stdin stdout stderrIgnored -> m (ExitCode, ByteString)

-- | Same as <a>readProcessStderr</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stderr.
readProcessStderr_ :: MonadIO m => ProcessConfig stdin stdout stderrIgnored -> m ByteString

-- | Wait for the process to exit and then return its <a>ExitCode</a>.
waitExitCode :: MonadIO m => Process stdin stdout stderr -> m ExitCode

-- | Same as <a>waitExitCode</a>, but in <a>STM</a>.
waitExitCodeSTM :: Process stdin stdout stderr -> STM ExitCode

-- | Check if a process has exited and, if so, return its <a>ExitCode</a>.
getExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode)

-- | Same as <a>getExitCode</a>, but in <a>STM</a>.
getExitCodeSTM :: Process stdin stdout stderr -> STM (Maybe ExitCode)

-- | Wait for a process to exit, and ensure that it exited successfully. If
--   not, throws an <a>ExitCodeException</a>.
--   
--   Exceptions thrown by this function will not include stdout or stderr
--   (This prevents unbounded memory usage from reading them into memory).
--   However, some callers such as <a>readProcess_</a> catch the exception,
--   add the stdout and stderr, and rethrow.
checkExitCode :: MonadIO m => Process stdin stdout stderr -> m ()

-- | Same as <a>checkExitCode</a>, but in <a>STM</a>.
checkExitCodeSTM :: Process stdin stdout stderr -> STM ()

-- | Get the child's standard input stream value.
getStdin :: Process stdin stdout stderr -> stdin

-- | Get the child's standard output stream value.
getStdout :: Process stdin stdout stderr -> stdout

-- | Get the child's standard error stream value.
getStderr :: Process stdin stdout stderr -> stderr

-- | Exception thrown by <tt>checkExitCode</tt> in the event of a
--   non-success exit code. Note that <tt>checkExitCode</tt> is called by
--   other functions as well, like <tt>runProcess_</tt> or
--   <tt>readProcess_</tt>.
--   
--   Note that several functions that throw an <a>ExitCodeException</a>
--   intentionally do not populate <a>eceStdout</a> or <a>eceStderr</a>.
--   This prevents unbounded memory usage for large stdout and stderrs.
data ExitCodeException
ExitCodeException :: ExitCode -> ProcessConfig () () () -> ByteString -> ByteString -> ExitCodeException
[eceExitCode] :: ExitCodeException -> ExitCode
[eceProcessConfig] :: ExitCodeException -> ProcessConfig () () ()
[eceStdout] :: ExitCodeException -> ByteString
[eceStderr] :: ExitCodeException -> ByteString

-- | Wrapper for when an exception is thrown when reading from a child
--   process, used by <a>byteStringOutput</a>.
data ByteStringOutputException
ByteStringOutputException :: SomeException -> ProcessConfig () () () -> ByteStringOutputException

-- | Take <a>ProcessHandle</a> out of the <a>Process</a>. This method is
--   needed in cases one need to use low level functions from the
--   <tt>process</tt> package. Use cases for this method are:
--   
--   <ol>
--   <li>Send a special signal to the process.</li>
--   <li>Terminate the process group instead of terminating single
--   process.</li>
--   <li>Use platform specific API on the underlying process.</li>
--   </ol>
--   
--   This method is considered unsafe because the actions it performs on
--   the underlying process may overlap with the functionality that
--   <tt>typed-process</tt> provides. For example the user should not call
--   <a>waitForProcess</a> on the process handle as either
--   <a>waitForProcess</a> or <a>stopProcess</a> will lock. Additionally,
--   even if process was terminated by the <a>terminateProcess</a> or by
--   sending signal, <a>stopProcess</a> should be called either way in
--   order to cleanup resources allocated by the <tt>typed-process</tt>.
unsafeProcessHandle :: Process stdin stdout stderr -> ProcessHandle
instance GHC.Classes.Eq RIO.Process.ProcessException
instance RIO.Prelude.Logger.HasLogFunc RIO.Process.LoggedProcessContext
instance RIO.Process.HasProcessContext RIO.Process.LoggedProcessContext
instance RIO.Process.HasProcessContext RIO.Process.ProcessContext
instance GHC.Show.Show RIO.Process.ProcessException
instance GHC.Exception.Type.Exception RIO.Process.ProcessException


-- | Provide a <tt><a>SimpleApp</a></tt> datatype, for providing a basic
--   <tt>App</tt>-like environment with common functionality built in. This
--   is intended to make it easier to, e.g., use rio's logging and process
--   code from within short scripts.
module RIO.Prelude.Simple

-- | A simple, non-customizable environment type for <tt>RIO</tt>, which
--   provides common functionality. If it's insufficient for your needs,
--   define your own, custom <tt>App</tt> data type.
data SimpleApp

-- | Constructor for <a>SimpleApp</a>. In case when <a>ProcessContext</a>
--   is not supplied <a>mkDefaultProcessContext</a> will be used to create
--   it.
mkSimpleApp :: MonadIO m => LogFunc -> Maybe ProcessContext -> m SimpleApp

-- | Run with a default configured <tt>SimpleApp</tt>, consisting of:
--   
--   <ul>
--   <li>Logging to stderr</li>
--   <li>If the <tt>RIO_VERBOSE</tt> environment variable is set, turns on
--   verbose logging</li>
--   <li>Default process context</li>
--   </ul>
runSimpleApp :: MonadIO m => RIO SimpleApp a -> m a
instance RIO.Prelude.Logger.HasLogFunc RIO.Prelude.Simple.SimpleApp
instance RIO.Process.HasProcessContext RIO.Prelude.Simple.SimpleApp


-- | <tt>Seq</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Seq as Seq
--   </pre>
module RIO.Seq

-- | General-purpose finite sequences.
data Seq a

-- | A bidirectional pattern synonym matching an empty sequence.
pattern Empty :: Seq a

-- | A bidirectional pattern synonym viewing the rear of a non-empty
--   sequence.
pattern (:|>) :: Seq a -> a -> Seq a

-- | A bidirectional pattern synonym viewing the front of a non-empty
--   sequence.
pattern (:<|) :: a -> Seq a -> Seq a
infixl 5 :|>
infixr 5 :<|

-- | &lt;math&gt;. The empty sequence.
empty :: Seq a

-- | &lt;math&gt;. A singleton sequence.
singleton :: a -> Seq a

-- | &lt;math&gt;. Add an element to the left end of a sequence. Mnemonic:
--   a triangle with the single element at the pointy end.
(<|) :: a -> Seq a -> Seq a
infixr 5 <|

-- | &lt;math&gt;. Add an element to the right end of a sequence. Mnemonic:
--   a triangle with the single element at the pointy end.
(|>) :: Seq a -> a -> Seq a
infixl 5 |>

-- | &lt;math&gt;. Concatenate two sequences.
(><) :: Seq a -> Seq a -> Seq a
infixr 5 ><

-- | &lt;math&gt;. Create a sequence from a finite list of elements. There
--   is a function <a>toList</a> in the opposite direction for all
--   instances of the <a>Foldable</a> class, including <a>Seq</a>.
fromList :: [a] -> Seq a

-- | &lt;math&gt;. Convert a given sequence length and a function
--   representing that sequence into a sequence.
fromFunction :: Int -> (Int -> a) -> Seq a

-- | &lt;math&gt;. Create a sequence consisting of the elements of an
--   <a>Array</a>. Note that the resulting sequence elements may be
--   evaluated lazily (as on GHC), so you must force the entire structure
--   to be sure that the original array can be garbage-collected.
fromArray :: Ix i => Array i a -> Seq a

-- | &lt;math&gt;. <tt>replicate n x</tt> is a sequence consisting of
--   <tt>n</tt> copies of <tt>x</tt>.
replicate :: Int -> a -> Seq a

-- | <a>replicateA</a> is an <a>Applicative</a> version of
--   <a>replicate</a>, and makes &lt;math&gt; calls to <a>liftA2</a> and
--   <a>pure</a>.
--   
--   <pre>
--   replicateA n x = sequenceA (replicate n x)
--   </pre>
replicateA :: Applicative f => Int -> f a -> f (Seq a)

-- | <a>replicateM</a> is a sequence counterpart of <a>replicateM</a>.
--   
--   <pre>
--   replicateM n x = sequence (replicate n x)
--   </pre>
--   
--   For <tt>base &gt;= 4.8.0</tt> and <tt>containers &gt;= 0.5.11</tt>,
--   <a>replicateM</a> is a synonym for <a>replicateA</a>.
replicateM :: Applicative m => Int -> m a -> m (Seq a)

-- | <i>O(</i>log<i> k)</i>. <tt><a>cycleTaking</a> k xs</tt> forms a
--   sequence of length <tt>k</tt> by repeatedly concatenating <tt>xs</tt>
--   with itself. <tt>xs</tt> may only be empty if <tt>k</tt> is 0.
--   
--   <pre>
--   cycleTaking k = fromList . take k . cycle . toList
--   </pre>
cycleTaking :: Int -> Seq a -> Seq a

-- | &lt;math&gt;. Constructs a sequence by repeated application of a
--   function to a seed value.
--   
--   <pre>
--   iterateN n f x = fromList (Prelude.take n (Prelude.iterate f x))
--   </pre>
iterateN :: Int -> (a -> a) -> a -> Seq a

-- | Builds a sequence from a seed value. Takes time linear in the number
--   of generated elements. <i>WARNING:</i> If the number of generated
--   elements is infinite, this method will not terminate.
unfoldr :: (b -> Maybe (a, b)) -> b -> Seq a

-- | <tt><a>unfoldl</a> f x</tt> is equivalent to <tt><a>reverse</a>
--   (<a>unfoldr</a> (<a>fmap</a> swap . f) x)</tt>.
unfoldl :: (b -> Maybe (b, a)) -> b -> Seq a

-- | &lt;math&gt;. Is this the empty sequence?
null :: Seq a -> Bool

-- | &lt;math&gt;. The number of elements in the sequence.
length :: Seq a -> Int

-- | View of the left end of a sequence.
data ViewL a

-- | empty sequence
EmptyL :: ViewL a

-- | leftmost element and the rest of the sequence
(:<) :: a -> Seq a -> ViewL a
infixr 5 :<

-- | &lt;math&gt;. Analyse the left end of a sequence.
viewl :: Seq a -> ViewL a

-- | View of the right end of a sequence.
data ViewR a

-- | empty sequence
EmptyR :: ViewR a

-- | the sequence minus the rightmost element, and the rightmost element
(:>) :: Seq a -> a -> ViewR a
infixl 5 :>

-- | &lt;math&gt;. Analyse the right end of a sequence.
viewr :: Seq a -> ViewR a

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a sequence of
--   reduced values from the left:
--   
--   <pre>
--   scanl f z (fromList [x1, x2, ...]) = fromList [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
scanl :: (a -> b -> a) -> a -> Seq b -> Seq a

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f (fromList [x1, x2, ...]) = fromList [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (a -> a -> a) -> Seq a -> Seq a

-- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>.
scanr :: (a -> b -> b) -> b -> Seq a -> Seq b

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (a -> a -> a) -> Seq a -> Seq a

-- | &lt;math&gt;. Returns a sequence of all suffixes of this sequence,
--   longest first. For example,
--   
--   <pre>
--   tails (fromList "abc") = fromList [fromList "abc", fromList "bc", fromList "c", fromList ""]
--   </pre>
--   
--   Evaluating the &lt;math&gt;th suffix takes &lt;math&gt;, but
--   evaluating every suffix in the sequence takes &lt;math&gt; due to
--   sharing.
tails :: Seq a -> Seq (Seq a)

-- | &lt;math&gt;. Returns a sequence of all prefixes of this sequence,
--   shortest first. For example,
--   
--   <pre>
--   inits (fromList "abc") = fromList [fromList "", fromList "a", fromList "ab", fromList "abc"]
--   </pre>
--   
--   Evaluating the &lt;math&gt;th prefix takes &lt;math&gt;, but
--   evaluating every prefix in the sequence takes &lt;math&gt; due to
--   sharing.
inits :: Seq a -> Seq (Seq a)

-- | &lt;math&gt;. <tt>chunksOf c xs</tt> splits <tt>xs</tt> into chunks of
--   size <tt>c&gt;0</tt>. If <tt>c</tt> does not divide the length of
--   <tt>xs</tt> evenly, then the last element of the result will be short.
--   
--   Side note: the given performance bound is missing some messy terms
--   that only really affect edge cases. Performance degrades smoothly from
--   &lt;math&gt; (for &lt;math&gt;) to &lt;math&gt; (for &lt;math&gt;).
--   The true bound is more like &lt;math&gt;
chunksOf :: Int -> Seq a -> Seq (Seq a)

-- | &lt;math&gt; where &lt;math&gt; is the prefix length.
--   <a>takeWhileL</a>, applied to a predicate <tt>p</tt> and a sequence
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhileL :: (a -> Bool) -> Seq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the suffix length.
--   <a>takeWhileR</a>, applied to a predicate <tt>p</tt> and a sequence
--   <tt>xs</tt>, returns the longest suffix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
--   
--   <tt><a>takeWhileR</a> p xs</tt> is equivalent to <tt><a>reverse</a>
--   (<a>takeWhileL</a> p (<a>reverse</a> xs))</tt>.
takeWhileR :: (a -> Bool) -> Seq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the prefix length.
--   <tt><a>dropWhileL</a> p xs</tt> returns the suffix remaining after
--   <tt><a>takeWhileL</a> p xs</tt>.
dropWhileL :: (a -> Bool) -> Seq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the suffix length.
--   <tt><a>dropWhileR</a> p xs</tt> returns the prefix remaining after
--   <tt><a>takeWhileR</a> p xs</tt>.
--   
--   <tt><a>dropWhileR</a> p xs</tt> is equivalent to <tt><a>reverse</a>
--   (<a>dropWhileL</a> p (<a>reverse</a> xs))</tt>.
dropWhileR :: (a -> Bool) -> Seq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the prefix length. <a>spanl</a>,
--   applied to a predicate <tt>p</tt> and a sequence <tt>xs</tt>, returns
--   a pair whose first element is the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt> and the second element
--   is the remainder of the sequence.
spanl :: (a -> Bool) -> Seq a -> (Seq a, Seq a)

-- | &lt;math&gt; where &lt;math&gt; is the suffix length. <a>spanr</a>,
--   applied to a predicate <tt>p</tt> and a sequence <tt>xs</tt>, returns
--   a pair whose <i>first</i> element is the longest <i>suffix</i>
--   (possibly empty) of <tt>xs</tt> of elements that satisfy <tt>p</tt>
--   and the second element is the remainder of the sequence.
spanr :: (a -> Bool) -> Seq a -> (Seq a, Seq a)

-- | &lt;math&gt; where &lt;math&gt; is the breakpoint index.
--   <a>breakl</a>, applied to a predicate <tt>p</tt> and a sequence
--   <tt>xs</tt>, returns a pair whose first element is the longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and the second element is the remainder of the sequence.
--   
--   <tt><a>breakl</a> p</tt> is equivalent to <tt><a>spanl</a> (not .
--   p)</tt>.
breakl :: (a -> Bool) -> Seq a -> (Seq a, Seq a)

-- | <tt><a>breakr</a> p</tt> is equivalent to <tt><a>spanr</a> (not .
--   p)</tt>.
breakr :: (a -> Bool) -> Seq a -> (Seq a, Seq a)

-- | &lt;math&gt;. The <a>partition</a> function takes a predicate
--   <tt>p</tt> and a sequence <tt>xs</tt> and returns sequences of those
--   elements which do and do not satisfy the predicate.
partition :: (a -> Bool) -> Seq a -> (Seq a, Seq a)

-- | &lt;math&gt;. The <a>filter</a> function takes a predicate <tt>p</tt>
--   and a sequence <tt>xs</tt> and returns a sequence of those elements
--   which satisfy the predicate.
filter :: (a -> Bool) -> Seq a -> Seq a

-- | &lt;math&gt;. <a>sort</a> sorts the specified <a>Seq</a> by the
--   natural ordering of its elements. The sort is stable. If stability is
--   not required, <a>unstableSort</a> can be slightly faster.
sort :: Ord a => Seq a -> Seq a

-- | &lt;math&gt;. <a>sortBy</a> sorts the specified <a>Seq</a> according
--   to the specified comparator. The sort is stable. If stability is not
--   required, <a>unstableSortBy</a> can be slightly faster.
sortBy :: (a -> a -> Ordering) -> Seq a -> Seq a

-- | &lt;math&gt;. <a>unstableSort</a> sorts the specified <a>Seq</a> by
--   the natural ordering of its elements, but the sort is not stable. This
--   algorithm is frequently faster and uses less memory than <a>sort</a>.
unstableSort :: Ord a => Seq a -> Seq a

-- | &lt;math&gt;. A generalization of <a>unstableSort</a>,
--   <a>unstableSortBy</a> takes an arbitrary comparator and sorts the
--   specified sequence. The sort is not stable. This algorithm is
--   frequently faster and uses less memory than <a>sortBy</a>.
unstableSortBy :: (a -> a -> Ordering) -> Seq a -> Seq a

-- | &lt;math&gt;. The element at the specified position, counting from 0.
--   If the specified position is negative or at least the length of the
--   sequence, <a>lookup</a> returns <a>Nothing</a>.
--   
--   <pre>
--   0 &lt;= i &lt; length xs ==&gt; lookup i xs == Just (toList xs !! i)
--   </pre>
--   
--   <pre>
--   i &lt; 0 || i &gt;= length xs ==&gt; lookup i xs = Nothing
--   </pre>
--   
--   Unlike <a>index</a>, this can be used to retrieve an element without
--   forcing it. For example, to insert the fifth element of a sequence
--   <tt>xs</tt> into a <a>Map</a> <tt>m</tt> at key <tt>k</tt>, you could
--   use
--   
--   <pre>
--   case lookup 5 xs of
--     Nothing -&gt; m
--     Just x -&gt; <a>insert</a> k x m
--   </pre>
lookup :: Int -> Seq a -> Maybe a

-- | &lt;math&gt;. A flipped, infix version of <a>lookup</a>.
(!?) :: Seq a -> Int -> Maybe a

-- | &lt;math&gt;. The element at the specified position, counting from 0.
--   The argument should thus be a non-negative integer less than the size
--   of the sequence. If the position is out of range, <a>index</a> fails
--   with an error.
--   
--   <pre>
--   xs `index` i = toList xs !! i
--   </pre>
--   
--   Caution: <a>index</a> necessarily delays retrieving the requested
--   element until the result is forced. It can therefore lead to a space
--   leak if the result is stored, unforced, in another structure. To
--   retrieve an element immediately without forcing it, use <a>lookup</a>
--   or <a>(!?)</a>.
index :: Seq a -> Int -> a

-- | &lt;math&gt;. Update the element at the specified position. If the
--   position is out of range, the original sequence is returned.
--   <a>adjust</a> can lead to poor performance and even memory leaks,
--   because it does not force the new value before installing it in the
--   sequence. <a>adjust'</a> should usually be preferred.
adjust :: (a -> a) -> Int -> Seq a -> Seq a

-- | &lt;math&gt;. Update the element at the specified position. If the
--   position is out of range, the original sequence is returned. The new
--   value is forced before it is installed in the sequence.
--   
--   <pre>
--   adjust' f i xs =
--    case xs !? i of
--      Nothing -&gt; xs
--      Just x -&gt; let !x' = f x
--                in update i x' xs
--   </pre>
adjust' :: (a -> a) -> Int -> Seq a -> Seq a

-- | &lt;math&gt;. Replace the element at the specified position. If the
--   position is out of range, the original sequence is returned.
update :: Int -> a -> Seq a -> Seq a

-- | &lt;math&gt;. The first <tt>i</tt> elements of a sequence. If
--   <tt>i</tt> is negative, <tt><a>take</a> i s</tt> yields the empty
--   sequence. If the sequence contains fewer than <tt>i</tt> elements, the
--   whole sequence is returned.
take :: Int -> Seq a -> Seq a

-- | &lt;math&gt;. Elements of a sequence after the first <tt>i</tt>. If
--   <tt>i</tt> is negative, <tt><a>drop</a> i s</tt> yields the whole
--   sequence. If the sequence contains fewer than <tt>i</tt> elements, the
--   empty sequence is returned.
drop :: Int -> Seq a -> Seq a

-- | &lt;math&gt;. <tt><a>insertAt</a> i x xs</tt> inserts <tt>x</tt> into
--   <tt>xs</tt> at the index <tt>i</tt>, shifting the rest of the sequence
--   over.
--   
--   <pre>
--   insertAt 2 x (fromList [a,b,c,d]) = fromList [a,b,x,c,d]
--   insertAt 4 x (fromList [a,b,c,d]) = insertAt 10 x (fromList [a,b,c,d])
--                                     = fromList [a,b,c,d,x]
--   </pre>
--   
--   <pre>
--   insertAt i x xs = take i xs &gt;&lt; singleton x &gt;&lt; drop i xs
--   </pre>
insertAt :: Int -> a -> Seq a -> Seq a

-- | &lt;math&gt;. Delete the element of a sequence at a given index.
--   Return the original sequence if the index is out of range.
--   
--   <pre>
--   deleteAt 2 [a,b,c,d] = [a,b,d]
--   deleteAt 4 [a,b,c,d] = deleteAt (-1) [a,b,c,d] = [a,b,c,d]
--   </pre>
deleteAt :: Int -> Seq a -> Seq a

-- | &lt;math&gt;. Split a sequence at a given position. <tt><a>splitAt</a>
--   i s = (<a>take</a> i s, <a>drop</a> i s)</tt>.
splitAt :: Int -> Seq a -> (Seq a, Seq a)

-- | <a>elemIndexL</a> finds the leftmost index of the specified element,
--   if it is present, and otherwise <a>Nothing</a>.
elemIndexL :: Eq a => a -> Seq a -> Maybe Int

-- | <a>elemIndicesL</a> finds the indices of the specified element, from
--   left to right (i.e. in ascending order).
elemIndicesL :: Eq a => a -> Seq a -> [Int]

-- | <a>elemIndexR</a> finds the rightmost index of the specified element,
--   if it is present, and otherwise <a>Nothing</a>.
elemIndexR :: Eq a => a -> Seq a -> Maybe Int

-- | <a>elemIndicesR</a> finds the indices of the specified element, from
--   right to left (i.e. in descending order).
elemIndicesR :: Eq a => a -> Seq a -> [Int]

-- | <tt><a>findIndexL</a> p xs</tt> finds the index of the leftmost
--   element that satisfies <tt>p</tt>, if any exist.
findIndexL :: (a -> Bool) -> Seq a -> Maybe Int

-- | <tt><a>findIndicesL</a> p</tt> finds all indices of elements that
--   satisfy <tt>p</tt>, in ascending order.
findIndicesL :: (a -> Bool) -> Seq a -> [Int]

-- | <tt><a>findIndexR</a> p xs</tt> finds the index of the rightmost
--   element that satisfies <tt>p</tt>, if any exist.
findIndexR :: (a -> Bool) -> Seq a -> Maybe Int

-- | <tt><a>findIndicesR</a> p</tt> finds all indices of elements that
--   satisfy <tt>p</tt>, in descending order.
findIndicesR :: (a -> Bool) -> Seq a -> [Int]
foldMapWithIndex :: Monoid m => (Int -> a -> m) -> Seq a -> m

-- | <a>foldlWithIndex</a> is a version of <a>foldl</a> that also provides
--   access to the index of each element.
foldlWithIndex :: (b -> Int -> a -> b) -> b -> Seq a -> b

-- | <a>foldrWithIndex</a> is a version of <a>foldr</a> that also provides
--   access to the index of each element.
foldrWithIndex :: (Int -> a -> b -> b) -> b -> Seq a -> b

-- | A generalization of <a>fmap</a>, <a>mapWithIndex</a> takes a mapping
--   function that also depends on the element's index, and applies it to
--   every element in the sequence.
mapWithIndex :: (Int -> a -> b) -> Seq a -> Seq b

-- | <a>traverseWithIndex</a> is a version of <a>traverse</a> that also
--   offers access to the index of each element.
traverseWithIndex :: Applicative f => (Int -> a -> f b) -> Seq a -> f (Seq b)

-- | &lt;math&gt;. The reverse of a sequence.
reverse :: Seq a -> Seq a

-- | &lt;math&gt;. Intersperse an element between the elements of a
--   sequence.
--   
--   <pre>
--   intersperse a empty = empty
--   intersperse a (singleton x) = singleton x
--   intersperse a (fromList [x,y]) = fromList [x,a,y]
--   intersperse a (fromList [x,y,z]) = fromList [x,a,y,a,z]
--   </pre>
intersperse :: a -> Seq a -> Seq a

-- | &lt;math&gt;. <a>zip</a> takes two sequences and returns a sequence of
--   corresponding pairs. If one input is short, excess elements are
--   discarded from the right end of the longer sequence.
zip :: Seq a -> Seq b -> Seq (a, b)

-- | &lt;math&gt;. <a>zipWith</a> generalizes <a>zip</a> by zipping with
--   the function given as the first argument, instead of a tupling
--   function. For example, <tt>zipWith (+)</tt> is applied to two
--   sequences to take the sequence of corresponding sums.
zipWith :: (a -> b -> c) -> Seq a -> Seq b -> Seq c

-- | &lt;math&gt;. <a>zip3</a> takes three sequences and returns a sequence
--   of triples, analogous to <a>zip</a>.
zip3 :: Seq a -> Seq b -> Seq c -> Seq (a, b, c)

-- | &lt;math&gt;. <a>zipWith3</a> takes a function which combines three
--   elements, as well as three sequences and returns a sequence of their
--   point-wise combinations, analogous to <a>zipWith</a>.
zipWith3 :: (a -> b -> c -> d) -> Seq a -> Seq b -> Seq c -> Seq d

-- | &lt;math&gt;. <a>zip4</a> takes four sequences and returns a sequence
--   of quadruples, analogous to <a>zip</a>.
zip4 :: Seq a -> Seq b -> Seq c -> Seq d -> Seq (a, b, c, d)

-- | &lt;math&gt;. <a>zipWith4</a> takes a function which combines four
--   elements, as well as four sequences and returns a sequence of their
--   point-wise combinations, analogous to <a>zipWith</a>.
zipWith4 :: (a -> b -> c -> d -> e) -> Seq a -> Seq b -> Seq c -> Seq d -> Seq e


-- | <tt>Set</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Set as Set
--   </pre>
--   
--   This module does not export any partial or unchecked functions. For
--   those, see <a>RIO.Set.Partial</a> and <a>RIO.Set.Unchecked</a>
module RIO.Set

-- | A set of values <tt>a</tt>.
data Set a

-- | <i>O(m*log(n/m+1)), m &lt;= n</i>. See <a>difference</a>.
(\\) :: Ord a => Set a -> Set a -> Set a
infixl 9 \\

-- | <i>O(1)</i>. Is this the empty set?
null :: Set a -> Bool

-- | <i>O(1)</i>. The number of elements in the set.
size :: Set a -> Int

-- | <i>O(log n)</i>. Is the element in the set?
member :: Ord a => a -> Set a -> Bool

-- | <i>O(log n)</i>. Is the element not in the set?
notMember :: Ord a => a -> Set a -> Bool

-- | <i>O(log n)</i>. Find largest element smaller than the given one.
--   
--   <pre>
--   lookupLT 3 (fromList [3, 5]) == Nothing
--   lookupLT 5 (fromList [3, 5]) == Just 3
--   </pre>
lookupLT :: Ord a => a -> Set a -> Maybe a

-- | <i>O(log n)</i>. Find smallest element greater than the given one.
--   
--   <pre>
--   lookupGT 4 (fromList [3, 5]) == Just 5
--   lookupGT 5 (fromList [3, 5]) == Nothing
--   </pre>
lookupGT :: Ord a => a -> Set a -> Maybe a

-- | <i>O(log n)</i>. Find largest element smaller or equal to the given
--   one.
--   
--   <pre>
--   lookupLE 2 (fromList [3, 5]) == Nothing
--   lookupLE 4 (fromList [3, 5]) == Just 3
--   lookupLE 5 (fromList [3, 5]) == Just 5
--   </pre>
lookupLE :: Ord a => a -> Set a -> Maybe a

-- | <i>O(log n)</i>. Find smallest element greater or equal to the given
--   one.
--   
--   <pre>
--   lookupGE 3 (fromList [3, 5]) == Just 3
--   lookupGE 4 (fromList [3, 5]) == Just 5
--   lookupGE 6 (fromList [3, 5]) == Nothing
--   </pre>
lookupGE :: Ord a => a -> Set a -> Maybe a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. <tt>(s1 `isSubsetOf` s2)</tt>
--   indicates whether <tt>s1</tt> is a subset of <tt>s2</tt>.
--   
--   <pre>
--   s1 `isSubsetOf` s2 = all (<a>`member`</a> s2) s1
--   s1 `isSubsetOf` s2 = null (s1 <a>`difference`</a> s2)
--   s1 `isSubsetOf` s2 = s1 <a>`union`</a> s2 == s2
--   s1 `isSubsetOf` s2 = s1 <a>`intersection`</a> s2 == s1
--   </pre>
isSubsetOf :: Ord a => Set a -> Set a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. <tt>(s1 `isProperSubsetOf`
--   s2)</tt> indicates whether <tt>s1</tt> is a proper subset of
--   <tt>s2</tt>.
--   
--   <pre>
--   s1 `isProperSubsetOf` s2 = s1 <a>`isSubsetOf`</a> s2 &amp;&amp; s1 /= s2
--   </pre>
isProperSubsetOf :: Ord a => Set a -> Set a -> Bool

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

-- | <i>O(1)</i>. Create a singleton set.
singleton :: a -> Set a

-- | <i>O(log n)</i>. Insert an element in a set. If the set already
--   contains an element equal to the given value, it is replaced with the
--   new value.
insert :: Ord a => a -> Set a -> Set a

-- | <i>O(log n)</i>. Delete an element from a set.
delete :: Ord a => a -> Set a -> Set a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The union of two sets, preferring
--   the first set when equal elements are encountered.
union :: Ord a => Set a -> Set a -> Set a

-- | The union of the sets in a Foldable structure : (<tt><a>unions</a> ==
--   <a>foldl</a> <a>union</a> <a>empty</a></tt>).
unions :: (Foldable f, Ord a) => f (Set a) -> Set a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two sets.
--   
--   Return elements of the first set not existing in the second set.
--   
--   <pre>
--   difference (fromList [5, 3]) (fromList [5, 7]) == singleton 3
--   </pre>
difference :: Ord a => Set a -> Set a -> Set a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The intersection of two sets.
--   Elements of the result come from the first set, so for example
--   
--   <pre>
--   import qualified Data.Set as S
--   data AB = A | B deriving Show
--   instance Ord AB where compare _ _ = EQ
--   instance Eq AB where _ == _ = True
--   main = print (S.singleton A `S.intersection` S.singleton B,
--                 S.singleton B `S.intersection` S.singleton A)
--   </pre>
--   
--   prints <tt>(fromList [A],fromList [B])</tt>.
intersection :: Ord a => Set a -> Set a -> Set a

-- | <i>O(n)</i>. Filter all elements that satisfy the predicate.
filter :: (a -> Bool) -> Set a -> Set a

-- | <i>O(log n)</i>. Take while a predicate on the elements holds. The
--   user is responsible for ensuring that for all elements <tt>j</tt> and
--   <tt>k</tt> in the set, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See
--   note at <a>spanAntitone</a>.
--   
--   <pre>
--   takeWhileAntitone p = <a>fromDistinctAscList</a> . <a>takeWhile</a> p . <a>toList</a>
--   takeWhileAntitone p = <a>filter</a> p
--   </pre>
takeWhileAntitone :: (a -> Bool) -> Set a -> Set a

-- | <i>O(log n)</i>. Drop while a predicate on the elements holds. The
--   user is responsible for ensuring that for all elements <tt>j</tt> and
--   <tt>k</tt> in the set, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See
--   note at <a>spanAntitone</a>.
--   
--   <pre>
--   dropWhileAntitone p = <a>fromDistinctAscList</a> . <a>dropWhile</a> p . <a>toList</a>
--   dropWhileAntitone p = <a>filter</a> (not . p)
--   </pre>
dropWhileAntitone :: (a -> Bool) -> Set a -> Set a

-- | <i>O(log n)</i>. Divide a set at the point where a predicate on the
--   elements stops holding. The user is responsible for ensuring that for
--   all elements <tt>j</tt> and <tt>k</tt> in the set, <tt>j &lt; k ==&gt;
--   p j &gt;= p k</tt>.
--   
--   <pre>
--   spanAntitone p xs = (<a>takeWhileAntitone</a> p xs, <a>dropWhileAntitone</a> p xs)
--   spanAntitone p xs = partition p xs
--   </pre>
--   
--   Note: if <tt>p</tt> is not actually antitone, then
--   <tt>spanAntitone</tt> will split the set at some <i>unspecified</i>
--   point where the predicate switches from holding to not holding (where
--   the predicate is seen to hold before the first element and to fail
--   after the last element).
spanAntitone :: (a -> Bool) -> Set a -> (Set a, Set a)

-- | <i>O(n)</i>. Partition the set into two sets, one with all elements
--   that satisfy the predicate and one with all elements that don't
--   satisfy the predicate. See also <a>split</a>.
partition :: (a -> Bool) -> Set a -> (Set a, Set a)

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> x set</tt>) is a
--   pair <tt>(set1,set2)</tt> where <tt>set1</tt> comprises the elements
--   of <tt>set</tt> less than <tt>x</tt> and <tt>set2</tt> comprises the
--   elements of <tt>set</tt> greater than <tt>x</tt>.
split :: Ord a => a -> Set a -> (Set a, Set a)

-- | <i>O(log n)</i>. Performs a <a>split</a> but also returns whether the
--   pivot element was found in the original set.
splitMember :: Ord a => a -> Set a -> (Set a, Bool, Set a)

-- | <i>O(1)</i>. Decompose a set into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a set in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first subset less than all elements in the second, and so on).
--   
--   Examples:
--   
--   <pre>
--   splitRoot (fromList [1..6]) ==
--     [fromList [1,2,3],fromList [4],fromList [5,6]]
--   </pre>
--   
--   <pre>
--   splitRoot empty == []
--   </pre>
--   
--   Note that the current implementation does not return more than three
--   subsets, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: Set a -> [Set a]

-- | <i>O(log n)</i>. Lookup the <i>index</i> of an element, which is its
--   zero-based index in the sorted sequence of elements. The index is a
--   number from <i>0</i> up to, but not including, the <a>size</a> of the
--   set.
--   
--   <pre>
--   isJust   (lookupIndex 2 (fromList [5,3])) == False
--   fromJust (lookupIndex 3 (fromList [5,3])) == 0
--   fromJust (lookupIndex 5 (fromList [5,3])) == 1
--   isJust   (lookupIndex 6 (fromList [5,3])) == False
--   </pre>
lookupIndex :: Ord a => a -> Set a -> Maybe Int

-- | Take a given number of elements in order, beginning with the smallest
--   ones.
--   
--   <pre>
--   take n = <a>fromDistinctAscList</a> . <a>take</a> n . <a>toAscList</a>
--   </pre>
take :: Int -> Set a -> Set a

-- | Drop a given number of elements in order, beginning with the smallest
--   ones.
--   
--   <pre>
--   drop n = <a>fromDistinctAscList</a> . <a>drop</a> n . <a>toAscList</a>
--   </pre>
drop :: Int -> Set a -> Set a

-- | <i>O(log n)</i>. Split a set at a particular index.
--   
--   <pre>
--   splitAt !n !xs = (<a>take</a> n xs, <a>drop</a> n xs)
--   </pre>
splitAt :: Int -> Set a -> (Set a, Set a)

-- | <i>O(n*log n)</i>. <tt><a>map</a> f s</tt> is the set obtained by
--   applying <tt>f</tt> to each element of <tt>s</tt>.
--   
--   It's worth noting that the size of the result may be smaller if, for
--   some <tt>(x,y)</tt>, <tt>x /= y &amp;&amp; f x == f y</tt>
map :: Ord b => (a -> b) -> Set a -> Set b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   toAscList set = foldr (:) [] set
--   </pre>
foldr :: (a -> b -> b) -> b -> Set a -> b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   toDescList set = foldl (flip (:)) [] set
--   </pre>
foldl :: (a -> b -> a) -> a -> Set b -> a

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> Set a -> b

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> Set b -> a

-- | <i>O(log n)</i>. The minimal element of a set.
lookupMin :: Set a -> Maybe a

-- | <i>O(log n)</i>. The maximal element of a set.
lookupMax :: Set a -> Maybe a

-- | <i>O(log n)</i>. Delete the minimal element. Returns an empty set if
--   the set is empty.
deleteMin :: Set a -> Set a

-- | <i>O(log n)</i>. Delete the maximal element. Returns an empty set if
--   the set is empty.
deleteMax :: Set a -> Set a

-- | <i>O(log n)</i>. Retrieves the maximal key of the set, and the set
--   stripped of that element, or <a>Nothing</a> if passed an empty set.
maxView :: Set a -> Maybe (a, Set a)

-- | <i>O(log n)</i>. Retrieves the minimal key of the set, and the set
--   stripped of that element, or <a>Nothing</a> if passed an empty set.
minView :: Set a -> Maybe (a, Set a)

-- | <i>O(n)</i>. An alias of <a>toAscList</a>. The elements of a set in
--   ascending order. Subject to list fusion.
elems :: Set a -> [a]

-- | <i>O(n)</i>. Convert the set to a list of elements. Subject to list
--   fusion.
toList :: Set a -> [a]

-- | <i>O(n*log n)</i>. Create a set from a list of elements.
--   
--   If the elements are ordered, a linear-time implementation is used,
--   with the performance equal to <a>fromDistinctAscList</a>.
fromList :: Ord a => [a] -> Set a

-- | <i>O(n)</i>. Convert the set to an ascending list of elements. Subject
--   to list fusion.
toAscList :: Set a -> [a]

-- | <i>O(n)</i>. Convert the set to a descending list of elements. Subject
--   to list fusion.
toDescList :: Set a -> [a]

-- | <i>O(n)</i>. Show the tree that implements the set. The tree is shown
--   in a compressed, hanging format.
showTree :: Show a => Set a -> String

-- | <i>O(n)</i>. The expression (<tt>showTreeWith hang wide map</tt>)
--   shows the tree that implements the set. If <tt>hang</tt> is
--   <tt>True</tt>, a <i>hanging</i> tree is shown otherwise a rotated tree
--   is shown. If <tt>wide</tt> is <a>True</a>, an extra wide version is
--   shown.
--   
--   <pre>
--   Set&gt; putStrLn $ showTreeWith True False $ fromDistinctAscList [1..5]
--   4
--   +--2
--   |  +--1
--   |  +--3
--   +--5
--   
--   Set&gt; putStrLn $ showTreeWith True True $ fromDistinctAscList [1..5]
--   4
--   |
--   +--2
--   |  |
--   |  +--1
--   |  |
--   |  +--3
--   |
--   +--5
--   
--   Set&gt; putStrLn $ showTreeWith False True $ fromDistinctAscList [1..5]
--   +--5
--   |
--   4
--   |
--   |  +--3
--   |  |
--   +--2
--      |
--      +--1
--   </pre>
showTreeWith :: Show a => Bool -> Bool -> Set a -> String

-- | <i>O(n)</i>. Test if the internal set structure is valid.
valid :: Ord a => Set a -> Bool


-- | <tt>Set</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Set.Partial as Set'
--   </pre>
module RIO.Set.Partial

-- | <i>O(log n)</i>. Return the <i>index</i> of an element, which is its
--   zero-based index in the sorted sequence of elements. The index is a
--   number from <i>0</i> up to, but not including, the <a>size</a> of the
--   set. Calls <a>error</a> when the element is not a <a>member</a> of the
--   set.
--   
--   <pre>
--   findIndex 2 (fromList [5,3])    Error: element is not in the set
--   findIndex 3 (fromList [5,3]) == 0
--   findIndex 5 (fromList [5,3]) == 1
--   findIndex 6 (fromList [5,3])    Error: element is not in the set
--   </pre>
findIndex :: Ord a => a -> Set a -> Int

-- | <i>O(log n)</i>. Retrieve an element by its <i>index</i>, i.e. by its
--   zero-based index in the sorted sequence of elements. If the
--   <i>index</i> is out of range (less than zero, greater or equal to
--   <a>size</a> of the set), <a>error</a> is called.
--   
--   <pre>
--   elemAt 0 (fromList [5,3]) == 3
--   elemAt 1 (fromList [5,3]) == 5
--   elemAt 2 (fromList [5,3])    Error: index out of range
--   </pre>
elemAt :: Int -> Set a -> a

-- | <i>O(log n)</i>. Delete the element at <i>index</i>, i.e. by its
--   zero-based index in the sorted sequence of elements. If the
--   <i>index</i> is out of range (less than zero, greater or equal to
--   <a>size</a> of the set), <a>error</a> is called.
--   
--   <pre>
--   deleteAt 0    (fromList [5,3]) == singleton 5
--   deleteAt 1    (fromList [5,3]) == singleton 3
--   deleteAt 2    (fromList [5,3])    Error: index out of range
--   deleteAt (-1) (fromList [5,3])    Error: index out of range
--   </pre>
deleteAt :: Int -> Set a -> Set a

-- | <i>O(log n)</i>. The minimal element of a set.
findMin :: Set a -> a

-- | <i>O(log n)</i>. The maximal element of a set.
findMax :: Set a -> a

-- | <i>O(log n)</i>. Delete and find the minimal element.
--   
--   <pre>
--   deleteFindMin set = (findMin set, deleteMin set)
--   </pre>
deleteFindMin :: Set a -> (a, Set a)

-- | <i>O(log n)</i>. Delete and find the maximal element.
--   
--   <pre>
--   deleteFindMax set = (findMax set, deleteMax set)
--   </pre>
deleteFindMax :: Set a -> (a, Set a)


-- | This module contains functions from <a>Data.Set</a> that have
--   unchecked preconditions on their input. If these preconditions are not
--   satisfied, the data structure may end up in an invalid state and other
--   operations may misbehave. Import as:
--   
--   <pre>
--   import qualified RIO.Set.Unchecked as Set'
--   </pre>
module RIO.Set.Unchecked

-- | <i>O(n)</i>. The
--   
--   <tt><a>mapMonotonic</a> f s == <a>map</a> f s</tt>, but works only
--   when <tt>f</tt> is strictly increasing. <i>The precondition is not
--   checked.</i> Semi-formally, we have:
--   
--   <pre>
--   and [x &lt; y ==&gt; f x &lt; f y | x &lt;- ls, y &lt;- ls]
--                       ==&gt; mapMonotonic f s == map f s
--       where ls = toList s
--   </pre>
mapMonotonic :: (a -> b) -> Set a -> Set b

-- | <i>O(n)</i>. Build a set from an ascending list in linear time. <i>The
--   precondition (input list is ascending) is not checked.</i>
fromAscList :: Eq a => [a] -> Set a

-- | <i>O(n)</i>. Build a set from a descending list in linear time. <i>The
--   precondition (input list is descending) is not checked.</i>
fromDescList :: Eq a => [a] -> Set a

-- | <i>O(n)</i>. Build a set from an ascending list of distinct elements
--   in linear time. <i>The precondition (input list is strictly ascending)
--   is not checked.</i>
fromDistinctAscList :: [a] -> Set a

-- | <i>O(n)</i>. Build a set from a descending list of distinct elements
--   in linear time. <i>The precondition (input list is strictly
--   descending) is not checked.</i>
fromDistinctDescList :: [a] -> Set a


-- | Provides reexports of <tt>MonadState</tt> and related helpers.
module RIO.State

-- | Minimal definition is either both of <tt>get</tt> and <tt>put</tt> or
--   just <tt>state</tt>
class Monad m => MonadState s (m :: Type -> Type) | m -> s

-- | Return the state from the internals of the monad.
get :: MonadState s m => m s

-- | Replace the state inside the monad.
put :: MonadState s m => s -> m ()

-- | Embed a simple state action into the monad.
state :: MonadState s m => (s -> (a, s)) -> m a

-- | Gets specific component of the state, using a projection function
--   supplied.
gets :: MonadState s m => (s -> a) -> m a

-- | Monadic state transformer.
--   
--   Maps an old state to a new state inside a state monad. The old state
--   is thrown away.
--   
--   <pre>
--   Main&gt; :t modify ((+1) :: Int -&gt; Int)
--   modify (...) :: (MonadState Int a) =&gt; a ()
--   </pre>
--   
--   This says that <tt>modify (+1)</tt> acts over any Monad that is a
--   member of the <tt>MonadState</tt> class, with an <tt>Int</tt> state.
modify :: MonadState s m => (s -> s) -> m ()

-- | A variant of <a>modify</a> in which the computation is strict in the
--   new state.
modify' :: MonadState s m => (s -> s) -> m ()

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Unwrap a state monad computation as a function. (The inverse of
--   <a>state</a>.)
runState :: State s a -> s -> (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalState</a> m s = <a>fst</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
evalState :: State s a -> s -> a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execState</a> m s = <a>snd</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
execState :: State s a -> s -> s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runState</a> (<a>mapState</a> f m) = f . <a>runState</a>
--   m</pre></li>
--   </ul>
mapState :: ((a, s) -> (b, s)) -> State s a -> State s b

-- | <tt><a>withState</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withState</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withState :: (s -> s) -> State s a -> State s a

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s (m :: Type -> Type) a
StateT :: (s -> m (a, s)) -> StateT s (m :: Type -> Type) a
[runStateT] :: StateT s (m :: Type -> Type) a -> s -> m (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runStateT</a> (<a>mapStateT</a> f m) = f .
--   <a>runStateT</a> m</pre></li>
--   </ul>
mapStateT :: (m (a, s) -> n (b, s)) -> StateT s m a -> StateT s n b

-- | <tt><a>withStateT</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withStateT</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withStateT :: forall s (m :: Type -> Type) a. (s -> s) -> StateT s m a -> StateT s m a


-- | Strict <tt>Text</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Text as T
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.Text.Partial</a>
module RIO.Text

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

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

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

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

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

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

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

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

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

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

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

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

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>Text</a> and a
--   list of <a>Text</a>s and concatenates the list after interspersing the
--   first argument between each element of the list.
--   
--   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>
--   
--   Subject to fusion. Performs replacement on invalid scalar values.
intersperse :: Char -> Text -> Text

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

-- | <i>O(n)</i> Reverse the characters of a string.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; T.reverse "desrever"
--   "reversed"
--   </pre>
--   
--   Subject to fusion (fuses with its argument).
reverse :: Text -> Text

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

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

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

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

-- | <i>O(n)</i> Left-justify a string to the given length, using the
--   specified fill character on the right. Subject to fusion. Performs
--   replacement on invalid scalar values.
--   
--   Examples:
--   
--   <pre>
--   &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. Subject to fusion.
foldl :: (a -> Char -> a) -> a -> Text -> a

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

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

-- | <i>O(n)</i> 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>. Subject to fusion.
any :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>all</a> <tt>p</tt> <tt>t</tt> determines whether all
--   characters in the <a>Text</a> <tt>t</tt> satisfy the predicate
--   <tt>p</tt>. Subject to fusion.
all :: (Char -> Bool) -> 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. Subject to fusion.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> Text -> Text

-- | <i>O(n)</i> <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument. 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. Subject to fusion. Performs
--   replacement on invalid scalar values.
unfoldr :: (a -> Maybe (Char, a)) -> a -> Text

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

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

-- | <i>O(n)</i> <a>takeEnd</a> <tt>n</tt> <tt>t</tt> returns the suffix
--   remaining after taking <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   &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>. Subject to fusion.
drop :: Int -> Text -> Text

-- | <i>O(n)</i> <a>dropEnd</a> <tt>n</tt> <tt>t</tt> returns the prefix
--   remaining after dropping <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   &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>. Subject to fusion.
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>. Subject to
--   fusion.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhileEnd</a> <tt>p</tt> <tt>t</tt> returns the
--   prefix remaining after dropping characters that 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>.
--   Subject to fusion.
dropAround :: (Char -> Bool) -> Text -> Text

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

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

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

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

-- | <i>O(n)</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 list.
--   
--   <pre>
--   &gt;&gt;&gt; T.span (=='0') "000AB"
--   ("000","AB")
--   </pre>
span :: (Char -> Bool) -> Text -> (Text, Text)

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

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

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

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

-- | <i>O(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 <a>Char</a>s. The resulting strings do not contain newlines.
lines :: Text -> [Text]

-- | <a>linesCR</a> breaks a <a>Text</a> up into a list of <a>Text</a>s at
--   newline <a>Char</a>s. It is very similar to <a>lines</a>, but it also
--   removes any trailing <tt>'r'</tt> characters. The resulting
--   <a>Text</a> values do not contain newlines or trailing <tt>'r'</tt>
--   characters.
linesCR :: Text -> [Text]

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

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

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

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

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

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

-- | <i>O(n)</i> Return the suffix of the second string if its prefix
--   matches the entire first string.
--   
--   Examples:
--   
--   <pre>
--   &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

-- | Drop prefix if present, otherwise return original <a>Text</a>.
dropPrefix :: Text -> Text -> Text

-- | Drop prefix if present, otherwise return original <a>Text</a>.
dropSuffix :: Text -> Text -> 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)</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. Subject to fusion.
find :: (Char -> Bool) -> Text -> Maybe Char

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

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

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

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

-- | <i>O(n)</i> <a>zipWith</a> generalises <a>zip</a> by zipping with the
--   function given as the first argument, instead of a tupling function.
--   Performs replacement on invalid scalar values.
zipWith :: (Char -> Char -> Char) -> Text -> Text -> Text

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

-- | <i>O(n)</i> Convert a literal string into a <a>Text</a>.
--   
--   This is exposed solely for people writing GHC rewrite rules.
unpackCString# :: Addr# -> Text

-- | Encode text using UTF-8 encoding.
encodeUtf8 :: Text -> ByteString

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text.
--   
--   <b>NOTE</b>: The replacement character returned by
--   <a>OnDecodeError</a> MUST be within the BMP plane; surrogate code
--   points will automatically be remapped to the replacement char
--   <tt>U+FFFD</tt> (<i>since 0.11.3.0</i>), whereas code points beyond
--   the BMP will throw an <a>error</a> (<i>since 1.2.3.1</i>); For earlier
--   versions of <tt>text</tt> using those unsupported code points would
--   result in undefined behavior.
decodeUtf8With :: OnDecodeError -> 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

-- | Replace an invalid input byte with the Unicode replacement character
--   U+FFFD.
lenientDecode :: OnDecodeError

module RIO

-- | The Reader+IO monad. This is different from a <a>ReaderT</a> because:
--   
--   <ul>
--   <li>It's not a transformer, it hardcodes IO for simpler usage and
--   error messages.</li>
--   <li>Instances of typeclasses like <tt>MonadLogger</tt> are implemented
--   using classes defined on the environment, instead of using an
--   underlying monad.</li>
--   </ul>
newtype RIO env a
RIO :: ReaderT env IO a -> RIO env a
[unRIO] :: RIO env a -> ReaderT env IO a

-- | Using the environment run in IO the action that requires that
--   environment.
runRIO :: MonadIO m => env -> RIO env a -> m a

-- | Abstract <a>RIO</a> to an arbitrary <a>MonadReader</a> instance, which
--   can handle IO.
liftRIO :: (MonadIO m, MonadReader env m) => RIO env a -> m a

-- | Given a <a>LogOptions</a> value, run the given function with the
--   specified <a>LogFunc</a>. A common way to use this function is:
--   
--   <pre>
--   let isVerbose = False -- get from the command line instead
--   logOptions' &lt;- logOptionsHandle stderr isVerbose
--   let logOptions = setLogUseTime True logOptions'
--   withLogFunc logOptions $ \lf -&gt; do
--     let app = App -- application specific environment
--           { appLogFunc = lf
--           , appOtherStuff = ...
--           }
--     runRIO app $ do
--       logInfo "Starting app"
--       myApp
--   </pre>
withLogFunc :: MonadUnliftIO m => LogOptions -> (LogFunc -> m a) -> m a

-- | Given a <a>LogOptions</a> value, returns both a new <a>LogFunc</a> and
--   a sub-routine that disposes it.
--   
--   Intended for use if you want to deal with the teardown of
--   <a>LogFunc</a> yourself, otherwise prefer the <a>withLogFunc</a>
--   function instead.
newLogFunc :: (MonadIO n, MonadIO m) => LogOptions -> n (LogFunc, m ())

-- | A logging function, wrapped in a newtype for better error messages.
--   
--   An implementation may choose any behavior of this value it wishes,
--   including printing to standard output or no action at all.
data LogFunc

-- | Environment values with a logging function.
class HasLogFunc env
logFuncL :: HasLogFunc env => Lens' env LogFunc

-- | Create a <a>LogOptions</a> value from the given <a>Handle</a> and
--   whether to perform verbose logging or not. Individiual settings can be
--   overridden using appropriate <tt>set</tt> functions. Logging output is
--   guaranteed to be non-interleaved only for a UTF-8 <a>Handle</a> in a
--   multi-thread environment.
--   
--   When Verbose Flag is <tt>True</tt>, the following happens:
--   
--   <ul>
--   <li><tt>setLogVerboseFormat</tt> is called with <tt>True</tt></li>
--   <li><tt>setLogUseColor</tt> is called with <tt>True</tt> (except on
--   Windows)</li>
--   <li><tt>setLogUseLoc</tt> is called with <tt>True</tt></li>
--   <li><tt>setLogUseTime</tt> is called with <tt>True</tt></li>
--   <li><tt>setLogMinLevel</tt> is called with <tt>Debug</tt> log
--   level</li>
--   </ul>
logOptionsHandle :: MonadIO m => Handle -> Bool -> m LogOptions

-- | Configuration for how to create a <a>LogFunc</a>. Intended to be used
--   with the <a>withLogFunc</a> function.
data LogOptions

-- | Set the minimum log level. Messages below this level will not be
--   printed.
--   
--   Default: in verbose mode, <a>LevelDebug</a>. Otherwise,
--   <a>LevelInfo</a>.
setLogMinLevel :: LogLevel -> LogOptions -> LogOptions

-- | Refer to <a>setLogMinLevel</a>. This modifier allows to alter the
--   verbose format value dynamically at runtime.
--   
--   Default: in verbose mode, <a>LevelDebug</a>. Otherwise,
--   <a>LevelInfo</a>.
setLogMinLevelIO :: IO LogLevel -> LogOptions -> LogOptions

-- | Use the verbose format for printing log messages.
--   
--   Default: follows the value of the verbose flag.
setLogVerboseFormat :: Bool -> LogOptions -> LogOptions

-- | Refer to <a>setLogVerboseFormat</a>. This modifier allows to alter the
--   verbose format value dynamically at runtime.
--   
--   Default: follows the value of the verbose flag.
setLogVerboseFormatIO :: IO Bool -> LogOptions -> LogOptions

-- | Do we treat output as a terminal. If <tt>True</tt>, we will enabled
--   sticky logging functionality.
--   
--   Default: checks if the <tt>Handle</tt> provided to
--   <a>logOptionsHandle</a> is a terminal with <a>hIsTerminalDevice</a>.
setLogTerminal :: Bool -> LogOptions -> LogOptions

-- | Include the time when printing log messages.
--   
--   Default: <a>True</a> in debug mode, <a>False</a> otherwise.
setLogUseTime :: Bool -> LogOptions -> LogOptions

-- | Use ANSI color codes in the log output.
--   
--   Default: <a>True</a> if in verbose mode <i>and</i> the <a>Handle</a>
--   is a terminal device.
setLogUseColor :: Bool -> LogOptions -> LogOptions

-- | Use code location in the log output.
--   
--   Default: <a>True</a> if in verbose mode, <a>False</a> otherwise.
setLogUseLoc :: Bool -> LogOptions -> LogOptions

-- | Set format method for messages
--   
--   Default: <a>id</a>
setLogFormat :: (Utf8Builder -> Utf8Builder) -> LogOptions -> LogOptions

-- | ANSI color codes for <a>LogLevel</a> in the log output.
--   
--   Default: <a>LevelDebug</a> = "\ESC[32m" -- Green <a>LevelInfo</a> =
--   "\ESC[34m" -- Blue <a>LevelWarn</a> = "\ESC[33m" -- Yellow
--   <a>LevelError</a> = "\ESC[31m" -- Red <a>LevelOther</a> _ = "\ESC[35m"
--   -- Magenta
setLogLevelColors :: (LogLevel -> Utf8Builder) -> LogOptions -> LogOptions

-- | ANSI color codes for secondary content in the log output.
--   
--   Default: "\ESC[90m" -- Bright black (gray)
setLogSecondaryColor :: Utf8Builder -> LogOptions -> LogOptions

-- | ANSI color codes for accents in the log output. Accent colors are
--   indexed by <a>Int</a>.
--   
--   Default: <a>const</a> "\ESC[92m" -- Bright green, for all indicies
setLogAccentColors :: (Int -> Utf8Builder) -> LogOptions -> LogOptions

-- | Log a debug level message with no source.
logDebug :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m ()

-- | Log an info level message with no source.
logInfo :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m ()

-- | Log a warn level message with no source.
logWarn :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m ()

-- | Log an error level message with no source.
logError :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m ()

-- | Log a message with the specified textual level and no source.
logOther :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Text -> Utf8Builder -> m ()

-- | Write a "sticky" line to the terminal. Any subsequent lines will
--   overwrite this one, and that same line will be repeated below again.
--   In other words, the line sticks at the bottom of the output forever.
--   Running this function again will replace the sticky line with a new
--   sticky line. When you want to get rid of the sticky line, run
--   <a>logStickyDone</a>.
--   
--   Note that not all <a>LogFunc</a> implementations will support sticky
--   messages as described. However, the <a>withLogFunc</a> implementation
--   provided by this module does.
logSticky :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m ()

-- | This will print out the given message with a newline and disable any
--   further stickiness of the line until a new call to <a>logSticky</a>
--   happens.
logStickyDone :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m ()

-- | Log a debug level message with the given source.
logDebugS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m ()

-- | Log an info level message with the given source.
logInfoS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m ()

-- | Log a warn level message with the given source.
logWarnS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m ()

-- | Log an error level message with the given source.
logErrorS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m ()

-- | Log a message with the specified textual level and the given source.
logOtherS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Text -> LogSource -> Utf8Builder -> m ()

-- | Generic, basic function for creating other logging functions.
logGeneric :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> LogLevel -> Utf8Builder -> m ()

-- | Create a <a>LogFunc</a> from the given function.
mkLogFunc :: (CallStack -> LogSource -> LogLevel -> Utf8Builder -> IO ()) -> LogFunc

-- | Create a <a>LogOptions</a> value which will store its data in memory.
--   This is primarily intended for testing purposes. This will return both
--   a <a>LogOptions</a> value and an <a>IORef</a> containing the resulting
--   <a>Builder</a> value.
--   
--   This will default to non-verbose settings and assume there is a
--   terminal attached. These assumptions can be overridden using the
--   appropriate <tt>set</tt> functions.
logOptionsMemory :: MonadIO m => m (IORef Builder, LogOptions)

-- | The log level of a message.
data LogLevel
LevelDebug :: LogLevel
LevelInfo :: LogLevel
LevelWarn :: LogLevel
LevelError :: LogLevel
LevelOther :: !Text -> LogLevel

-- | Where in the application a log message came from. Used for display
--   purposes only.
type LogSource = Text

-- | <a>CallStack</a>s are a lightweight method of obtaining a partial
--   call-stack at any point in the program.
--   
--   A function can request its call-site with the <a>HasCallStack</a>
--   constraint. For example, we can define
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   </pre>
--   
--   as a variant of <tt>putStrLn</tt> that will get its call-site and
--   print it, along with the string given as argument. We can access the
--   call-stack inside <tt>putStrLnWithCallStack</tt> with
--   <a>callStack</a>.
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--   </pre>
--   
--   Thus, if we call <tt>putStrLnWithCallStack</tt> we will get a
--   formatted call-stack alongside our string.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at &lt;interactive&gt;:2:1 in interactive:Ghci1
--   </pre>
--   
--   GHC solves <a>HasCallStack</a> constraints in three steps:
--   
--   <ol>
--   <li>If there is a <a>CallStack</a> in scope -- i.e. the enclosing
--   function has a <a>HasCallStack</a> constraint -- GHC will append the
--   new call-site to the existing <a>CallStack</a>.</li>
--   <li>If there is no <a>CallStack</a> in scope -- e.g. in the GHCi
--   session above -- and the enclosing definition does not have an
--   explicit type signature, GHC will infer a <a>HasCallStack</a>
--   constraint for the enclosing definition (subject to the monomorphism
--   restriction).</li>
--   <li>If there is no <a>CallStack</a> in scope and the enclosing
--   definition has an explicit type signature, GHC will solve the
--   <a>HasCallStack</a> constraint for the singleton <a>CallStack</a>
--   containing just the current call-site.</li>
--   </ol>
--   
--   <a>CallStack</a>s do not interact with the RTS and do not require
--   compilation with <tt>-prof</tt>. On the other hand, as they are built
--   up explicitly via the <a>HasCallStack</a> constraints, they will
--   generally not contain as much information as the simulated call-stacks
--   maintained by the RTS.
--   
--   A <a>CallStack</a> is a <tt>[(String, SrcLoc)]</tt>. The
--   <tt>String</tt> is the name of function that was called, the
--   <a>SrcLoc</a> is the call-site. The list is ordered with the most
--   recently called function at the head.
--   
--   NOTE: The intrepid user may notice that <a>HasCallStack</a> is just an
--   alias for an implicit parameter <tt>?callStack :: CallStack</tt>. This
--   is an implementation detail and <b>should not</b> be considered part
--   of the <a>CallStack</a> API, we may decide to change the
--   implementation in the future.
data CallStack

-- | Convert a <a>CallStack</a> value into a <a>Utf8Builder</a> indicating
--   the first source location.
--   
--   TODO Consider showing the entire call stack instead.
displayCallStack :: CallStack -> Utf8Builder

-- | Disable logging capabilities in a given sub-routine
--   
--   Intended to skip logging in general purpose implementations, where
--   secrets might be logged accidently.
noLogging :: (HasLogFunc env, MonadReader env m) => m a -> m a

-- | Is the log func configured to use color output?
--   
--   Intended for use by code which wants to optionally add additional
--   color to its log messages.
logFuncUseColorL :: HasLogFunc env => SimpleGetter env Bool

-- | What color is the log func configured to use for each <a>LogLevel</a>?
--   
--   Intended for use by code which wants to optionally add additional
--   color to its log messages.
logFuncLogLevelColorsL :: HasLogFunc env => SimpleGetter env (LogLevel -> Utf8Builder)

-- | What color is the log func configured to use for secondary content?
--   
--   Intended for use by code which wants to optionally add additional
--   color to its log messages.
logFuncSecondaryColorL :: HasLogFunc env => SimpleGetter env Utf8Builder

-- | What accent colors, indexed by <a>Int</a>, is the log func configured
--   to use?
--   
--   Intended for use by code which wants to optionally add additional
--   color to its log messages.
logFuncAccentColorsL :: HasLogFunc env => SimpleGetter env (Int -> Utf8Builder)

-- | Log a value generically.
glog :: (MonadIO m, HasCallStack, HasGLogFunc env, MonadReader env m) => GMsg env -> m ()

-- | A generic logger of some type <tt>msg</tt>.
--   
--   Your <tt>GLocFunc</tt> can re-use the existing classical logging
--   framework of RIO, and/or implement additional transforms, filters.
--   Alternatively, you may log to a JSON source in a database, or anywhere
--   else as needed. You can decide how to log levels or severities based
--   on the constructors in your type. You will normally determine this in
--   your main app entry point.
data GLogFunc msg

-- | Make a <a>GLogFunc</a> via classic <a>LogFunc</a>. Use this if you'd
--   like to log your generic data type via the classic RIO terminal
--   logger.
gLogFuncClassic :: (HasLogLevel msg, HasLogSource msg, Display msg) => LogFunc -> GLogFunc msg

-- | Make a custom generic logger. With this you could, for example, write
--   to a database or a log digestion service. For example:
--   
--   <pre>
--   mkGLogFunc (\stack msg -&gt; send (Data.Aeson.encode (JsonLog stack msg)))
--   </pre>
mkGLogFunc :: (CallStack -> msg -> IO ()) -> GLogFunc msg

-- | A vesion of <a>contramapMaybeGLogFunc</a> which supports filering.
contramapMaybeGLogFunc :: (a -> Maybe b) -> GLogFunc b -> GLogFunc a

-- | A contramap. Use this to wrap sub-loggers via <a>mapRIO</a>.
--   
--   If you are on base &gt; 4.12.0, you can just use <a>contramap</a>.
contramapGLogFunc :: (a -> b) -> GLogFunc b -> GLogFunc a

-- | An app is capable of generic logging if it implements this.
class HasGLogFunc env where {
    type family GMsg env;
}
gLogFuncL :: HasGLogFunc env => Lens' env (GLogFunc (GMsg env))

-- | Level, if any, of your logs. If unknown, use <tt>LogOther</tt>. Use
--   for your generic log data types that want to sit inside the classic
--   log framework.
class HasLogLevel msg
getLogLevel :: HasLogLevel msg => msg -> LogLevel

-- | Source of a log. This can be whatever you want. Use for your generic
--   log data types that want to sit inside the classic log framework.
class HasLogSource msg
getLogSource :: HasLogSource msg => msg -> LogSource

-- | A builder of binary data, with the invariant that the underlying data
--   is supposed to be UTF-8 encoded.
newtype Utf8Builder
Utf8Builder :: Builder -> Utf8Builder
[getUtf8Builder] :: Utf8Builder -> Builder

-- | A typeclass for values which can be converted to a <a>Utf8Builder</a>.
--   The intention of this typeclass is to provide a human-friendly display
--   of the data.
class Display a
display :: Display a => a -> Utf8Builder

-- | Display data as <a>Text</a>, which will also be used for
--   <a>display</a> if it is not overriden.
textDisplay :: Display a => a -> Text

-- | Use the <a>Show</a> instance for a value to convert it to a
--   <a>Utf8Builder</a>.
displayShow :: Show a => a -> Utf8Builder

-- | Convert a <a>Utf8Builder</a> value into a strict <a>Text</a>.
utf8BuilderToText :: Utf8Builder -> Text

-- | Convert a <a>Utf8Builder</a> value into a lazy <a>Text</a>.
utf8BuilderToLazyText :: Utf8Builder -> Text

-- | Convert a <a>ByteString</a> into a <a>Utf8Builder</a>.
--   
--   <i>NOTE</i> This function performs no checks to ensure that the data
--   is, in fact, UTF8 encoded. If you provide non-UTF8 data, later
--   functions may fail.
displayBytesUtf8 :: ByteString -> Utf8Builder

-- | Write the given <a>Utf8Builder</a> value to a file.
writeFileUtf8Builder :: MonadIO m => FilePath -> Utf8Builder -> m ()

-- | <a>view</a> is a synonym for (<a>^.</a>), generalised for
--   <a>MonadReader</a> (we are able to use it instead of (<a>^.</a>) since
--   functions are instances of the <a>MonadReader</a> class):
--   
--   <pre>
--   &gt;&gt;&gt; view _1 (1, 2)
--   1
--   </pre>
--   
--   When you're using <a>Reader</a> for config and your config type has
--   lenses generated for it, most of the time you'll be using <a>view</a>
--   instead of <a>asks</a>:
--   
--   <pre>
--   doSomething :: (<a>MonadReader</a> Config m) =&gt; m Int
--   doSomething = do
--     thingy        &lt;- <a>view</a> setting1  -- same as “<a>asks</a> (<a>^.</a> setting1)”
--     anotherThingy &lt;- <a>view</a> setting2
--     ...
--   </pre>
view :: MonadReader s m => Getting a s a -> m a

-- | <a>preview</a> is a synonym for (<a>^?</a>), generalised for
--   <a>MonadReader</a> (just like <a>view</a>, which is a synonym for
--   (<a>^.</a>)).
--   
--   <pre>
--   &gt;&gt;&gt; preview each [1..5]
--   Just 1
--   </pre>
preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a)

-- | <tt>ASetter s t a b</tt> is something that turns a function modifying
--   a value into a function modifying a <i>structure</i>. If you ignore
--   <a>Identity</a> (as <tt>Identity a</tt> is the same thing as
--   <tt>a</tt>), the type is:
--   
--   <pre>
--   type ASetter s t a b = (a -&gt; b) -&gt; s -&gt; t
--   </pre>
--   
--   The reason <a>Identity</a> is used here is for <a>ASetter</a> to be
--   composable with other types, such as <a>Lens</a>.
--   
--   Technically, if you're writing a library, you shouldn't use this type
--   for setters you are exporting from your library; the right type to use
--   is <tt><a>Setter</a></tt>, but it is not provided by this package
--   (because then it'd have to depend on <a>distributive</a>). It's
--   completely alright, however, to export functions which take an
--   <a>ASetter</a> as an argument.
type ASetter s t a b = a -> Identity b -> s -> Identity t

-- | This is a type alias for monomorphic setters which don't change the
--   type of the container (or of the value inside). It's useful more often
--   than the same type in lens, because we can't provide real setters and
--   so it does the job of both <tt><a>ASetter'</a></tt> and
--   <tt><a>Setter'</a></tt>.
type ASetter' s a = ASetter s s a a

-- | Functions that operate on getters and folds – such as (<a>^.</a>),
--   (<a>^..</a>), (<a>^?</a>) – use <tt>Getter r s a</tt> (with different
--   values of <tt>r</tt>) to describe what kind of result they need. For
--   instance, (<a>^.</a>) needs the getter to be able to return a single
--   value, and so it accepts a getter of type <tt>Getting a s a</tt>.
--   (<a>^..</a>) wants the getter to gather values together, so it uses
--   <tt>Getting (Endo [a]) s a</tt> (it could've used <tt>Getting [a] s
--   a</tt> instead, but it's faster with <a>Endo</a>). The choice of
--   <tt>r</tt> depends on what you want to do with elements you're
--   extracting from <tt>s</tt>.
type Getting r s a = a -> Const r a -> s -> Const r s

-- | <tt>Lens s t a b</tt> is the lowest common denominator of a setter and
--   a getter, something that has the power of both; it has a
--   <a>Functor</a> constraint, and since both <a>Const</a> and
--   <a>Identity</a> are functors, it can be used whenever a getter or a
--   setter is needed.
--   
--   <ul>
--   <li><tt>a</tt> is the type of the value inside of structure</li>
--   <li><tt>b</tt> is the type of the replaced value</li>
--   <li><tt>s</tt> is the type of the whole structure</li>
--   <li><tt>t</tt> is the type of the structure after replacing <tt>a</tt>
--   in it with <tt>b</tt></li>
--   </ul>
type Lens s t a b = forall (f :: Type -> Type). Functor f => a -> f b -> s -> f t

-- | This is a type alias for monomorphic lenses which don't change the
--   type of the container (or of the value inside).
type Lens' s a = Lens s s a a

-- | A <tt>SimpleGetter s a</tt> extracts <tt>a</tt> from <tt>s</tt>; so,
--   it's the same thing as <tt>(s -&gt; a)</tt>, but you can use it in
--   lens chains because its type looks like this:
--   
--   <pre>
--   type SimpleGetter s a =
--     forall r. (a -&gt; Const r a) -&gt; s -&gt; Const r s
--   </pre>
--   
--   Since <tt>Const r</tt> is a functor, <a>SimpleGetter</a> has the same
--   shape as other lens types and can be composed with them. To get <tt>(s
--   -&gt; a)</tt> out of a <a>SimpleGetter</a>, choose <tt>r ~ a</tt> and
--   feed <tt>Const :: a -&gt; Const a a</tt> to the getter:
--   
--   <pre>
--   -- the actual signature is more permissive:
--   -- <a>view</a> :: <a>Getting</a> a s a -&gt; s -&gt; a
--   <a>view</a> :: <a>SimpleGetter</a> s a -&gt; s -&gt; a
--   <a>view</a> getter = <a>getConst</a> . getter <a>Const</a>
--   </pre>
--   
--   The actual <tt><a>Getter</a></tt> from lens is more general:
--   
--   <pre>
--   type Getter s a =
--     forall f. (Contravariant f, Functor f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   I'm not currently aware of any functions that take lens's
--   <tt>Getter</tt> but won't accept <a>SimpleGetter</a>, but you should
--   try to avoid exporting <a>SimpleGetter</a>s anyway to minimise
--   confusion. Alternatively, look at <a>microlens-contra</a>, which
--   provides a fully lens-compatible <tt>Getter</tt>.
--   
--   Lens users: you can convert a <a>SimpleGetter</a> to <tt>Getter</tt>
--   by applying <tt>to . view</tt> to it.
type SimpleGetter s a = forall r. () => Getting r s a

-- | <a>lens</a> creates a <a>Lens</a> from a getter and a setter. The
--   resulting lens isn't the most effective one (because of having to
--   traverse the structure twice when modifying), but it shouldn't matter
--   much.
--   
--   A (partial) lens for list indexing:
--   
--   <pre>
--   ix :: Int -&gt; <a>Lens'</a> [a] a
--   ix i = <a>lens</a> (<a>!!</a> i)                                   -- getter
--               (\s b -&gt; take i s ++ b : drop (i+1) s)   -- setter
--   </pre>
--   
--   Usage:
--   
--   <pre>
--   &gt;&gt;&gt; [1..9] <a>^.</a> ix 3
--   4
--   
--   &gt;&gt;&gt; [1..9] &amp; ix 3 <a>%~</a> negate
--   [1,2,3,-4,5,6,7,8,9]
--   </pre>
--   
--   When getting, the setter is completely unused; when setting, the
--   getter is unused. Both are used only when the value is being modified.
--   For instance, here we define a lens for the 1st element of a list, but
--   instead of a legitimate getter we use <a>undefined</a>. Then we use
--   the resulting lens for <i>setting</i> and it works, which proves that
--   the getter wasn't used:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &amp; lens undefined (\s b -&gt; b : tail s) .~ 10
--   [10,2,3]
--   </pre>
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b

-- | <a>over</a> is a synonym for (<a>%~</a>).
--   
--   Getting <a>fmap</a> in a roundabout way:
--   
--   <pre>
--   <a>over</a> <a>mapped</a> :: <a>Functor</a> f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   <a>over</a> <a>mapped</a> = <a>fmap</a>
--   </pre>
--   
--   Applying a function to both components of a pair:
--   
--   <pre>
--   <a>over</a> <a>both</a> :: (a -&gt; b) -&gt; (a, a) -&gt; (b, b)
--   <a>over</a> <a>both</a> = \f t -&gt; (f (fst t), f (snd t))
--   </pre>
--   
--   Using <tt><a>over</a> <a>_2</a></tt> as a replacement for
--   <a>second</a>:
--   
--   <pre>
--   &gt;&gt;&gt; over _2 show (10,20)
--   (10,"20")
--   </pre>
over :: ASetter s t a b -> (a -> b) -> s -> t

-- | <a>set</a> is a synonym for (<a>.~</a>).
--   
--   Setting the 1st component of a pair:
--   
--   <pre>
--   <a>set</a> <a>_1</a> :: x -&gt; (a, b) -&gt; (x, b)
--   <a>set</a> <a>_1</a> = \x t -&gt; (x, snd t)
--   </pre>
--   
--   Using it to rewrite (<a>&lt;$</a>):
--   
--   <pre>
--   <a>set</a> <a>mapped</a> :: <a>Functor</a> f =&gt; a -&gt; f b -&gt; f a
--   <a>set</a> <a>mapped</a> = (<a>&lt;$</a>)
--   </pre>
set :: ASetter s t a b -> b -> s -> t

-- | <a>sets</a> creates an <a>ASetter</a> from an ordinary function. (The
--   only thing it does is wrapping and unwrapping <a>Identity</a>.)
sets :: ((a -> b) -> s -> t) -> ASetter s t a b

-- | <a>to</a> creates a getter from any function:
--   
--   <pre>
--   a <a>^.</a> <a>to</a> f = f a
--   </pre>
--   
--   It's most useful in chains, because it lets you mix lenses and
--   ordinary functions. Suppose you have a record which comes from some
--   third-party library and doesn't have any lens accessors. You want to
--   do something like this:
--   
--   <pre>
--   value ^. _1 . field . at 2
--   </pre>
--   
--   However, <tt>field</tt> isn't a getter, and you have to do this
--   instead:
--   
--   <pre>
--   field (value ^. _1) ^. at 2
--   </pre>
--   
--   but now <tt>value</tt> is in the middle and it's hard to read the
--   resulting code. A variant with <a>to</a> is prettier and more
--   readable:
--   
--   <pre>
--   value ^. _1 . to field . at 2
--   </pre>
to :: (s -> a) -> SimpleGetter s a

-- | (<a>^.</a>) applies a getter to a value; in other words, it gets a
--   value out of a structure using a getter (which can be a lens,
--   traversal, fold, etc.).
--   
--   Getting 1st field of a tuple:
--   
--   <pre>
--   (<a>^.</a> <a>_1</a>) :: (a, b) -&gt; a
--   (<a>^.</a> <a>_1</a>) = <a>fst</a>
--   </pre>
--   
--   When (<a>^.</a>) is used with a traversal, it combines all results
--   using the <a>Monoid</a> instance for the resulting type. For instance,
--   for lists it would be simple concatenation:
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") ^. each
--   "string"
--   </pre>
--   
--   The reason for this is that traversals use <a>Applicative</a>, and the
--   <a>Applicative</a> instance for <a>Const</a> uses monoid concatenation
--   to combine “effects” of <a>Const</a>.
--   
--   A non-operator version of (<a>^.</a>) is called <tt>view</tt>, and
--   it's a bit more general than (<a>^.</a>) (it works in
--   <tt>MonadReader</tt>). If you need the general version, you can get it
--   from <a>microlens-mtl</a>; otherwise there's <a>view</a> available in
--   <a>Lens.Micro.Extras</a>.
(^.) :: s -> Getting a s a -> a
infixl 8 ^.

-- | <tt>s ^? t</tt> returns the 1st element <tt>t</tt> returns, or
--   <a>Nothing</a> if <tt>t</tt> doesn't return anything. It's trivially
--   implemented by passing the <a>First</a> monoid to the getter.
--   
--   Safe <a>head</a>:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^? each
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1..3] ^? each
--   Just 1
--   </pre>
--   
--   Converting <a>Either</a> to <a>Maybe</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Left 1 ^? _Right
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Right 1 ^? _Right
--   Just 1
--   </pre>
--   
--   A non-operator version of (<a>^?</a>) is called <tt>preview</tt>, and
--   – like <tt>view</tt> – it's a bit more general than (<a>^?</a>) (it
--   works in <tt>MonadReader</tt>). If you need the general version, you
--   can get it from <a>microlens-mtl</a>; otherwise there's <a>preview</a>
--   available in <a>Lens.Micro.Extras</a>.
(^?) :: s -> Getting (First a) s a -> Maybe a
infixl 8 ^?

-- | <tt>s ^.. t</tt> returns the list of all values that <tt>t</tt> gets
--   from <tt>s</tt>.
--   
--   A <a>Maybe</a> contains either 0 or 1 values:
--   
--   <pre>
--   &gt;&gt;&gt; Just 3 ^.. _Just
--   [3]
--   </pre>
--   
--   Gathering all values in a list of tuples:
--   
--   <pre>
--   &gt;&gt;&gt; [(1,2),(3,4)] ^.. each.each
--   [1,2,3,4]
--   </pre>
(^..) :: s -> Getting (Endo [a]) s a -> [a]
infixl 8 ^..

-- | (<a>%~</a>) applies a function to the target; an alternative
--   explanation is that it is an inverse of <a>sets</a>, which turns a
--   setter into an ordinary function. <tt><a>mapped</a> <a>%~</a>
--   <a>reverse</a></tt> is the same thing as <tt><a>fmap</a>
--   <a>reverse</a></tt>.
--   
--   See <a>over</a> if you want a non-operator synonym.
--   
--   Negating the 1st element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) &amp; _1 %~ negate
--   (-1,2)
--   </pre>
--   
--   Turning all <tt>Left</tt>s in a list to upper case:
--   
--   <pre>
--   &gt;&gt;&gt; (mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]
--   [Left "FOO",Right "bar"]
--   </pre>
(%~) :: ASetter s t a b -> (a -> b) -> s -> t
infixr 4 %~

-- | (<a>.~</a>) assigns a value to the target. It's the same thing as
--   using (<a>%~</a>) with <a>const</a>:
--   
--   <pre>
--   l <a>.~</a> x = l <a>%~</a> <a>const</a> x
--   </pre>
--   
--   See <a>set</a> if you want a non-operator synonym.
--   
--   Here it is used to change 2 fields of a 3-tuple:
--   
--   <pre>
--   &gt;&gt;&gt; (0,0,0) &amp; _1 .~ 1 &amp; _3 .~ 3
--   (1,0,3)
--   </pre>
(.~) :: ASetter s t a b -> b -> s -> t
infixr 4 .~

-- | A <a>ThreadId</a> is an abstract type representing a handle to a
--   thread. <a>ThreadId</a> is an instance of <a>Eq</a>, <a>Ord</a> and
--   <a>Show</a>, where the <a>Ord</a> instance implements an arbitrary
--   total ordering over <a>ThreadId</a>s. The <a>Show</a> instance lets
--   you convert an arbitrary-valued <a>ThreadId</a> to string form;
--   showing a <a>ThreadId</a> value is occasionally useful when debugging
--   or diagnosing the behaviour of a concurrent program.
--   
--   <i>Note</i>: in GHC, if you have a <a>ThreadId</a>, you essentially
--   have a pointer to the thread itself. This means the thread itself
--   can't be garbage collected until you drop the <a>ThreadId</a>. This
--   misfeature will hopefully be corrected at a later date.
data ThreadId

-- | Lifted version of <a>myThreadId</a>.
myThreadId :: MonadIO m => m ThreadId

-- | Lifted version of <a>isCurrentThreadBound</a>.
isCurrentThreadBound :: MonadIO m => m Bool

-- | Lifted version of <a>threadWaitRead</a>.
threadWaitRead :: MonadIO m => Fd -> m ()

-- | Lifted version of <a>threadWaitWrite</a>.
threadWaitWrite :: MonadIO m => Fd -> m ()

-- | Lifted version of <a>threadDelay</a>.
threadDelay :: MonadIO m => Int -> m ()
yieldThread :: MonadIO m => m ()

-- | Throw an exception. Note that this throws when this action is run in
--   the monad <tt>m</tt>, not when it is applied. It is a generalization
--   of <a>Control.Exception</a>'s <a>throwIO</a>.
--   
--   Should satisfy the law:
--   
--   <pre>
--   throwM e &gt;&gt; f = throwM e
--   </pre>
throwM :: (MonadThrow m, Exception e) => e -> m a

-- | Lazily get the contents of a file. Unlike <a>readFile</a>, this
--   ensures that if an exception is thrown, the file handle is closed
--   immediately.
withLazyFile :: MonadUnliftIO m => FilePath -> (ByteString -> m a) -> m a

-- | Lazily read a file in UTF8 encoding.
withLazyFileUtf8 :: MonadUnliftIO m => FilePath -> (Text -> m a) -> m a

-- | Same as <a>readFile</a>, but generalized to <a>MonadIO</a>
readFileBinary :: MonadIO m => FilePath -> m ByteString

-- | Same as <a>writeFile</a>, but generalized to <a>MonadIO</a>
writeFileBinary :: MonadIO m => FilePath -> ByteString -> m ()

-- | Read a file in UTF8 encoding, throwing an exception on invalid
--   character encoding.
--   
--   This function will use OS-specific line ending handling.
readFileUtf8 :: MonadIO m => FilePath -> m Text

-- | Write a file in UTF8 encoding
--   
--   This function will use OS-specific line ending handling.
writeFileUtf8 :: MonadIO m => FilePath -> Text -> m ()
hPutBuilder :: MonadIO m => Handle -> Builder -> m ()

-- | Lifted version of "System.Exit.exitFailure".
--   
--   @since 0.1.9.0.
exitFailure :: MonadIO m => m a

-- | Lifted version of "System.Exit.exitSuccess".
--   
--   @since 0.1.9.0.
exitSuccess :: MonadIO m => m a

-- | Lifted version of "System.Exit.exitWith".
--   
--   @since 0.1.9.0.
exitWith :: MonadIO m => ExitCode -> m a

-- | Defines the exit codes that a program can return.
data ExitCode

-- | indicates successful termination;
ExitSuccess :: ExitCode

-- | indicates program failure with an exit code. The exact interpretation
--   of the code is operating-system dependent. In particular, some values
--   may be prohibited (e.g. 0 on a POSIX-compliant system).
ExitFailure :: Int -> ExitCode

-- | Environment values with writing capabilities to SomeRef
class HasWriteRef w env | env -> w
writeRefL :: HasWriteRef w env => Lens' env (SomeRef w)

-- | Environment values with stateful capabilities to SomeRef
class HasStateRef s env | env -> s
stateRefL :: HasStateRef s env => Lens' env (SomeRef s)

-- | Abstraction over how to read from and write to a mutable reference
data SomeRef a

-- | Lift one RIO env to another.
mapRIO :: (outer -> inner) -> RIO inner a -> RIO outer a

-- | Read from a SomeRef
readSomeRef :: MonadIO m => SomeRef a -> m a

-- | Write to a SomeRef
writeSomeRef :: MonadIO m => SomeRef a -> a -> m ()

-- | Modify a SomeRef This function is subject to change due to the lack of
--   atomic operations
modifySomeRef :: MonadIO m => SomeRef a -> (a -> a) -> m ()

-- | create a new boxed SomeRef
newSomeRef :: MonadIO m => a -> m (SomeRef a)

-- | create a new unboxed SomeRef
newUnboxedSomeRef :: (MonadIO m, Unbox a) => a -> m (SomeRef a)

-- | An unboxed reference. This works like an <a>IORef</a>, but the data is
--   stored in a bytearray instead of a heap object, avoiding significant
--   allocation overhead in some cases. For a concrete example, see this
--   Stack Overflow question:
--   <a>https://stackoverflow.com/questions/27261813/why-is-my-little-stref-int-require-allocating-gigabytes</a>.
--   
--   The first parameter is the state token type, the same as would be used
--   for the <a>ST</a> monad. If you're using an <a>IO</a>-based monad, you
--   can use the convenience <a>IOURef</a> type synonym instead.
data URef s a

-- | Helpful type synonym for using a <a>URef</a> from an <a>IO</a>-based
--   stack.
type IOURef = URef (PrimState IO)

-- | Create a new <a>URef</a>
newURef :: (PrimMonad m, Unbox a) => a -> m (URef (PrimState m) a)

-- | Read the value in a <a>URef</a>
readURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> m a

-- | Write a value into a <a>URef</a>. Note that this action is strict, and
--   will force evalution of the value.
writeURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> a -> m ()

-- | Modify a value in a <a>URef</a>. Note that this action is strict, and
--   will force evaluation of the result value.
modifyURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> (a -> a) -> m ()


-- | <i>Warning: Trace statement left in code</i>
trace :: Text -> a -> a


-- | <i>Warning: Trace statement left in code</i>
traceId :: Text -> Text


-- | <i>Warning: Trace statement left in code</i>
traceIO :: MonadIO m => Text -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceM :: Applicative f => Text -> f ()


-- | <i>Warning: Trace statement left in code</i>
traceEvent :: Text -> a -> a


-- | <i>Warning: Trace statement left in code</i>
traceEventIO :: MonadIO m => Text -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceMarker :: Text -> a -> a


-- | <i>Warning: Trace statement left in code</i>
traceMarkerIO :: MonadIO m => Text -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceStack :: Text -> a -> a


-- | <i>Warning: Trace statement left in code</i>
traceShow :: Show a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceShowId :: Show a => a -> a


-- | <i>Warning: Trace statement left in code</i>
traceShowIO :: (Show a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceShowM :: (Show a, Applicative f) => a -> f ()


-- | <i>Warning: Trace statement left in code</i>
traceShowEvent :: Show a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceShowEventIO :: (Show a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceShowMarker :: Show a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceShowMarkerIO :: (Show a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceShowStack :: Show a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceDisplay :: Display a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceDisplayId :: Display a => a -> a


-- | <i>Warning: Trace statement left in code</i>
traceDisplayIO :: (Display a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceDisplayM :: (Display a, Applicative f) => a -> f ()


-- | <i>Warning: Trace statement left in code</i>
traceDisplayEvent :: Display a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceDisplayEventIO :: (Display a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceDisplayMarker :: Display a => a -> b -> b


-- | <i>Warning: Trace statement left in code</i>
traceDisplayMarkerIO :: (Display a, MonadIO m) => a -> m ()


-- | <i>Warning: Trace statement left in code</i>
traceDisplayStack :: Display a => a -> b -> b


-- | Lazy <tt>ByteString</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.ByteString.Lazy as BL
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.ByteString.Lazy.Partial</a>
module RIO.ByteString.Lazy

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A lazy <a>ByteString</a> contains 8-bit bytes, or by using the
--   operations from <a>Data.ByteString.Lazy.Char8</a> it can be
--   interpreted as containing 8-bit characters.
data ByteString

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

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'.
unpack :: ByteString -> [Word8]

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

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   lazy ByteString into memory and then copies all the data. If possible,
--   try to avoid converting back and forth between strict and lazy
--   bytestrings.
toStrict :: ByteString -> ByteString

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

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
--   <a>ByteString</a>
toChunks :: ByteString -> [ByteString]

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

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

-- | <i>O(1)</i> <a>cons</a> is analogous to <a>(:)</a> for lists.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(1)</i> Unlike <a>cons</a>, <a>cons'</a> is strict in the
--   ByteString that we are consing onto. More precisely, it forces the
--   head and the first chunk. It does this because, for space efficiency,
--   it may coalesce the new byte onto the first 'chunk' rather than
--   starting a new 'chunk'.
--   
--   So that means you can't use a lazy recursive contruction like this:
--   
--   <pre>
--   let xs = cons' c xs in xs
--   </pre>
--   
--   You can however use <a>cons</a>, as well as <a>repeat</a> and
--   <a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: Word8 -> ByteString -> ByteString
infixr 5 `cons'`

-- | <i>O(n/c)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`

-- | <i>O(n/c)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(n/c)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
--   returning Nothing if it is empty.
--   
--   <ul>
--   <li>It is no faster than using <a>init</a> and <a>last</a></li>
--   </ul>
unsnoc :: ByteString -> Maybe (ByteString, Word8)

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(c)</i> <a>length</a> returns the length of a ByteString as an
--   <a>Int64</a>
length :: ByteString -> Int64

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

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

-- | The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

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

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

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

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

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
--   determines if all elements of the <a>ByteString</a> satisfy the
--   predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <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 :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt>
--   the value of every element.
repeat :: Word8 -> ByteString

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
replicate :: Int64 -> Word8 -> ByteString

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString.
cycle :: ByteString -> ByteString

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
iterate :: (Word8 -> Word8) -> Word8 -> ByteString

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List
--   'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in
--   which case, <tt>a</tt> is a prepending to the ByteString and
--   <tt>b</tt> is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n/c)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)

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

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

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings 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 :: ByteString -> [ByteString]

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

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

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

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith (==97) []        == []
--   </pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

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

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

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

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

-- | <i>O(c)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int64 -> Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element. This
--   implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs ==
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int64]

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int64

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int64]

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int64

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

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | Lifted <a>getContents</a>
getContents :: MonadIO m => m LByteString

-- | Lifted <a>putStr</a>
putStr :: MonadIO m => LByteString -> m ()

-- | Lifted <a>putStrLn</a>
putStrLn :: MonadIO m => LByteString -> m ()

-- | Lifted <a>interact</a>
interact :: MonadIO m => (LByteString -> LByteString) -> m ()

-- | Lifted <a>readFile</a>
readFile :: MonadIO m => FilePath -> m LByteString

-- | Lifted <a>writeFile</a>
writeFile :: MonadIO m => FilePath -> LByteString -> m ()

-- | Lifted <a>appendFile</a>
appendFile :: MonadIO m => FilePath -> LByteString -> m ()

-- | Lifted <a>hGetContents</a>
hGetContents :: MonadIO m => Handle -> m LByteString

-- | Lifted <a>hGet</a>
hGet :: MonadIO m => Handle -> Int -> m LByteString

-- | Lifted <a>hGetNonBlocking</a>
hGetNonBlocking :: MonadIO m => Handle -> Int -> m LByteString

-- | Lifted <a>hPut</a>
hPut :: MonadIO m => Handle -> LByteString -> m ()

-- | Lifted <a>hPutNonBlocking</a>
hPutNonBlocking :: MonadIO m => Handle -> LByteString -> m LByteString

-- | Lifted <a>hPutStr</a>
hPutStr :: MonadIO m => Handle -> LByteString -> m ()


-- | Strict <tt>ByteString</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.ByteString as B
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.ByteString.Partial</a>
module RIO.ByteString

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

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

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

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

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

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   and:
--   
--   <pre>
--   findSubstring s l ==
--      if null s then Just 0
--                else case breakSubstring s l of
--                         (x,y) | null y    -&gt; Nothing
--                               | otherwise -&gt; Just (length x)
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Check whether one string is a substring of another. <tt>isInfixOf p
--   s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implemenation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

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

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

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

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>findIndexEnd</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the last element in the
--   ByteString satisfying the predicate.
findIndexEnd :: (Word8 -> Bool) -> ByteString -> Maybe Int

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

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs ==
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element. This
--   implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int -> Word8

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

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

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings 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. It is about 40% faster than <i>groupBy
--   (==)</i>
group :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith (==97) []        == []
--   </pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
--   <a>ByteString</a>. We have
--   
--   <pre>
--   spanEnd (not.isSpace) "x y z" == ("x y ","z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      ==
--   let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
--   <a>ByteString</a>
--   
--   breakEnd p == spanEnd (not.p)
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
--   
--   Under GHC, a rewrite rule will transform break (==) into a call to the
--   specialised breakByte:
--   
--   <pre>
--   break ((==) x) = breakByte x
--   break (==x) = breakByte x
--   </pre>
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>dropWhileEnd</a> <tt>p xs</tt> returns the prefix remaining after
--   <a>takeWhileEnd</a> <tt>p xs</tt>.
dropWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

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

-- | <a>takeWhileEnd</a>, applied to a predicate <tt>p</tt> and a
--   ByteString <tt>xs</tt>, returns the longest suffix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

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

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   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 <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a)

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ByteString from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Word8 -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument. This function will fuse.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <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 :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   list.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
--   determines if all elements of the <a>ByteString</a> satisfy the
--   predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

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

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a

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

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <i>O(n)</i> The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

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

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
--   returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Word8)

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(n)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
--   <a>Int</a>.
length :: ByteString -> Int

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <tt>[<a>Word8</a>]</tt>.
unpack :: ByteString -> [Word8]

-- | <i>O(n)</i> Convert a <tt>[<a>Word8</a>]</tt> into a
--   <a>ByteString</a>.
--   
--   For applications with large numbers of string literals, <a>pack</a>
--   can be a bottleneck. In such cases, consider using
--   <a>unsafePackAddress</a> (GHC only).
pack :: [Word8] -> ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

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

-- | Lifted <a>packCString</a>
packCString :: MonadIO m => CString -> m ByteString

-- | Lifted <a>packCStringLen</a>
packCStringLen :: MonadIO m => CStringLen -> m ByteString

-- | Unlifted <a>useAsCString</a>
useAsCString :: MonadUnliftIO m => ByteString -> (CString -> m a) -> m a

-- | Unlifted <a>useAsCStringLen</a>
useAsCStringLen :: MonadUnliftIO m => ByteString -> (CStringLen -> m a) -> m a

-- | Lifted <a>getLine</a>
getLine :: MonadIO m => m ByteString

-- | Lifted <a>getContents</a>
getContents :: MonadIO m => m ByteString

-- | Lifted <a>putStr</a>
putStr :: MonadIO m => ByteString -> m ()

-- | Lifted <a>interact</a>
interact :: MonadIO m => (ByteString -> ByteString) -> m ()

-- | Lifted <a>readFile</a>
readFile :: MonadIO m => FilePath -> m ByteString

-- | Lifted <a>writeFile</a>
writeFile :: MonadIO m => FilePath -> ByteString -> m ()

-- | Lifted <a>appendFile</a>
appendFile :: MonadIO m => FilePath -> ByteString -> m ()

-- | Lifted <a>hGetLine</a>
hGetLine :: MonadIO m => Handle -> m ByteString

-- | Lifted <a>hGetContents</a>
hGetContents :: MonadIO m => Handle -> m ByteString

-- | Lifted <a>hGet</a>
hGet :: MonadIO m => Handle -> Int -> m ByteString

-- | Lifted <a>hGetSome</a>
hGetSome :: MonadIO m => Handle -> Int -> m ByteString

-- | Lifted <a>hGetNonBlocking</a>
hGetNonBlocking :: MonadIO m => Handle -> Int -> m ByteString

-- | Lifted <a>hPut</a>
hPut :: MonadIO m => Handle -> ByteString -> m ()

-- | Lifted <a>hPutNonBlocking</a>
hPutNonBlocking :: MonadIO m => Handle -> ByteString -> m ByteString

-- | Lifted <a>hPutStr</a>
hPutStr :: MonadIO m => Handle -> ByteString -> m ()


-- | Lazy <tt>Text</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Text.Lazy as TL
--   </pre>
--   
--   This module does not export any partial functions. For those, see
--   <a>RIO.Text.Lazy.Partial</a>
module RIO.Text.Lazy
data Text

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

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

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

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

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

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

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

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

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

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

-- | <i>O(1)</i> Adds a character to the front of a <a>Text</a>. Subject to
--   fusion.
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, unless fused. Subject to fusion.
snoc :: Text -> Char -> Text

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | <i>O(n)</i> Left-justify a string to the given length, using the
--   specified fill character on the right. Subject to fusion. Performs
--   replacement on invalid scalar values.
--   
--   Examples:
--   
--   <pre>
--   justifyLeft 7 'x' "foo"    == "fooxxxx"
--   justifyLeft 3 'x' "foobar" == "foobar"
--   </pre>
justifyLeft :: Int64 -> Char -> Text -> Text

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

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

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

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

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

-- | <i>O(n)</i> 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>. Subject to fusion.
any :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> <a>all</a> <tt>p</tt> <tt>t</tt> determines whether all
--   characters in the <a>Text</a> <tt>t</tt> satisfy the predicate
--   <tt>p</tt>. Subject to fusion.
all :: (Char -> Bool) -> 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. Subject to fusion.
--   Performs replacement on invalid scalar values.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> Text -> Text

-- | <i>O(n)</i> <a>scanl1</a> is a variant of <a>scanl</a> that has no
--   starting value argument. 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 :: 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. Subject to fusion. Performs
--   replacement on invalid scalar values.
unfoldr :: (a -> Maybe (Char, a)) -> a -> Text

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

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

-- | <i>O(n)</i> <a>takeEnd</a> <tt>n</tt> <tt>t</tt> returns the suffix
--   remaining after taking <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   takeEnd 3 "foobar" == "bar"
--   </pre>
takeEnd :: Int64 -> Text -> Text

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

-- | <i>O(n)</i> <a>dropEnd</a> <tt>n</tt> <tt>t</tt> returns the prefix
--   remaining after dropping <tt>n</tt> characters from the end of
--   <tt>t</tt>.
--   
--   Examples:
--   
--   <pre>
--   dropEnd 3 "foobar" == "foo"
--   </pre>
dropEnd :: Int64 -> Text -> Text

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

-- | <i>O(n)</i> <a>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>. Subject to
--   fusion.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <a>dropWhileEnd</a> <tt>p</tt> <tt>t</tt> returns the
--   prefix remaining after dropping characters that 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 list.
--   
--   <pre>
--   &gt;&gt;&gt; T.span (=='0') "000AB"
--   ("000","AB")
--   </pre>
span :: (Char -> Bool) -> 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 final segments of the given <a>Text</a>,
--   longest first.
tails :: Text -> [Text]

-- | <i>O(n)</i> Splits a <a>Text</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   split (=='a') "aabbaca" == ["","","bb","c",""]
--   split (=='a') []        == [""]
--   </pre>
split :: (Char -> Bool) -> Text -> [Text]

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

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

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

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

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

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

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

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

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

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

-- | <i>O(n)</i> Find the longest non-empty common prefix of two strings
--   and return it, along with the suffixes of each string at which they no
--   longer match.
--   
--   If the strings do not have a common prefix or either one is empty,
--   this function returns <a>Nothing</a>.
--   
--   Examples:
--   
--   <pre>
--   commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
--   commonPrefixes "veeble" "fetzer"  == Nothing
--   commonPrefixes "" "baz"           == Nothing
--   </pre>
commonPrefixes :: Text -> Text -> Maybe (Text, Text, Text)

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

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

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

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

-- | <i>O(n+m)</i> The <a>count</a> function returns the number of times
--   the query string appears in the given <a>Text</a>. An empty query
--   string is invalid, and will cause an error to be raised.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
count :: Text -> Text -> Int64

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

-- | <i>O(n)</i> <a>zipWith</a> generalises <a>zip</a> by zipping with the
--   function given as the first argument, instead of a tupling function.
--   Performs replacement on invalid scalar values.
zipWith :: (Char -> Char -> Char) -> Text -> Text -> Text


-- | Lazy <tt>Text</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Text.Lazy.Partial as TL'
--   </pre>
module RIO.Text.Lazy.Partial

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

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

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

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

-- | <i>O(m+n)</i> Replace every non-overlapping occurrence of
--   <tt>needle</tt> in <tt>haystack</tt> with <tt>replacement</tt>.
--   
--   This function behaves as though it was defined as follows:
--   
--   <pre>
--   replace needle replacement haystack =
--     <a>intercalate</a> replacement (<a>splitOn</a> needle haystack)
--   </pre>
--   
--   As this suggests, each occurrence is replaced exactly once. So if
--   <tt>needle</tt> occurs in <tt>replacement</tt>, that occurrence will
--   <i>not</i> itself be replaced recursively:
--   
--   <pre>
--   replace "oo" "foo" "oo" == "foo"
--   </pre>
--   
--   In cases where several instances of <tt>needle</tt> overlap, only the
--   first one will be replaced:
--   
--   <pre>
--   replace "ofo" "bar" "ofofo" == "barfo"
--   </pre>
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
replace :: Text -> Text -> Text -> Text

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

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

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

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

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

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

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

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

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


-- | Strict <tt>Text</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Text.Partial as T'
--   </pre>
module RIO.Text.Partial

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

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

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

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

-- | <i>O(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 :: Text -> Text -> Text -> Text

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

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

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

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

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

-- | <i>O(n+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 :: 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 :: Text -> Text -> (Text, Text)

-- | <i>O(m+n)</i> Break a <a>Text</a> into pieces separated by the first
--   <a>Text</a> argument (which cannot be empty), consuming the delimiter.
--   An empty delimiter is invalid, and will cause an error to be raised.
--   
--   Examples:
--   
--   <pre>
--   &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 :: Text -> 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 :: Text -> Text -> [(Text, Text)]

-- | <i>O(n+m)</i> The <a>count</a> function returns the number of times
--   the query string appears in the given <a>Text</a>. An empty query
--   string is invalid, and will cause an error to be raised.
--   
--   In (unlikely) bad cases, this function's time complexity degrades
--   towards <i>O(n*m)</i>.
count :: Text -> Text -> Int

module RIO.Time
readsTime :: ParseTime t => TimeLocale -> String -> ReadS t
readTime :: ParseTime t => TimeLocale -> String -> String -> t
parseTime :: ParseTime t => TimeLocale -> String -> String -> Maybe t

-- | Parse a time value given a format string. See <a>parseTimeM</a> for
--   details.
readPTime :: ParseTime t => Bool -> TimeLocale -> String -> ReadP t

-- | Parse a time value given a format string. See <a>parseTimeM</a> for
--   details.
readSTime :: ParseTime t => Bool -> TimeLocale -> String -> ReadS t

-- | Parse a time value given a format string. Fails if the input could not
--   be parsed using the given format. See <a>parseTimeM</a> for details.
parseTimeOrError :: ParseTime t => Bool -> TimeLocale -> String -> String -> t

-- | Parses a time value given a format string. Supports the same %-codes
--   as <tt>formatTime</tt>, including <tt>%-</tt>, <tt>%_</tt> and
--   <tt>%0</tt> modifiers, however padding widths are not supported. Case
--   is not significant in the input string. Some variations in the input
--   are accepted:
--   
--   <ul>
--   <li><i><tt>%z</tt></i> accepts any of <tt>±HHMM</tt> or
--   <tt>±HH:MM</tt>.</li>
--   <li><i><tt>%Z</tt></i> accepts any string of letters, or any of the
--   formats accepted by <tt>%z</tt>.</li>
--   <li><i><tt>%0Y</tt></i> accepts exactly four digits.</li>
--   <li><i><tt>%0G</tt></i> accepts exactly four digits.</li>
--   <li><i><tt>%0C</tt></i> accepts exactly two digits.</li>
--   <li><i><tt>%0f</tt></i> accepts exactly two digits.</li>
--   </ul>
--   
--   For example, to parse a date in YYYY-MM-DD format, while allowing the
--   month and date to have optional leading zeros (notice the <tt>-</tt>
--   modifier used for <tt>%m</tt> and <tt>%d</tt>):
--   
--   <pre>
--   Prelude Data.Time&gt; parseTimeM True defaultTimeLocale "%Y-%-m-%-d" "2010-3-04" :: Maybe Day
--   Just 2010-03-04
--   </pre>
parseTimeM :: (MonadFail m, ParseTime t) => Bool -> TimeLocale -> String -> String -> m t
zonedTimeToUTC :: ZonedTime -> UTCTime
utcToZonedTime :: TimeZone -> UTCTime -> ZonedTime

-- | A local time together with a time zone.
--   
--   There is no <a>Eq</a> instance for <tt>ZonedTime</tt>. If you want to
--   compare local times, use <a>zonedTimeToLocalTime</a>. If you want to
--   compare absolute times, use <a>zonedTimeToUTC</a>.
data ZonedTime
ZonedTime :: LocalTime -> TimeZone -> ZonedTime
[zonedTimeToLocalTime] :: ZonedTime -> LocalTime
[zonedTimeZone] :: ZonedTime -> TimeZone

-- | Substitute various time-related information for each %-code in the
--   string, as per <a>formatCharacter</a>.
--   
--   The general form is
--   <tt>%&lt;modifier&gt;&lt;width&gt;&lt;alternate&gt;&lt;specifier&gt;</tt>,
--   where <tt>&lt;modifier&gt;</tt>, <tt>&lt;width&gt;</tt>, and
--   <tt>&lt;alternate&gt;</tt> are optional.
--   
--   <h2><tt>&lt;modifier&gt;</tt></h2>
--   
--   glibc-style modifiers can be used before the specifier (here marked as
--   <tt>z</tt>):
--   
--   <ul>
--   <li><i><tt>%-z</tt></i> no padding</li>
--   <li><i><tt>%_z</tt></i> pad with spaces</li>
--   <li><i><tt>%0z</tt></i> pad with zeros</li>
--   <li><i><tt>%^z</tt></i> convert to upper case</li>
--   <li><i><tt>%#z</tt></i> convert to lower case (consistently, unlike
--   glibc)</li>
--   </ul>
--   
--   <h2><tt>&lt;width&gt;</tt></h2>
--   
--   Width digits can also be used after any modifiers and before the
--   specifier (here marked as <tt>z</tt>), for example:
--   
--   <ul>
--   <li><i><tt>%4z</tt></i> pad to 4 characters (with default padding
--   character)</li>
--   <li><i><tt>%_12z</tt></i> pad with spaces to 12 characters</li>
--   </ul>
--   
--   <h2><tt>&lt;alternate&gt;</tt></h2>
--   
--   An optional <tt>E</tt> character indicates an alternate formatting.
--   Currently this only affects <tt>%Z</tt> and <tt>%z</tt>.
--   
--   <ul>
--   <li><i><tt>%Ez</tt></i> alternate formatting</li>
--   </ul>
--   
--   <h2><tt>&lt;specifier&gt;</tt></h2>
--   
--   For all types (note these three are done by <a>formatTime</a>, not by
--   <a>formatCharacter</a>):
--   
--   <ul>
--   <li><i><tt>%%</tt></i> <tt>%</tt></li>
--   <li><i><tt>%t</tt></i> tab</li>
--   <li><i><tt>%n</tt></i> newline</li>
--   </ul>
--   
--   <h3><tt>TimeZone</tt></h3>
--   
--   For <tt>TimeZone</tt> (and <tt>ZonedTime</tt> and <tt>UTCTime</tt>):
--   
--   <ul>
--   <li><i><tt>%z</tt></i> timezone offset in the format
--   <tt>±HHMM</tt></li>
--   <li><i><tt>%Ez</tt></i> timezone offset in the format
--   <tt>±HH:MM</tt></li>
--   <li><i><tt>%Z</tt></i> timezone name (or else offset in the format
--   <tt>±HHMM</tt>)</li>
--   <li><i><tt>%EZ</tt></i> timezone name (or else offset in the format
--   <tt>±HH:MM</tt>)</li>
--   </ul>
--   
--   <h3><tt>LocalTime</tt></h3>
--   
--   For <tt>LocalTime</tt> (and <tt>ZonedTime</tt> and <tt>UTCTime</tt>
--   and <tt>UniversalTime</tt>):
--   
--   <ul>
--   <li><i><tt>%c</tt></i> as <a>dateTimeFmt</a> <tt>locale</tt> (e.g.
--   <tt>%a %b %e %H:%M:%S %Z %Y</tt>)</li>
--   </ul>
--   
--   <h3><tt>TimeOfDay</tt></h3>
--   
--   For <tt>TimeOfDay</tt> (and <tt>LocalTime</tt> and <tt>ZonedTime</tt>
--   and <tt>UTCTime</tt> and <tt>UniversalTime</tt>):
--   
--   <ul>
--   <li><i><tt>%R</tt></i> same as <tt>%H:%M</tt></li>
--   <li><i><tt>%T</tt></i> same as <tt>%H:%M:%S</tt></li>
--   <li><i><tt>%X</tt></i> as <a>timeFmt</a> <tt>locale</tt> (e.g.
--   <tt>%H:%M:%S</tt>)</li>
--   <li><i><tt>%r</tt></i> as <a>time12Fmt</a> <tt>locale</tt> (e.g.
--   <tt>%I:%M:%S %p</tt>)</li>
--   <li><i><tt>%P</tt></i> day-half of day from (<a>amPm</a>
--   <tt>locale</tt>), converted to lowercase, <tt>am</tt>,
--   <tt>pm</tt></li>
--   <li><i><tt>%p</tt></i> day-half of day from (<a>amPm</a>
--   <tt>locale</tt>), <tt>AM</tt>, <tt>PM</tt></li>
--   <li><i><tt>%H</tt></i> hour of day (24-hour), 0-padded to two chars,
--   <tt>00</tt> - <tt>23</tt></li>
--   <li><i><tt>%k</tt></i> hour of day (24-hour), space-padded to two
--   chars, <tt> 0</tt> - <tt>23</tt></li>
--   <li><i><tt>%I</tt></i> hour of day-half (12-hour), 0-padded to two
--   chars, <tt>01</tt> - <tt>12</tt></li>
--   <li><i><tt>%l</tt></i> hour of day-half (12-hour), space-padded to two
--   chars, <tt> 1</tt> - <tt>12</tt></li>
--   <li><i><tt>%M</tt></i> minute of hour, 0-padded to two chars,
--   <tt>00</tt> - <tt>59</tt></li>
--   <li><i><tt>%S</tt></i> second of minute (without decimal part),
--   0-padded to two chars, <tt>00</tt> - <tt>60</tt></li>
--   <li><i><tt>%q</tt></i> picosecond of second, 0-padded to twelve chars,
--   <tt>000000000000</tt> - <tt>999999999999</tt>.</li>
--   <li><i><tt>%Q</tt></i> decimal point and fraction of second, up to 12
--   second decimals, without trailing zeros. For a whole number of
--   seconds, <tt>%Q</tt> omits the decimal point unless padding is
--   specified.</li>
--   </ul>
--   
--   <h3><tt>UTCTime</tt> and <tt>ZonedTime</tt></h3>
--   
--   For <tt>UTCTime</tt> and <tt>ZonedTime</tt>:
--   
--   <ul>
--   <li><i><tt>%s</tt></i> number of whole seconds since the Unix epoch.
--   For times before the Unix epoch, this is a negative number. Note that
--   in <tt>%s.%q</tt> and <tt>%s%Q</tt> the decimals are positive, not
--   negative. For example, 0.9 seconds before the Unix epoch is formatted
--   as <tt>-1.1</tt> with <tt>%s%Q</tt>.</li>
--   </ul>
--   
--   <h3><tt>DayOfWeek</tt></h3>
--   
--   For <tt>DayOfWeek</tt> (and <tt>Day</tt> and <tt>LocalTime</tt> and
--   <tt>ZonedTime</tt> and <tt>UTCTime</tt> and <tt>UniversalTime</tt>):
--   
--   <ul>
--   <li><i><tt>%u</tt></i> day of week number for Week Date format,
--   <tt>1</tt> (= Monday) - <tt>7</tt> (= Sunday)</li>
--   <li><i><tt>%w</tt></i> day of week number, <tt>0</tt> (= Sunday) -
--   <tt>6</tt> (= Saturday)</li>
--   <li><i><tt>%a</tt></i> day of week, short form (<a>snd</a> from
--   <a>wDays</a> <tt>locale</tt>), <tt>Sun</tt> - <tt>Sat</tt></li>
--   <li><i><tt>%A</tt></i> day of week, long form (<a>fst</a> from
--   <a>wDays</a> <tt>locale</tt>), <tt>Sunday</tt> -
--   <tt>Saturday</tt></li>
--   </ul>
--   
--   <h3><tt>Day</tt></h3>
--   
--   For <tt>Day</tt> (and <tt>LocalTime</tt> and <tt>ZonedTime</tt> and
--   <tt>UTCTime</tt> and <tt>UniversalTime</tt>):
--   
--   <ul>
--   <li><i><tt>%D</tt></i> same as <tt>%m/%d/%y</tt></li>
--   <li><i><tt>%F</tt></i> same as <tt>%Y-%m-%d</tt></li>
--   <li><i><tt>%x</tt></i> as <a>dateFmt</a> <tt>locale</tt> (e.g.
--   <tt>%m/%d/%y</tt>)</li>
--   <li><i><tt>%Y</tt></i> year, no padding. Note <tt>%0Y</tt> and
--   <tt>%_Y</tt> pad to four chars</li>
--   <li><i><tt>%y</tt></i> year of century, 0-padded to two chars,
--   <tt>00</tt> - <tt>99</tt></li>
--   <li><i><tt>%C</tt></i> century, no padding. Note <tt>%0C</tt> and
--   <tt>%_C</tt> pad to two chars</li>
--   <li><i><tt>%B</tt></i> month name, long form (<a>fst</a> from
--   <a>months</a> <tt>locale</tt>), <tt>January</tt> -
--   <tt>December</tt></li>
--   <li><i><tt>%b</tt>, <tt>%h</tt></i> month name, short form (<a>snd</a>
--   from <a>months</a> <tt>locale</tt>), <tt>Jan</tt> - <tt>Dec</tt></li>
--   <li><i><tt>%m</tt></i> month of year, 0-padded to two chars,
--   <tt>01</tt> - <tt>12</tt></li>
--   <li><i><tt>%d</tt></i> day of month, 0-padded to two chars,
--   <tt>01</tt> - <tt>31</tt></li>
--   <li><i><tt>%e</tt></i> day of month, space-padded to two chars, <tt>
--   1</tt> - <tt>31</tt></li>
--   <li><i><tt>%j</tt></i> day of year, 0-padded to three chars,
--   <tt>001</tt> - <tt>366</tt></li>
--   <li><i><tt>%f</tt></i> century for Week Date format, no padding. Note
--   <tt>%0f</tt> and <tt>%_f</tt> pad to two chars</li>
--   <li><i><tt>%V</tt></i> week of year for Week Date format, 0-padded to
--   two chars, <tt>01</tt> - <tt>53</tt></li>
--   <li><i><tt>%U</tt></i> week of year where weeks start on Sunday (as
--   <tt>sundayStartWeek</tt>), 0-padded to two chars, <tt>00</tt> -
--   <tt>53</tt></li>
--   <li><i><tt>%W</tt></i> week of year where weeks start on Monday (as
--   <tt>mondayStartWeek</tt>), 0-padded to two chars, <tt>00</tt> -
--   <tt>53</tt></li>
--   </ul>
--   
--   <h2>Duration types</h2>
--   
--   The specifiers for <tt>DiffTime</tt>, <tt>NominalDiffTime</tt>,
--   <tt>CalendarDiffDays</tt>, and <tt>CalendarDiffTime</tt> are
--   semantically separate from the other types. Specifiers on negative
--   time differences will generally be negative (think <a>rem</a> rather
--   than <a>mod</a>).
--   
--   <h3><tt>NominalDiffTime</tt> and <tt>DiffTime</tt></h3>
--   
--   Note that a "minute" of <tt>DiffTime</tt> is simply 60 SI seconds,
--   rather than a minute of civil time. Use <tt>NominalDiffTime</tt> to
--   work with civil time, ignoring any leap seconds.
--   
--   For <tt>NominalDiffTime</tt> and <tt>DiffTime</tt>:
--   
--   <ul>
--   <li><i><tt>%w</tt></i> total whole weeks</li>
--   <li><i><tt>%d</tt></i> total whole days</li>
--   <li><i><tt>%D</tt></i> whole days of week</li>
--   <li><i><tt>%h</tt></i> total whole hours</li>
--   <li><i><tt>%H</tt></i> whole hours of day</li>
--   <li><i><tt>%m</tt></i> total whole minutes</li>
--   <li><i><tt>%M</tt></i> whole minutes of hour</li>
--   <li><i><tt>%s</tt></i> total whole seconds</li>
--   <li><i><tt>%Es</tt></i> total seconds, with decimal point and up to
--   &lt;width&gt; (default 12) decimal places, without trailing zeros. For
--   a whole number of seconds, <tt>%Es</tt> omits the decimal point unless
--   padding is specified.</li>
--   <li><i><tt>%0Es</tt></i> total seconds, with decimal point and
--   &lt;width&gt; (default 12) decimal places.</li>
--   <li><i><tt>%S</tt></i> whole seconds of minute</li>
--   <li><i><tt>%ES</tt></i> seconds of minute, with decimal point and up
--   to &lt;width&gt; (default 12) decimal places, without trailing zeros.
--   For a whole number of seconds, <tt>%ES</tt> omits the decimal point
--   unless padding is specified.</li>
--   <li><i><tt>%0ES</tt></i> seconds of minute as two digits, with decimal
--   point and &lt;width&gt; (default 12) decimal places.</li>
--   </ul>
--   
--   <h3><tt>CalendarDiffDays</tt></h3>
--   
--   For <tt>CalendarDiffDays</tt> (and <tt>CalendarDiffTime</tt>):
--   
--   <ul>
--   <li><i><tt>%y</tt></i> total years</li>
--   <li><i><tt>%b</tt></i> total months</li>
--   <li><i><tt>%B</tt></i> months of year</li>
--   <li><i><tt>%w</tt></i> total weeks, not including months</li>
--   <li><i><tt>%d</tt></i> total days, not including months</li>
--   <li><i><tt>%D</tt></i> days of week</li>
--   </ul>
--   
--   <h3><tt>CalendarDiffTime</tt></h3>
--   
--   For <tt>CalendarDiffTime</tt>:
--   
--   <ul>
--   <li><i><tt>%h</tt></i> total hours, not including months</li>
--   <li><i><tt>%H</tt></i> hours of day</li>
--   <li><i><tt>%m</tt></i> total minutes, not including months</li>
--   <li><i><tt>%M</tt></i> minutes of hour</li>
--   <li><i><tt>%s</tt></i> total whole seconds, not including months</li>
--   <li><i><tt>%Es</tt></i> total seconds, not including months, with
--   decimal point and up to &lt;width&gt; (default 12) decimal places,
--   without trailing zeros. For a whole number of seconds, <tt>%Es</tt>
--   omits the decimal point unless padding is specified.</li>
--   <li><i><tt>%0Es</tt></i> total seconds, not including months, with
--   decimal point and &lt;width&gt; (default 12) decimal places.</li>
--   <li><i><tt>%S</tt></i> whole seconds of minute</li>
--   <li><i><tt>%ES</tt></i> seconds of minute, with decimal point and up
--   to &lt;width&gt; (default 12) decimal places, without trailing zeros.
--   For a whole number of seconds, <tt>%ES</tt> omits the decimal point
--   unless padding is specified.</li>
--   <li><i><tt>%0ES</tt></i> seconds of minute as two digits, with decimal
--   point and &lt;width&gt; (default 12) decimal places.</li>
--   </ul>
formatTime :: FormatTime t => TimeLocale -> String -> t -> String
class FormatTime t

-- | The class of types which can be parsed given a UNIX-style time format
--   string.
class ParseTime t

-- | Format string according to <a>RFC822</a>.
rfc822DateFormat :: String

-- | Construct format string according to <a>ISO-8601</a>.
--   
--   The <tt>Maybe String</tt> argument allows to supply an optional time
--   specification. E.g.:
--   
--   <pre>
--   <a>iso8601DateFormat</a> Nothing            == "%Y-%m-%d"           -- i.e. <tt><i>YYYY-MM-DD</i></tt>
--   <a>iso8601DateFormat</a> (Just "%H:%M:%S")  == "%Y-%m-%dT%H:%M:%S"  -- i.e. <tt><i>YYYY-MM-DD</i>T<i>HH:MM:SS</i></tt>
--   </pre>
iso8601DateFormat :: Maybe String -> String

-- | Locale representing American usage.
--   
--   <a>knownTimeZones</a> contains only the ten time-zones mentioned in
--   RFC 822 sec. 5: "UT", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT",
--   "PST", "PDT". Note that the parsing functions will regardless parse
--   "UTC", single-letter military time-zones, and +HHMM format.
defaultTimeLocale :: TimeLocale
data TimeLocale
TimeLocale :: [(String, String)] -> [(String, String)] -> (String, String) -> String -> String -> String -> String -> [TimeZone] -> TimeLocale

-- | full and abbreviated week days, starting with Sunday
[wDays] :: TimeLocale -> [(String, String)]

-- | full and abbreviated months
[months] :: TimeLocale -> [(String, String)]

-- | AM/PM symbols
[amPm] :: TimeLocale -> (String, String)

-- | formatting strings
[dateTimeFmt] :: TimeLocale -> String

-- | formatting strings
[dateFmt] :: TimeLocale -> String

-- | formatting strings
[timeFmt] :: TimeLocale -> String

-- | formatting strings
[time12Fmt] :: TimeLocale -> String

-- | time zones known by name
[knownTimeZones] :: TimeLocale -> [TimeZone]

-- | Get the UT1 time of a local time on a particular meridian (in degrees,
--   positive is East).
localTimeToUT1 :: Rational -> LocalTime -> UniversalTime

-- | Get the local time of a UT1 time on a particular meridian (in degrees,
--   positive is East).
ut1ToLocalTime :: Rational -> UniversalTime -> LocalTime

-- | Get the UTC time of a local time in a time zone.
localTimeToUTC :: TimeZone -> LocalTime -> UTCTime

-- | Get the local time of a UTC time in a time zone.
utcToLocalTime :: TimeZone -> UTCTime -> LocalTime

-- | diffLocalTime a b = a - b
diffLocalTime :: LocalTime -> LocalTime -> NominalDiffTime

-- | addLocalTime a b = a + b
addLocalTime :: NominalDiffTime -> LocalTime -> LocalTime

-- | A simple day and time aggregate, where the day is of the specified
--   parameter, and the time is a TimeOfDay. Conversion of this (as local
--   civil time) to UTC depends on the time zone. Conversion of this (as
--   local mean time) to UT1 depends on the longitude.
data LocalTime
LocalTime :: Day -> TimeOfDay -> LocalTime
[localDay] :: LocalTime -> Day
[localTimeOfDay] :: LocalTime -> TimeOfDay

-- | Get the fraction of a day since midnight given a time of day.
timeOfDayToDayFraction :: TimeOfDay -> Rational

-- | Get the time of day given the fraction of a day since midnight.
dayFractionToTimeOfDay :: Rational -> TimeOfDay

-- | Get the time since midnight for a given time of day.
timeOfDayToTime :: TimeOfDay -> DiffTime

-- | Get the time of day given a time since midnight. Time more than 24h
--   will be converted to leap-seconds.
timeToTimeOfDay :: DiffTime -> TimeOfDay

-- | Convert a time of day in some timezone to a time of day in UTC,
--   together with a day adjustment.
localToUTCTimeOfDay :: TimeZone -> TimeOfDay -> (Integer, TimeOfDay)

-- | Convert a time of day in UTC to a time of day in some timezone,
--   together with a day adjustment.
utcToLocalTimeOfDay :: TimeZone -> TimeOfDay -> (Integer, TimeOfDay)

-- | Convert a count of days and a time of day since midnight into a period
--   of time.
daysAndTimeOfDayToTime :: Integer -> TimeOfDay -> NominalDiffTime

-- | Convert a period of time into a count of days and a time of day since
--   midnight. The time of day will never have a leap second.
timeToDaysAndTimeOfDay :: NominalDiffTime -> (Integer, TimeOfDay)
makeTimeOfDayValid :: Int -> Int -> Pico -> Maybe TimeOfDay

-- | Hour twelve
midday :: TimeOfDay

-- | Hour zero
midnight :: TimeOfDay

-- | Time of day as represented in hour, minute and second (with
--   picoseconds), typically used to express local time of day.
data TimeOfDay
TimeOfDay :: Int -> Int -> Pico -> TimeOfDay

-- | range 0 - 23
[todHour] :: TimeOfDay -> Int

-- | range 0 - 59
[todMin] :: TimeOfDay -> Int

-- | Note that 0 &lt;= <a>todSec</a> &lt; 61, accomodating leap seconds.
--   Any local minute may have a leap second, since leap seconds happen in
--   all zones simultaneously
[todSec] :: TimeOfDay -> Pico

-- | The UTC time zone.
utc :: TimeZone

-- | Text representing the offset of this timezone, such as "-0800" or
--   "+0400" (like <tt>%z</tt> in formatTime).
timeZoneOffsetString :: TimeZone -> String

-- | Text representing the offset of this timezone, such as "-0800" or
--   "+0400" (like <tt>%z</tt> in formatTime), with arbitrary padding.
timeZoneOffsetString' :: Maybe Char -> TimeZone -> String

-- | Create a nameless non-summer timezone for this number of hours.
hoursToTimeZone :: Int -> TimeZone

-- | Create a nameless non-summer timezone for this number of minutes.
minutesToTimeZone :: Int -> TimeZone

-- | A TimeZone is a whole number of minutes offset from UTC, together with
--   a name and a "just for summer" flag.
data TimeZone
TimeZone :: Int -> Bool -> String -> TimeZone

-- | The number of minutes offset from UTC. Positive means local time will
--   be later in the day than UTC.
[timeZoneMinutes] :: TimeZone -> Int

-- | Is this time zone just persisting for the summer?
[timeZoneSummerOnly] :: TimeZone -> Bool

-- | The name of the zone, typically a three- or four-letter acronym.
[timeZoneName] :: TimeZone -> String

-- | Scale by a factor. Note that <tt>scaleCalendarDiffTime (-1)</tt> will
--   not perfectly invert a duration, due to variable month lengths.
scaleCalendarDiffTime :: Integer -> CalendarDiffTime -> CalendarDiffTime
calendarTimeTime :: NominalDiffTime -> CalendarDiffTime
calendarTimeDays :: CalendarDiffDays -> CalendarDiffTime
data CalendarDiffTime
CalendarDiffTime :: Integer -> NominalDiffTime -> CalendarDiffTime
[ctMonths] :: CalendarDiffTime -> Integer
[ctTime] :: CalendarDiffTime -> NominalDiffTime

-- | diffUTCTime a b = a - b
diffUTCTime :: UTCTime -> UTCTime -> NominalDiffTime

-- | addUTCTime a b = a + b
addUTCTime :: NominalDiffTime -> UTCTime -> UTCTime

-- | The Modified Julian Date is the day with the fraction of the day,
--   measured from UT midnight. It's used to represent UT1, which is time
--   as measured by the earth's rotation, adjusted for various wobbles.
newtype UniversalTime
ModJulianDate :: Rational -> UniversalTime
[getModJulianDate] :: UniversalTime -> Rational

-- | This is the simplest representation of UTC. It consists of the day
--   number, and a time offset from midnight. Note that if a day has a leap
--   second added to it, it will have 86401 seconds.
data UTCTime
UTCTime :: Day -> DiffTime -> UTCTime

-- | the day
[utctDay] :: UTCTime -> Day

-- | the time from midnight, 0 &lt;= t &lt; 86401s (because of
--   leap-seconds)
[utctDayTime] :: UTCTime -> DiffTime

-- | The resolution of <a>getSystemTime</a>, <tt>getCurrentTime</tt>,
--   <tt>getPOSIXTime</tt>
getTime_resolution :: DiffTime

-- | One day in <a>NominalDiffTime</a>.
nominalDay :: NominalDiffTime

-- | Get the seconds in a <a>NominalDiffTime</a>.
nominalDiffTimeToSeconds :: NominalDiffTime -> Pico

-- | Create a <a>NominalDiffTime</a> from a number of seconds.
secondsToNominalDiffTime :: Pico -> NominalDiffTime

-- | This is a length of time, as measured by UTC. It has a precision of
--   10^-12 s.
--   
--   Conversion functions will treat it as seconds. For example, <tt>(0.010
--   :: NominalDiffTime)</tt> corresponds to 10 milliseconds.
--   
--   It ignores leap-seconds, so it's not necessarily a fixed amount of
--   clock time. For instance, 23:00 UTC + 2 hours of NominalDiffTime =
--   01:00 UTC (+ 1 day), regardless of whether a leap-second intervened.
data NominalDiffTime

-- | Get the number of picoseconds in a <a>DiffTime</a>.
diffTimeToPicoseconds :: DiffTime -> Integer

-- | Create a <a>DiffTime</a> from a number of picoseconds.
picosecondsToDiffTime :: Integer -> DiffTime

-- | Create a <a>DiffTime</a> which represents an integral number of
--   seconds.
secondsToDiffTime :: Integer -> DiffTime

-- | This is a length of time, as measured by a clock. Conversion functions
--   will treat it as seconds. It has a precision of 10^-12 s.
data DiffTime
dayOfWeek :: Day -> DayOfWeek
data DayOfWeek
Monday :: DayOfWeek
Tuesday :: DayOfWeek
Wednesday :: DayOfWeek
Thursday :: DayOfWeek
Friday :: DayOfWeek
Saturday :: DayOfWeek
Sunday :: DayOfWeek

-- | Calendrical difference, with as many whole months as possible. Same as
--   <a>diffGregorianDurationClip</a> for positive durations.
diffGregorianDurationRollOver :: Day -> Day -> CalendarDiffDays

-- | Calendrical difference, with as many whole months as possible
diffGregorianDurationClip :: Day -> Day -> CalendarDiffDays

-- | Add months (rolling over to next month), then add days
addGregorianDurationRollOver :: CalendarDiffDays -> Day -> Day

-- | Add months (clipped to last day), then add days
addGregorianDurationClip :: CalendarDiffDays -> Day -> Day

-- | Add years, matching month and day, with Feb 29th rolled over to Mar
--   1st if necessary. For instance, 2004-02-29 + 2 years = 2006-03-01.
addGregorianYearsRollOver :: Integer -> Day -> Day

-- | Add years, matching month and day, with Feb 29th clipped to Feb 28th
--   if necessary. For instance, 2004-02-29 + 2 years = 2006-02-28.
addGregorianYearsClip :: Integer -> Day -> Day

-- | Add months, with days past the last day of the month rolling over to
--   the next month. For instance, 2005-01-30 + 1 month = 2005-03-02.
addGregorianMonthsRollOver :: Integer -> Day -> Day

-- | Add months, with days past the last day of the month clipped to the
--   last day. For instance, 2005-01-30 + 1 month = 2005-02-28.
addGregorianMonthsClip :: Integer -> Day -> Day

-- | The number of days in a given month according to the proleptic
--   Gregorian calendar. First argument is year, second is month.
gregorianMonthLength :: Integer -> Int -> Int

-- | Show in ISO 8601 format (yyyy-mm-dd)
showGregorian :: Day -> String

-- | Convert from proleptic Gregorian calendar. First argument is year,
--   second month number (1-12), third day (1-31). Invalid values will
--   return Nothing
fromGregorianValid :: Integer -> Int -> Int -> Maybe Day

-- | Convert from proleptic Gregorian calendar. First argument is year,
--   second month number (1-12), third day (1-31). Invalid values will be
--   clipped to the correct range, month first, then day.
fromGregorian :: Integer -> Int -> Int -> Day

-- | Convert to proleptic Gregorian calendar. First element of result is
--   year, second month number (1-12), third day (1-31).
toGregorian :: Day -> (Integer, Int, Int)

-- | Is this year a leap year according to the proleptic Gregorian
--   calendar?
isLeapYear :: Integer -> Bool
diffDays :: Day -> Day -> Integer
addDays :: Integer -> Day -> Day

-- | The Modified Julian Day is a standard count of days, with zero being
--   the day 1858-11-17.
newtype Day
ModifiedJulianDay :: Integer -> Day
[toModifiedJulianDay] :: Day -> Integer

-- | Scale by a factor. Note that <tt>scaleCalendarDiffDays (-1)</tt> will
--   not perfectly invert a duration, due to variable month lengths.
scaleCalendarDiffDays :: Integer -> CalendarDiffDays -> CalendarDiffDays
calendarYear :: CalendarDiffDays
calendarMonth :: CalendarDiffDays
calendarWeek :: CalendarDiffDays
calendarDay :: CalendarDiffDays
data CalendarDiffDays
CalendarDiffDays :: Integer -> Integer -> CalendarDiffDays
[cdMonths] :: CalendarDiffDays -> Integer
[cdDays] :: CalendarDiffDays -> Integer
getCurrentTime :: MonadIO m => m UTCTime
getTimeZone :: MonadIO m => UTCTime -> m TimeZone
getCurrentTimeZone :: MonadIO m => m TimeZone
getZonedTime :: MonadIO m => m ZonedTime
utcToLocalZonedTime :: MonadIO m => UTCTime -> m ZonedTime


-- | Generic <tt>Vector</tt> interface. Import as:
--   
--   <pre>
--   import qualified RIO.Vector as V
--   </pre>
--   
--   This module does not export any partial or unsafe functions. For
--   those, see <a>RIO.Vector.Partial</a> and <a>RIO.Vector.Unsafe</a>
module RIO.Vector

-- | Class of immutable vectors. Every immutable vector is associated with
--   its mutable version through the <a>Mutable</a> type family. Methods of
--   this class should not be used directly. Instead,
--   <a>Data.Vector.Generic</a> and other <tt>Data.Vector</tt> modules
--   provide safe and fusible wrappers.
--   
--   Minimum complete implementation:
--   
--   <ul>
--   <li><a>basicUnsafeFreeze</a></li>
--   <li><a>basicUnsafeThaw</a></li>
--   <li><a>basicLength</a></li>
--   <li><a>basicUnsafeSlice</a></li>
--   <li><a>basicUnsafeIndexM</a></li>
--   </ul>
class MVector Mutable v a => Vector (v :: Type -> Type) a

-- | <i>O(1)</i> Yield the length of the vector.
length :: Vector v a => v a -> Int

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Vector v a => v a -> Bool

-- | O(1) Safe indexing.
(!?) :: Vector v a => v a -> Int -> Maybe a
infixl 9 !?

-- | <i>O(1)</i> Yield a slice of the vector without copying it. The vector
--   must contain at least <tt>i+n</tt> elements.
slice :: (HasCallStack, Vector v a) => Int -> Int -> v a -> v a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements without copying. The
--   vector may contain less than <tt>n</tt> elements, in which case it is
--   returned unchanged.
take :: Vector v a => Int -> v a -> v a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector may contain less than <tt>n</tt> elements, in
--   which case an empty vector is returned.
drop :: Vector v a => Int -> v a -> v a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements paired with the
--   remainder, without copying.
--   
--   Note that <tt><a>splitAt</a> n v</tt> is equivalent to
--   <tt>(<a>take</a> n v, <a>drop</a> n v)</tt>, but slightly more
--   efficient.
splitAt :: Vector v a => Int -> v a -> (v a, v a)

-- | <i>O(1)</i> The empty vector.
empty :: Vector v a => v a

-- | <i>O(1)</i> A vector with exactly one element.
singleton :: Vector v a => a -> v a

-- | <i>O(n)</i> A vector of the given length with the same value in each
--   position.
replicate :: Vector v a => Int -> a -> v a

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   function to each index.
generate :: Vector v a => Int -> (Int -> a) -> v a

-- | <i>O(n)</i> Apply the function &lt;math&gt; times to an initial value,
--   producing a vector of length &lt;math&gt;. The 0th element will
--   contain the initial value, which is why there is one less function
--   application than the number of elements in the produced vector.
--   
--   &lt;math&gt;
iterateN :: Vector v a => Int -> (a -> a) -> a -> v a

-- | <i>O(n)</i> Execute the monadic action the given number of times and
--   store the results in a vector.
replicateM :: (Monad m, Vector v a) => Int -> m a -> m (v a)

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   monadic action to each index.
generateM :: (Monad m, Vector v a) => Int -> (Int -> m a) -> m (v a)

-- | <i>O(n)</i> Apply the monadic function &lt;math&gt; times to an
--   initial value, producing a vector of length &lt;math&gt;. The 0th
--   element will contain the initial value, which is why there is one less
--   function application than the number of elements in the produced
--   vector.
--   
--   For a non-monadic version, see <a>iterateN</a>.
iterateNM :: (Monad m, Vector v a) => Int -> (a -> m a) -> a -> m (v a)

-- | Execute the monadic action and freeze the resulting vector.
--   
--   <pre>
--   create (do { v &lt;- <a>new</a> 2; <a>write</a> v 0 'a'; <a>write</a> v 1 'b'; return v }) = &lt;<tt>a</tt>,<tt>b</tt>&gt;
--   </pre>
create :: Vector v a => (forall s. () => ST s (Mutable v s a)) -> v a

-- | Execute the monadic action and freeze the resulting vectors.
createT :: (Traversable f, Vector v a) => (forall s. () => ST s (f (Mutable v s a))) -> f (v a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the generator
--   function to a seed. The generator function yields <a>Just</a> the next
--   element and the new seed or <a>Nothing</a> if there are no more
--   elements.
--   
--   <pre>
--   unfoldr (\n -&gt; if n == 0 then Nothing else Just (n,n-1)) 10
--    = &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldr :: Vector v a => (b -> Maybe (a, b)) -> b -> v a

-- | <i>O(n)</i> Construct a vector with at most <tt>n</tt> elements by
--   repeatedly applying the generator function to a seed. The generator
--   function yields <a>Just</a> the next element and the new seed or
--   <a>Nothing</a> if there are no more elements.
--   
--   <pre>
--   unfoldrN 3 (\n -&gt; Just (n,n-1)) 10 = &lt;10,9,8&gt;
--   </pre>
unfoldrN :: Vector v a => Int -> (b -> Maybe (a, b)) -> b -> v a

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <a>Just</a> the next element and the new seed or <a>Nothing</a> if
--   there are no more elements.
unfoldrM :: (Monad m, Vector v a) => (b -> m (Maybe (a, b))) -> b -> m (v a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <a>Just</a> the next element and the new seed or <a>Nothing</a> if
--   there are no more elements.
unfoldrNM :: (Monad m, Vector v a) => Int -> (b -> m (Maybe (a, b))) -> b -> m (v a)

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements by repeatedly
--   applying the generator function to the already constructed part of the
--   vector.
--   
--   <pre>
--   constructN 3 f = let a = f &lt;&gt; ; b = f &lt;a&gt; ; c = f &lt;a,b&gt; in &lt;a,b,c&gt;
--   </pre>
constructN :: Vector v a => Int -> (v a -> a) -> v a

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements from right to
--   left by repeatedly applying the generator function to the already
--   constructed part of the vector.
--   
--   <pre>
--   constructrN 3 f = let a = f &lt;&gt; ; b = f&lt;a&gt; ; c = f &lt;b,a&gt; in &lt;c,b,a&gt;
--   </pre>
constructrN :: Vector v a => Int -> (v a -> a) -> v a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+1</tt> etc. This operation is usually more efficient
--   than <a>enumFromTo</a>.
--   
--   <pre>
--   enumFromN 5 3 = &lt;5,6,7&gt;
--   </pre>
enumFromN :: (Vector v a, Num a) => a -> Int -> v a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+y</tt>, <tt>x+y+y</tt> etc. This operations is
--   usually more efficient than <a>enumFromThenTo</a>.
--   
--   <pre>
--   enumFromStepN 1 2 5 = &lt;1,3,5,7,9&gt;
--   </pre>
enumFromStepN :: (Vector v a, Num a) => a -> a -> Int -> v a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromN</a> instead.
enumFromTo :: (Vector v a, Enum a) => a -> a -> v a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt> with a
--   specific step <tt>z</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromStepN</a> instead.
enumFromThenTo :: (Vector v a, Enum a) => a -> a -> a -> v a

-- | <i>O(n)</i> Prepend an element.
cons :: Vector v a => a -> v a -> v a

-- | <i>O(n)</i> Append an element.
snoc :: Vector v a => v a -> a -> v a

-- | <i>O(m+n)</i> Concatenate two vectors.
(++) :: Vector v a => v a -> v a -> v a
infixr 5 ++

-- | <i>O(n)</i> Concatenate all vectors in the list.
concat :: Vector v a => [v a] -> v a

-- | <i>O(n)</i> Concatenate all vectors in the non-empty list.
concatNE :: Vector v a => NonEmpty (v a) -> v a

-- | <i>O(n)</i> Yield the argument, but force it not to retain any extra
--   memory, possibly by copying it.
--   
--   This is especially useful when dealing with slices. For example:
--   
--   <pre>
--   force (slice 0 2 &lt;huge vector&gt;)
--   </pre>
--   
--   Here, the slice retains a reference to the huge vector. Forcing it
--   creates a copy of just the elements that belong to the slice and
--   allows the huge vector to be garbage collected.
force :: Vector v a => v a -> v a

-- | <i>O(n)</i> Reverse a vector.
reverse :: Vector v a => v a -> v a

-- | Apply a destructive operation to a vector. The operation may be
--   performed in place if it is safe to do so and will modify a copy of
--   the vector otherwise (see <a>New</a> for details).
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Mutable as MV
--   
--   &gt;&gt;&gt; V.modify (\v -&gt; MV.write v 0 'x') $ V.replicate 4 'a'
--   "xaaa"
--   </pre>
modify :: Vector v a => (forall s. () => Mutable v s a -> ST s ()) -> v a -> v a

-- | <i>O(n)</i> Pair each element in a vector with its index.
indexed :: (Vector v a, Vector v (Int, a)) => v a -> v (Int, a)

-- | <i>O(n)</i> Map a function over a vector.
map :: (Vector v a, Vector v b) => (a -> b) -> v a -> v b

-- | <i>O(n)</i> Apply a function to every element of a vector and its
--   index.
imap :: (Vector v a, Vector v b) => (Int -> a -> b) -> v a -> v b

-- | Map a function over a vector and concatenate the results.
concatMap :: (Vector v a, Vector v b) => (a -> v b) -> v a -> v b

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results.
mapM :: (Monad m, Vector v a, Vector v b) => (a -> m b) -> v a -> m (v b)

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, yielding a vector of results.
imapM :: (Monad m, Vector v a, Vector v b) => (Int -> a -> m b) -> v a -> m (v b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results.
mapM_ :: (Monad m, Vector v a) => (a -> m b) -> v a -> m ()

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, ignoring the results.
imapM_ :: (Monad m, Vector v a) => (Int -> a -> m b) -> v a -> m ()

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results. Equivalent to <tt>flip <a>mapM</a></tt>.
forM :: (Monad m, Vector v a, Vector v b) => v a -> (a -> m b) -> m (v b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results. Equivalent to <tt>flip <a>mapM_</a></tt>.
forM_ :: (Monad m, Vector v a) => v a -> (a -> m b) -> m ()

-- | <i>O(min(m,n))</i> Zip two vectors with the given function.
zipWith :: (Vector v a, Vector v b, Vector v c) => (a -> b -> c) -> v a -> v b -> v c

-- | Zip three vectors with the given function.
zipWith3 :: (Vector v a, Vector v b, Vector v c, Vector v d) => (a -> b -> c -> d) -> v a -> v b -> v c -> v d
zipWith4 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e) => (a -> b -> c -> d -> e) -> v a -> v b -> v c -> v d -> v e
zipWith5 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f) => (a -> b -> c -> d -> e -> f) -> v a -> v b -> v c -> v d -> v e -> v f
zipWith6 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f, Vector v g) => (a -> b -> c -> d -> e -> f -> g) -> v a -> v b -> v c -> v d -> v e -> v f -> v g

-- | <i>O(min(m,n))</i> Zip two vectors with a function that also takes the
--   elements' indices.
izipWith :: (Vector v a, Vector v b, Vector v c) => (Int -> a -> b -> c) -> v a -> v b -> v c

-- | Zip three vectors and their indices with the given function.
izipWith3 :: (Vector v a, Vector v b, Vector v c, Vector v d) => (Int -> a -> b -> c -> d) -> v a -> v b -> v c -> v d
izipWith4 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e) => (Int -> a -> b -> c -> d -> e) -> v a -> v b -> v c -> v d -> v e
izipWith5 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f) => (Int -> a -> b -> c -> d -> e -> f) -> v a -> v b -> v c -> v d -> v e -> v f
izipWith6 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f, Vector v g) => (Int -> a -> b -> c -> d -> e -> f -> g) -> v a -> v b -> v c -> v d -> v e -> v f -> v g

-- | <i>O(min(m,n))</i> Zip two vectors.
zip :: (Vector v a, Vector v b, Vector v (a, b)) => v a -> v b -> v (a, b)

-- | Zip together three vectors into a vector of triples.
zip3 :: (Vector v a, Vector v b, Vector v c, Vector v (a, b, c)) => v a -> v b -> v c -> v (a, b, c)
zip4 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v (a, b, c, d)) => v a -> v b -> v c -> v d -> v (a, b, c, d)
zip5 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v (a, b, c, d, e)) => v a -> v b -> v c -> v d -> v e -> v (a, b, c, d, e)
zip6 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f, Vector v (a, b, c, d, e, f)) => v a -> v b -> v c -> v d -> v e -> v f -> v (a, b, c, d, e, f)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   yield a vector of results.
zipWithM :: (Monad m, Vector v a, Vector v b, Vector v c) => (a -> b -> m c) -> v a -> v b -> m (v c)

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and yield a vector of results.
izipWithM :: (Monad m, Vector v a, Vector v b, Vector v c) => (Int -> a -> b -> m c) -> v a -> v b -> m (v c)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   ignore the results.
zipWithM_ :: (Monad m, Vector v a, Vector v b) => (a -> b -> m c) -> v a -> v b -> m ()

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and ignore the results.
izipWithM_ :: (Monad m, Vector v a, Vector v b) => (Int -> a -> b -> m c) -> v a -> v b -> m ()

-- | <i>O(min(m,n))</i> Unzip a vector of pairs.
unzip :: (Vector v a, Vector v b, Vector v (a, b)) => v (a, b) -> (v a, v b)
unzip3 :: (Vector v a, Vector v b, Vector v c, Vector v (a, b, c)) => v (a, b, c) -> (v a, v b, v c)
unzip4 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v (a, b, c, d)) => v (a, b, c, d) -> (v a, v b, v c, v d)
unzip5 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v (a, b, c, d, e)) => v (a, b, c, d, e) -> (v a, v b, v c, v d, v e)
unzip6 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v e, Vector v f, Vector v (a, b, c, d, e, f)) => v (a, b, c, d, e, f) -> (v a, v b, v c, v d, v e, v f)

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate.
filter :: Vector v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate which
--   is applied to the values and their indices.
ifilter :: Vector v a => (Int -> a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Drop repeated adjacent elements. The first element in each
--   group is returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.uniq $ V.fromList [1,3,3,200,3]
--   [1,3,200,3]
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.uniq $ V.fromList [ Arg 1 'a', Arg 1 'b', Arg 1 'c']
--   [Arg 1 'a']
--   </pre>
uniq :: (Vector v a, Eq a) => v a -> v a

-- | <i>O(n)</i> Map the values and collect the <a>Just</a> results.
mapMaybe :: (Vector v a, Vector v b) => (a -> Maybe b) -> v a -> v b

-- | <i>O(n)</i> Map the indices/values and collect the <a>Just</a>
--   results.
imapMaybe :: (Vector v a, Vector v b) => (Int -> a -> Maybe b) -> v a -> v b

-- | <i>O(n)</i> Drop all elements that do not satisfy the monadic
--   predicate.
filterM :: (Monad m, Vector v a) => (a -> m Bool) -> v a -> m (v a)

-- | <i>O(n)</i> Yield the longest prefix of elements satisfying the
--   predicate. The current implementation is not copy-free, unless the
--   result vector is fused away.
takeWhile :: Vector v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Drop the longest prefix of elements that satisfy the
--   predicate without copying.
dropWhile :: Vector v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The relative order of the elements is preserved at the
--   cost of a sometimes reduced performance compared to
--   <a>unstablePartition</a>.
partition :: Vector v a => (a -> Bool) -> v a -> (v a, v a)

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The order of the elements is not preserved, but the
--   operation is often faster than <a>partition</a>.
unstablePartition :: Vector v a => (a -> Bool) -> v a -> (v a, v a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: Vector v a => (a -> Bool) -> v a -> (v a, v a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   do not satisfy the predicate and the rest without copying.
break :: Vector v a => (a -> Bool) -> v a -> (v a, v a)

-- | <i>O(n)</i> Check if the vector contains an element.
elem :: (Vector v a, Eq a) => a -> v a -> Bool
infix 4 `elem`

-- | <i>O(n)</i> Check if the vector does not contain an element (inverse
--   of <a>elem</a>).
notElem :: (Vector v a, Eq a) => a -> v a -> Bool
infix 4 `notElem`

-- | <i>O(n)</i> Yield <a>Just</a> the first element matching the predicate
--   or <a>Nothing</a> if no such element exists.
find :: Vector v a => (a -> Bool) -> v a -> Maybe a

-- | <i>O(n)</i> Yield <a>Just</a> the index of the first element matching
--   the predicate or <a>Nothing</a> if no such element exists.
findIndex :: Vector v a => (a -> Bool) -> v a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of elements satisfying the predicate in
--   ascending order.
findIndices :: (Vector v a, Vector v Int) => (a -> Bool) -> v a -> v Int

-- | <i>O(n)</i> Yield <a>Just</a> the index of the first occurrence of the
--   given element or <a>Nothing</a> if the vector does not contain the
--   element. This is a specialised version of <a>findIndex</a>.
elemIndex :: (Vector v a, Eq a) => a -> v a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of all occurrences of the given element
--   in ascending order. This is a specialised version of
--   <a>findIndices</a>.
elemIndices :: (Vector v a, Vector v Int, Eq a) => a -> v a -> v Int

-- | <i>O(n)</i> Left fold.
foldl :: Vector v b => (a -> b -> a) -> a -> v b -> a

-- | <i>O(n)</i> Left fold with strict accumulator.
foldl' :: Vector v b => (a -> b -> a) -> a -> v b -> a

-- | <i>O(n)</i> Right fold.
foldr :: Vector v a => (a -> b -> b) -> b -> v a -> b

-- | <i>O(n)</i> Right fold with a strict accumulator.
foldr' :: Vector v a => (a -> b -> b) -> b -> v a -> b

-- | <i>O(n)</i> Left fold using a function applied to each element and its
--   index.
ifoldl :: Vector v b => (a -> Int -> b -> a) -> a -> v b -> a

-- | <i>O(n)</i> Left fold with strict accumulator using a function applied
--   to each element and its index.
ifoldl' :: Vector v b => (a -> Int -> b -> a) -> a -> v b -> a

-- | <i>O(n)</i> Right fold using a function applied to each element and
--   its index.
ifoldr :: Vector v a => (Int -> a -> b -> b) -> b -> v a -> b

-- | <i>O(n)</i> Right fold with strict accumulator using a function
--   applied to each element and its index.
ifoldr' :: Vector v a => (Int -> a -> b -> b) -> b -> v a -> b

-- | <i>O(n)</i> Check if all elements satisfy the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.all even $ V.fromList [2, 4, 12]
--   True
--   
--   &gt;&gt;&gt; V.all even $ V.fromList [2, 4, 13]
--   False
--   
--   &gt;&gt;&gt; V.all even (V.empty :: V.Vector Int)
--   True
--   </pre>
all :: Vector v a => (a -> Bool) -> v a -> Bool

-- | <i>O(n)</i> Check if any element satisfies the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.any even $ V.fromList [1, 3, 7]
--   False
--   
--   &gt;&gt;&gt; V.any even $ V.fromList [3, 2, 13]
--   True
--   
--   &gt;&gt;&gt; V.any even (V.empty :: V.Vector Int)
--   False
--   </pre>
any :: Vector v a => (a -> Bool) -> v a -> Bool

-- | <i>O(n)</i> Check if all elements are <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.and $ V.fromList [True, False]
--   False
--   
--   &gt;&gt;&gt; V.and V.empty
--   True
--   </pre>
and :: Vector v Bool => v Bool -> Bool

-- | <i>O(n)</i> Check if any element is <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.or $ V.fromList [True, False]
--   True
--   
--   &gt;&gt;&gt; V.or V.empty
--   False
--   </pre>
or :: Vector v Bool => v Bool -> Bool

-- | <i>O(n)</i> Compute the sum of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.sum $ V.fromList [300,20,1]
--   321
--   
--   &gt;&gt;&gt; V.sum (V.empty :: V.Vector Int)
--   0
--   </pre>
sum :: (Vector v a, Num a) => v a -> a

-- | <i>O(n)</i> Compute the product of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.product $ V.fromList [1,2,3,4]
--   24
--   
--   &gt;&gt;&gt; V.product (V.empty :: V.Vector Int)
--   1
--   </pre>
product :: (Vector v a, Num a) => v a -> a

-- | <i>O(n)</i> Monadic fold.
foldM :: (Monad m, Vector v b) => (a -> b -> m a) -> a -> v b -> m a

-- | <i>O(n)</i> Monadic fold using a function applied to each element and
--   its index.
ifoldM :: (Monad m, Vector v b) => (a -> Int -> b -> m a) -> a -> v b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator.
foldM' :: (Monad m, Vector v b) => (a -> b -> m a) -> a -> v b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator using a function
--   applied to each element and its index.
ifoldM' :: (Monad m, Vector v b) => (a -> Int -> b -> m a) -> a -> v b -> m a

-- | <i>O(n)</i> Monadic fold that discards the result.
foldM_ :: (Monad m, Vector v b) => (a -> b -> m a) -> a -> v b -> m ()

-- | <i>O(n)</i> Monadic fold that discards the result using a function
--   applied to each element and its index.
ifoldM_ :: (Monad m, Vector v b) => (a -> Int -> b -> m a) -> a -> v b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result.
foldM'_ :: (Monad m, Vector v b) => (a -> b -> m a) -> a -> v b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result using a function applied to each element and its index.
ifoldM'_ :: (Monad m, Vector v b) => (a -> Int -> b -> m a) -> a -> v b -> m ()

-- | Evaluate each action and collect the results.
sequence :: (Monad m, Vector v a, Vector v (m a)) => v (m a) -> m (v a)

-- | Evaluate each action and discard the results.
sequence_ :: (Monad m, Vector v (m a)) => v (m a) -> m ()

-- | <i>O(n)</i> Left-to-right prescan.
--   
--   <pre>
--   prescanl f z = <a>init</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.prescanl (+) 0 (V.fromList [1,2,3,4])
--   [0,1,3,6]
--   </pre>
prescanl :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right prescan with strict accumulator.
prescanl' :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right postscan.
--   
--   <pre>
--   postscanl f z = <a>tail</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.postscanl (+) 0 (V.fromList [1,2,3,4])
--   [1,3,6,10]
--   </pre>
postscanl :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right postscan with strict accumulator.
postscanl' :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right scan.
--   
--   <pre>
--   scanl f z &lt;x1,...,xn&gt; = &lt;y1,...,y(n+1)&gt;
--     where y1 = z
--           yi = f y(i-1) x(i-1)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl (+) 0 (V.fromList [1,2,3,4])
--   [0,1,3,6,10]
--   </pre>
scanl :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right scan with strict accumulator.
scanl' :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right scan over a vector with its index.
iscanl :: (Vector v a, Vector v b) => (Int -> a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Left-to-right scan over a vector (strictly) with its
--   index.
iscanl' :: (Vector v a, Vector v b) => (Int -> a -> b -> a) -> a -> v b -> v a

-- | <i>O(n)</i> Right-to-left prescan.
--   
--   <pre>
--   prescanr f z = <a>reverse</a> . <a>prescanl</a> (flip f) z . <a>reverse</a>
--   </pre>
prescanr :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left prescan with strict accumulator.
prescanr' :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left postscan.
postscanr :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left postscan with strict accumulator.
postscanr' :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left scan.
scanr :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left scan with strict accumulator.
scanr' :: (Vector v a, Vector v b) => (a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left scan over a vector with its index.
iscanr :: (Vector v a, Vector v b) => (Int -> a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Right-to-left scan over a vector (strictly) with its
--   index.
iscanr' :: (Vector v a, Vector v b) => (Int -> a -> b -> b) -> b -> v a -> v b

-- | <i>O(n)</i> Convert a vector to a list.
toList :: Vector v a => v a -> [a]

-- | <i>O(n)</i> Convert a list to a vector.
fromList :: Vector v a => [a] -> v a

-- | <i>O(n)</i> Convert the first <tt>n</tt> elements of a list to a
--   vector. It's expected that the supplied list will be exactly
--   <tt>n</tt> elements long. As an optimization, this function allocates
--   a buffer for <tt>n</tt> elements, which could be used for DoS-attacks
--   by exhausting the memory if an attacker controls that parameter.
--   
--   <pre>
--   fromListN n xs = <a>fromList</a> (<a>take</a> n xs)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.fromListN 3 [1,2,3,4,5]
--   [1,2,3]
--   
--   &gt;&gt;&gt; V.fromListN 3 [1]
--   [1]
--   </pre>
fromListN :: Vector v a => Int -> [a] -> v a

-- | <i>O(n)</i> Convert between different vector types.
convert :: (Vector v a, Vector w a) => v a -> w a

-- | <i>O(n)</i> Yield an immutable copy of the mutable vector.
freeze :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> m (v a)

-- | <i>O(n)</i> Yield a mutable copy of an immutable vector.
thaw :: (PrimMonad m, Vector v a) => v a -> m (Mutable v (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length.
copy :: (HasCallStack, PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> v a -> m ()

-- | <i>O(1)</i> Convert a vector to a <a>Bundle</a>.
stream :: Vector v a => v a -> Bundle v a

-- | <i>O(n)</i> Construct a vector from a <a>Bundle</a>.
unstream :: Vector v a => Bundle v a -> v a

-- | <i>O(1)</i> Convert a vector to a <a>Bundle</a>, proceeding from right
--   to left.
streamR :: forall v a (u :: Type -> Type). Vector v a => v a -> Bundle u a

-- | <i>O(n)</i> Construct a vector from a <a>Bundle</a>, proceeding from
--   right to left.
unstreamR :: Vector v a => Bundle v a -> v a

-- | Construct a vector from a monadic initialiser.
new :: Vector v a => New v a -> v a

-- | Convert a vector to an initialiser which, when run, produces a copy of
--   the vector.
clone :: Vector v a => v a -> New v a

-- | <i>O(n)</i> Check if two vectors are equal. All <a>Vector</a>
--   instances are also instances of <a>Eq</a> and it is usually more
--   appropriate to use those. This function is primarily intended for
--   implementing <a>Eq</a> instances for new vector types.
eq :: (Vector v a, Eq a) => v a -> v a -> Bool

-- | <i>O(n)</i> Compare two vectors lexicographically. All <a>Vector</a>
--   instances are also instances of <a>Ord</a> and it is usually more
--   appropriate to use those. This function is primarily intended for
--   implementing <a>Ord</a> instances for new vector types.
cmp :: (Vector v a, Ord a) => v a -> v a -> Ordering

-- | <i>O(n)</i> Check if two vectors are equal using the supplied equality
--   predicate.
eqBy :: (Vector v a, Vector v b) => (a -> b -> Bool) -> v a -> v b -> Bool

-- | <i>O(n)</i> Compare two vectors using the supplied comparison function
--   for vector elements. Comparison works the same as for lists.
--   
--   <pre>
--   cmpBy compare == cmp
--   </pre>
cmpBy :: (Vector v a, Vector v b) => (a -> b -> Ordering) -> v a -> v b -> Ordering

-- | Generic definition of <a>showsPrec</a>.
showsPrec :: (Vector v a, Show a) => Int -> v a -> ShowS

-- | Generic definition of <a>readPrec</a>.
readPrec :: (Vector v a, Read a) => ReadPrec (v a)
liftShowsPrec :: Vector v a => (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> v a -> ShowS

-- | <i>Note:</i> uses <a>ReadS</a>.
liftReadsPrec :: Vector v a => (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (v a)

-- | Generic definion of <a>gfoldl</a> that views a <a>Vector</a> as a
--   list.
gfoldl :: (Vector v a, Data a) => (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. () => g -> c g) -> v a -> c (v a)
dataCast :: (Vector v a, Data a, Typeable v, Typeable t) => (forall d. Data d => c (t d)) -> Maybe (c (v a))
mkType :: String -> DataType


-- | Boxed <tt>Vector</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Boxed as VB
--   </pre>
--   
--   This module does not export any partial or unsafe functions. For
--   those, see <a>RIO.Vector.Boxed.Partial</a> and
--   <a>RIO.Vector.Boxed.Unsafe</a>
module RIO.Vector.Boxed

-- | Boxed vectors, supporting efficient slicing.
data Vector a

-- | Mutable boxed vectors keyed on the monad they live in (<tt>IO</tt> or
--   <tt><tt>ST</tt> s</tt>).
data MVector s a

-- | <i>O(1)</i> Yield the length of the vector.
length :: Vector a -> Int

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Vector a -> Bool

-- | O(1) Safe indexing.
(!?) :: Vector a -> Int -> Maybe a

-- | <i>O(1)</i> Yield a slice of the vector without copying it. The vector
--   must contain at least <tt>i+n</tt> elements.
slice :: Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield at the first <tt>n</tt> elements without copying.
--   The vector may contain less than <tt>n</tt> elements, in which case it
--   is returned unchanged.
take :: Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector may contain less than <tt>n</tt> elements, in
--   which case an empty vector is returned.
drop :: Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements paired with the
--   remainder, without copying.
--   
--   Note that <tt><a>splitAt</a> n v</tt> is equivalent to
--   <tt>(<a>take</a> n v, <a>drop</a> n v)</tt>, but slightly more
--   efficient.
splitAt :: Int -> Vector a -> (Vector a, Vector a)

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

-- | <i>O(1)</i> A vector with exactly one element.
singleton :: a -> Vector a

-- | <i>O(n)</i> A vector of the given length with the same value in each
--   position.
replicate :: Int -> a -> Vector a

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   function to each index.
generate :: Int -> (Int -> a) -> Vector a

-- | <i>O(n)</i> Apply the function &lt;math&gt; times to an initial value,
--   producing a vector of length &lt;math&gt;. The 0th element will
--   contain the initial value, which is why there is one less function
--   application than the number of elements in the produced vector.
--   
--   &lt;math&gt;
--   
--   <h3><b>Examples</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.iterateN 0 undefined undefined :: V.Vector String
--   []
--   
--   &gt;&gt;&gt; V.iterateN 4 (\x -&gt; x &lt;&gt; x) "Hi"
--   ["Hi","HiHi","HiHiHiHi","HiHiHiHiHiHiHiHi"]
--   </pre>
iterateN :: Int -> (a -> a) -> a -> Vector a

-- | <i>O(n)</i> Execute the monadic action the given number of times and
--   store the results in a vector.
replicateM :: Monad m => Int -> m a -> m (Vector a)

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   monadic action to each index.
generateM :: Monad m => Int -> (Int -> m a) -> m (Vector a)

-- | <i>O(n)</i> Apply the monadic function &lt;math&gt; times to an
--   initial value, producing a vector of length &lt;math&gt;. The 0th
--   element will contain the initial value, which is why there is one less
--   function application than the number of elements in the produced
--   vector.
--   
--   For a non-monadic version, see <a>iterateN</a>.
iterateNM :: Monad m => Int -> (a -> m a) -> a -> m (Vector a)

-- | Execute the monadic action and freeze the resulting vector.
--   
--   <pre>
--   create (do { v &lt;- new 2; write v 0 'a'; write v 1 'b'; return v }) = &lt;<tt>a</tt>,<tt>b</tt>&gt;
--   </pre>
create :: (forall s. () => ST s (MVector s a)) -> Vector a

-- | Execute the monadic action and freeze the resulting vectors.
createT :: Traversable f => (forall s. () => ST s (f (MVector s a))) -> f (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the generator
--   function to a seed. The generator function yields <tt>Just</tt> the
--   next element and the new seed or <tt>Nothing</tt> if there are no more
--   elements.
--   
--   <pre>
--   unfoldr (\n -&gt; if n == 0 then Nothing else Just (n,n-1)) 10
--    = &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldr :: (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector with at most <tt>n</tt> elements by
--   repeatedly applying the generator function to a seed. The generator
--   function yields <tt>Just</tt> the next element and the new seed or
--   <tt>Nothing</tt> if there are no more elements.
--   
--   <pre>
--   unfoldrN 3 (\n -&gt; Just (n,n-1)) 10 = &lt;10,9,8&gt;
--   </pre>
unfoldrN :: Int -> (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrM :: Monad m => (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrNM :: Monad m => Int -> (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements by repeatedly
--   applying the generator function to the already constructed part of the
--   vector.
--   
--   <pre>
--   constructN 3 f = let a = f &lt;&gt; ; b = f &lt;a&gt; ; c = f &lt;a,b&gt; in &lt;a,b,c&gt;
--   </pre>
constructN :: Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements from right to
--   left by repeatedly applying the generator function to the already
--   constructed part of the vector.
--   
--   <pre>
--   constructrN 3 f = let a = f &lt;&gt; ; b = f&lt;a&gt; ; c = f &lt;b,a&gt; in &lt;c,b,a&gt;
--   </pre>
constructrN :: Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+1</tt> etc. This operation is usually more efficient
--   than <a>enumFromTo</a>.
--   
--   <pre>
--   enumFromN 5 3 = &lt;5,6,7&gt;
--   </pre>
enumFromN :: Num a => a -> Int -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+y</tt>, <tt>x+y+y</tt> etc. This operations is
--   usually more efficient than <a>enumFromThenTo</a>.
--   
--   <pre>
--   enumFromStepN 1 2 5 = &lt;1,3,5,7,9&gt;
--   </pre>
enumFromStepN :: Num a => a -> a -> Int -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromN</a> instead.
enumFromTo :: Enum a => a -> a -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt> with a
--   specific step <tt>z</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromStepN</a> instead.
enumFromThenTo :: Enum a => a -> a -> a -> Vector a

-- | <i>O(n)</i> Prepend an element.
cons :: a -> Vector a -> Vector a

-- | <i>O(n)</i> Append an element.
snoc :: Vector a -> a -> Vector a

-- | <i>O(m+n)</i> Concatenate two vectors.
(++) :: Vector a -> Vector a -> Vector a
infixr 5 ++

-- | <i>O(n)</i> Concatenate all vectors in the list.
concat :: [Vector a] -> Vector a

-- | <i>O(n)</i> Yield the argument, but force it not to retain any extra
--   memory, possibly by copying it.
--   
--   This is especially useful when dealing with slices. For example:
--   
--   <pre>
--   force (slice 0 2 &lt;huge vector&gt;)
--   </pre>
--   
--   Here, the slice retains a reference to the huge vector. Forcing it
--   creates a copy of just the elements that belong to the slice and
--   allows the huge vector to be garbage collected.
force :: Vector a -> Vector a

-- | <i>O(n)</i> Reverse a vector.
reverse :: Vector a -> Vector a

-- | Apply a destructive operation to a vector. The operation may be
--   performed in place if it is safe to do so and will modify a copy of
--   the vector otherwise (see <a>New</a> for details).
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Mutable as MV
--   
--   &gt;&gt;&gt; V.modify (\v -&gt; MV.write v 0 'x') $ V.replicate 4 'a'
--   "xaaa"
--   </pre>
modify :: (forall s. () => MVector s a -> ST s ()) -> Vector a -> Vector a

-- | <i>O(n)</i> Pair each element in a vector with its index.
indexed :: Vector a -> Vector (Int, a)

-- | <i>O(n)</i> Map a function over a vector.
map :: (a -> b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply a function to every element of a vector and its
--   index.
imap :: (Int -> a -> b) -> Vector a -> Vector b

-- | Map a function over a vector and concatenate the results.
concatMap :: (a -> Vector b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results.
mapM :: Monad m => (a -> m b) -> Vector a -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, yielding a vector of results.
imapM :: Monad m => (Int -> a -> m b) -> Vector a -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results.
mapM_ :: Monad m => (a -> m b) -> Vector a -> m ()

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, ignoring the results.
imapM_ :: Monad m => (Int -> a -> m b) -> Vector a -> m ()

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results. Equivalent to <tt>flip <a>mapM</a></tt>.
forM :: Monad m => Vector a -> (a -> m b) -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results. Equivalent to <tt>flip <a>mapM_</a></tt>.
forM_ :: Monad m => Vector a -> (a -> m b) -> m ()

-- | <i>O(min(m,n))</i> Zip two vectors with the given function.
zipWith :: (a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors with the given function.
zipWith3 :: (a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
zipWith4 :: (a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
zipWith5 :: (a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(min(m,n))</i> Zip two vectors with a function that also takes the
--   elements' indices.
izipWith :: (Int -> a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors and their indices with the given function.
izipWith3 :: (Int -> a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
izipWith4 :: (Int -> a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
izipWith5 :: (Int -> a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
izipWith6 :: (Int -> a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(min(m,n))</i> Zip two vectors.
zip :: Vector a -> Vector b -> Vector (a, b)

-- | Zip together three vectors into a vector of triples.
zip3 :: Vector a -> Vector b -> Vector c -> Vector (a, b, c)
zip4 :: Vector a -> Vector b -> Vector c -> Vector d -> Vector (a, b, c, d)
zip5 :: Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector (a, b, c, d, e)
zip6 :: Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector (a, b, c, d, e, f)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   yield a vector of results.
zipWithM :: Monad m => (a -> b -> m c) -> Vector a -> Vector b -> m (Vector c)

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and yield a vector of results.
izipWithM :: Monad m => (Int -> a -> b -> m c) -> Vector a -> Vector b -> m (Vector c)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   ignore the results.
zipWithM_ :: Monad m => (a -> b -> m c) -> Vector a -> Vector b -> m ()

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and ignore the results.
izipWithM_ :: Monad m => (Int -> a -> b -> m c) -> Vector a -> Vector b -> m ()

-- | <i>O(min(m,n))</i> Unzip a vector of pairs.
unzip :: Vector (a, b) -> (Vector a, Vector b)
unzip3 :: Vector (a, b, c) -> (Vector a, Vector b, Vector c)
unzip4 :: Vector (a, b, c, d) -> (Vector a, Vector b, Vector c, Vector d)
unzip5 :: Vector (a, b, c, d, e) -> (Vector a, Vector b, Vector c, Vector d, Vector e)
unzip6 :: Vector (a, b, c, d, e, f) -> (Vector a, Vector b, Vector c, Vector d, Vector e, Vector f)

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate.
filter :: (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate which
--   is applied to the values and their indices.
ifilter :: (Int -> a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop repeated adjacent elements. The first element in each
--   group is returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.uniq $ V.fromList [1,3,3,200,3]
--   [1,3,200,3]
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.uniq $ V.fromList [ Arg 1 'a', Arg 1 'b', Arg 1 'c']
--   [Arg 1 'a']
--   </pre>
uniq :: Eq a => Vector a -> Vector a

-- | <i>O(n)</i> Map the values and collect the <tt>Just</tt> results.
mapMaybe :: (a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Map the indices/values and collect the <tt>Just</tt>
--   results.
imapMaybe :: (Int -> a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Drop all elements that do not satisfy the monadic
--   predicate.
filterM :: Monad m => (a -> m Bool) -> Vector a -> m (Vector a)

-- | <i>O(n)</i> Yield the longest prefix of elements satisfying the
--   predicate. The current implementation is not copy-free, unless the
--   result vector is fused away.
takeWhile :: (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop the longest prefix of elements that satisfy the
--   predicate without copying.
dropWhile :: (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The relative order of the elements is preserved at the
--   cost of a sometimes reduced performance compared to
--   <a>unstablePartition</a>.
partition :: (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The order of the elements is not preserved, but the
--   operation is often faster than <a>partition</a>.
unstablePartition :: (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   do not satisfy the predicate and the rest without copying.
break :: (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Check if the vector contains an element.
elem :: Eq a => a -> Vector a -> Bool
infix 4 `elem`

-- | <i>O(n)</i> Check if the vector does not contain an element (inverse
--   of <a>elem</a>).
notElem :: Eq a => a -> Vector a -> Bool
infix 4 `notElem`

-- | <i>O(n)</i> Yield <tt>Just</tt> the first element matching the
--   predicate or <tt>Nothing</tt> if no such element exists.
find :: (a -> Bool) -> Vector a -> Maybe a

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first element
--   matching the predicate or <tt>Nothing</tt> if no such element exists.
findIndex :: (a -> Bool) -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of elements satisfying the predicate in
--   ascending order.
findIndices :: (a -> Bool) -> Vector a -> Vector Int

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first occurrence of
--   the given element or <tt>Nothing</tt> if the vector does not contain
--   the element. This is a specialised version of <a>findIndex</a>.
elemIndex :: Eq a => a -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of all occurrences of the given element
--   in ascending order. This is a specialised version of
--   <a>findIndices</a>.
elemIndices :: Eq a => a -> Vector a -> Vector Int

-- | <i>O(n)</i> Left fold.
foldl :: (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator.
foldl' :: (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold.
foldr :: (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with a strict accumulator.
foldr' :: (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Left fold using a function applied to each element and its
--   index.
ifoldl :: (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator using a function applied
--   to each element and its index.
ifoldl' :: (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold using a function applied to each element and
--   its index.
ifoldr :: (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with strict accumulator using a function
--   applied to each element and its index.
ifoldr' :: (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Check if all elements satisfy the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.all even $ V.fromList [2, 4, 12]
--   True
--   
--   &gt;&gt;&gt; V.all even $ V.fromList [2, 4, 13]
--   False
--   
--   &gt;&gt;&gt; V.all even (V.empty :: V.Vector Int)
--   True
--   </pre>
all :: (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if any element satisfies the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.any even $ V.fromList [1, 3, 7]
--   False
--   
--   &gt;&gt;&gt; V.any even $ V.fromList [3, 2, 13]
--   True
--   
--   &gt;&gt;&gt; V.any even (V.empty :: V.Vector Int)
--   False
--   </pre>
any :: (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if all elements are <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.and $ V.fromList [True, False]
--   False
--   
--   &gt;&gt;&gt; V.and V.empty
--   True
--   </pre>
and :: Vector Bool -> Bool

-- | <i>O(n)</i> Check if any element is <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.or $ V.fromList [True, False]
--   True
--   
--   &gt;&gt;&gt; V.or V.empty
--   False
--   </pre>
or :: Vector Bool -> Bool

-- | <i>O(n)</i> Compute the sum of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.sum $ V.fromList [300,20,1]
--   321
--   
--   &gt;&gt;&gt; V.sum (V.empty :: V.Vector Int)
--   0
--   </pre>
sum :: Num a => Vector a -> a

-- | <i>O(n)</i> Compute the product of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.product $ V.fromList [1,2,3,4]
--   24
--   
--   &gt;&gt;&gt; V.product (V.empty :: V.Vector Int)
--   1
--   </pre>
product :: Num a => Vector a -> a

-- | <i>O(n)</i> Monadic fold.
foldM :: Monad m => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold using a function applied to each element and
--   its index.
ifoldM :: Monad m => (a -> Int -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator.
foldM' :: Monad m => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator using a function
--   applied to each element and its index.
ifoldM' :: Monad m => (a -> Int -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold that discards the result.
foldM_ :: Monad m => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold that discards the result using a function
--   applied to each element and its index.
ifoldM_ :: Monad m => (a -> Int -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result.
foldM'_ :: Monad m => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result using a function applied to each element and its index.
ifoldM'_ :: Monad m => (a -> Int -> b -> m a) -> a -> Vector b -> m ()

-- | Evaluate each action and collect the results.
sequence :: Monad m => Vector (m a) -> m (Vector a)

-- | Evaluate each action and discard the results.
sequence_ :: Monad m => Vector (m a) -> m ()

-- | <i>O(n)</i> Left-to-right prescan.
--   
--   <pre>
--   prescanl f z = <a>init</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.prescanl (+) 0 (V.fromList [1,2,3,4])
--   [0,1,3,6]
--   </pre>
prescanl :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right prescan with strict accumulator.
prescanl' :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan.
--   
--   <pre>
--   postscanl f z = <a>tail</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.postscanl (+) 0 (V.fromList [1,2,3,4])
--   [1,3,6,10]
--   </pre>
postscanl :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan with strict accumulator.
postscanl' :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan.
--   
--   <pre>
--   scanl f z &lt;x1,...,xn&gt; = &lt;y1,...,y(n+1)&gt;
--     where y1 = z
--           yi = f y(i-1) x(i-1)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl (+) 0 (V.fromList [1,2,3,4])
--   [0,1,3,6,10]
--   </pre>
scanl :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan with strict accumulator.
scanl' :: (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan over a vector with its index.
iscanl :: (Int -> a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan over a vector (strictly) with its
--   index.
iscanl' :: (Int -> a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Right-to-left prescan.
--   
--   <pre>
--   prescanr f z = <a>reverse</a> . <a>prescanl</a> (flip f) z . <a>reverse</a>
--   </pre>
prescanr :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left prescan with strict accumulator.
prescanr' :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan.
postscanr :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan with strict accumulator.
postscanr' :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan.
scanr :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan with strict accumulator.
scanr' :: (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan over a vector with its index.
iscanr :: (Int -> a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan over a vector (strictly) with its
--   index.
iscanr' :: (Int -> a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Convert a vector to a list.
toList :: Vector a -> [a]

-- | <i>O(n)</i> Convert a list to a vector.
fromList :: [a] -> Vector a

-- | <i>O(n)</i> Convert the first <tt>n</tt> elements of a list to a
--   vector. It's expected that the supplied list will be exactly
--   <tt>n</tt> elements long. As an optimization, this function allocates
--   a buffer for <tt>n</tt> elements, which could be used for DoS-attacks
--   by exhausting the memory if an attacker controls that parameter.
--   
--   <pre>
--   fromListN n xs = <a>fromList</a> (<a>take</a> n xs)
--   </pre>
fromListN :: Int -> [a] -> Vector a

-- | <i>O(n)</i> Convert between different vector types.
convert :: (Vector v a, Vector w a) => v a -> w a

-- | <i>O(n)</i> Yield an immutable copy of the mutable vector.
freeze :: PrimMonad m => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(n)</i> Yield a mutable copy of an immutable vector.
thaw :: PrimMonad m => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length.
copy :: PrimMonad m => MVector (PrimState m) a -> Vector a -> m ()


-- | Boxed <tt>Vector</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Boxed.Partial as VB'
--   </pre>
module RIO.Vector.Boxed.Partial

-- | O(1) Indexing.
(!) :: Vector a -> Int -> a

-- | <i>O(1)</i> First element.
head :: Vector a -> a

-- | <i>O(1)</i> Last element.
last :: Vector a -> a

-- | <i>O(1)</i> Indexing in a monad.
--   
--   The monad allows operations to be strict in the vector when necessary.
--   Suppose vector copying is implemented like this:
--   
--   <pre>
--   copy mv v = ... write mv i (v ! i) ...
--   </pre>
--   
--   For lazy vectors, <tt>v ! i</tt> would not be evaluated which means
--   that <tt>mv</tt> would unnecessarily retain a reference to <tt>v</tt>
--   in each element written.
--   
--   With <a>indexM</a>, copying can be implemented like this instead:
--   
--   <pre>
--   copy mv v = ... do
--                     x &lt;- indexM v i
--                     write mv i x
--   </pre>
--   
--   Here, no references to <tt>v</tt> are retained because indexing (but
--   <i>not</i> the element) is evaluated eagerly.
indexM :: Monad m => Vector a -> Int -> m a

-- | <i>O(1)</i> First element of a vector in a monad. See <a>indexM</a>
--   for an explanation of why this is useful.
headM :: Monad m => Vector a -> m a

-- | <i>O(1)</i> Last element of a vector in a monad. See <a>indexM</a> for
--   an explanation of why this is useful.
lastM :: Monad m => Vector a -> m a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty.
init :: Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty.
tail :: Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the list of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   &lt;5,9,2,7&gt; // [(2,1),(0,3),(2,8)] = &lt;3,9,8,7&gt;
--   </pre>
(//) :: Vector a -> [(Int, a)] -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the vector of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   update &lt;5,9,2,7&gt; &lt;(2,1),(0,3),(2,8)&gt; = &lt;3,9,8,7&gt;
--   </pre>
update :: Vector a -> Vector (Int, a) -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>a</tt> from the value vector, replace
--   the element of the initial vector at position <tt>i</tt> by
--   <tt>a</tt>.
--   
--   <pre>
--   update_ &lt;5,9,2,7&gt;  &lt;2,0,2&gt; &lt;1,3,8&gt; = &lt;3,9,8,7&gt;
--   </pre>
--   
--   The function <a>update</a> provides the same functionality and is
--   usually more convenient.
--   
--   <pre>
--   update_ xs is ys = <a>update</a> xs (<a>zip</a> is ys)
--   </pre>
update_ :: Vector a -> Vector Int -> Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the list, replace the
--   vector element <tt>a</tt> at position <tt>i</tt> by <tt>f a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.accum (+) (V.fromList [1000,2000,3000]) [(2,4),(1,6),(0,3),(1,10)]
--   [1003,2016,3004]
--   </pre>
accum :: (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the vector of pairs,
--   replace the vector element <tt>a</tt> at position <tt>i</tt> by <tt>f
--   a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.accumulate (+) (V.fromList [1000,2000,3000]) (V.fromList [(2,4),(1,6),(0,3),(1,10)])
--   [1003,2016,3004]
--   </pre>
accumulate :: (a -> b -> a) -> Vector a -> Vector (Int, b) -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>b</tt> from the the value vector,
--   replace the element of the initial vector at position <tt>i</tt> by
--   <tt>f a b</tt>.
--   
--   <pre>
--   accumulate_ (+) &lt;5,9,2&gt; &lt;2,1,0,1&gt; &lt;4,6,3,7&gt; = &lt;5+3, 9+6+7, 2+4&gt;
--   </pre>
--   
--   The function <a>accumulate</a> provides the same functionality and is
--   usually more convenient.
--   
--   <pre>
--   accumulate_ f as is bs = <a>accumulate</a> f as (<a>zip</a> is bs)
--   </pre>
accumulate_ :: (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | <i>O(n)</i> Yield the vector obtained by replacing each element
--   <tt>i</tt> of the index vector by <tt>xs<a>!</a>i</tt>. This is
--   equivalent to <tt><a>map</a> (xs<a>!</a>) is</tt>, but is often much
--   more efficient.
--   
--   <pre>
--   backpermute &lt;a,b,c,d&gt; &lt;0,3,2,3,1,0&gt; = &lt;a,d,c,d,b,a&gt;
--   </pre>
backpermute :: Vector a -> Vector Int -> Vector a

-- | <i>O(n)</i> Left fold on non-empty vectors.
foldl1 :: (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Left fold on non-empty vectors with strict accumulator.
foldl1' :: (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors.
foldr1 :: (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors with strict accumulator.
foldr1' :: (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [2, 1]
--   2
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [Arg 1 'a', Arg 2 'b']
--   Arg 2 'b'
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [Arg 1 'a', Arg 1 'b']
--   Arg 1 'a'
--   </pre>
maximum :: Ord a => Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins. This behavior is different from
--   <a>maximumBy</a> which returns the last tie.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maximumBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   (2,'a')
--   
--   &gt;&gt;&gt; V.maximumBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   (1,'a')
--   </pre>
maximumBy :: (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [2, 1]
--   1
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [Arg 2 'a', Arg 1 'b']
--   Arg 1 'b'
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [Arg 1 'a', Arg 1 'b']
--   Arg 1 'a'
--   </pre>
minimum :: Ord a => Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minimumBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   (1,'b')
--   
--   &gt;&gt;&gt; V.minimumBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   (1,'a')
--   </pre>
minimumBy :: (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the index of the minimum element of the vector. The
--   vector may not be empty.
minIndex :: Ord a => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the minimum element of the vector
--   according to the given comparison function. The vector may not be
--   empty.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minIndexBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   1
--   
--   &gt;&gt;&gt; V.minIndexBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
minIndexBy :: (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector. The
--   vector may not be empty.
maxIndex :: Ord a => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector
--   according to the given comparison function. The vector may not be
--   empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maxIndexBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   0
--   
--   &gt;&gt;&gt; V.maxIndexBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
maxIndexBy :: (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Monadic fold over non-empty vectors.
fold1M :: Monad m => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator.
fold1M' :: Monad m => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors that discards the
--   result.
fold1M_ :: Monad m => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator that discards the result.
fold1M'_ :: Monad m => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector.
--   
--   <pre>
--   scanl f &lt;x1,...,xn&gt; = &lt;y1,...,yn&gt;
--     where y1 = x1
--           yi = f y(i-1) xi
--   </pre>
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl1 min $ V.fromListN 5 [4,2,4,1,3]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; V.scanl1 max $ V.fromListN 5 [1,3,2,5,4]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; V.scanl1 min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanl1 :: (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector with a
--   strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl1' min $ V.fromListN 5 [4,2,4,1,3]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; V.scanl1' max $ V.fromListN 5 [1,3,2,5,4]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; V.scanl1' min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanl1' :: (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanr1 min $ V.fromListN 5 [3,1,4,2,4]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; V.scanr1 max $ V.fromListN 5 [4,5,2,3,1]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; V.scanr1 min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanr1 :: (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector with
--   a strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanr1' min $ V.fromListN 5 [3,1,4,2,4]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; V.scanr1' max $ V.fromListN 5 [4,5,2,3,1]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; V.scanr1' min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanr1' :: (a -> a -> a) -> Vector a -> Vector a


-- | Boxed <tt>Vector</tt> unsafe functions. These perform no bounds
--   checking, and may cause segmentation faults etc.! Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Boxed.Unsafe as VB'
--   </pre>
module RIO.Vector.Boxed.Unsafe

-- | <i>O(1)</i> Unsafe indexing without bounds checking.
unsafeIndex :: Vector a -> Int -> a

-- | <i>O(1)</i> First element, without checking if the vector is empty.
unsafeHead :: Vector a -> a

-- | <i>O(1)</i> Last element, without checking if the vector is empty.
unsafeLast :: Vector a -> a

-- | <i>O(1)</i> Indexing in a monad, without bounds checks. See
--   <a>indexM</a> for an explanation of why this is useful.
unsafeIndexM :: Monad m => Vector a -> Int -> m a

-- | <i>O(1)</i> First element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeHeadM :: Monad m => Vector a -> m a

-- | <i>O(1)</i> Last element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeLastM :: Monad m => Vector a -> m a

-- | <i>O(1)</i> Yield a slice of the vector without copying. The vector
--   must contain at least <tt>i+n</tt> elements, but this is not checked.
unsafeSlice :: Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty, but this is not checked.
unsafeInit :: Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty, but this is not checked.
unsafeTail :: Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements without copying. The
--   vector must contain at least <tt>n</tt> elements, but this is not
--   checked.
unsafeTake :: Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector must contain at least <tt>n</tt> elements, but
--   this is not checked.
unsafeDrop :: Int -> Vector a -> Vector a

-- | Same as (<a>//</a>), but without bounds checking.
unsafeUpd :: Vector a -> [(Int, a)] -> Vector a

-- | Same as <a>update</a>, but without bounds checking.
unsafeUpdate :: Vector a -> Vector (Int, a) -> Vector a

-- | Same as <a>update_</a>, but without bounds checking.
unsafeUpdate_ :: Vector a -> Vector Int -> Vector a -> Vector a

-- | Same as <a>accum</a>, but without bounds checking.
unsafeAccum :: (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | Same as <a>accumulate</a>, but without bounds checking.
unsafeAccumulate :: (a -> b -> a) -> Vector a -> Vector (Int, b) -> Vector a

-- | Same as <a>accumulate_</a>, but without bounds checking.
unsafeAccumulate_ :: (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | Same as <a>backpermute</a>, but without bounds checking.
unsafeBackpermute :: Vector a -> Vector Int -> Vector a

-- | <i>O(1)</i> Unsafely convert a mutable vector to an immutable one
--   without copying. The mutable vector may not be used after this
--   operation.
unsafeFreeze :: PrimMonad m => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(1)</i> Unsafely convert an immutable vector to a mutable one
--   without copying. Note that this is a very dangerous function and
--   generally it's only safe to read from the resulting vector. In this
--   case, the immutable vector could be used safely as well.
--   
--   Problems with mutation happen because GHC has a lot of freedom to
--   introduce sharing. As a result mutable vectors produced by
--   <tt>unsafeThaw</tt> may or may not share the same underlying buffer.
--   For example:
--   
--   <pre>
--   foo = do
--     let vec = V.generate 10 id
--     mvec &lt;- V.unsafeThaw vec
--     do_something mvec
--   </pre>
--   
--   Here GHC could lift <tt>vec</tt> outside of foo which means that all
--   calls to <tt>do_something</tt> will use same buffer with possibly
--   disastrous results. Whether such aliasing happens or not depends on
--   the program in question, optimization levels, and GHC flags.
--   
--   All in all, attempts to modify a vector produced by
--   <tt>unsafeThaw</tt> fall out of domain of software engineering and
--   into realm of black magic, dark rituals, and unspeakable horrors. The
--   only advice that could be given is: "Don't attempt to mutate a vector
--   produced by <tt>unsafeThaw</tt> unless you know how to prevent GHC
--   from aliasing buffers accidentally. We don't."
unsafeThaw :: PrimMonad m => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length. This is not checked.
unsafeCopy :: PrimMonad m => MVector (PrimState m) a -> Vector a -> m ()


-- | Generic <tt>Vector</tt> interface partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Partial as V'
--   </pre>
module RIO.Vector.Partial

-- | O(1) Indexing.
(!) :: (HasCallStack, Vector v a) => v a -> Int -> a
infixl 9 !

-- | <i>O(1)</i> First element.
head :: Vector v a => v a -> a

-- | <i>O(1)</i> Last element.
last :: Vector v a => v a -> a

-- | <i>O(1)</i> Indexing in a monad.
--   
--   The monad allows operations to be strict in the vector when necessary.
--   Suppose vector copying is implemented like this:
--   
--   <pre>
--   copy mv v = ... write mv i (v ! i) ...
--   </pre>
--   
--   For lazy vectors, <tt>v ! i</tt> would not be evaluated which means
--   that <tt>mv</tt> would unnecessarily retain a reference to <tt>v</tt>
--   in each element written.
--   
--   With <a>indexM</a>, copying can be implemented like this instead:
--   
--   <pre>
--   copy mv v = ... do
--                     x &lt;- indexM v i
--                     write mv i x
--   </pre>
--   
--   Here, no references to <tt>v</tt> are retained because indexing (but
--   <i>not</i> the element) is evaluated eagerly.
indexM :: (HasCallStack, Vector v a, Monad m) => v a -> Int -> m a

-- | <i>O(1)</i> First element of a vector in a monad. See <a>indexM</a>
--   for an explanation of why this is useful.
headM :: (Vector v a, Monad m) => v a -> m a

-- | <i>O(1)</i> Last element of a vector in a monad. See <a>indexM</a> for
--   an explanation of why this is useful.
lastM :: (Vector v a, Monad m) => v a -> m a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty.
init :: Vector v a => v a -> v a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty.
tail :: Vector v a => v a -> v a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the list of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   &lt;5,9,2,7&gt; // [(2,1),(0,3),(2,8)] = &lt;3,9,8,7&gt;
--   </pre>
(//) :: Vector v a => v a -> [(Int, a)] -> v a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the vector of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   update &lt;5,9,2,7&gt; &lt;(2,1),(0,3),(2,8)&gt; = &lt;3,9,8,7&gt;
--   </pre>
update :: (Vector v a, Vector v (Int, a)) => v a -> v (Int, a) -> v a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>a</tt> from the value vector, replace
--   the element of the initial vector at position <tt>i</tt> by
--   <tt>a</tt>.
--   
--   <pre>
--   update_ &lt;5,9,2,7&gt;  &lt;2,0,2&gt; &lt;1,3,8&gt; = &lt;3,9,8,7&gt;
--   </pre>
--   
--   This function is useful for instances of <a>Vector</a> that cannot
--   store pairs. Otherwise, <a>update</a> is probably more convenient.
--   
--   <pre>
--   update_ xs is ys = <a>update</a> xs (<a>zip</a> is ys)
--   </pre>
update_ :: (Vector v a, Vector v Int) => v a -> v Int -> v a -> v a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the list, replace the
--   vector element <tt>a</tt> at position <tt>i</tt> by <tt>f a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.accum (+) (V.fromList [1000,2000,3000]) [(2,4),(1,6),(0,3),(1,10)]
--   [1003,2016,3004]
--   </pre>
accum :: Vector v a => (a -> b -> a) -> v a -> [(Int, b)] -> v a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the vector of pairs,
--   replace the vector element <tt>a</tt> at position <tt>i</tt> by <tt>f
--   a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.accumulate (+) (V.fromList [1000,2000,3000]) (V.fromList [(2,4),(1,6),(0,3),(1,10)])
--   [1003,2016,3004]
--   </pre>
accumulate :: (Vector v a, Vector v (Int, b)) => (a -> b -> a) -> v a -> v (Int, b) -> v a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>b</tt> from the the value vector,
--   replace the element of the initial vector at position <tt>i</tt> by
--   <tt>f a b</tt>.
--   
--   <pre>
--   accumulate_ (+) &lt;5,9,2&gt; &lt;2,1,0,1&gt; &lt;4,6,3,7&gt; = &lt;5+3, 9+6+7, 2+4&gt;
--   </pre>
--   
--   This function is useful for instances of <a>Vector</a> that cannot
--   store pairs. Otherwise, <a>accumulate</a> is probably more convenient:
--   
--   <pre>
--   accumulate_ f as is bs = <a>accumulate</a> f as (<a>zip</a> is bs)
--   </pre>
accumulate_ :: (Vector v a, Vector v Int, Vector v b) => (a -> b -> a) -> v a -> v Int -> v b -> v a

-- | <i>O(n)</i> Yield the vector obtained by replacing each element
--   <tt>i</tt> of the index vector by <tt>xs<a>!</a>i</tt>. This is
--   equivalent to <tt><a>map</a> (xs<a>!</a>) is</tt>, but is often much
--   more efficient.
--   
--   <pre>
--   backpermute &lt;a,b,c,d&gt; &lt;0,3,2,3,1,0&gt; = &lt;a,d,c,d,b,a&gt;
--   </pre>
backpermute :: (HasCallStack, Vector v a, Vector v Int) => v a -> v Int -> v a

-- | <i>O(n)</i> Left fold on non-empty vectors.
foldl1 :: Vector v a => (a -> a -> a) -> v a -> a

-- | <i>O(n)</i> Left fold on non-empty vectors with strict accumulator.
foldl1' :: Vector v a => (a -> a -> a) -> v a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors.
foldr1 :: Vector v a => (a -> a -> a) -> v a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors with strict accumulator.
foldr1' :: Vector v a => (a -> a -> a) -> v a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [2, 1]
--   2
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [Arg 1 'a', Arg 2 'b']
--   Arg 2 'b'
--   
--   &gt;&gt;&gt; V.maximum $ V.fromList [Arg 1 'a', Arg 1 'b']
--   Arg 1 'a'
--   </pre>
maximum :: (Vector v a, Ord a) => v a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins. This behavior is different from
--   <a>maximumBy</a> which returns the last tie.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maximumBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   (2,'a')
--   
--   &gt;&gt;&gt; V.maximumBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   (1,'a')
--   </pre>
maximumBy :: Vector v a => (a -> a -> Ordering) -> v a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [2, 1]
--   1
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [Arg 2 'a', Arg 1 'b']
--   Arg 1 'b'
--   
--   &gt;&gt;&gt; V.minimum $ V.fromList [Arg 1 'a', Arg 1 'b']
--   Arg 1 'a'
--   </pre>
minimum :: (Vector v a, Ord a) => v a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minimumBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   (1,'b')
--   
--   &gt;&gt;&gt; V.minimumBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   (1,'a')
--   </pre>
minimumBy :: Vector v a => (a -> a -> Ordering) -> v a -> a

-- | <i>O(n)</i> Yield the index of the minimum element of the vector. The
--   vector may not be empty.
minIndex :: (Vector v a, Ord a) => v a -> Int

-- | <i>O(n)</i> Yield the index of the minimum element of the vector
--   according to the given comparison function. The vector may not be
--   empty.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.minIndexBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   1
--   
--   &gt;&gt;&gt; V.minIndexBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
minIndexBy :: Vector v a => (a -> a -> Ordering) -> v a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector. The
--   vector may not be empty.
maxIndex :: (Vector v a, Ord a) => v a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector
--   according to the given comparison function. The vector may not be
--   empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.maxIndexBy (comparing fst) $ V.fromList [(2,'a'), (1,'b')]
--   0
--   
--   &gt;&gt;&gt; V.maxIndexBy (comparing fst) $ V.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
maxIndexBy :: Vector v a => (a -> a -> Ordering) -> v a -> Int

-- | <i>O(n)</i> Monadic fold over non-empty vectors.
fold1M :: (Monad m, Vector v a) => (a -> a -> m a) -> v a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator.
fold1M' :: (Monad m, Vector v a) => (a -> a -> m a) -> v a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors that discards the
--   result.
fold1M_ :: (Monad m, Vector v a) => (a -> a -> m a) -> v a -> m ()

-- | <i>O(n)</i> Monad fold over non-empty vectors with strict accumulator
--   that discards the result.
fold1M'_ :: (Monad m, Vector v a) => (a -> a -> m a) -> v a -> m ()

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector.
--   
--   <pre>
--   scanl f &lt;x1,...,xn&gt; = &lt;y1,...,yn&gt;
--     where y1 = x1
--           yi = f y(i-1) xi
--   </pre>
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl1 min $ V.fromListN 5 [4,2,4,1,3]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; V.scanl1 max $ V.fromListN 5 [1,3,2,5,4]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; V.scanl1 min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanl1 :: Vector v a => (a -> a -> a) -> v a -> v a

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector with a
--   strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanl1' min $ V.fromListN 5 [4,2,4,1,3]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; V.scanl1' max $ V.fromListN 5 [1,3,2,5,4]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; V.scanl1' min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanl1' :: Vector v a => (a -> a -> a) -> v a -> v a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanr1 min $ V.fromListN 5 [3,1,4,2,4]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; V.scanr1 max $ V.fromListN 5 [4,5,2,3,1]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; V.scanr1 min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanr1 :: Vector v a => (a -> a -> a) -> v a -> v a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector with
--   a strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as V
--   
--   &gt;&gt;&gt; V.scanr1' min $ V.fromListN 5 [3,1,4,2,4]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; V.scanr1' max $ V.fromListN 5 [4,5,2,3,1]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; V.scanr1' min (V.empty :: V.Vector Int)
--   []
--   </pre>
scanr1' :: Vector v a => (a -> a -> a) -> v a -> v a


-- | Storable <tt>Vector</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Storable as VS
--   </pre>
--   
--   This module does not export any partial or unsafe functions. For
--   those, see <a>RIO.Vector.Storable.Partial</a> and
--   <a>RIO.Vector.Storable.Unsafe</a>
module RIO.Vector.Storable

-- | <a>Storable</a>-based vectors.
data Vector a

-- | Mutable <a>Storable</a>-based vectors.
data MVector s a
MVector :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !ForeignPtr a -> MVector s a

-- | The member functions of this class facilitate writing values of
--   primitive types to raw memory (which may have been allocated with the
--   above mentioned routines) and reading values from blocks of raw
--   memory. The class, furthermore, includes support for computing the
--   storage requirements and alignment restrictions of storable types.
--   
--   Memory addresses are represented as values of type <tt><a>Ptr</a>
--   a</tt>, for some <tt>a</tt> which is an instance of class
--   <a>Storable</a>. The type argument to <a>Ptr</a> helps provide some
--   valuable type safety in FFI code (you can't mix pointers of different
--   types without an explicit cast), while helping the Haskell type system
--   figure out which marshalling method is needed for a given pointer.
--   
--   All marshalling between Haskell and a foreign language ultimately
--   boils down to translating Haskell data structures into the binary
--   representation of a corresponding data structure of the foreign
--   language and vice versa. To code this marshalling in Haskell, it is
--   necessary to manipulate primitive data types stored in unstructured
--   memory blocks. The class <a>Storable</a> facilitates this manipulation
--   on all types for which it is instantiated, which are the standard
--   basic types of Haskell, the fixed size <tt>Int</tt> types
--   (<a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>), the fixed
--   size <tt>Word</tt> types (<a>Word8</a>, <a>Word16</a>, <a>Word32</a>,
--   <a>Word64</a>), <a>StablePtr</a>, all types from
--   <a>Foreign.C.Types</a>, as well as <a>Ptr</a>.
class Storable a

-- | <i>O(1)</i> Yield the length of the vector.
length :: Storable a => Vector a -> Int

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Storable a => Vector a -> Bool

-- | O(1) Safe indexing.
(!?) :: Storable a => Vector a -> Int -> Maybe a

-- | <i>O(1)</i> Yield a slice of the vector without copying it. The vector
--   must contain at least <tt>i+n</tt> elements.
slice :: Storable a => Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield at the first <tt>n</tt> elements without copying.
--   The vector may contain less than <tt>n</tt> elements, in which case it
--   is returned unchanged.
take :: Storable a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector may contain less than <tt>n</tt> elements, in
--   which case an empty vector is returned.
drop :: Storable a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements paired with the
--   remainder, without copying.
--   
--   Note that <tt><a>splitAt</a> n v</tt> is equivalent to
--   <tt>(<a>take</a> n v, <a>drop</a> n v)</tt>, but slightly more
--   efficient.
splitAt :: Storable a => Int -> Vector a -> (Vector a, Vector a)

-- | <i>O(1)</i> The empty vector.
empty :: Storable a => Vector a

-- | <i>O(1)</i> A vector with exactly one element.
singleton :: Storable a => a -> Vector a

-- | <i>O(n)</i> A vector of the given length with the same value in each
--   position.
replicate :: Storable a => Int -> a -> Vector a

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   function to each index.
generate :: Storable a => Int -> (Int -> a) -> Vector a

-- | <i>O(n)</i> Apply the function &lt;math&gt; times to an initial value,
--   producing a vector of length &lt;math&gt;. The 0th element will
--   contain the initial value, which is why there is one less function
--   application than the number of elements in the produced vector.
--   
--   &lt;math&gt;
--   
--   <h3><b>Examples</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.iterateN 0 undefined undefined :: VS.Vector Int
--   []
--   
--   &gt;&gt;&gt; VS.iterateN 26 succ 'a'
--   "abcdefghijklmnopqrstuvwxyz"
--   </pre>
iterateN :: Storable a => Int -> (a -> a) -> a -> Vector a

-- | <i>O(n)</i> Execute the monadic action the given number of times and
--   store the results in a vector.
replicateM :: (Monad m, Storable a) => Int -> m a -> m (Vector a)

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   monadic action to each index.
generateM :: (Monad m, Storable a) => Int -> (Int -> m a) -> m (Vector a)

-- | <i>O(n)</i> Apply the monadic function &lt;math&gt; times to an
--   initial value, producing a vector of length &lt;math&gt;. The 0th
--   element will contain the initial value, which is why there is one less
--   function application than the number of elements in the produced
--   vector.
--   
--   For a non-monadic version, see <a>iterateN</a>.
iterateNM :: (Monad m, Storable a) => Int -> (a -> m a) -> a -> m (Vector a)

-- | Execute the monadic action and freeze the resulting vector.
--   
--   <pre>
--   create (do { v &lt;- new 2; write v 0 'a'; write v 1 'b'; return v }) = &lt;<tt>a</tt>,<tt>b</tt>&gt;
--   </pre>
create :: Storable a => (forall s. () => ST s (MVector s a)) -> Vector a

-- | Execute the monadic action and freeze the resulting vectors.
createT :: (Traversable f, Storable a) => (forall s. () => ST s (f (MVector s a))) -> f (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the generator
--   function to a seed. The generator function yields <tt>Just</tt> the
--   next element and the new seed or <tt>Nothing</tt> if there are no more
--   elements.
--   
--   <pre>
--   unfoldr (\n -&gt; if n == 0 then Nothing else Just (n,n-1)) 10
--    = &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldr :: Storable a => (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector with at most <tt>n</tt> elements by
--   repeatedly applying the generator function to a seed. The generator
--   function yields <tt>Just</tt> the next element and the new seed or
--   <tt>Nothing</tt> if there are no more elements.
--   
--   <pre>
--   unfoldrN 3 (\n -&gt; Just (n,n-1)) 10 = &lt;10,9,8&gt;
--   </pre>
unfoldrN :: Storable a => Int -> (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrM :: (Monad m, Storable a) => (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrNM :: (Monad m, Storable a) => Int -> (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements by repeatedly
--   applying the generator function to the already constructed part of the
--   vector.
--   
--   <pre>
--   constructN 3 f = let a = f &lt;&gt; ; b = f &lt;a&gt; ; c = f &lt;a,b&gt; in &lt;a,b,c&gt;
--   </pre>
constructN :: Storable a => Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements from right to
--   left by repeatedly applying the generator function to the already
--   constructed part of the vector.
--   
--   <pre>
--   constructrN 3 f = let a = f &lt;&gt; ; b = f&lt;a&gt; ; c = f &lt;b,a&gt; in &lt;c,b,a&gt;
--   </pre>
constructrN :: Storable a => Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+1</tt> etc. This operation is usually more efficient
--   than <a>enumFromTo</a>.
--   
--   <pre>
--   enumFromN 5 3 = &lt;5,6,7&gt;
--   </pre>
enumFromN :: (Storable a, Num a) => a -> Int -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+y</tt>, <tt>x+y+y</tt> etc. This operations is
--   usually more efficient than <a>enumFromThenTo</a>.
--   
--   <pre>
--   enumFromStepN 1 2 5 = &lt;1,3,5,7,9&gt;
--   </pre>
enumFromStepN :: (Storable a, Num a) => a -> a -> Int -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromN</a> instead.
enumFromTo :: (Storable a, Enum a) => a -> a -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt> with a
--   specific step <tt>z</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromStepN</a> instead.
enumFromThenTo :: (Storable a, Enum a) => a -> a -> a -> Vector a

-- | <i>O(n)</i> Prepend an element.
cons :: Storable a => a -> Vector a -> Vector a

-- | <i>O(n)</i> Append an element.
snoc :: Storable a => Vector a -> a -> Vector a

-- | <i>O(m+n)</i> Concatenate two vectors.
(++) :: Storable a => Vector a -> Vector a -> Vector a
infixr 5 ++

-- | <i>O(n)</i> Concatenate all vectors in the list.
concat :: Storable a => [Vector a] -> Vector a

-- | <i>O(n)</i> Yield the argument, but force it not to retain any extra
--   memory, possibly by copying it.
--   
--   This is especially useful when dealing with slices. For example:
--   
--   <pre>
--   force (slice 0 2 &lt;huge vector&gt;)
--   </pre>
--   
--   Here, the slice retains a reference to the huge vector. Forcing it
--   creates a copy of just the elements that belong to the slice and
--   allows the huge vector to be garbage collected.
force :: Storable a => Vector a -> Vector a

-- | <i>O(n)</i> Reverse a vector.
reverse :: Storable a => Vector a -> Vector a

-- | Apply a destructive operation to a vector. The operation may be
--   performed in place if it is safe to do so and will modify a copy of
--   the vector otherwise (see <a>New</a> for details).
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Storable.Mutable as MVS
--   
--   &gt;&gt;&gt; VS.modify (\v -&gt; MVS.write v 0 'x') $ VS.replicate 4 'a'
--   "xaaa"
--   </pre>
modify :: Storable a => (forall s. () => MVector s a -> ST s ()) -> Vector a -> Vector a

-- | <i>O(n)</i> Map a function over a vector.
map :: (Storable a, Storable b) => (a -> b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply a function to every element of a vector and its
--   index.
imap :: (Storable a, Storable b) => (Int -> a -> b) -> Vector a -> Vector b

-- | Map a function over a vector and concatenate the results.
concatMap :: (Storable a, Storable b) => (a -> Vector b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results.
mapM :: (Monad m, Storable a, Storable b) => (a -> m b) -> Vector a -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results.
mapM_ :: (Monad m, Storable a) => (a -> m b) -> Vector a -> m ()

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results. Equivalent to <tt>flip <a>mapM</a></tt>.
forM :: (Monad m, Storable a, Storable b) => Vector a -> (a -> m b) -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results. Equivalent to <tt>flip <a>mapM_</a></tt>.
forM_ :: (Monad m, Storable a) => Vector a -> (a -> m b) -> m ()

-- | <i>O(min(m,n))</i> Zip two vectors with the given function.
zipWith :: (Storable a, Storable b, Storable c) => (a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors with the given function.
zipWith3 :: (Storable a, Storable b, Storable c, Storable d) => (a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
zipWith4 :: (Storable a, Storable b, Storable c, Storable d, Storable e) => (a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
zipWith5 :: (Storable a, Storable b, Storable c, Storable d, Storable e, Storable f) => (a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
zipWith6 :: (Storable a, Storable b, Storable c, Storable d, Storable e, Storable f, Storable g) => (a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(min(m,n))</i> Zip two vectors with a function that also takes the
--   elements' indices.
izipWith :: (Storable a, Storable b, Storable c) => (Int -> a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors and their indices with the given function.
izipWith3 :: (Storable a, Storable b, Storable c, Storable d) => (Int -> a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
izipWith4 :: (Storable a, Storable b, Storable c, Storable d, Storable e) => (Int -> a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
izipWith5 :: (Storable a, Storable b, Storable c, Storable d, Storable e, Storable f) => (Int -> a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
izipWith6 :: (Storable a, Storable b, Storable c, Storable d, Storable e, Storable f, Storable g) => (Int -> a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   yield a vector of results.
zipWithM :: (Monad m, Storable a, Storable b, Storable c) => (a -> b -> m c) -> Vector a -> Vector b -> m (Vector c)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   ignore the results.
zipWithM_ :: (Monad m, Storable a, Storable b) => (a -> b -> m c) -> Vector a -> Vector b -> m ()

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate.
filter :: Storable a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate which
--   is applied to the values and their indices.
ifilter :: Storable a => (Int -> a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop repeated adjacent elements. The first element in each
--   group is returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.uniq $ VS.fromList [1,3,3,200,3 :: Int]
--   [1,3,200,3]
--   </pre>
uniq :: (Storable a, Eq a) => Vector a -> Vector a

-- | <i>O(n)</i> Map the values and collect the <tt>Just</tt> results.
mapMaybe :: (Storable a, Storable b) => (a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Map the indices/values and collect the <tt>Just</tt>
--   results.
imapMaybe :: (Storable a, Storable b) => (Int -> a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Drop all elements that do not satisfy the monadic
--   predicate.
filterM :: (Monad m, Storable a) => (a -> m Bool) -> Vector a -> m (Vector a)

-- | <i>O(n)</i> Yield the longest prefix of elements satisfying the
--   predicate. The current implementation is not copy-free, unless the
--   result vector is fused away.
takeWhile :: Storable a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop the longest prefix of elements that satisfy the
--   predicate without copying.
dropWhile :: Storable a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The relative order of the elements is preserved at the
--   cost of a sometimes reduced performance compared to
--   <a>unstablePartition</a>.
partition :: Storable a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The order of the elements is not preserved, but the
--   operation is often faster than <a>partition</a>.
unstablePartition :: Storable a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: Storable a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   do not satisfy the predicate and the rest without copying.
break :: Storable a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Check if the vector contains an element.
elem :: (Storable a, Eq a) => a -> Vector a -> Bool
infix 4 `elem`

-- | <i>O(n)</i> Check if the vector does not contain an element (inverse
--   of <a>elem</a>).
notElem :: (Storable a, Eq a) => a -> Vector a -> Bool
infix 4 `notElem`

-- | <i>O(n)</i> Yield <tt>Just</tt> the first element matching the
--   predicate or <tt>Nothing</tt> if no such element exists.
find :: Storable a => (a -> Bool) -> Vector a -> Maybe a

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first element
--   matching the predicate or <tt>Nothing</tt> if no such element exists.
findIndex :: Storable a => (a -> Bool) -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of elements satisfying the predicate in
--   ascending order.
findIndices :: Storable a => (a -> Bool) -> Vector a -> Vector Int

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first occurrence of
--   the given element or <tt>Nothing</tt> if the vector does not contain
--   the element. This is a specialised version of <a>findIndex</a>.
elemIndex :: (Storable a, Eq a) => a -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of all occurrences of the given element
--   in ascending order. This is a specialised version of
--   <a>findIndices</a>.
elemIndices :: (Storable a, Eq a) => a -> Vector a -> Vector Int

-- | <i>O(n)</i> Left fold.
foldl :: Storable b => (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator.
foldl' :: Storable b => (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold.
foldr :: Storable a => (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with a strict accumulator.
foldr' :: Storable a => (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Left fold using a function applied to each element and its
--   index.
ifoldl :: Storable b => (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator using a function applied
--   to each element and its index.
ifoldl' :: Storable b => (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold using a function applied to each element and
--   its index.
ifoldr :: Storable a => (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with strict accumulator using a function
--   applied to each element and its index.
ifoldr' :: Storable a => (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Check if all elements satisfy the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.all even $ VS.fromList [2, 4, 12 :: Int]
--   True
--   
--   &gt;&gt;&gt; VS.all even $ VS.fromList [2, 4, 13 :: Int]
--   False
--   
--   &gt;&gt;&gt; VS.all even (VS.empty :: VS.Vector Int)
--   True
--   </pre>
all :: Storable a => (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if any element satisfies the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.any even $ VS.fromList [1, 3, 7 :: Int]
--   False
--   
--   &gt;&gt;&gt; VS.any even $ VS.fromList [3, 2, 13 :: Int]
--   True
--   
--   &gt;&gt;&gt; VS.any even (VS.empty :: VS.Vector Int)
--   False
--   </pre>
any :: Storable a => (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if all elements are <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.and $ VS.fromList [True, False]
--   False
--   
--   &gt;&gt;&gt; VS.and VS.empty
--   True
--   </pre>
and :: Vector Bool -> Bool

-- | <i>O(n)</i> Check if any element is <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.or $ VS.fromList [True, False]
--   True
--   
--   &gt;&gt;&gt; VS.or VS.empty
--   False
--   </pre>
or :: Vector Bool -> Bool

-- | <i>O(n)</i> Compute the sum of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.sum $ VS.fromList [300,20,1 :: Int]
--   321
--   
--   &gt;&gt;&gt; VS.sum (VS.empty :: VS.Vector Int)
--   0
--   </pre>
sum :: (Storable a, Num a) => Vector a -> a

-- | <i>O(n)</i> Compute the product of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.product $ VS.fromList [1,2,3,4 :: Int]
--   24
--   
--   &gt;&gt;&gt; VS.product (VS.empty :: VS.Vector Int)
--   1
--   </pre>
product :: (Storable a, Num a) => Vector a -> a

-- | <i>O(n)</i> Monadic fold.
foldM :: (Monad m, Storable b) => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator.
foldM' :: (Monad m, Storable b) => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold that discards the result.
foldM_ :: (Monad m, Storable b) => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result.
foldM'_ :: (Monad m, Storable b) => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Left-to-right prescan.
--   
--   <pre>
--   prescanl f z = <a>init</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.prescanl (+) 0 (VS.fromList [1,2,3,4 :: Int])
--   [0,1,3,6]
--   </pre>
prescanl :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right prescan with strict accumulator.
prescanl' :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan.
--   
--   <pre>
--   postscanl f z = <a>tail</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.postscanl (+) 0 (VS.fromList [1,2,3,4 :: Int])
--   [1,3,6,10]
--   </pre>
postscanl :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan with strict accumulator.
postscanl' :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan.
--   
--   <pre>
--   scanl f z &lt;x1,...,xn&gt; = &lt;y1,...,y(n+1)&gt;
--     where y1 = z
--           yi = f y(i-1) x(i-1)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.scanl (+) 0 (VS.fromList [1,2,3,4 :: Int])
--   [0,1,3,6,10]
--   </pre>
scanl :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan with strict accumulator.
scanl' :: (Storable a, Storable b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Right-to-left prescan.
--   
--   <pre>
--   prescanr f z = <a>reverse</a> . <a>prescanl</a> (flip f) z . <a>reverse</a>
--   </pre>
prescanr :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left prescan with strict accumulator.
prescanr' :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan.
postscanr :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan with strict accumulator.
postscanr' :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan.
scanr :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan with strict accumulator.
scanr' :: (Storable a, Storable b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Convert a vector to a list.
toList :: Storable a => Vector a -> [a]

-- | <i>O(n)</i> Convert a list to a vector.
fromList :: Storable a => [a] -> Vector a

-- | <i>O(n)</i> Convert the first <tt>n</tt> elements of a list to a
--   vector. It's expected that the supplied list will be exactly
--   <tt>n</tt> elements long. As an optimization, this function allocates
--   a buffer for <tt>n</tt> elements, which could be used for DoS-attacks
--   by exhausting the memory if an attacker controls that parameter.
--   
--   <pre>
--   fromListN n xs = <a>fromList</a> (<a>take</a> n xs)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.fromListN 3 [1,2,3,4,5 :: Int]
--   [1,2,3]
--   
--   &gt;&gt;&gt; VS.fromListN 3 [1 :: Int]
--   [1]
--   </pre>
fromListN :: Storable a => Int -> [a] -> Vector a

-- | <i>O(n)</i> Convert between different vector types.
convert :: (Vector v a, Vector w a) => v a -> w a

-- | <i>O(n)</i> Yield an immutable copy of the mutable vector.
freeze :: (Storable a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(n)</i> Yield a mutable copy of an immutable vector.
thaw :: (Storable a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length.
copy :: (Storable a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()


-- | Storable <tt>Vector</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Storable.Partial as VS'
--   </pre>
module RIO.Vector.Storable.Partial

-- | O(1) Indexing.
(!) :: Storable a => Vector a -> Int -> a

-- | <i>O(1)</i> First element.
head :: Storable a => Vector a -> a

-- | <i>O(1)</i> Last element.
last :: Storable a => Vector a -> a

-- | <i>O(1)</i> Indexing in a monad.
--   
--   The monad allows operations to be strict in the vector when necessary.
--   Suppose vector copying is implemented like this:
--   
--   <pre>
--   copy mv v = ... write mv i (v ! i) ...
--   </pre>
--   
--   For lazy vectors, <tt>v ! i</tt> would not be evaluated which means
--   that <tt>mv</tt> would unnecessarily retain a reference to <tt>v</tt>
--   in each element written.
--   
--   With <a>indexM</a>, copying can be implemented like this instead:
--   
--   <pre>
--   copy mv v = ... do
--                     x &lt;- indexM v i
--                     write mv i x
--   </pre>
--   
--   Here, no references to <tt>v</tt> are retained because indexing (but
--   <i>not</i> the element) is evaluated eagerly.
indexM :: (Storable a, Monad m) => Vector a -> Int -> m a

-- | <i>O(1)</i> First element of a vector in a monad. See <a>indexM</a>
--   for an explanation of why this is useful.
headM :: (Storable a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Last element of a vector in a monad. See <a>indexM</a> for
--   an explanation of why this is useful.
lastM :: (Storable a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty.
init :: Storable a => Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty.
tail :: Storable a => Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the list of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   &lt;5,9,2,7&gt; // [(2,1),(0,3),(2,8)] = &lt;3,9,8,7&gt;
--   </pre>
(//) :: Storable a => Vector a -> [(Int, a)] -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>a</tt> from the value vector, replace
--   the element of the initial vector at position <tt>i</tt> by
--   <tt>a</tt>.
--   
--   <pre>
--   update_ &lt;5,9,2,7&gt;  &lt;2,0,2&gt; &lt;1,3,8&gt; = &lt;3,9,8,7&gt;
--   </pre>
update_ :: Storable a => Vector a -> Vector Int -> Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the list, replace the
--   vector element <tt>a</tt> at position <tt>i</tt> by <tt>f a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.accum (+) (VS.fromList [1000,2000,3000 :: Int]) [(2,4),(1,6),(0,3),(1,10)]
--   [1003,2016,3004]
--   </pre>
accum :: Storable a => (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>b</tt> from the the value vector,
--   replace the element of the initial vector at position <tt>i</tt> by
--   <tt>f a b</tt>.
--   
--   <pre>
--   accumulate_ (+) &lt;5,9,2&gt; &lt;2,1,0,1&gt; &lt;4,6,3,7&gt; = &lt;5+3, 9+6+7, 2+4&gt;
--   </pre>
accumulate_ :: (Storable a, Storable b) => (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | <i>O(n)</i> Yield the vector obtained by replacing each element
--   <tt>i</tt> of the index vector by <tt>xs<a>!</a>i</tt>. This is
--   equivalent to <tt><a>map</a> (xs<a>!</a>) is</tt>, but is often much
--   more efficient.
--   
--   <pre>
--   backpermute &lt;a,b,c,d&gt; &lt;0,3,2,3,1,0&gt; = &lt;a,d,c,d,b,a&gt;
--   </pre>
backpermute :: Storable a => Vector a -> Vector Int -> Vector a

-- | <i>O(n)</i> Left fold on non-empty vectors.
foldl1 :: Storable a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Left fold on non-empty vectors with strict accumulator.
foldl1' :: Storable a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors.
foldr1 :: Storable a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors with strict accumulator.
foldr1' :: Storable a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.maximum $ VS.fromList [2, 1 :: Int]
--   2
--   </pre>
maximum :: (Storable a, Ord a) => Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins. This behavior is different from
--   <a>maximumBy</a> which returns the last tie.
maximumBy :: Storable a => (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.minimum $ VS.fromList [2, 1 :: Int]
--   1
--   </pre>
minimum :: (Storable a, Ord a) => Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins.
minimumBy :: Storable a => (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the index of the minimum element of the vector. The
--   vector may not be empty.
minIndex :: (Storable a, Ord a) => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the minimum element of the vector
--   according to the given comparison function. The vector may not be
--   empty.
minIndexBy :: Storable a => (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector. The
--   vector may not be empty.
maxIndex :: (Storable a, Ord a) => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector
--   according to the given comparison function. The vector may not be
--   empty. In case of a tie, the first occurrence wins.
maxIndexBy :: Storable a => (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Monadic fold over non-empty vectors.
fold1M :: (Monad m, Storable a) => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator.
fold1M' :: (Monad m, Storable a) => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors that discards the
--   result.
fold1M_ :: (Monad m, Storable a) => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator that discards the result.
fold1M'_ :: (Monad m, Storable a) => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector.
--   
--   <pre>
--   scanl f &lt;x1,...,xn&gt; = &lt;y1,...,yn&gt;
--     where y1 = x1
--           yi = f y(i-1) xi
--   </pre>
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.scanl1 min $ VS.fromListN 5 [4,2,4,1,3 :: Int]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; VS.scanl1 max $ VS.fromListN 5 [1,3,2,5,4 :: Int]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; VS.scanl1 min (VS.empty :: VS.Vector Int)
--   []
--   </pre>
scanl1 :: Storable a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector with a
--   strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.scanl1' min $ VS.fromListN 5 [4,2,4,1,3 :: Int]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; VS.scanl1' max $ VS.fromListN 5 [1,3,2,5,4 :: Int]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; VS.scanl1' min (VS.empty :: VS.Vector Int)
--   []
--   </pre>
scanl1' :: Storable a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.scanr1 min $ VS.fromListN 5 [3,1,4,2,4 :: Int]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; VS.scanr1 max $ VS.fromListN 5 [4,5,2,3,1 :: Int]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; VS.scanr1 min (VS.empty :: VS.Vector Int)
--   []
--   </pre>
scanr1 :: Storable a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector with
--   a strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Storable as VS
--   
--   &gt;&gt;&gt; VS.scanr1' min $ VS.fromListN 5 [3,1,4,2,4 :: Int]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; VS.scanr1' max $ VS.fromListN 5 [4,5,2,3,1 :: Int]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; VS.scanr1' min (VS.empty :: VS.Vector Int)
--   []
--   </pre>
scanr1' :: Storable a => (a -> a -> a) -> Vector a -> Vector a


-- | Storable <tt>Vector</tt> unsafe functions. These perform no bounds
--   checking, and may cause segmentation faults etc.! Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Storable.Unsafe as VS'
--   </pre>
module RIO.Vector.Storable.Unsafe

-- | <i>O(1)</i> Unsafe indexing without bounds checking.
unsafeIndex :: Storable a => Vector a -> Int -> a

-- | <i>O(1)</i> First element, without checking if the vector is empty.
unsafeHead :: Storable a => Vector a -> a

-- | <i>O(1)</i> Last element, without checking if the vector is empty.
unsafeLast :: Storable a => Vector a -> a

-- | <i>O(1)</i> Indexing in a monad, without bounds checks. See
--   <a>indexM</a> for an explanation of why this is useful.
unsafeIndexM :: (Storable a, Monad m) => Vector a -> Int -> m a

-- | <i>O(1)</i> First element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeHeadM :: (Storable a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Last element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeLastM :: (Storable a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Yield a slice of the vector without copying. The vector
--   must contain at least <tt>i+n</tt> elements, but this is not checked.
unsafeSlice :: Storable a => Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty, but this is not checked.
unsafeInit :: Storable a => Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty, but this is not checked.
unsafeTail :: Storable a => Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements without copying. The
--   vector must contain at least <tt>n</tt> elements, but this is not
--   checked.
unsafeTake :: Storable a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector must contain at least <tt>n</tt> elements, but
--   this is not checked.
unsafeDrop :: Storable a => Int -> Vector a -> Vector a

-- | Same as (<a>//</a>), but without bounds checking.
unsafeUpd :: Storable a => Vector a -> [(Int, a)] -> Vector a

-- | Same as <a>update_</a>, but without bounds checking.
unsafeUpdate_ :: Storable a => Vector a -> Vector Int -> Vector a -> Vector a

-- | Same as <a>accum</a>, but without bounds checking.
unsafeAccum :: Storable a => (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | Same as <a>accumulate_</a>, but without bounds checking.
unsafeAccumulate_ :: (Storable a, Storable b) => (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | Same as <a>backpermute</a>, but without bounds checking.
unsafeBackpermute :: Storable a => Vector a -> Vector Int -> Vector a

-- | <i>O(1)</i> Unsafely convert a mutable vector to an immutable one
--   without copying. The mutable vector may not be used after this
--   operation.
unsafeFreeze :: (Storable a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(1)</i> Unsafely convert an immutable vector to a mutable one
--   without copying. Note that this is a very dangerous function and
--   generally it's only safe to read from the resulting vector. In this
--   case, the immutable vector could be used safely as well.
--   
--   Problems with mutation happen because GHC has a lot of freedom to
--   introduce sharing. As a result mutable vectors produced by
--   <tt>unsafeThaw</tt> may or may not share the same underlying buffer.
--   For example:
--   
--   <pre>
--   foo = do
--     let vec = V.generate 10 id
--     mvec &lt;- V.unsafeThaw vec
--     do_something mvec
--   </pre>
--   
--   Here GHC could lift <tt>vec</tt> outside of foo which means that all
--   calls to <tt>do_something</tt> will use same buffer with possibly
--   disastrous results. Whether such aliasing happens or not depends on
--   the program in question, optimization levels, and GHC flags.
--   
--   All in all, attempts to modify a vector produced by
--   <tt>unsafeThaw</tt> fall out of domain of software engineering and
--   into realm of black magic, dark rituals, and unspeakable horrors. The
--   only advice that could be given is: "Don't attempt to mutate a vector
--   produced by <tt>unsafeThaw</tt> unless you know how to prevent GHC
--   from aliasing buffers accidentally. We don't."
unsafeThaw :: (Storable a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length. This is not checked.
unsafeCopy :: (Storable a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()

-- | <i>O(1)</i> Create a vector from a <a>ForeignPtr</a> with an offset
--   and a length.
--   
--   The data may not be modified through the pointer afterwards.
--   
--   If your offset is 0 it is more efficient to use
--   <a>unsafeFromForeignPtr0</a>.
unsafeFromForeignPtr :: Storable a => ForeignPtr a -> Int -> Int -> Vector a

-- | <i>O(1)</i> Create a vector from a <a>ForeignPtr</a> and a length.
--   
--   It is assumed the pointer points directly to the data (no offset). Use
--   <a>unsafeFromForeignPtr</a> if you need to specify an offset.
--   
--   The data may not be modified through the pointer afterwards.
unsafeFromForeignPtr0 :: ForeignPtr a -> Int -> Vector a

-- | <i>O(1)</i> Yield the underlying <a>ForeignPtr</a> together with the
--   offset to the data and its length. The data may not be modified
--   through the <a>ForeignPtr</a>.
unsafeToForeignPtr :: Vector a -> (ForeignPtr a, Int, Int)

-- | <i>O(1)</i> Yield the underlying <a>ForeignPtr</a> together with its
--   length.
--   
--   You can assume that the pointer points directly to the data (no
--   offset).
--   
--   The data may not be modified through the <a>ForeignPtr</a>.
unsafeToForeignPtr0 :: Vector a -> (ForeignPtr a, Int)

-- | Lifted version of <a>unsafeWith</a>
unsafeWith :: (MonadUnliftIO m, Storable a) => Vector a -> (Ptr a -> m b) -> m b


-- | Unboxed <tt>Vector</tt>. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Unboxed as VU
--   </pre>
--   
--   This module does not export any partial or unsafe functions. For
--   those, see <a>RIO.Vector.Unboxed.Partial</a> and
--   <a>RIO.Vector.Unboxed.Unsafe</a>
module RIO.Vector.Unboxed
data family Vector a
data family MVector s a
class (Vector Vector a, MVector MVector a) => Unbox a

-- | <i>O(1)</i> Yield the length of the vector.
length :: Unbox a => Vector a -> Int

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Unbox a => Vector a -> Bool

-- | O(1) Safe indexing.
(!?) :: Unbox a => Vector a -> Int -> Maybe a

-- | <i>O(1)</i> Yield a slice of the vector without copying it. The vector
--   must contain at least <tt>i+n</tt> elements.
slice :: Unbox a => Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield at the first <tt>n</tt> elements without copying.
--   The vector may contain less than <tt>n</tt> elements, in which case it
--   is returned unchanged.
take :: Unbox a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector may contain less than <tt>n</tt> elements, in
--   which case an empty vector is returned.
drop :: Unbox a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements paired with the
--   remainder, without copying.
--   
--   Note that <tt><a>splitAt</a> n v</tt> is equivalent to
--   <tt>(<a>take</a> n v, <a>drop</a> n v)</tt>, but slightly more
--   efficient.
splitAt :: Unbox a => Int -> Vector a -> (Vector a, Vector a)

-- | <i>O(1)</i> The empty vector.
empty :: Unbox a => Vector a

-- | <i>O(1)</i> A vector with exactly one element.
singleton :: Unbox a => a -> Vector a

-- | <i>O(n)</i> A vector of the given length with the same value in each
--   position.
replicate :: Unbox a => Int -> a -> Vector a

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   function to each index.
generate :: Unbox a => Int -> (Int -> a) -> Vector a

-- | <i>O(n)</i> Apply the function &lt;math&gt; times to an initial value,
--   producing a vector of length &lt;math&gt;. The 0th element will
--   contain the initial value, which is why there is one less function
--   application than the number of elements in the produced vector.
--   
--   &lt;math&gt;
--   
--   <h3><b>Examples</b></h3>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.iterateN 0 undefined undefined :: VU.Vector Int
--   []
--   
--   &gt;&gt;&gt; VU.iterateN 3 (\(i, c) -&gt; (pred i, succ c)) (0 :: Int, 'a')
--   [(0,'a'),(-1,'b'),(-2,'c')]
--   </pre>
iterateN :: Unbox a => Int -> (a -> a) -> a -> Vector a

-- | <i>O(n)</i> Execute the monadic action the given number of times and
--   store the results in a vector.
replicateM :: (Monad m, Unbox a) => Int -> m a -> m (Vector a)

-- | <i>O(n)</i> Construct a vector of the given length by applying the
--   monadic action to each index.
generateM :: (Monad m, Unbox a) => Int -> (Int -> m a) -> m (Vector a)

-- | <i>O(n)</i> Apply the monadic function &lt;math&gt; times to an
--   initial value, producing a vector of length &lt;math&gt;. The 0th
--   element will contain the initial value, which is why there is one less
--   function application than the number of elements in the produced
--   vector.
--   
--   For a non-monadic version, see <a>iterateN</a>.
iterateNM :: (Monad m, Unbox a) => Int -> (a -> m a) -> a -> m (Vector a)

-- | Execute the monadic action and freeze the resulting vector.
--   
--   <pre>
--   create (do { v &lt;- new 2; write v 0 'a'; write v 1 'b'; return v }) = &lt;<tt>a</tt>,<tt>b</tt>&gt;
--   </pre>
create :: Unbox a => (forall s. () => ST s (MVector s a)) -> Vector a

-- | Execute the monadic action and freeze the resulting vectors.
createT :: (Traversable f, Unbox a) => (forall s. () => ST s (f (MVector s a))) -> f (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the generator
--   function to a seed. The generator function yields <tt>Just</tt> the
--   next element and the new seed or <tt>Nothing</tt> if there are no more
--   elements.
--   
--   <pre>
--   unfoldr (\n -&gt; if n == 0 then Nothing else Just (n,n-1)) 10
--    = &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldr :: Unbox a => (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector with at most <tt>n</tt> elements by
--   repeatedly applying the generator function to a seed. The generator
--   function yields <tt>Just</tt> the next element and the new seed or
--   <tt>Nothing</tt> if there are no more elements.
--   
--   <pre>
--   unfoldrN 3 (\n -&gt; Just (n,n-1)) 10 = &lt;10,9,8&gt;
--   </pre>
unfoldrN :: Unbox a => Int -> (b -> Maybe (a, b)) -> b -> Vector a

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrM :: (Monad m, Unbox a) => (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector by repeatedly applying the monadic
--   generator function to a seed. The generator function yields
--   <tt>Just</tt> the next element and the new seed or <tt>Nothing</tt> if
--   there are no more elements.
unfoldrNM :: (Monad m, Unbox a) => Int -> (b -> m (Maybe (a, b))) -> b -> m (Vector a)

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements by repeatedly
--   applying the generator function to the already constructed part of the
--   vector.
--   
--   <pre>
--   constructN 3 f = let a = f &lt;&gt; ; b = f &lt;a&gt; ; c = f &lt;a,b&gt; in &lt;a,b,c&gt;
--   </pre>
constructN :: Unbox a => Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Construct a vector with <tt>n</tt> elements from right to
--   left by repeatedly applying the generator function to the already
--   constructed part of the vector.
--   
--   <pre>
--   constructrN 3 f = let a = f &lt;&gt; ; b = f&lt;a&gt; ; c = f &lt;b,a&gt; in &lt;c,b,a&gt;
--   </pre>
constructrN :: Unbox a => Int -> (Vector a -> a) -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+1</tt> etc. This operation is usually more efficient
--   than <a>enumFromTo</a>.
--   
--   <pre>
--   enumFromN 5 3 = &lt;5,6,7&gt;
--   </pre>
enumFromN :: (Unbox a, Num a) => a -> Int -> Vector a

-- | <i>O(n)</i> Yield a vector of the given length, containing the values
--   <tt>x</tt>, <tt>x+y</tt>, <tt>x+y+y</tt> etc. This operations is
--   usually more efficient than <a>enumFromThenTo</a>.
--   
--   <pre>
--   enumFromStepN 1 2 5 = &lt;1,3,5,7,9&gt;
--   </pre>
enumFromStepN :: (Unbox a, Num a) => a -> a -> Int -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromN</a> instead.
enumFromTo :: (Unbox a, Enum a) => a -> a -> Vector a

-- | <i>O(n)</i> Enumerate values from <tt>x</tt> to <tt>y</tt> with a
--   specific step <tt>z</tt>.
--   
--   <i>WARNING:</i> This operation can be very inefficient. If possible,
--   use <a>enumFromStepN</a> instead.
enumFromThenTo :: (Unbox a, Enum a) => a -> a -> a -> Vector a

-- | <i>O(n)</i> Prepend an element.
cons :: Unbox a => a -> Vector a -> Vector a

-- | <i>O(n)</i> Append an element.
snoc :: Unbox a => Vector a -> a -> Vector a

-- | <i>O(m+n)</i> Concatenate two vectors.
(++) :: Unbox a => Vector a -> Vector a -> Vector a
infixr 5 ++

-- | <i>O(n)</i> Concatenate all vectors in the list.
concat :: Unbox a => [Vector a] -> Vector a

-- | <i>O(n)</i> Yield the argument, but force it not to retain any extra
--   memory, possibly by copying it.
--   
--   This is especially useful when dealing with slices. For example:
--   
--   <pre>
--   force (slice 0 2 &lt;huge vector&gt;)
--   </pre>
--   
--   Here, the slice retains a reference to the huge vector. Forcing it
--   creates a copy of just the elements that belong to the slice and
--   allows the huge vector to be garbage collected.
force :: Unbox a => Vector a -> Vector a

-- | <i>O(n)</i> Reverse a vector.
reverse :: Unbox a => Vector a -> Vector a

-- | Apply a destructive operation to a vector. The operation may be
--   performed in place if it is safe to do so and will modify a copy of
--   the vector otherwise (see <a>New</a> for details).
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed.Mutable as MVU
--   
--   &gt;&gt;&gt; VU.modify (\v -&gt; MVU.write v 0 'x') $ VU.replicate 4 'a'
--   "xaaa"
--   </pre>
modify :: Unbox a => (forall s. () => MVector s a -> ST s ()) -> Vector a -> Vector a

-- | <i>O(n)</i> Pair each element in a vector with its index.
indexed :: Unbox a => Vector a -> Vector (Int, a)

-- | <i>O(n)</i> Map a function over a vector.
map :: (Unbox a, Unbox b) => (a -> b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply a function to every element of a vector and its
--   index.
imap :: (Unbox a, Unbox b) => (Int -> a -> b) -> Vector a -> Vector b

-- | Map a function over a vector and concatenate the results.
concatMap :: (Unbox a, Unbox b) => (a -> Vector b) -> Vector a -> Vector b

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results.
mapM :: (Monad m, Unbox a, Unbox b) => (a -> m b) -> Vector a -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, yielding a vector of results.
imapM :: (Monad m, Unbox a, Unbox b) => (Int -> a -> m b) -> Vector a -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results.
mapM_ :: (Monad m, Unbox a) => (a -> m b) -> Vector a -> m ()

-- | <i>O(n)</i> Apply the monadic action to every element of a vector and
--   its index, ignoring the results.
imapM_ :: (Monad m, Unbox a) => (Int -> a -> m b) -> Vector a -> m ()

-- | <i>O(n)</i> Apply the monadic action to all elements of the vector,
--   yielding a vector of results. Equivalent to <tt>flip <a>mapM</a></tt>.
forM :: (Monad m, Unbox a, Unbox b) => Vector a -> (a -> m b) -> m (Vector b)

-- | <i>O(n)</i> Apply the monadic action to all elements of a vector and
--   ignore the results. Equivalent to <tt>flip <a>mapM_</a></tt>.
forM_ :: (Monad m, Unbox a) => Vector a -> (a -> m b) -> m ()

-- | <i>O(min(m,n))</i> Zip two vectors with the given function.
zipWith :: (Unbox a, Unbox b, Unbox c) => (a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors with the given function.
zipWith3 :: (Unbox a, Unbox b, Unbox c, Unbox d) => (a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
zipWith4 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e) => (a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
zipWith5 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f) => (a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
zipWith6 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f, Unbox g) => (a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(min(m,n))</i> Zip two vectors with a function that also takes the
--   elements' indices.
izipWith :: (Unbox a, Unbox b, Unbox c) => (Int -> a -> b -> c) -> Vector a -> Vector b -> Vector c

-- | Zip three vectors and their indices with the given function.
izipWith3 :: (Unbox a, Unbox b, Unbox c, Unbox d) => (Int -> a -> b -> c -> d) -> Vector a -> Vector b -> Vector c -> Vector d
izipWith4 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e) => (Int -> a -> b -> c -> d -> e) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e
izipWith5 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f) => (Int -> a -> b -> c -> d -> e -> f) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f
izipWith6 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f, Unbox g) => (Int -> a -> b -> c -> d -> e -> f -> g) -> Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector g

-- | <i>O(1)</i> Zip 2 vectors.
zip :: (Unbox a, Unbox b) => Vector a -> Vector b -> Vector (a, b)

-- | <i>O(1)</i> Zip 3 vectors.
zip3 :: (Unbox a, Unbox b, Unbox c) => Vector a -> Vector b -> Vector c -> Vector (a, b, c)

-- | <i>O(1)</i> Zip 4 vectors.
zip4 :: (Unbox a, Unbox b, Unbox c, Unbox d) => Vector a -> Vector b -> Vector c -> Vector d -> Vector (a, b, c, d)

-- | <i>O(1)</i> Zip 5 vectors.
zip5 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e) => Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector (a, b, c, d, e)

-- | <i>O(1)</i> Zip 6 vectors.
zip6 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f) => Vector a -> Vector b -> Vector c -> Vector d -> Vector e -> Vector f -> Vector (a, b, c, d, e, f)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   yield a vector of results.
zipWithM :: (Monad m, Unbox a, Unbox b, Unbox c) => (a -> b -> m c) -> Vector a -> Vector b -> m (Vector c)

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and yield a vector of results.
izipWithM :: (Monad m, Unbox a, Unbox b, Unbox c) => (Int -> a -> b -> m c) -> Vector a -> Vector b -> m (Vector c)

-- | <i>O(min(m,n))</i> Zip the two vectors with the monadic action and
--   ignore the results.
zipWithM_ :: (Monad m, Unbox a, Unbox b) => (a -> b -> m c) -> Vector a -> Vector b -> m ()

-- | <i>O(min(m,n))</i> Zip the two vectors with a monadic action that also
--   takes the element index and ignore the results.
izipWithM_ :: (Monad m, Unbox a, Unbox b) => (Int -> a -> b -> m c) -> Vector a -> Vector b -> m ()

-- | <i>O(1)</i> Unzip 2 vectors.
unzip :: (Unbox a, Unbox b) => Vector (a, b) -> (Vector a, Vector b)

-- | <i>O(1)</i> Unzip 3 vectors.
unzip3 :: (Unbox a, Unbox b, Unbox c) => Vector (a, b, c) -> (Vector a, Vector b, Vector c)

-- | <i>O(1)</i> Unzip 4 vectors.
unzip4 :: (Unbox a, Unbox b, Unbox c, Unbox d) => Vector (a, b, c, d) -> (Vector a, Vector b, Vector c, Vector d)

-- | <i>O(1)</i> Unzip 5 vectors.
unzip5 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e) => Vector (a, b, c, d, e) -> (Vector a, Vector b, Vector c, Vector d, Vector e)

-- | <i>O(1)</i> Unzip 6 vectors.
unzip6 :: (Unbox a, Unbox b, Unbox c, Unbox d, Unbox e, Unbox f) => Vector (a, b, c, d, e, f) -> (Vector a, Vector b, Vector c, Vector d, Vector e, Vector f)

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate.
filter :: Unbox a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop all elements that do not satisfy the predicate which
--   is applied to the values and their indices.
ifilter :: Unbox a => (Int -> a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop repeated adjacent elements. The first element in each
--   group is returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.uniq $ VU.fromList [1,3,3,200,3 :: Int]
--   [1,3,200,3]
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; VU.uniq $ VU.fromList [ Arg 1 'a', Arg 1 'b', Arg (1 :: Int) 'c']
--   [Arg 1 'a']
--   </pre>
uniq :: (Unbox a, Eq a) => Vector a -> Vector a

-- | <i>O(n)</i> Map the values and collect the <tt>Just</tt> results.
mapMaybe :: (Unbox a, Unbox b) => (a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Map the indices/values and collect the <tt>Just</tt>
--   results.
imapMaybe :: (Unbox a, Unbox b) => (Int -> a -> Maybe b) -> Vector a -> Vector b

-- | <i>O(n)</i> Drop all elements that do not satisfy the monadic
--   predicate.
filterM :: (Monad m, Unbox a) => (a -> m Bool) -> Vector a -> m (Vector a)

-- | <i>O(n)</i> Yield the longest prefix of elements satisfying the
--   predicate. The current implementation is not copy-free, unless the
--   result vector is fused away.
takeWhile :: Unbox a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Drop the longest prefix of elements that satisfy the
--   predicate without copying.
dropWhile :: Unbox a => (a -> Bool) -> Vector a -> Vector a

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The relative order of the elements is preserved at the
--   cost of a sometimes reduced performance compared to
--   <a>unstablePartition</a>.
partition :: Unbox a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector in two parts, the first one containing
--   those elements that satisfy the predicate and the second one those
--   that don't. The order of the elements is not preserved, but the
--   operation is often faster than <a>partition</a>.
unstablePartition :: Unbox a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: Unbox a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Split the vector into the longest prefix of elements that
--   do not satisfy the predicate and the rest without copying.
break :: Unbox a => (a -> Bool) -> Vector a -> (Vector a, Vector a)

-- | <i>O(n)</i> Check if the vector contains an element.
elem :: (Unbox a, Eq a) => a -> Vector a -> Bool
infix 4 `elem`

-- | <i>O(n)</i> Check if the vector does not contain an element (inverse
--   of <a>elem</a>).
notElem :: (Unbox a, Eq a) => a -> Vector a -> Bool
infix 4 `notElem`

-- | <i>O(n)</i> Yield <tt>Just</tt> the first element matching the
--   predicate or <tt>Nothing</tt> if no such element exists.
find :: Unbox a => (a -> Bool) -> Vector a -> Maybe a

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first element
--   matching the predicate or <tt>Nothing</tt> if no such element exists.
findIndex :: Unbox a => (a -> Bool) -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of elements satisfying the predicate in
--   ascending order.
findIndices :: Unbox a => (a -> Bool) -> Vector a -> Vector Int

-- | <i>O(n)</i> Yield <tt>Just</tt> the index of the first occurrence of
--   the given element or <tt>Nothing</tt> if the vector does not contain
--   the element. This is a specialised version of <a>findIndex</a>.
elemIndex :: (Unbox a, Eq a) => a -> Vector a -> Maybe Int

-- | <i>O(n)</i> Yield the indices of all occurrences of the given element
--   in ascending order. This is a specialised version of
--   <a>findIndices</a>.
elemIndices :: (Unbox a, Eq a) => a -> Vector a -> Vector Int

-- | <i>O(n)</i> Left fold.
foldl :: Unbox b => (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator.
foldl' :: Unbox b => (a -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold.
foldr :: Unbox a => (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with a strict accumulator.
foldr' :: Unbox a => (a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Left fold using a function applied to each element and its
--   index.
ifoldl :: Unbox b => (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Left fold with strict accumulator using a function applied
--   to each element and its index.
ifoldl' :: Unbox b => (a -> Int -> b -> a) -> a -> Vector b -> a

-- | <i>O(n)</i> Right fold using a function applied to each element and
--   its index.
ifoldr :: Unbox a => (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Right fold with strict accumulator using a function
--   applied to each element and its index.
ifoldr' :: Unbox a => (Int -> a -> b -> b) -> b -> Vector a -> b

-- | <i>O(n)</i> Check if all elements satisfy the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.all even $ VU.fromList [2, 4, 12 :: Int]
--   True
--   
--   &gt;&gt;&gt; VU.all even $ VU.fromList [2, 4, 13 :: Int]
--   False
--   
--   &gt;&gt;&gt; VU.all even (VU.empty :: VU.Vector Int)
--   True
--   </pre>
all :: Unbox a => (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if any element satisfies the predicate.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.any even $ VU.fromList [1, 3, 7 :: Int]
--   False
--   
--   &gt;&gt;&gt; VU.any even $ VU.fromList [3, 2, 13 :: Int]
--   True
--   
--   &gt;&gt;&gt; VU.any even (VU.empty :: VU.Vector Int)
--   False
--   </pre>
any :: Unbox a => (a -> Bool) -> Vector a -> Bool

-- | <i>O(n)</i> Check if all elements are <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.and $ VU.fromList [True, False]
--   False
--   
--   &gt;&gt;&gt; VU.and VU.empty
--   True
--   </pre>
and :: Vector Bool -> Bool

-- | <i>O(n)</i> Check if any element is <tt>True</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.or $ VU.fromList [True, False]
--   True
--   
--   &gt;&gt;&gt; VU.or VU.empty
--   False
--   </pre>
or :: Vector Bool -> Bool

-- | <i>O(n)</i> Compute the sum of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.sum $ VU.fromList [300,20,1 :: Int]
--   321
--   
--   &gt;&gt;&gt; VU.sum (VU.empty :: VU.Vector Int)
--   0
--   </pre>
sum :: (Unbox a, Num a) => Vector a -> a

-- | <i>O(n)</i> Compute the product of the elements.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.product $ VU.fromList [1,2,3,4 :: Int]
--   24
--   
--   &gt;&gt;&gt; VU.product (VU.empty :: VU.Vector Int)
--   1
--   </pre>
product :: (Unbox a, Num a) => Vector a -> a

-- | <i>O(n)</i> Monadic fold.
foldM :: (Monad m, Unbox b) => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold using a function applied to each element and
--   its index.
ifoldM :: (Monad m, Unbox b) => (a -> Int -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator.
foldM' :: (Monad m, Unbox b) => (a -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold with strict accumulator using a function
--   applied to each element and its index.
ifoldM' :: (Monad m, Unbox b) => (a -> Int -> b -> m a) -> a -> Vector b -> m a

-- | <i>O(n)</i> Monadic fold that discards the result.
foldM_ :: (Monad m, Unbox b) => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold that discards the result using a function
--   applied to each element and its index.
ifoldM_ :: (Monad m, Unbox b) => (a -> Int -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result.
foldM'_ :: (Monad m, Unbox b) => (a -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Monadic fold with strict accumulator that discards the
--   result using a function applied to each element and its index.
ifoldM'_ :: (Monad m, Unbox b) => (a -> Int -> b -> m a) -> a -> Vector b -> m ()

-- | <i>O(n)</i> Left-to-right prescan.
--   
--   <pre>
--   prescanl f z = <a>init</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector as VU
--   
--   &gt;&gt;&gt; VU.prescanl (+) 0 (VU.fromList [1,2,3,4 :: Int])
--   [0,1,3,6]
--   </pre>
prescanl :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right prescan with strict accumulator.
prescanl' :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan.
--   
--   <pre>
--   postscanl f z = <a>tail</a> . <a>scanl</a> f z
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.postscanl (+) 0 (VU.fromList [1,2,3,4 :: Int])
--   [1,3,6,10]
--   </pre>
postscanl :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right postscan with strict accumulator.
postscanl' :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan.
--   
--   <pre>
--   scanl f z &lt;x1,...,xn&gt; = &lt;y1,...,y(n+1)&gt;
--     where y1 = z
--           yi = f y(i-1) x(i-1)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.scanl (+) 0 (VU.fromList [1,2,3,4 :: Int])
--   [0,1,3,6,10]
--   </pre>
scanl :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Left-to-right scan with strict accumulator.
scanl' :: (Unbox a, Unbox b) => (a -> b -> a) -> a -> Vector b -> Vector a

-- | <i>O(n)</i> Right-to-left prescan.
--   
--   <pre>
--   prescanr f z = <a>reverse</a> . <a>prescanl</a> (flip f) z . <a>reverse</a>
--   </pre>
prescanr :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left prescan with strict accumulator.
prescanr' :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan.
postscanr :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left postscan with strict accumulator.
postscanr' :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan.
scanr :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Right-to-left scan with strict accumulator.
scanr' :: (Unbox a, Unbox b) => (a -> b -> b) -> b -> Vector a -> Vector b

-- | <i>O(n)</i> Convert a vector to a list.
toList :: Unbox a => Vector a -> [a]

-- | <i>O(n)</i> Convert a list to a vector.
fromList :: Unbox a => [a] -> Vector a

-- | <i>O(n)</i> Convert the first <tt>n</tt> elements of a list to a
--   vector. It's expected that the supplied list will be exactly
--   <tt>n</tt> elements long. As an optimization, this function allocates
--   a buffer for <tt>n</tt> elements, which could be used for DoS-attacks
--   by exhausting the memory if an attacker controls that parameter.
--   
--   <pre>
--   fromListN n xs = <a>fromList</a> (<a>take</a> n xs)
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.fromListN 3 [1,2,3,4,5 :: Int]
--   [1,2,3]
--   
--   &gt;&gt;&gt; VU.fromListN 3 [1 :: Int]
--   [1]
--   </pre>
fromListN :: Unbox a => Int -> [a] -> Vector a

-- | <i>O(n)</i> Convert between different vector types.
convert :: (Vector v a, Vector w a) => v a -> w a

-- | <i>O(n)</i> Yield an immutable copy of the mutable vector.
freeze :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(n)</i> Yield a mutable copy of an immutable vector.
thaw :: (Unbox a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length.
copy :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()


-- | Unboxed <tt>Vector</tt> partial functions. Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Unboxed.Partial as VU'
--   </pre>
module RIO.Vector.Unboxed.Partial

-- | O(1) Indexing.
(!) :: Unbox a => Vector a -> Int -> a

-- | <i>O(1)</i> First element.
head :: Unbox a => Vector a -> a

-- | <i>O(1)</i> Last element.
last :: Unbox a => Vector a -> a

-- | <i>O(1)</i> Indexing in a monad.
--   
--   The monad allows operations to be strict in the vector when necessary.
--   Suppose vector copying is implemented like this:
--   
--   <pre>
--   copy mv v = ... write mv i (v ! i) ...
--   </pre>
--   
--   For lazy vectors, <tt>v ! i</tt> would not be evaluated which means
--   that <tt>mv</tt> would unnecessarily retain a reference to <tt>v</tt>
--   in each element written.
--   
--   With <a>indexM</a>, copying can be implemented like this instead:
--   
--   <pre>
--   copy mv v = ... do
--                     x &lt;- indexM v i
--                     write mv i x
--   </pre>
--   
--   Here, no references to <tt>v</tt> are retained because indexing (but
--   <i>not</i> the element) is evaluated eagerly.
indexM :: (Unbox a, Monad m) => Vector a -> Int -> m a

-- | <i>O(1)</i> First element of a vector in a monad. See <a>indexM</a>
--   for an explanation of why this is useful.
headM :: (Unbox a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Last element of a vector in a monad. See <a>indexM</a> for
--   an explanation of why this is useful.
lastM :: (Unbox a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty.
init :: Unbox a => Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty.
tail :: Unbox a => Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the list of
--   idnex/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   &lt;5,9,2,7&gt; // [(2,1),(0,3),(2,8)] = &lt;3,9,8,7&gt;
--   </pre>
(//) :: Unbox a => Vector a -> [(Int, a)] -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,a)</tt> from the vector of
--   index/value pairs, replace the vector element at position <tt>i</tt>
--   by <tt>a</tt>.
--   
--   <pre>
--   update &lt;5,9,2,7&gt; &lt;(2,1),(0,3),(2,8)&gt; = &lt;3,9,8,7&gt;
--   </pre>
update :: Unbox a => Vector a -> Vector (Int, a) -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>a</tt> from the value vector, replace
--   the element of the initial vector at position <tt>i</tt> by
--   <tt>a</tt>.
--   
--   <pre>
--   update_ &lt;5,9,2,7&gt;  &lt;2,0,2&gt; &lt;1,3,8&gt; = &lt;3,9,8,7&gt;
--   </pre>
--   
--   The function <a>update</a> provides the same functionality and is
--   usually more convenient.
--   
--   <pre>
--   update_ xs is ys = <a>update</a> xs (<a>zip</a> is ys)
--   </pre>
update_ :: Unbox a => Vector a -> Vector Int -> Vector a -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the list, replace the
--   vector element <tt>a</tt> at position <tt>i</tt> by <tt>f a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.accum (+) (VU.fromList [1000,2000,3000 :: Int]) [(2,4),(1,6),(0,3),(1,10)]
--   [1003,2016,3004]
--   </pre>
accum :: Unbox a => (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | <i>O(m+n)</i> For each pair <tt>(i,b)</tt> from the vector of pairs,
--   replace the vector element <tt>a</tt> at position <tt>i</tt> by <tt>f
--   a b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.accumulate (+) (VU.fromList [1000,2000,3000 :: Int]) (VU.fromList [(2,4),(1,6),(0,3),(1,10)])
--   [1003,2016,3004]
--   </pre>
accumulate :: (Unbox a, Unbox b) => (a -> b -> a) -> Vector a -> Vector (Int, b) -> Vector a

-- | <i>O(m+min(n1,n2))</i> For each index <tt>i</tt> from the index vector
--   and the corresponding value <tt>b</tt> from the the value vector,
--   replace the element of the initial vector at position <tt>i</tt> by
--   <tt>f a b</tt>.
--   
--   <pre>
--   accumulate_ (+) &lt;5,9,2&gt; &lt;2,1,0,1&gt; &lt;4,6,3,7&gt; = &lt;5+3, 9+6+7, 2+4&gt;
--   </pre>
--   
--   The function <a>accumulate</a> provides the same functionality and is
--   usually more convenient.
--   
--   <pre>
--   accumulate_ f as is bs = <a>accumulate</a> f as (<a>zip</a> is bs)
--   </pre>
accumulate_ :: (Unbox a, Unbox b) => (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | <i>O(n)</i> Yield the vector obtained by replacing each element
--   <tt>i</tt> of the index vector by <tt>xs<a>!</a>i</tt>. This is
--   equivalent to <tt><a>map</a> (xs<a>!</a>) is</tt>, but is often much
--   more efficient.
--   
--   <pre>
--   backpermute &lt;a,b,c,d&gt; &lt;0,3,2,3,1,0&gt; = &lt;a,d,c,d,b,a&gt;
--   </pre>
backpermute :: Unbox a => Vector a -> Vector Int -> Vector a

-- | <i>O(n)</i> Left fold on non-empty vectors.
foldl1 :: Unbox a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Left fold on non-empty vectors with strict accumulator.
foldl1' :: Unbox a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors.
foldr1 :: Unbox a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Right fold on non-empty vectors with strict accumulator.
foldr1' :: Unbox a => (a -> a -> a) -> Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.maximum $ VU.fromList [2, 1 :: Int]
--   2
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; VU.maximum $ VU.fromList [Arg 1 'a', Arg (2 :: Int) 'b']
--   Arg 2 'b'
--   
--   &gt;&gt;&gt; VU.maximum $ VU.fromList [Arg 1 'a', Arg (1 :: Int) 'b']
--   Arg 1 'a'
--   </pre>
maximum :: (Unbox a, Ord a) => Vector a -> a

-- | <i>O(n)</i> Yield the maximum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins. This behavior is different from
--   <a>maximumBy</a> which returns the last tie.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.maximumBy (comparing fst) $ VU.fromList [(2,'a'), (1 :: Int,'b')]
--   (2,'a')
--   
--   &gt;&gt;&gt; VU.maximumBy (comparing fst) $ VU.fromList [(1,'a'), (1 :: Int,'b')]
--   (1,'a')
--   </pre>
maximumBy :: Unbox a => (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector. The vector may
--   not be empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.minimum $ VU.fromList [2, 1 :: Int]
--   1
--   
--   &gt;&gt;&gt; import Data.Semigroup
--   
--   &gt;&gt;&gt; VU.minimum $ VU.fromList [Arg 2 'a', Arg (1 :: Int) 'b']
--   Arg 1 'b'
--   
--   &gt;&gt;&gt; VU.minimum $ VU.fromList [Arg 1 'a', Arg (1 :: Int) 'b']
--   Arg 1 'a'
--   </pre>
minimum :: (Unbox a, Ord a) => Vector a -> a

-- | <i>O(n)</i> Yield the minimum element of the vector according to the
--   given comparison function. The vector may not be empty.
--   
--   <i>O(n)</i> Yield the minimum element of the vector according to the
--   given comparison function. The vector may not be empty. In case of a
--   tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.minimumBy (comparing fst) $ VU.fromList [(2,'a'), (1 :: Int,'b')]
--   (1,'b')
--   
--   &gt;&gt;&gt; VU.minimumBy (comparing fst) $ VU.fromList [(1,'a'), (1 :: Int,'b')]
--   (1,'a')
--   </pre>
minimumBy :: Unbox a => (a -> a -> Ordering) -> Vector a -> a

-- | <i>O(n)</i> Yield the index of the minimum element of the vector. The
--   vector may not be empty.
minIndex :: (Unbox a, Ord a) => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the minimum element of the vector
--   according to the given comparison function. The vector may not be
--   empty.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.minIndexBy (comparing fst) $ VU.fromList [(2,'a'), (1,'b')]
--   1
--   
--   &gt;&gt;&gt; VU.minIndexBy (comparing fst) $ VU.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
minIndexBy :: Unbox a => (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector. The
--   vector may not be empty.
maxIndex :: (Unbox a, Ord a) => Vector a -> Int

-- | <i>O(n)</i> Yield the index of the maximum element of the vector
--   according to the given comparison function. The vector may not be
--   empty. In case of a tie, the first occurrence wins.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Ord
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.maxIndexBy (comparing fst) $ VU.fromList [(2,'a'), (1,'b')]
--   0
--   
--   &gt;&gt;&gt; VU.maxIndexBy (comparing fst) $ VU.fromList [(1,'a'), (1,'b')]
--   0
--   </pre>
maxIndexBy :: Unbox a => (a -> a -> Ordering) -> Vector a -> Int

-- | <i>O(n)</i> Monadic fold over non-empty vectors.
fold1M :: (Monad m, Unbox a) => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator.
fold1M' :: (Monad m, Unbox a) => (a -> a -> m a) -> Vector a -> m a

-- | <i>O(n)</i> Monadic fold over non-empty vectors that discards the
--   result.
fold1M_ :: (Monad m, Unbox a) => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Monadic fold over non-empty vectors with strict
--   accumulator that discards the result.
fold1M'_ :: (Monad m, Unbox a) => (a -> a -> m a) -> Vector a -> m ()

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector.
--   
--   <pre>
--   scanl f &lt;x1,...,xn&gt; = &lt;y1,...,yn&gt;
--     where y1 = x1
--           yi = f y(i-1) xi
--   </pre>
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.scanl1 min $ VU.fromListN 5 [4,2,4,1,3 :: Int]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; VU.scanl1 max $ VU.fromListN 5 [1,3,2,5,4 :: Int]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; VU.scanl1 min (VU.empty :: VU.Vector Int)
--   []
--   </pre>
scanl1 :: Unbox a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Initial-value free left-to-right scan over a vector with a
--   strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.scanl1' min $ VU.fromListN 5 [4,2,4,1,3 :: Int]
--   [4,2,2,1,1]
--   
--   &gt;&gt;&gt; VU.scanl1' max $ VU.fromListN 5 [1,3,2,5,4 :: Int]
--   [1,3,3,5,5]
--   
--   &gt;&gt;&gt; VU.scanl1' min (VU.empty :: VU.Vector Int)
--   []
--   </pre>
scanl1' :: Unbox a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.scanr1 min $ VU.fromListN 5 [3,1,4,2,4 :: Int]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; VU.scanr1 max $ VU.fromListN 5 [4,5,2,3,1 :: Int]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; VU.scanr1 min (VU.empty :: VU.Vector Int)
--   []
--   </pre>
scanr1 :: Unbox a => (a -> a -> a) -> Vector a -> Vector a

-- | <i>O(n)</i> Right-to-left, initial-value free scan over a vector with
--   a strict accumulator.
--   
--   Note: Since 0.13, application of this to an empty vector no longer
--   results in an error; instead it produces an empty vector.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as VU
--   
--   &gt;&gt;&gt; VU.scanr1' min $ VU.fromListN 5 [3,1,4,2,4 :: Int]
--   [1,1,2,2,4]
--   
--   &gt;&gt;&gt; VU.scanr1' max $ VU.fromListN 5 [4,5,2,3,1 :: Int]
--   [5,5,3,3,1]
--   
--   &gt;&gt;&gt; VU.scanr1' min (VU.empty :: VU.Vector Int)
--   []
--   </pre>
scanr1' :: Unbox a => (a -> a -> a) -> Vector a -> Vector a


-- | Unoxed <tt>Vector</tt> unsafe functions. These perform no bounds
--   checking, and may cause segmentation faults etc.! Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Unoxed.Unsafe as VU'
--   </pre>
module RIO.Vector.Unboxed.Unsafe

-- | <i>O(1)</i> Unsafe indexing without bounds checking.
unsafeIndex :: Unbox a => Vector a -> Int -> a

-- | <i>O(1)</i> First element, without checking if the vector is empty.
unsafeHead :: Unbox a => Vector a -> a

-- | <i>O(1)</i> Last element, without checking if the vector is empty.
unsafeLast :: Unbox a => Vector a -> a

-- | <i>O(1)</i> Indexing in a monad, without bounds checks. See
--   <a>indexM</a> for an explanation of why this is useful.
unsafeIndexM :: (Unbox a, Monad m) => Vector a -> Int -> m a

-- | <i>O(1)</i> First element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeHeadM :: (Unbox a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Last element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeLastM :: (Unbox a, Monad m) => Vector a -> m a

-- | <i>O(1)</i> Yield a slice of the vector without copying. The vector
--   must contain at least <tt>i+n</tt> elements, but this is not checked.
unsafeSlice :: Unbox a => Int -> Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty, but this is not checked.
unsafeInit :: Unbox a => Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty, but this is not checked.
unsafeTail :: Unbox a => Vector a -> Vector a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements without copying. The
--   vector must contain at least <tt>n</tt> elements, but this is not
--   checked.
unsafeTake :: Unbox a => Int -> Vector a -> Vector a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector must contain at least <tt>n</tt> elements, but
--   this is not checked.
unsafeDrop :: Unbox a => Int -> Vector a -> Vector a

-- | Same as (<a>//</a>), but without bounds checking.
unsafeUpd :: Unbox a => Vector a -> [(Int, a)] -> Vector a

-- | Same as <a>update</a>, but without bounds checking.
unsafeUpdate :: Unbox a => Vector a -> Vector (Int, a) -> Vector a

-- | Same as <a>update_</a>, but without bounds checking.
unsafeUpdate_ :: Unbox a => Vector a -> Vector Int -> Vector a -> Vector a

-- | Same as <a>accum</a>, but without bounds checking.
unsafeAccum :: Unbox a => (a -> b -> a) -> Vector a -> [(Int, b)] -> Vector a

-- | Same as <a>accumulate</a>, but without bounds checking.
unsafeAccumulate :: (Unbox a, Unbox b) => (a -> b -> a) -> Vector a -> Vector (Int, b) -> Vector a

-- | Same as <a>accumulate_</a>, but without bounds checking.
unsafeAccumulate_ :: (Unbox a, Unbox b) => (a -> b -> a) -> Vector a -> Vector Int -> Vector b -> Vector a

-- | Same as <a>backpermute</a>, but without bounds checking.
unsafeBackpermute :: Unbox a => Vector a -> Vector Int -> Vector a

-- | <i>O(1)</i> Unsafely convert a mutable vector to an immutable one
--   without copying. The mutable vector may not be used after this
--   operation.
unsafeFreeze :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> m (Vector a)

-- | <i>O(1)</i> Unsafely convert an immutable vector to a mutable one
--   without copying. Note that this is a very dangerous function and
--   generally it's only safe to read from the resulting vector. In this
--   case, the immutable vector could be used safely as well.
--   
--   Problems with mutation happen because GHC has a lot of freedom to
--   introduce sharing. As a result mutable vectors produced by
--   <tt>unsafeThaw</tt> may or may not share the same underlying buffer.
--   For example:
--   
--   <pre>
--   foo = do
--     let vec = V.generate 10 id
--     mvec &lt;- V.unsafeThaw vec
--     do_something mvec
--   </pre>
--   
--   Here GHC could lift <tt>vec</tt> outside of foo which means that all
--   calls to <tt>do_something</tt> will use same buffer with possibly
--   disastrous results. Whether such aliasing happens or not depends on
--   the program in question, optimization levels, and GHC flags.
--   
--   All in all, attempts to modify a vector produced by
--   <tt>unsafeThaw</tt> fall out of domain of software engineering and
--   into realm of black magic, dark rituals, and unspeakable horrors. The
--   only advice that could be given is: "Don't attempt to mutate a vector
--   produced by <tt>unsafeThaw</tt> unless you know how to prevent GHC
--   from aliasing buffers accidentally. We don't."
unsafeThaw :: (Unbox a, PrimMonad m) => Vector a -> m (MVector (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length. This is not checked.
unsafeCopy :: (Unbox a, PrimMonad m) => MVector (PrimState m) a -> Vector a -> m ()


-- | Generic <tt>Vector</tt> interface unsafe functions. These perform no
--   bounds checking, and may cause segmentation faults etc.! Import as:
--   
--   <pre>
--   import qualified RIO.Vector.Unsafe as V'
--   </pre>
module RIO.Vector.Unsafe

-- | Class of immutable vectors. Every immutable vector is associated with
--   its mutable version through the <a>Mutable</a> type family. Methods of
--   this class should not be used directly. Instead,
--   <a>Data.Vector.Generic</a> and other <tt>Data.Vector</tt> modules
--   provide safe and fusible wrappers.
--   
--   Minimum complete implementation:
--   
--   <ul>
--   <li><a>basicUnsafeFreeze</a></li>
--   <li><a>basicUnsafeThaw</a></li>
--   <li><a>basicLength</a></li>
--   <li><a>basicUnsafeSlice</a></li>
--   <li><a>basicUnsafeIndexM</a></li>
--   </ul>
class MVector Mutable v a => Vector (v :: Type -> Type) a

-- | <i>Assumed complexity: O(1)</i>
--   
--   Unsafely convert a mutable vector to its immutable version without
--   copying. The mutable vector may not be used after this operation.
basicUnsafeFreeze :: Vector v a => Mutable v s a -> ST s (v a)

-- | <i>Assumed complexity: O(1)</i>
--   
--   Unsafely convert an immutable vector to its mutable version without
--   copying. The immutable vector may not be used after this operation.
basicUnsafeThaw :: Vector v a => v a -> ST s (Mutable v s a)

-- | <i>Assumed complexity: O(1)</i>
--   
--   Yield the length of the vector.
basicLength :: Vector v a => v a -> Int

-- | <i>Assumed complexity: O(1)</i>
--   
--   Yield a slice of the vector without copying it. No range checks are
--   performed.
basicUnsafeSlice :: Vector v a => Int -> Int -> v a -> v a

-- | <i>Assumed complexity: O(1)</i>
--   
--   Yield the element at the given position in a monad. No range checks
--   are performed.
--   
--   The monad allows us to be strict in the vector if we want. Suppose we
--   had
--   
--   <pre>
--   unsafeIndex :: v a -&gt; Int -&gt; a
--   </pre>
--   
--   instead. Now, if we wanted to copy a vector, we'd do something like
--   
--   <pre>
--   copy mv v ... = ... unsafeWrite mv i (unsafeIndex v i) ...
--   </pre>
--   
--   For lazy vectors, the indexing would not be evaluated, which means
--   that we would retain a reference to the original vector in each
--   element we write. This is not what we want!
--   
--   With <a>basicUnsafeIndexM</a>, we can do
--   
--   <pre>
--   copy mv v ... = ... case basicUnsafeIndexM v i of
--                         Box x -&gt; unsafeWrite mv i x ...
--   </pre>
--   
--   which does not have this problem, because indexing (but not the
--   returned element!) is evaluated immediately.
basicUnsafeIndexM :: Vector v a => v a -> Int -> Box a

-- | <i>Assumed complexity: O(n)</i>
--   
--   Copy an immutable vector into a mutable one. The two vectors must have
--   the same length, but this is not checked.
--   
--   Instances of <a>Vector</a> should redefine this method if they wish to
--   support an efficient block copy operation.
--   
--   Default definition: copying based on <a>basicUnsafeIndexM</a> and
--   <tt>basicUnsafeWrite</tt>.
basicUnsafeCopy :: Vector v a => Mutable v s a -> v a -> ST s ()

-- | Evaluate <tt>a</tt> as far as storing it in a vector would and yield
--   <tt>b</tt>. The <tt>v a</tt> argument only fixes the type and is not
--   touched. This method is only used for optimisation purposes. Thus, it
--   is safe for instances of <a>Vector</a> to evaluate <tt>a</tt> less
--   than it would be when stored in a vector, although this might result
--   in suboptimal code.
--   
--   <pre>
--   elemseq v x y = (singleton x `asTypeOf` v) `seq` y
--   </pre>
--   
--   Default defintion: <tt>a</tt> is not evaluated at all.
elemseq :: Vector v a => v a -> a -> b -> b

-- | <i>O(1)</i> Unsafe indexing without bounds checking.
unsafeIndex :: Vector v a => v a -> Int -> a

-- | <i>O(1)</i> First element, without checking if the vector is empty.
unsafeHead :: Vector v a => v a -> a

-- | <i>O(1)</i> Last element, without checking if the vector is empty.
unsafeLast :: Vector v a => v a -> a

-- | <i>O(1)</i> Indexing in a monad, without bounds checks. See
--   <a>indexM</a> for an explanation of why this is useful.
unsafeIndexM :: (Vector v a, Monad m) => v a -> Int -> m a

-- | <i>O(1)</i> First element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeHeadM :: (Vector v a, Monad m) => v a -> m a

-- | <i>O(1)</i> Last element in a monad, without checking for empty
--   vectors. See <a>indexM</a> for an explanation of why this is useful.
unsafeLastM :: (Vector v a, Monad m) => v a -> m a

-- | <i>O(1)</i> Yield a slice of the vector without copying. The vector
--   must contain at least <tt>i+n</tt> elements, but this is not checked.
unsafeSlice :: Vector v a => Int -> Int -> v a -> v a

-- | <i>O(1)</i> Yield all but the last element without copying. The vector
--   may not be empty, but this is not checked.
unsafeInit :: Vector v a => v a -> v a

-- | <i>O(1)</i> Yield all but the first element without copying. The
--   vector may not be empty, but this is not checked.
unsafeTail :: Vector v a => v a -> v a

-- | <i>O(1)</i> Yield the first <tt>n</tt> elements without copying. The
--   vector must contain at least <tt>n</tt> elements, but this is not
--   checked.
unsafeTake :: Vector v a => Int -> v a -> v a

-- | <i>O(1)</i> Yield all but the first <tt>n</tt> elements without
--   copying. The vector must contain at least <tt>n</tt> elements, but
--   this is not checked.
unsafeDrop :: Vector v a => Int -> v a -> v a

-- | Same as (<a>//</a>), but without bounds checking.
unsafeUpd :: Vector v a => v a -> [(Int, a)] -> v a

-- | Same as <a>update</a>, but without bounds checking.
unsafeUpdate :: (Vector v a, Vector v (Int, a)) => v a -> v (Int, a) -> v a

-- | Same as <a>update_</a>, but without bounds checking.
unsafeUpdate_ :: (Vector v a, Vector v Int) => v a -> v Int -> v a -> v a

-- | Same as <a>accum</a>, but without bounds checking.
unsafeAccum :: Vector v a => (a -> b -> a) -> v a -> [(Int, b)] -> v a

-- | Same as <a>accumulate</a>, but without bounds checking.
unsafeAccumulate :: (Vector v a, Vector v (Int, b)) => (a -> b -> a) -> v a -> v (Int, b) -> v a

-- | Same as <a>accumulate_</a>, but without bounds checking.
unsafeAccumulate_ :: (Vector v a, Vector v Int, Vector v b) => (a -> b -> a) -> v a -> v Int -> v b -> v a

-- | Same as <a>backpermute</a>, but without bounds checking.
unsafeBackpermute :: (Vector v a, Vector v Int) => v a -> v Int -> v a

-- | <i>O(1)</i> Unsafely convert a mutable vector to an immutable one
--   without copying. The mutable vector may not be used after this
--   operation.
unsafeFreeze :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> m (v a)

-- | <i>O(1)</i> Unsafely convert an immutable vector to a mutable one
--   without copying. Note that this is a very dangerous function and
--   generally it's only safe to read from the resulting vector. In this
--   case, the immutable vector could be used safely as well.
--   
--   Problems with mutation happen because GHC has a lot of freedom to
--   introduce sharing. As a result mutable vectors produced by
--   <tt>unsafeThaw</tt> may or may not share the same underlying buffer.
--   For example:
--   
--   <pre>
--   foo = do
--     let vec = V.generate 10 id
--     mvec &lt;- V.unsafeThaw vec
--     do_something mvec
--   </pre>
--   
--   Here GHC could lift <tt>vec</tt> outside of foo which means that all
--   calls to <tt>do_something</tt> will use same buffer with possibly
--   disastrous results. Whether such aliasing happens or not depends on
--   the program in question, optimization levels, and GHC flags.
--   
--   All in all, attempts to modify a vector produced by
--   <tt>unsafeThaw</tt> fall out of domain of software engineering and
--   into realm of black magic, dark rituals, and unspeakable horrors. The
--   only advice that could be given is: "Don't attempt to mutate a vector
--   produced by <tt>unsafeThaw</tt> unless you know how to prevent GHC
--   from aliasing buffers accidentally. We don't."
unsafeThaw :: (PrimMonad m, Vector v a) => v a -> m (Mutable v (PrimState m) a)

-- | <i>O(n)</i> Copy an immutable vector into a mutable one. The two
--   vectors must have the same length. This is not checked.
unsafeCopy :: (PrimMonad m, Vector v a) => Mutable v (PrimState m) a -> v a -> m ()


-- | Provides reexports of <tt>MonadWriter</tt> and related helpers.
module RIO.Writer
class (Monoid w, Monad m) => MonadWriter w (m :: Type -> Type) | m -> w

-- | <tt><a>writer</a> (a,w)</tt> embeds a simple writer action.
writer :: MonadWriter w m => (a, w) -> m a

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: MonadWriter w m => w -> m ()

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
listen :: MonadWriter w m => m a -> m (a, w)

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
pass :: MonadWriter w m => m (a, w -> w) -> m a

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   </ul>
listens :: MonadWriter w m => (w -> b) -> m a -> m (a, b)

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\x -&gt;
--   (x,f)) m)</pre></li>
--   </ul>
censor :: MonadWriter w m => (w -> w) -> m a -> m a

-- | A writer monad parameterized by the type <tt>w</tt> of output to
--   accumulate.
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
type Writer w = WriterT w Identity

-- | Unwrap a writer computation as a (result, output) pair. (The inverse
--   of <a>writer</a>.)
runWriter :: Writer w a -> (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriter</a> m = <a>snd</a> (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
execWriter :: Writer w a -> w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriter</a> (<a>mapWriter</a> f m) = f (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
mapWriter :: ((a, w) -> (b, w')) -> Writer w a -> Writer w' b

-- | A writer monad parameterized by:
--   
--   <ul>
--   <li><tt>w</tt> - the output to accumulate.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
newtype WriterT w (m :: Type -> Type) a
WriterT :: m (a, w) -> WriterT w (m :: Type -> Type) a
[runWriterT] :: WriterT w (m :: Type -> Type) a -> m (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriterT</a> m = <a>liftM</a> <a>snd</a>
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
execWriterT :: Monad m => WriterT w m a -> m w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>mapWriterT</a> f m) = f
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
mapWriterT :: (m (a, w) -> n (b, w')) -> WriterT w m a -> WriterT w' n b
