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


-- | Array, vector and text
--   
--   This package provides array, slice and text operations
@package Z-Data
@version 0.6.1.0


-- | ASCII Chars utility.
module Z.Data.ASCII

-- | Conversion between <a>Word8</a> and <a>Char</a>. Should compile to a
--   no-op.
w2c :: Word8 -> Char

-- | Unsafe conversion between <a>Char</a> and <a>Word8</a>. This is a
--   no-op and silently truncates to 8 bits Chars &gt; <tt>\255</tt>.
c2w :: Char -> Word8

-- | <pre>
--   \NUL &lt;= w &amp;&amp; w &lt;= \DEL
--   </pre>
isASCII :: Word8 -> Bool

-- | <pre>
--   A ~ Z
--   </pre>
isUpper :: Word8 -> Bool

-- | <pre>
--   a ~ z
--   </pre>
isLower :: Word8 -> Bool

-- | <tt>ISO-8859-1</tt> control letter.
isControl :: Word8 -> Bool

-- | <tt>ISO-8859-1</tt> space letter.
isSpace :: Word8 -> Bool

-- | <pre>
--   0 ~ 9
--   </pre>
isDigit :: Word8 -> Bool

-- | <pre>
--   0 ~ 7
--   </pre>
isOctDigit :: Word8 -> Bool

-- | <pre>
--   0 ~ 9, A ~ F, a ~ f
--   </pre>
isHexDigit :: Word8 -> Bool

-- | <pre>
--   \NUL
--   </pre>
pattern NUL :: Word8

-- | <pre>
--   \t
--   </pre>
pattern TAB :: Word8

-- | <pre>
--   \n
--   </pre>
pattern NEWLINE :: Word8

-- | <pre>
--   \v
--   </pre>
pattern VERTICAL_TAB :: Word8

-- | <pre>
--   \f
--   </pre>
pattern FORM_FEED :: Word8

-- | <pre>
--   \r
--   </pre>
pattern CARRIAGE_RETURN :: Word8

-- | <pre>
--   ' '
--   </pre>
pattern SPACE :: Word8

-- | <pre>
--   !
--   </pre>
pattern EXCLAM :: Word8

-- | <pre>
--   "
--   </pre>
pattern QUOTE_DOUBLE :: Word8

-- | <pre>
--   #
--   </pre>
pattern HASH :: Word8

-- | <pre>
--   #
--   </pre>
pattern NUMBER_SIGN :: Word8

-- | <pre>
--   $
--   </pre>
pattern DOLLAR :: Word8

-- | <pre>
--   %
--   </pre>
pattern PERCENT :: Word8

-- | <pre>
--   &amp;
--   </pre>
pattern AMPERSAND :: Word8

-- | <pre>
--   &amp;
--   </pre>
pattern AND :: Word8

-- | <pre>
--   '
--   </pre>
pattern QUOTE_SINGLE :: Word8

-- | <pre>
--   (
--   </pre>
pattern PAREN_LEFT :: Word8

-- | <pre>
--   )
--   </pre>
pattern PAREN_RIGHT :: Word8

-- | <pre>
--   *
--   </pre>
pattern ASTERISK :: Word8

-- | <pre>
--   +
--   </pre>
pattern PLUS :: Word8

-- | <pre>
--   ,
--   </pre>
pattern COMMA :: Word8

-- | <pre>
--   -
--   </pre>
pattern HYPHEN :: Word8

-- | <pre>
--   -
--   </pre>
pattern MINUS :: Word8

-- | <pre>
--   .
--   </pre>
pattern PERIOD :: Word8

-- | <pre>
--   .
--   </pre>
pattern DOT :: Word8

-- | <pre>
--   /
--   </pre>
pattern SLASH :: Word8
pattern DIGIT_0 :: Word8
pattern DIGIT_1 :: Word8
pattern DIGIT_2 :: Word8
pattern DIGIT_3 :: Word8
pattern DIGIT_4 :: Word8
pattern DIGIT_5 :: Word8
pattern DIGIT_6 :: Word8
pattern DIGIT_7 :: Word8
pattern DIGIT_8 :: Word8
pattern DIGIT_9 :: Word8

-- | <pre>
--   :
--   </pre>
pattern COLON :: Word8

-- | <pre>
--   ;
--   </pre>
pattern SEMICOLON :: Word8

-- | <pre>
--   &lt;
--   </pre>
pattern LESS :: Word8

-- | <pre>
--   &lt;
--   </pre>
pattern ANGLE_LEFT :: Word8

-- | <pre>
--   =
--   </pre>
pattern EQUAL :: Word8

-- | <pre>
--   &gt;
--   </pre>
pattern GREATER :: Word8

-- | <pre>
--   &gt;
--   </pre>
pattern ANGLE_RIGHT :: Word8

-- | <pre>
--   ?
--   </pre>
pattern QUESTION :: Word8

-- | <pre>
--   @
--   </pre>
pattern AT :: Word8
pattern LETTER_A :: Word8
pattern LETTER_B :: Word8
pattern LETTER_C :: Word8
pattern LETTER_D :: Word8
pattern LETTER_E :: Word8
pattern LETTER_F :: Word8
pattern LETTER_G :: Word8
pattern LETTER_H :: Word8
pattern LETTER_I :: Word8
pattern LETTER_J :: Word8
pattern LETTER_K :: Word8
pattern LETTER_L :: Word8
pattern LETTER_M :: Word8
pattern LETTER_N :: Word8
pattern LETTER_O :: Word8
pattern LETTER_P :: Word8
pattern LETTER_Q :: Word8
pattern LETTER_R :: Word8
pattern LETTER_S :: Word8
pattern LETTER_T :: Word8
pattern LETTER_U :: Word8
pattern LETTER_V :: Word8
pattern LETTER_W :: Word8
pattern LETTER_X :: Word8
pattern LETTER_Y :: Word8
pattern LETTER_Z :: Word8

-- | <pre>
--   [
--   </pre>
pattern BRACKET_LEFT :: Word8

-- | <pre>
--   [
--   </pre>
pattern SQUARE_LEFT :: Word8

-- | <pre>
--   \
--   </pre>
pattern BACKSLASH :: Word8

-- | <pre>
--   ]
--   </pre>
pattern BRACKET_RIGHT :: Word8

-- | <pre>
--   ]
--   </pre>
pattern SQUARE_RIGHT :: Word8

-- | <pre>
--   ^
--   </pre>
pattern CIRCUM :: Word8

-- | <pre>
--   _
--   </pre>
pattern UNDERSCORE :: Word8

-- | <pre>
--   `
--   </pre>
pattern GRAVE :: Word8
pattern LETTER_a :: Word8
pattern LETTER_b :: Word8
pattern LETTER_c :: Word8
pattern LETTER_d :: Word8
pattern LETTER_e :: Word8
pattern LETTER_f :: Word8
pattern LETTER_g :: Word8
pattern LETTER_h :: Word8
pattern LETTER_i :: Word8
pattern LETTER_j :: Word8
pattern LETTER_k :: Word8
pattern LETTER_l :: Word8
pattern LETTER_m :: Word8
pattern LETTER_n :: Word8
pattern LETTER_o :: Word8
pattern LETTER_p :: Word8
pattern LETTER_q :: Word8
pattern LETTER_r :: Word8
pattern LETTER_s :: Word8
pattern LETTER_t :: Word8
pattern LETTER_u :: Word8
pattern LETTER_v :: Word8
pattern LETTER_w :: Word8
pattern LETTER_x :: Word8
pattern LETTER_y :: Word8
pattern LETTER_z :: Word8

-- | <pre>
--   {
--   </pre>
pattern BRACE_LEFT :: Word8

-- | <pre>
--   {
--   </pre>
pattern CURLY_LEFT :: Word8

-- | <pre>
--   |
--   </pre>
pattern BAR :: Word8

-- | <pre>
--   |
--   </pre>
pattern OR :: Word8

-- | <pre>
--   }
--   </pre>
pattern BRACE_RIGHT :: Word8

-- | <pre>
--   }
--   </pre>
pattern CURLY_RIGHT :: Word8

-- | <pre>
--   ~
--   </pre>
pattern TILDE :: Word8

-- | <pre>
--   \DEL
--   </pre>
pattern DEL :: Word8


-- | This module is borrowed from basement's Cast module with conditional
--   instances removed. The purpose of <a>Cast</a> is to provide primitive
--   types which share the same byte size, so that arrays and vectors
--   parameterized by them can be safely coerced without breaking the index
--   bounds. You can also use it to directly cast primitives just like
--   <tt>reinterpret_cast</tt>. A <a>Coercible</a> based instance is also
--   provide for convenience.
module Z.Data.Array.Cast

-- | <a>Cast</a> between primitive types of the same size.
class Cast source destination
cast :: Cast source destination => source -> destination
instance GHC.Types.Coercible a b => Z.Data.Array.Cast.Cast a b
instance Z.Data.Array.Cast.Cast GHC.Int.Int8 GHC.Word.Word8
instance Z.Data.Array.Cast.Cast GHC.Int.Int16 GHC.Word.Word16
instance Z.Data.Array.Cast.Cast GHC.Int.Int32 GHC.Word.Word32
instance Z.Data.Array.Cast.Cast GHC.Int.Int64 GHC.Word.Word64
instance Z.Data.Array.Cast.Cast GHC.Types.Int GHC.Types.Word
instance Z.Data.Array.Cast.Cast GHC.Word.Word8 GHC.Int.Int8
instance Z.Data.Array.Cast.Cast GHC.Word.Word16 GHC.Int.Int16
instance Z.Data.Array.Cast.Cast GHC.Word.Word32 GHC.Int.Int32
instance Z.Data.Array.Cast.Cast GHC.Word.Word64 GHC.Int.Int64
instance Z.Data.Array.Cast.Cast GHC.Types.Word GHC.Types.Int
instance Z.Data.Array.Cast.Cast GHC.Word.Word64 GHC.Types.Double
instance Z.Data.Array.Cast.Cast GHC.Word.Word32 GHC.Types.Float
instance Z.Data.Array.Cast.Cast GHC.Types.Double GHC.Word.Word64
instance Z.Data.Array.Cast.Cast GHC.Types.Float GHC.Word.Word32
instance Z.Data.Array.Cast.Cast GHC.Int.Int64 GHC.Types.Double
instance Z.Data.Array.Cast.Cast GHC.Int.Int32 GHC.Types.Float
instance Z.Data.Array.Cast.Cast GHC.Types.Double GHC.Int.Int64
instance Z.Data.Array.Cast.Cast GHC.Types.Float GHC.Int.Int32


-- | This module implements unaligned element access with ghc primitives
--   (&gt; 8.6), which can be used as a simple binary encoding / decoding
--   method.
module Z.Data.Array.Unaligned
newtype UnalignedSize a
UnalignedSize :: Int -> UnalignedSize a
[getUnalignedSize] :: UnalignedSize a -> Int

-- | Primitive types which can be unaligned accessed
--   
--   It can also be used as a lightweight method to peek/poke value from/to
--   C structs when you pass <a>MutableByteArray#</a> to FFI as struct
--   pointer, e.g.
--   
--   <pre>
--   -- | note the .hsc syntax
--   peekSocketAddrMBA :: HasCallStack =&gt; MBA## SocketAddr -&gt; IO SocketAddr
--   peekSocketAddrMBA p = do
--       family &lt;- peekMBA p (#offset struct sockaddr, sa_family)
--       case family :: CSaFamily of
--           (#const AF_INET) -&gt; do
--               addr &lt;- peekMBA p (#offset struct sockaddr_in, sin_addr)
--               port &lt;- peekMBA p (#offset struct sockaddr_in, sin_port)
--               return (SocketAddrInet (PortNumber port) addr)
--           ....
--   </pre>
class Unaligned a

-- | byte size
unalignedSize :: Unaligned a => UnalignedSize a

-- | index element off byte array with offset in bytes(maybe unaligned)
indexWord8ArrayAs# :: Unaligned a => ByteArray# -> Int# -> a

-- | read element from byte array with offset in bytes(maybe unaligned)
readWord8ArrayAs# :: Unaligned a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)

-- | write element to byte array with offset in bytes(maybe unaligned)
writeWord8ArrayAs# :: Unaligned a => MutableByteArray# s -> Int# -> a -> State# s -> State# s

-- | IO version of <a>writeWord8ArrayAs#</a> but more convenient to write
--   manually.
peekMBA :: Unaligned a => MutableByteArray# RealWorld -> Int -> IO a

-- | IO version of <a>readWord8ArrayAs#</a> but more convenient to write
--   manually.
pokeMBA :: Unaligned a => MutableByteArray# RealWorld -> Int -> a -> IO ()

-- | index element off byte array with offset in bytes(maybe unaligned)
indexBA :: Unaligned a => ByteArray# -> Int -> a

-- | Lifted version of <a>writeWord8ArrayAs#</a>
writeWord8ArrayAs :: (PrimMonad m, Unaligned a) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Lifted version of <a>readWord8ArrayAs#</a>
readWord8ArrayAs :: (PrimMonad m, Unaligned a) => MutableByteArray (PrimState m) -> Int -> m a

-- | Lifted version of <a>indexWord8ArrayAs#</a>
indexWord8ArrayAs :: Unaligned a => ByteArray -> Int -> a

-- | Lifted version of <a>writeWord8ArrayAs#</a>
writePrimWord8ArrayAs :: (PrimMonad m, Unaligned a) => MutablePrimArray (PrimState m) Word8 -> Int -> a -> m ()

-- | Lifted version of <a>readWord8ArrayAs#</a>
readPrimWord8ArrayAs :: (PrimMonad m, Unaligned a) => MutablePrimArray (PrimState m) Word8 -> Int -> m a

-- | Lifted version of <a>indexWord8ArrayAs#</a>
indexPrimWord8ArrayAs :: Unaligned a => PrimArray Word8 -> Int -> a

-- | Encode PrimArray elements in big endian.
primArrayToBE :: forall a. (Prim a, Unaligned (BE a)) => PrimArray a -> Int -> Int -> PrimArray Word8

-- | Decode PrimArray elements in big endian.
primArrayFromBE :: forall a. (Prim a, Unaligned (BE a)) => PrimArray Word8 -> Int -> Int -> PrimArray a

-- | little endianess wrapper
newtype LE a
LE :: a -> LE a
[getLE] :: LE a -> a

-- | big endianess wrapper
newtype BE a
BE :: a -> BE a
[getBE] :: BE a -> a
instance forall k (a :: k). GHC.Num.Num (Z.Data.Array.Unaligned.UnalignedSize a)
instance forall k (a :: k). GHC.Classes.Ord (Z.Data.Array.Unaligned.UnalignedSize a)
instance forall k (a :: k). GHC.Classes.Eq (Z.Data.Array.Unaligned.UnalignedSize a)
instance forall k (a :: k). GHC.Show.Show (Z.Data.Array.Unaligned.UnalignedSize a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Z.Data.Array.Unaligned.LE a)
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Array.Unaligned.LE a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Z.Data.Array.Unaligned.BE a)
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Array.Unaligned.BE a)
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CChar
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CSChar
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUChar
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CShort
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUShort
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CInt
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUInt
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CLong
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CULong
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CPtrdiff
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CSize
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CWchar
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CSigAtomic
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CLLong
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CULLong
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CBool
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CIntPtr
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUIntPtr
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CIntMax
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUIntMax
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CClock
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CTime
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CUSeconds
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CSUSeconds
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CFloat
instance Z.Data.Array.Unaligned.Unaligned Foreign.C.Types.CDouble
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Word.Word16)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Word.Word32)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Word.Word64)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Types.Word)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Int.Int16)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Int.Int32)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Int.Int64)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Types.Int)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Types.Float)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Types.Double)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.BE GHC.Types.Char)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Word.Word16)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Word.Word32)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Word.Word64)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Types.Word)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Int.Int16)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Int.Int32)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Int.Int64)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Types.Int)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Types.Float)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Types.Double)
instance Z.Data.Array.Unaligned.Unaligned (Z.Data.Array.Unaligned.LE GHC.Types.Char)
instance Z.Data.Array.Unaligned.Unaligned GHC.Word.Word8
instance Z.Data.Array.Unaligned.Unaligned GHC.Int.Int8
instance Z.Data.Array.Unaligned.Unaligned GHC.Word.Word16
instance Z.Data.Array.Unaligned.Unaligned GHC.Word.Word32
instance Z.Data.Array.Unaligned.Unaligned GHC.Word.Word64
instance Z.Data.Array.Unaligned.Unaligned GHC.Types.Word
instance Z.Data.Array.Unaligned.Unaligned GHC.Int.Int16
instance Z.Data.Array.Unaligned.Unaligned GHC.Int.Int32
instance Z.Data.Array.Unaligned.Unaligned GHC.Int.Int64
instance Z.Data.Array.Unaligned.Unaligned GHC.Types.Int
instance Z.Data.Array.Unaligned.Unaligned (GHC.Ptr.Ptr a)
instance Z.Data.Array.Unaligned.Unaligned GHC.Types.Float
instance Z.Data.Array.Unaligned.Unaligned GHC.Types.Double
instance Z.Data.Array.Unaligned.Unaligned GHC.Types.Char
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b) => Z.Data.Array.Unaligned.Unaligned (a, b)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c) => Z.Data.Array.Unaligned.Unaligned (a, b, c)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c, Z.Data.Array.Unaligned.Unaligned d) => Z.Data.Array.Unaligned.Unaligned (a, b, c, d)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c, Z.Data.Array.Unaligned.Unaligned d, Z.Data.Array.Unaligned.Unaligned e) => Z.Data.Array.Unaligned.Unaligned (a, b, c, d, e)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c, Z.Data.Array.Unaligned.Unaligned d, Z.Data.Array.Unaligned.Unaligned e, Z.Data.Array.Unaligned.Unaligned f) => Z.Data.Array.Unaligned.Unaligned (a, b, c, d, e, f)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c, Z.Data.Array.Unaligned.Unaligned d, Z.Data.Array.Unaligned.Unaligned e, Z.Data.Array.Unaligned.Unaligned f, Z.Data.Array.Unaligned.Unaligned g) => Z.Data.Array.Unaligned.Unaligned (a, b, c, d, e, f, g)
instance (Z.Data.Array.Unaligned.Unaligned a, Z.Data.Array.Unaligned.Unaligned b, Z.Data.Array.Unaligned.Unaligned c, Z.Data.Array.Unaligned.Unaligned d, Z.Data.Array.Unaligned.Unaligned e, Z.Data.Array.Unaligned.Unaligned f, Z.Data.Array.Unaligned.Unaligned g, Z.Data.Array.Unaligned.Unaligned h) => Z.Data.Array.Unaligned.Unaligned (a, b, c, d, e, f, g, h)


-- | GHC contains three general classes of value types:
--   
--   <ol>
--   <li>Unboxed types: values are machine values made up of fixed numbers
--   of bytes</li>
--   <li>Unlifted types: values are pointers, but strictly evaluated</li>
--   <li>Lifted types: values are pointers, lazily evaluated</li>
--   </ol>
--   
--   The first category can be stored in a <a>ByteArray</a>, and this
--   allows types in category 3 that are simple wrappers around category 1
--   types to be stored more efficiently using a <a>ByteArray</a>. This
--   module provides the same facility for category 2 types.
--   
--   GHC has two primitive types, <a>ArrayArray#</a> and
--   <a>MutableArrayArray#</a>. These are arrays of pointers, but of
--   category 2 values, so they are known to not be bottom. This allows
--   types that are wrappers around such types to be stored in an array
--   without an extra level of indirection.
--   
--   The way that the <a>ArrayArray#</a> API works is that one can read and
--   write <a>ArrayArray#</a> values to the positions. This works because
--   all category 2 types share a uniform representation, unlike unboxed
--   values which are represented by varying (by type) numbers of bytes.
--   However, using the this makes the internal API very unsafe to use, as
--   one has to coerce values to and from <a>ArrayArray#</a>.
--   
--   The API presented by this module is more type safe.
--   <a>UnliftedArray</a> and <a>MutableUnliftedArray</a> are parameterized
--   by the type of arrays they contain, and the coercions necessary are
--   abstracted into a class, <a>PrimUnlifted</a>, of things that are
--   eligible to be stored.
module Z.Data.Array.UnliftedArray

-- | Types with <a>TYPE</a> <a>UnliftedRep</a>, which can be stored /
--   retrieved in <a>ArrayArray#</a>.
class PrimUnlifted a
writeUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> a -> State# s -> State# s
readUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> State# s -> (# State# s, a #)
indexUnliftedArray# :: PrimUnlifted a => ArrayArray# -> Int# -> a

-- | Mutable array holding <a>PrimUnlifted</a> values.
data MutableUnliftedArray s a
MutableUnliftedArray :: MutableArrayArray# s -> MutableUnliftedArray s a

-- | Array holding <a>PrimUnlifted</a> values.
data UnliftedArray a
UnliftedArray :: ArrayArray# -> UnliftedArray a

-- | Creates a new <a>MutableUnliftedArray</a>. This function is unsafe
--   because it initializes all elements of the array as pointers to the
--   array itself. Attempting to read one of these elements before writing
--   to it is in effect an unsafe coercion from the
--   <tt><a>MutableUnliftedArray</a> s a</tt> to the element type.
unsafeNewUnliftedArray :: PrimMonad m => Int -> m (MutableUnliftedArray (PrimState m) a)

-- | Creates a new <a>MutableUnliftedArray</a> with the specified value as
--   initial contents. This is slower than <a>unsafeNewUnliftedArray</a>,
--   but safer.
newUnliftedArray :: (PrimMonad m, PrimUnlifted a) => Int -> a -> m (MutableUnliftedArray (PrimState m) a)
setUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> Int -> a -> m ()

-- | Yields the length of an <a>UnliftedArray</a>.
sizeofUnliftedArray :: UnliftedArray e -> Int

-- | Yields the length of a <a>MutableUnliftedArray</a>.
sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int
writeUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> a -> m ()
readUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> m a
indexUnliftedArray :: PrimUnlifted a => UnliftedArray a -> Int -> a

-- | Freezes a <a>MutableUnliftedArray</a>, yielding an
--   <a>UnliftedArray</a>. This simply marks the array as frozen in place,
--   so it should only be used when no further modifications to the mutable
--   array will be performed.
unsafeFreezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a)

-- | Determines whether two <a>MutableUnliftedArray</a> values are the
--   same. This is object/pointer identity, not based on the contents.
sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool

-- | Copies the contents of an immutable array into a mutable array.
copyUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> UnliftedArray a -> Int -> Int -> m ()

-- | Copies the contents of one mutable array into another.
copyMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> MutableUnliftedArray (PrimState m) a -> Int -> Int -> m ()

-- | Freezes a portion of a <a>MutableUnliftedArray</a>, yielding an
--   <a>UnliftedArray</a>. This operation is safe, in that it copies the
--   frozen portion, and the existing mutable array may still be used
--   afterward.
freezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (UnliftedArray a)

-- | Thaws a portion of an <a>UnliftedArray</a>, yielding a
--   <a>MutableUnliftedArray</a>. This copies the thawed portion, so
--   mutations will not affect the original array.
thawUnliftedArray :: PrimMonad m => UnliftedArray a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)

-- | Creates a copy of a portion of an <a>UnliftedArray</a>
cloneUnliftedArray :: UnliftedArray a -> Int -> Int -> UnliftedArray a

-- | Creates a new <a>MutableUnliftedArray</a> containing a copy of a
--   portion of another mutable array.
cloneMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (Data.Primitive.PrimArray.PrimArray a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted Data.Primitive.ByteArray.ByteArray
instance Z.Data.Array.UnliftedArray.PrimUnlifted (Data.Primitive.ByteArray.MutableByteArray s)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (Data.Primitive.PrimArray.MutablePrimArray s a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (GHC.MVar.MVar a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (GHC.Conc.Sync.TVar a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (GHC.STRef.STRef s a)
instance Z.Data.Array.UnliftedArray.PrimUnlifted (GHC.IORef.IORef a)


-- | Unified unboxed and boxed array operations using type family.
--   
--   All operations are NOT bound checked, if you need checked operations
--   please use <a>Z.Data.Array.Checked</a>. It exports exactly same APIs
--   so that you can switch between without pain.
--   
--   Some mnemonics:
--   
--   <ul>
--   <li><a>newArr</a>, <a>newArrWith</a> return mutable array,
--   <a>readArr</a>, <a>writeArr</a> works on them, <a>setArr</a> fill
--   elements with offset and length.</li>
--   <li><a>indexArr</a> works on immutable one, use <a>indexArr'</a> to
--   avoid indexing thunk.</li>
--   <li>The order of arguements of <a>copyArr</a>, <a>copyMutableArr</a>
--   and <a>moveArr</a> are always target and its offset come first, and
--   source and source offset follow, copying length comes last.</li>
--   </ul>
module Z.Data.Array

-- | A typeclass to unify box &amp; unboxed, mutable &amp; immutable array
--   operations.
--   
--   Most of these functions simply wrap their primitive counterpart, if
--   there's no primitive ones, we polyfilled using other operations to get
--   the same semantics.
--   
--   One exception is that <a>shrinkMutableArr</a> only perform closure
--   resizing on <a>PrimArray</a> because current RTS support only that,
--   <a>shrinkMutableArr</a> will do nothing on other array type.
--   
--   It's reasonable to trust GHC with specializing &amp; inlining these
--   polymorphric functions. They are used across this package and perform
--   identical to their monomophric counterpart.
class Arr (arr :: * -> *) a where {
    
    -- | Mutable version of this array type.
    type family MArr arr = (mar :: * -> * -> *) | mar -> arr;
}

-- | Make a new array with given size.
--   
--   For boxed array, all elements are <a>uninitialized</a> which shall not
--   be accessed. For primitive array, elements are just random garbage.
newArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => Int -> m (MArr arr s a)

-- | Make a new array and fill it with an initial value.
newArrWith :: (Arr arr a, PrimMonad m, PrimState m ~ s) => Int -> a -> m (MArr arr s a)

-- | Index mutable array in a primitive monad.
readArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> m a

-- | Write mutable array in a primitive monad.
writeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> a -> m ()

-- | Fill mutable array with a given value.
setArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> Int -> a -> m ()

-- | Index immutable array, which is a pure operation. This operation often
--   result in an indexing thunk for lifted arrays, use 'indexArr'' or
--   <a>indexArrM</a> if that's not desired.
indexArr :: Arr arr a => arr a -> Int -> a

-- | Index immutable array, pattern match on the unboxed unit tuple to
--   force indexing (without forcing the element).
indexArr' :: Arr arr a => arr a -> Int -> (# a #)

-- | Index immutable array in a primitive monad, this helps in situations
--   that you want your indexing result is not a thunk referencing whole
--   array.
indexArrM :: (Arr arr a, Monad m) => arr a -> Int -> m a

-- | Safely freeze mutable array by make a immutable copy of its slice.
freezeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> Int -> m (arr a)

-- | Safely thaw immutable array by make a mutable copy of its slice.
thawArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => arr a -> Int -> Int -> m (MArr arr s a)

-- | In place freeze a mutable array, the original mutable array can not be
--   used anymore.
unsafeFreezeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> m (arr a)

-- | In place thaw a immutable array, the original immutable array can not
--   be used anymore.
unsafeThawArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => arr a -> m (MArr arr s a)

-- | Copy a slice of immutable array to mutable array at given offset.
copyArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> arr a -> Int -> Int -> m ()

-- | Copy a slice of mutable array to mutable array at given offset. The
--   two mutable arrays shall no be the same one.
copyMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> MArr arr s a -> Int -> Int -> m ()

-- | Copy a slice of mutable array to mutable array at given offset. The
--   two mutable arrays may be the same one.
moveArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> MArr arr s a -> Int -> Int -> m ()

-- | Create immutable copy.
cloneArr :: Arr arr a => arr a -> Int -> Int -> arr a

-- | Create mutable copy.
cloneMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> Int -> m (MArr arr s a)

-- | Resize mutable array to given size.
resizeMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> m (MArr arr s a)

-- | Shrink mutable array to given size. This operation only works on
--   primitive arrays. For some array types, this is a no-op, e.g.
--   <tt>sizeOfMutableArr</tt> will not change.
shrinkMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> Int -> m ()

-- | Is two mutable array are reference equal.
sameMutableArr :: Arr arr a => MArr arr s a -> MArr arr s a -> Bool

-- | Size of immutable array.
sizeofArr :: Arr arr a => arr a -> Int

-- | Size of mutable array.
sizeofMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> m Int

-- | Is two immutable array are referencing the same one.
--   
--   Note that <a>sameArr</a> 's result may change depending on compiler's
--   optimizations, for example <tt>let arr = runST ... in arr
--   <a>sameArr</a> arr</tt> may return false if compiler decides to inline
--   it.
--   
--   See <a>https://ghc.haskell.org/trac/ghc/ticket/13908</a> for more
--   background.
sameArr :: Arr arr a => arr a -> arr a -> Bool
singletonArr :: Arr arr a => a -> arr a
doubletonArr :: Arr arr a => a -> a -> arr a

-- | Modify(strictly) an immutable array's element at given index to
--   produce a new array.
modifyIndexArr :: Arr arr a => arr a -> Int -> Int -> Int -> (a -> a) -> arr a

-- | Insert an immutable array's element at given index to produce a new
--   array.
insertIndexArr :: Arr arr a => arr a -> Int -> Int -> Int -> a -> arr a

-- | Delete an immutable array's element at given index to produce a new
--   array.
deleteIndexArr :: Arr arr a => arr a -> Int -> Int -> Int -> arr a

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld

-- | Boxed arrays
data Array a
Array :: Array# a -> Array a
[array#] :: Array a -> Array# a

-- | Mutable boxed arrays associated with a primitive state token.
data MutableArray s a
MutableArray :: MutableArray# s a -> MutableArray s a
[marray#] :: MutableArray s a -> MutableArray# s a
data SmallArray a
SmallArray :: SmallArray# a -> SmallArray a
data SmallMutableArray s a
SmallMutableArray :: SmallMutableArray# s a -> SmallMutableArray s a

-- | Bottom value (<tt>throw (<a>UndefinedElement</a>
--   <a>uninitialized</a>)</tt>) for initialize new boxed
--   array(<a>Array</a>, <a>SmallArray</a>..).
uninitialized :: a

-- | Arrays of unboxed elements. This accepts types like <a>Double</a>,
--   <a>Char</a>, <a>Int</a>, and <a>Word</a>, as well as their
--   fixed-length variants (<tt>Word8</tt>, <tt>Word16</tt>, etc.). Since
--   the elements are unboxed, a <a>PrimArray</a> is strict in its
--   elements. This differs from the behavior of <tt>Array</tt>, which is
--   lazy in its elements.
data PrimArray a
PrimArray :: ByteArray# -> PrimArray a

-- | Mutable primitive arrays associated with a primitive state token.
--   These can be written to and read from in a monadic context that
--   supports sequencing such as <a>IO</a> or <a>ST</a>. Typically, a
--   mutable primitive array will be built and then convert to an immutable
--   primitive array using <a>unsafeFreezePrimArray</a>. However, it is
--   also acceptable to simply discard a mutable primitive array since it
--   lives in managed memory and will be garbage collected when no longer
--   referenced.
data MutablePrimArray s a
MutablePrimArray :: MutableByteArray# s -> MutablePrimArray s a

-- | Class of types supporting primitive array operations. This includes
--   interfacing with GC-managed memory (functions suffixed with
--   <tt>ByteArray#</tt>) and interfacing with unmanaged memory (functions
--   suffixed with <tt>Addr#</tt>). Endianness is platform-dependent.
class Prim a

-- | Size of values of type <tt>a</tt>. The argument is not used.
sizeOf# :: Prim a => a -> Int#

-- | Alignment of values of type <tt>a</tt>. The argument is not used.
alignment# :: Prim a => a -> Int#

-- | Read a value from the array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
indexByteArray# :: Prim a => ByteArray# -> Int# -> a

-- | Read a value from the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)

-- | Write a value to the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s

-- | Fill a slice of the mutable array with a value. The offset and length
--   of the chunk are in elements of type <tt>a</tt> rather than in bytes.
setByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s

-- | Read a value from a memory position given by an address and an offset.
--   The memory block the address refers to must be immutable. The offset
--   is in elements of type <tt>a</tt> rather than in bytes.
indexOffAddr# :: Prim a => Addr# -> Int# -> a

-- | Read a value from a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
readOffAddr# :: Prim a => Addr# -> Int# -> State# s -> (# State# s, a #)

-- | Write a value to a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
writeOffAddr# :: Prim a => Addr# -> Int# -> a -> State# s -> State# s

-- | Fill a memory block given by an address, an offset and a length. The
--   offset and length are in elements of type <tt>a</tt> rather than in
--   bytes.
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s

-- | Create a <i>pinned</i> primitive array of the specified size in
--   elements. The garbage collector is guaranteed not to move it.
newPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Create a <i>pinned</i> primitive array of the specified size in
--   elements and with the alignment given by its <a>Prim</a> instance. The
--   garbage collector is guaranteed not to move it.
newAlignedPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Copy a slice of an immutable primitive array to an address. The offset
--   and length are given in elements of type <tt>a</tt>. This function
--   assumes that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <tt>Storable</tt> instance. This function is only available when
--   building with GHC 7.8 or newer.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyPrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> PrimArray a -> Int -> Int -> m ()

-- | Copy a slice of an immutable primitive array to an address. The offset
--   and length are given in elements of type <tt>a</tt>. This function
--   assumes that the <a>Prim</a> instance of <tt>a</tt> agrees with the
--   <tt>Storable</tt> instance. This function is only available when
--   building with GHC 7.8 or newer.
--   
--   <i>Note:</i> this function does not do bounds or overlap checking.
copyMutablePrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()

-- | Copy from a pointer to a mutable primitive array. The offset and
--   length are given in elements of type <tt>a</tt>. This function is only
--   available when building with GHC 7.8 or newer.
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> prim arrays allocated by <tt>newPinnedByteArray</tt> or
--   <tt>newAlignedPinnedByteArray</tt>.
primArrayContents :: PrimArray a -> Ptr a

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <tt>newPinnedByteArray</tt> or
--   <tt>newAlignedPinnedByteArray</tt>.
mutablePrimArrayContents :: MutablePrimArray s a -> Ptr a

-- | Yield a pointer to the array's data and do computation with it.
--   
--   This operation is only safe on <i>pinned</i> primitive arrays
--   allocated by <a>newPinnedPrimArray</a> or
--   <a>newAlignedPinnedPrimArray</a>.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimArrayContents :: PrimArray a -> (Ptr a -> IO b) -> IO b

-- | Yield a pointer to the array's data and do computation with it.
--   
--   This operation is only safe on <i>pinned</i> primitive arrays
--   allocated by <a>newPinnedPrimArray</a> or
--   <a>newAlignedPinnedPrimArray</a>.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withMutablePrimArrayContents :: MutablePrimArray RealWorld a -> (Ptr a -> IO b) -> IO b

-- | Check whether or not the byte array is pinned. Pinned primitive arrays
--   cannot be moved by the garbage collector. It is safe to use
--   <a>primArrayContents</a> on such byte arrays. This function is only
--   available when compiling with GHC 8.2 or newer.
isPrimArrayPinned :: PrimArray a -> Bool

-- | Check whether or not the mutable primitive array is pinned. This
--   function is only available when compiling with GHC 8.2 or newer.
isMutablePrimArrayPinned :: MutablePrimArray s a -> Bool

-- | Array holding <a>PrimUnlifted</a> values.
data UnliftedArray a
UnliftedArray :: ArrayArray# -> UnliftedArray a

-- | Mutable array holding <a>PrimUnlifted</a> values.
data MutableUnliftedArray s a
MutableUnliftedArray :: MutableArrayArray# s -> MutableUnliftedArray s a

-- | Types with <a>TYPE</a> <a>UnliftedRep</a>, which can be stored /
--   retrieved in <a>ArrayArray#</a>.
class PrimUnlifted a
writeUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> a -> State# s -> State# s
readUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> State# s -> (# State# s, a #)
indexUnliftedArray# :: PrimUnlifted a => ArrayArray# -> Int# -> a

-- | Exceptions generated by array operations
data ArrayException

-- | An attempt was made to index an array outside its declared bounds.
IndexOutOfBounds :: String -> ArrayException

-- | An attempt was made to evaluate an element of an array that had not
--   been initialized.
UndefinedElement :: String -> ArrayException

-- | <a>Cast</a> between primitive types of the same size.
class Cast source destination

-- | Cast between arrays
castArray :: (Arr arr a, Cast a b) => arr a -> arr b

-- | Cast between mutable arrays
castMutableArray :: (Arr arr a, Cast a b) => MArr arr s a -> MArr arr s b

-- | Size of values of type <tt>a</tt>. The argument is not used.
--   
--   This function has existed since 0.1, but was moved from
--   <a>Primitive</a> to <a>Types</a> in version 0.6.3.0
sizeOf :: Prim a => a -> Int
instance Z.Data.Array.Arr Data.Primitive.Array.Array a
instance Z.Data.Array.Arr Data.Primitive.SmallArray.SmallArray a
instance Data.Primitive.Types.Prim a => Z.Data.Array.Arr Data.Primitive.PrimArray.PrimArray a
instance Z.Data.Array.UnliftedArray.PrimUnlifted a => Z.Data.Array.Arr Z.Data.Array.UnliftedArray.UnliftedArray a


-- | This module provides functions for writing <a>PrimArray</a> related
--   literals <tt>QuasiQuote</tt>.
--   
--   <pre>
--   &gt; :set -XQuasiQuotes
--   &gt; :t [arrASCII|asdfg|]
--   [arrASCII|asdfg|] :: PrimArray GHC.Word.Word8
--   &gt; [arrASCII|asdfg|]
--   fromListN 5 [97,115,100,102,103]
--   &gt; :t [arrI16|1,2,3,4,5|]
--   [arrI16|1,2,3,4,5|] :: PrimArray GHC.Int.Int16
--   &gt; [arrI16|1,2,3,4,5|]
--   fromListN 5 [1,2,3,4,5]
--   </pre>
module Z.Data.Array.QQ

-- | <pre>
--   [arrASCII|asdfg|] :: PrimArray Word8
--   </pre>
arrASCII :: QuasiQuoter

-- | <pre>
--   [arrW8|1,2,3,4,5|] :: PrimArray Word8
--   </pre>
arrW8 :: QuasiQuoter

-- | <pre>
--   [arrW16|1,2,3,4,5|] :: PrimArray Word16
--   </pre>
arrW16 :: QuasiQuoter

-- | <pre>
--   [arrW32|1,2,3,4,5|] :: PrimArray Word32
--   </pre>
arrW32 :: QuasiQuoter

-- | <pre>
--   [arrW64|1,2,3,4,5|] :: PrimArray Word64
--   </pre>
arrW64 :: QuasiQuoter

-- | <pre>
--   [arrWord|1,2,3,4,5|] :: PrimArray Word
--   </pre>
arrWord :: QuasiQuoter

-- | <pre>
--   [arrW8|1,2,3,4,5|] :: PrimArray Int8
--   </pre>
arrI8 :: QuasiQuoter

-- | <pre>
--   [arrI16|1,2,3,4,5|] :: PrimArray Int16
--   </pre>
arrI16 :: QuasiQuoter

-- | <pre>
--   [arrI32|1,2,3,4,5|] :: PrimArray Int32
--   </pre>
arrI32 :: QuasiQuoter

-- | <pre>
--   [arrI64|1,2,3,4,5|] :: PrimArray Int64
--   </pre>
arrI64 :: QuasiQuoter

-- | <pre>
--   [arrInt|1,2,3,4,5|] :: PrimArray Int
--   </pre>
arrInt :: QuasiQuoter
asciiLiteral :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct data with UTF8 encoded literals.
--   
--   See <a>asciiLiteral</a>
utf8Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct data with array literals <tt>e.g. 1,2,3</tt>.
arrayLiteral :: ([Integer] -> Q [Word8]) -> (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Word8</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
word8Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Word16</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
word16Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Word32</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
word32Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Word64</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
word64Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Word</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
wordLiteral :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Int8</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
int8Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Int16</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
int16Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Int32</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
int32Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Int64</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
int64Literal :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ

-- | Construct <a>PrimArray</a> <a>Int</a> with array literals <tt>e.g.
--   1,2,3</tt>. See <a>asciiLiteral</a>
intLiteral :: (ExpQ -> ExpQ -> ExpQ) -> String -> ExpQ
word8ArrayFromAddr :: Int -> Addr# -> PrimArray Word8
word16ArrayFromAddr :: Int -> Addr# -> PrimArray Word16
word32ArrayFromAddr :: Int -> Addr# -> PrimArray Word32
word64ArrayFromAddr :: Int -> Addr# -> PrimArray Word64
wordArrayFromAddr :: Int -> Addr# -> PrimArray Word
int8ArrayFromAddr :: Int -> Addr# -> PrimArray Int8
int16ArrayFromAddr :: Int -> Addr# -> PrimArray Int16
int32ArrayFromAddr :: Int -> Addr# -> PrimArray Int32
int64ArrayFromAddr :: Int -> Addr# -> PrimArray Int64
intArrayFromAddr :: Int -> Addr# -> PrimArray Int


-- | This module provides exactly the same API with <a>Z.Data.Array</a>,
--   but will throw an <a>IndexOutOfBounds</a> <a>ArrayException</a> on
--   bound check failure, it's useful when debugging array algorithms: just
--   swap this module with <a>Z.Data.Array</a>, segmentation faults caused
--   by out bound access will be turned into exceptions with more
--   informations.
module Z.Data.Array.Checked

-- | A typeclass to unify box &amp; unboxed, mutable &amp; immutable array
--   operations.
--   
--   Most of these functions simply wrap their primitive counterpart, if
--   there's no primitive ones, we polyfilled using other operations to get
--   the same semantics.
--   
--   One exception is that <a>shrinkMutableArr</a> only perform closure
--   resizing on <a>PrimArray</a> because current RTS support only that,
--   <a>shrinkMutableArr</a> will do nothing on other array type.
--   
--   It's reasonable to trust GHC with specializing &amp; inlining these
--   polymorphric functions. They are used across this package and perform
--   identical to their monomophric counterpart.
class Arr (arr :: * -> *) a

-- | Mutable version of this array type.
type family MArr arr = (mar :: * -> * -> *) | mar -> arr
singletonArr :: Arr arr a => a -> arr a
doubletonArr :: Arr arr a => a -> a -> arr a
modifyIndexArr :: (Arr arr a, HasCallStack) => arr a -> Int -> Int -> Int -> (a -> a) -> arr a

-- | Insert an immutable array's element at given index to produce a new
--   array.
insertIndexArr :: Arr arr a => arr a -> Int -> Int -> Int -> a -> arr a

-- | Drop an immutable array's element at given index to produce a new
--   array.
deleteIndexArr :: Arr arr a => arr a -> Int -> Int -> Int -> arr a

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld

-- | Boxed arrays
data Array a
Array :: Array# a -> Array a
[array#] :: Array a -> Array# a

-- | Mutable boxed arrays associated with a primitive state token.
data MutableArray s a
MutableArray :: MutableArray# s a -> MutableArray s a
[marray#] :: MutableArray s a -> MutableArray# s a
data SmallArray a
SmallArray :: SmallArray# a -> SmallArray a
data SmallMutableArray s a
SmallMutableArray :: SmallMutableArray# s a -> SmallMutableArray s a

-- | Bottom value (<tt>throw (<a>UndefinedElement</a>
--   <a>uninitialized</a>)</tt>) for initialize new boxed
--   array(<a>Array</a>, <a>SmallArray</a>..).
uninitialized :: a

-- | Arrays of unboxed elements. This accepts types like <a>Double</a>,
--   <a>Char</a>, <a>Int</a>, and <a>Word</a>, as well as their
--   fixed-length variants (<tt>Word8</tt>, <tt>Word16</tt>, etc.). Since
--   the elements are unboxed, a <a>PrimArray</a> is strict in its
--   elements. This differs from the behavior of <tt>Array</tt>, which is
--   lazy in its elements.
data PrimArray a
PrimArray :: ByteArray# -> PrimArray a

-- | Mutable primitive arrays associated with a primitive state token.
--   These can be written to and read from in a monadic context that
--   supports sequencing such as <a>IO</a> or <a>ST</a>. Typically, a
--   mutable primitive array will be built and then convert to an immutable
--   primitive array using <a>unsafeFreezePrimArray</a>. However, it is
--   also acceptable to simply discard a mutable primitive array since it
--   lives in managed memory and will be garbage collected when no longer
--   referenced.
data MutablePrimArray s a
MutablePrimArray :: MutableByteArray# s -> MutablePrimArray s a

-- | Class of types supporting primitive array operations. This includes
--   interfacing with GC-managed memory (functions suffixed with
--   <tt>ByteArray#</tt>) and interfacing with unmanaged memory (functions
--   suffixed with <tt>Addr#</tt>). Endianness is platform-dependent.
class Prim a

-- | Size of values of type <tt>a</tt>. The argument is not used.
sizeOf# :: Prim a => a -> Int#

-- | Alignment of values of type <tt>a</tt>. The argument is not used.
alignment# :: Prim a => a -> Int#

-- | Read a value from the array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
indexByteArray# :: Prim a => ByteArray# -> Int# -> a

-- | Read a value from the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)

-- | Write a value to the mutable array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s

-- | Fill a slice of the mutable array with a value. The offset and length
--   of the chunk are in elements of type <tt>a</tt> rather than in bytes.
setByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s

-- | Read a value from a memory position given by an address and an offset.
--   The memory block the address refers to must be immutable. The offset
--   is in elements of type <tt>a</tt> rather than in bytes.
indexOffAddr# :: Prim a => Addr# -> Int# -> a

-- | Read a value from a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
readOffAddr# :: Prim a => Addr# -> Int# -> State# s -> (# State# s, a #)

-- | Write a value to a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
writeOffAddr# :: Prim a => Addr# -> Int# -> a -> State# s -> State# s

-- | Fill a memory block given by an address, an offset and a length. The
--   offset and length are in elements of type <tt>a</tt> rather than in
--   bytes.
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s
newArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => Int -> m (MArr arr s a)
newArrWith :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => Int -> a -> m (MArr arr s a)
readArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> m a
writeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> a -> m ()
setArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> Int -> a -> m ()
indexArr :: (Arr arr a, HasCallStack) => arr a -> Int -> a
indexArr' :: (Arr arr a, HasCallStack) => arr a -> Int -> (# a #)
indexArrM :: (Arr arr a, Monad m, HasCallStack) => arr a -> Int -> m a
freezeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> Int -> m (arr a)
thawArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => arr a -> Int -> Int -> m (MArr arr s a)
copyArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> arr a -> Int -> Int -> m ()
copyMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> MArr arr s a -> Int -> Int -> m ()
moveArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> MArr arr s a -> Int -> Int -> m ()
cloneArr :: (Arr arr a, HasCallStack) => arr a -> Int -> Int -> arr a
cloneMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> Int -> m (MArr arr s a)
resizeMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> m (MArr arr s a)

-- | New size should be &gt;= 0, and &lt;= original size.
shrinkMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s, HasCallStack) => MArr arr s a -> Int -> m ()

-- | In place freeze a mutable array, the original mutable array can not be
--   used anymore.
unsafeFreezeArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> m (arr a)

-- | In place thaw a immutable array, the original immutable array can not
--   be used anymore.
unsafeThawArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => arr a -> m (MArr arr s a)

-- | Is two mutable array are reference equal.
sameMutableArr :: Arr arr a => MArr arr s a -> MArr arr s a -> Bool

-- | Size of immutable array.
sizeofArr :: Arr arr a => arr a -> Int

-- | Size of mutable array.
sizeofMutableArr :: (Arr arr a, PrimMonad m, PrimState m ~ s) => MArr arr s a -> m Int

-- | Is two immutable array are referencing the same one.
--   
--   Note that <a>sameArr</a> 's result may change depending on compiler's
--   optimizations, for example <tt>let arr = runST ... in arr
--   <a>sameArr</a> arr</tt> may return false if compiler decides to inline
--   it.
--   
--   See <a>https://ghc.haskell.org/trac/ghc/ticket/13908</a> for more
--   background.
sameArr :: Arr arr a => arr a -> arr a -> Bool

-- | Create a <i>pinned</i> byte array of the specified size, The garbage
--   collector is guaranteed not to move it.
newPinnedPrimArray :: (PrimMonad m, Prim a, HasCallStack) => Int -> m (MutablePrimArray (PrimState m) a)

-- | Create a <i>pinned</i> primitive array of the specified size and
--   respect given primitive type's alignment. The garbage collector is
--   guaranteed not to move it.
newAlignedPinnedPrimArray :: (PrimMonad m, Prim a, HasCallStack) => Int -> m (MutablePrimArray (PrimState m) a)
copyPrimArrayToPtr :: (PrimMonad m, Prim a, HasCallStack) => Ptr a -> PrimArray a -> Int -> Int -> m ()
copyMutablePrimArrayToPtr :: (PrimMonad m, Prim a, HasCallStack) => Ptr a -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a, HasCallStack) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> prim arrays allocated by <tt>newPinnedByteArray</tt> or
--   <tt>newAlignedPinnedByteArray</tt>.
primArrayContents :: PrimArray a -> Ptr a

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <tt>newPinnedByteArray</tt> or
--   <tt>newAlignedPinnedByteArray</tt>.
mutablePrimArrayContents :: MutablePrimArray s a -> Ptr a

-- | Yield a pointer to the array's data and do computation with it.
--   
--   This operation is only safe on <i>pinned</i> primitive arrays
--   allocated by <a>newPinnedPrimArray</a> or
--   <a>newAlignedPinnedPrimArray</a>.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimArrayContents :: PrimArray a -> (Ptr a -> IO b) -> IO b

-- | Yield a pointer to the array's data and do computation with it.
--   
--   This operation is only safe on <i>pinned</i> primitive arrays
--   allocated by <a>newPinnedPrimArray</a> or
--   <a>newAlignedPinnedPrimArray</a>.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withMutablePrimArrayContents :: MutablePrimArray RealWorld a -> (Ptr a -> IO b) -> IO b

-- | Check whether or not the byte array is pinned. Pinned primitive arrays
--   cannot be moved by the garbage collector. It is safe to use
--   <a>primArrayContents</a> on such byte arrays. This function is only
--   available when compiling with GHC 8.2 or newer.
isPrimArrayPinned :: PrimArray a -> Bool

-- | Check whether or not the mutable primitive array is pinned. This
--   function is only available when compiling with GHC 8.2 or newer.
isMutablePrimArrayPinned :: MutablePrimArray s a -> Bool

-- | Array holding <a>PrimUnlifted</a> values.
data UnliftedArray a
UnliftedArray :: ArrayArray# -> UnliftedArray a

-- | Mutable array holding <a>PrimUnlifted</a> values.
data MutableUnliftedArray s a
MutableUnliftedArray :: MutableArrayArray# s -> MutableUnliftedArray s a

-- | Types with <a>TYPE</a> <a>UnliftedRep</a>, which can be stored /
--   retrieved in <a>ArrayArray#</a>.
class PrimUnlifted a
writeUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> a -> State# s -> State# s
readUnliftedArray# :: PrimUnlifted a => MutableArrayArray# s -> Int# -> State# s -> (# State# s, a #)
indexUnliftedArray# :: PrimUnlifted a => ArrayArray# -> Int# -> a

-- | Exceptions generated by array operations
data ArrayException

-- | An attempt was made to index an array outside its declared bounds.
IndexOutOfBounds :: String -> ArrayException

-- | An attempt was made to evaluate an element of an array that had not
--   been initialized.
UndefinedElement :: String -> ArrayException

-- | <a>Cast</a> between primitive types of the same size.
class Cast source destination

-- | Cast between arrays
castArray :: (Arr arr a, Cast a b) => arr a -> arr b

-- | Cast between mutable arrays
castMutableArray :: (Arr arr a, Cast a b) => MArr arr s a -> MArr arr s b

-- | Size of values of type <tt>a</tt>. The argument is not used.
--   
--   This function has existed since 0.1, but was moved from
--   <a>Primitive</a> to <a>Types</a> in version 0.6.3.0
sizeOf :: Prim a => a -> Int


-- | Internal module, provides lookup table for converting numeric value
--   into ASCII bytes.
module Z.Data.Builder.Numeric.DigitTable
decDigitTable :: Ptr Word8
hexDigitTable :: Ptr Word8
hexDigitTableUpper :: Ptr Word8


-- | This module provides a helper class to compute product size via
--   <a>Generic</a> instance, e.g. This class is useful during JSON
--   deserializing, to decide the array length used to store record KVs.
module Z.Data.Generics.Utils

-- | type class for calculating product size.
class KnownNat (PSize f) => ProductSize (f :: * -> *) where {
    type family PSize f :: Nat;
}
productSize :: forall f. KnownNat (PSize f) => Proxy# f -> Int
instance Z.Data.Generics.Utils.ProductSize (GHC.Generics.S1 s a)
instance (GHC.TypeNats.KnownNat (Z.Data.Generics.Utils.PSize a GHC.TypeNats.+ Z.Data.Generics.Utils.PSize b), Z.Data.Generics.Utils.ProductSize a, Z.Data.Generics.Utils.ProductSize b) => Z.Data.Generics.Utils.ProductSize (a GHC.Generics.:*: b)


-- | This package provide fast unboxed references for ST monad. Unboxed
--   reference is implemented using single cell MutableByteArray s to
--   eliminate indirection overhead which MutVar# s a carry, on the
--   otherhand unboxed reference only support limited type(instances of
--   <a>Prim</a> class).
module Z.Data.PrimRef.PrimSTRef

-- | A mutable variable in the ST monad which can hold an instance of
--   <a>Prim</a>.
newtype PrimSTRef s a
PrimSTRef :: MutableByteArray s -> PrimSTRef s a

-- | Build a new <a>PrimSTRef</a>
newPrimSTRef :: Prim a => a -> ST s (PrimSTRef s a)

-- | Read the value of an <a>PrimSTRef</a>
readPrimSTRef :: Prim a => PrimSTRef s a -> ST s a

-- | Write a new value into an <a>PrimSTRef</a>
writePrimSTRef :: Prim a => PrimSTRef s a -> a -> ST s ()

-- | Mutate the contents of an <a>PrimSTRef</a>.
--   
--   Unboxed reference is always strict on the value it hold.
modifyPrimSTRef :: Prim a => PrimSTRef s a -> (a -> a) -> ST s ()


-- | This package provide fast unboxed references for IO monad and atomic
--   operations for <a>Counter</a> type. Unboxed reference is implemented
--   using single cell MutableByteArray s to eliminate indirection overhead
--   which MutVar# s a carry, on the otherhand unboxed reference only
--   support limited type(instances of Prim class).
--   
--   Atomic operations on <a>Counter</a> type are implemented using
--   fetch-and-add primitives, which is much faster than a CAS
--   loop(<tt>atomicModifyIORef</tt>). Beside basic atomic counter usage,
--   you can also leverage idempotence of <tt>and 0</tt>, <tt>or (-1)</tt>
--   to make a concurrent flag.
module Z.Data.PrimRef.PrimIORef

-- | A mutable variable in the IO monad which can hold an instance of
--   <a>Prim</a>.
data PrimIORef a

-- | Build a new <a>PrimIORef</a>
newPrimIORef :: Prim a => a -> IO (PrimIORef a)

-- | Read the value of an <a>PrimIORef</a>
readPrimIORef :: Prim a => PrimIORef a -> IO a

-- | Write a new value into an <a>PrimIORef</a>
writePrimIORef :: Prim a => PrimIORef a -> a -> IO ()

-- | Mutate the contents of an <tt>IORef</tt>.
--   
--   Unboxed reference is always strict on the value it hold.
modifyPrimIORef :: Prim a => PrimIORef a -> (a -> a) -> IO ()

-- | Alias for 'PrimIORef Int' which support several atomic operations.
type Counter = PrimIORef Int

-- | Build a new <a>Counter</a>
newCounter :: Int -> IO Counter

-- | Atomically add a <a>Counter</a>, return the value BEFORE added.
atomicAddCounter :: Counter -> Int -> IO Int

-- | Atomically sub a <a>Counter</a>, return the value BEFORE subbed.
atomicSubCounter :: Counter -> Int -> IO Int

-- | Atomically and a <a>Counter</a>, return the value BEFORE anded.
atomicAndCounter :: Counter -> Int -> IO Int

-- | Atomically nand a <a>Counter</a>, return the value BEFORE nanded.
atomicNandCounter :: Counter -> Int -> IO Int

-- | Atomically or a <a>Counter</a>, return the value BEFORE ored.
atomicOrCounter :: Counter -> Int -> IO Int

-- | Atomically xor a <a>Counter</a>, return the value BEFORE xored.
atomicXorCounter :: Counter -> Int -> IO Int

-- | Atomically add a <a>Counter</a>, return the value AFTER added.
atomicAddCounter' :: Counter -> Int -> IO Int

-- | Atomically sub a <a>Counter</a>, return the value AFTER subbed.
atomicSubCounter' :: Counter -> Int -> IO Int

-- | Atomically and a <a>Counter</a>, return the value AFTER anded.
atomicAndCounter' :: Counter -> Int -> IO Int

-- | Atomically nand a <a>Counter</a>, return the value AFTER nanded.
atomicNandCounter' :: Counter -> Int -> IO Int

-- | Atomically or a <a>Counter</a>, return the value AFTER ored.
atomicOrCounter' :: Counter -> Int -> IO Int

-- | Atomically xor a <a>Counter</a>, return the value AFTER xored.
atomicXorCounter' :: Counter -> Int -> IO Int

-- | Atomically add a <a>Counter</a>.
atomicAddCounter_ :: Counter -> Int -> IO ()

-- | Atomically sub a <a>Counter</a>
atomicSubCounter_ :: Counter -> Int -> IO ()

-- | Atomically and a <a>Counter</a>
atomicAndCounter_ :: Counter -> Int -> IO ()

-- | Atomically nand a <a>Counter</a>
atomicNandCounter_ :: Counter -> Int -> IO ()

-- | Atomically or a <a>Counter</a>
atomicOrCounter_ :: Counter -> Int -> IO ()

-- | Atomically xor a <a>Counter</a>
atomicXorCounter_ :: Counter -> Int -> IO ()


-- | This module provide fast unboxed references for ST and IO monad, and
--   atomic operations for <a>Counter</a> type. Unboxed reference is
--   implemented using single cell MutableByteArray s to eliminate
--   indirection overhead which MutVar# s a carry, on the otherhand unboxed
--   reference only support limited type(instances of Prim class).
module Z.Data.PrimRef

-- | A mutable variable in the ST monad which can hold an instance of
--   <a>Prim</a>.
data PrimSTRef s a

-- | Build a new <a>PrimSTRef</a>
newPrimSTRef :: Prim a => a -> ST s (PrimSTRef s a)

-- | Read the value of an <a>PrimSTRef</a>
readPrimSTRef :: Prim a => PrimSTRef s a -> ST s a

-- | Write a new value into an <a>PrimSTRef</a>
writePrimSTRef :: Prim a => PrimSTRef s a -> a -> ST s ()

-- | Mutate the contents of an <a>PrimSTRef</a>.
--   
--   Unboxed reference is always strict on the value it hold.
modifyPrimSTRef :: Prim a => PrimSTRef s a -> (a -> a) -> ST s ()

-- | A mutable variable in the IO monad which can hold an instance of
--   <a>Prim</a>.
data PrimIORef a

-- | Build a new <a>PrimIORef</a>
newPrimIORef :: Prim a => a -> IO (PrimIORef a)

-- | Read the value of an <a>PrimIORef</a>
readPrimIORef :: Prim a => PrimIORef a -> IO a

-- | Write a new value into an <a>PrimIORef</a>
writePrimIORef :: Prim a => PrimIORef a -> a -> IO ()

-- | Mutate the contents of an <tt>IORef</tt>.
--   
--   Unboxed reference is always strict on the value it hold.
modifyPrimIORef :: Prim a => PrimIORef a -> (a -> a) -> IO ()

-- | Alias for 'PrimIORef Int' which support several atomic operations.
type Counter = PrimIORef Int

-- | Build a new <a>Counter</a>
newCounter :: Int -> IO Counter

-- | Atomically add a <a>Counter</a>, return the value BEFORE added.
atomicAddCounter :: Counter -> Int -> IO Int

-- | Atomically sub a <a>Counter</a>, return the value BEFORE subbed.
atomicSubCounter :: Counter -> Int -> IO Int

-- | Atomically and a <a>Counter</a>, return the value BEFORE anded.
atomicAndCounter :: Counter -> Int -> IO Int

-- | Atomically nand a <a>Counter</a>, return the value BEFORE nanded.
atomicNandCounter :: Counter -> Int -> IO Int

-- | Atomically or a <a>Counter</a>, return the value BEFORE ored.
atomicOrCounter :: Counter -> Int -> IO Int

-- | Atomically xor a <a>Counter</a>, return the value BEFORE xored.
atomicXorCounter :: Counter -> Int -> IO Int

-- | Atomically add a <a>Counter</a>, return the value AFTER added.
atomicAddCounter' :: Counter -> Int -> IO Int

-- | Atomically sub a <a>Counter</a>, return the value AFTER subbed.
atomicSubCounter' :: Counter -> Int -> IO Int

-- | Atomically and a <a>Counter</a>, return the value AFTER anded.
atomicAndCounter' :: Counter -> Int -> IO Int

-- | Atomically nand a <a>Counter</a>, return the value AFTER nanded.
atomicNandCounter' :: Counter -> Int -> IO Int

-- | Atomically or a <a>Counter</a>, return the value AFTER ored.
atomicOrCounter' :: Counter -> Int -> IO Int

-- | Atomically xor a <a>Counter</a>, return the value AFTER xored.
atomicXorCounter' :: Counter -> Int -> IO Int

-- | Atomically add a <a>Counter</a>.
atomicAddCounter_ :: Counter -> Int -> IO ()

-- | Atomically sub a <a>Counter</a>
atomicSubCounter_ :: Counter -> Int -> IO ()

-- | Atomically and a <a>Counter</a>
atomicAndCounter_ :: Counter -> Int -> IO ()

-- | Atomically nand a <a>Counter</a>
atomicNandCounter_ :: Counter -> Int -> IO ()

-- | Atomically or a <a>Counter</a>
atomicOrCounter_ :: Counter -> Int -> IO ()

-- | Atomically xor a <a>Counter</a>
atomicXorCounter_ :: Counter -> Int -> IO ()


-- | UTF-8 codecs and helpers.
module Z.Data.Text.UTF8Codec

-- | Return a codepoint's encoded length in bytes
--   
--   If the codepoint is invalid, we return 3(encoded bytes length of
--   replacement char <tt>U+FFFD</tt>).
encodeCharLength :: Char -> Int

-- | Encode a <a>Char</a> into bytes, write <a>replacementChar</a> for
--   invalid unicode codepoint.
--   
--   This function assumed there're enough space for encoded bytes, and
--   return the advanced index.
encodeChar :: PrimMonad m => MutablePrimArray (PrimState m) Word8 -> Int -> Char -> m Int

-- | The unboxed version of <a>encodeChar</a>.
--   
--   This function is marked as <tt>NOINLINE</tt> to reduce code size, and
--   stop messing up simplifier due to too much branches.
encodeChar# :: MutableByteArray# s -> Int# -> Char# -> State# s -> (# State# s, Int# #)

-- | Encode a <a>Char</a> into bytes with non-standard UTF-8 encoding(Used
--   in <a>Data.CBytes</a>).
--   
--   <tt>\NUL</tt> is encoded as two bytes <tt>C0 80</tt> , <tt>\xD800</tt>
--   ~ <tt>\xDFFF</tt> is encoded as a three bytes normal UTF-8 codepoint.
--   This function assumed there're enough space for encoded bytes, and
--   return the advanced index.
encodeCharModifiedUTF8 :: PrimMonad m => MutablePrimArray (PrimState m) Word8 -> Int -> Char -> m Int

-- | The unboxed version of <a>encodeCharModifiedUTF8</a>.
encodeCharModifiedUTF8# :: MutableByteArray# s -> Int# -> Char# -> State# s -> (# State# s, Int# #)

-- | Decode a <a>Char</a> from bytes
--   
--   This function assumed all bytes are UTF-8 encoded, and the index param
--   point to the beginning of a codepoint, the decoded character and the
--   advancing offset are returned.
--   
--   It's annoying to use unboxed tuple here but we really don't want
--   allocation even if GHC can't optimize it away.
decodeChar :: PrimArray Word8 -> Int -> (# Char, Int #)
decodeChar_ :: PrimArray Word8 -> Int -> Char

-- | The unboxed version of <a>decodeChar</a>
--   
--   This function is marked as <tt>NOINLINE</tt> to reduce code size, and
--   stop messing up simplifier due to too much branches.
decodeChar# :: ByteArray# -> Int# -> (# Char#, Int# #)

-- | Decode a codepoint's length in bytes
--   
--   This function assumed all bytes are UTF-8 encoded, and the index param
--   point to the beginning of a codepoint.
decodeCharLen :: PrimArray Word8 -> Int -> Int

-- | The unboxed version of <a>decodeCharLen</a>
--   
--   This function is marked as <tt>NOINLINE</tt> to reduce code size, and
--   stop messing up simplifier due to too much branches.
decodeCharLen# :: ByteArray# -> Int# -> Int#

-- | Decode a <a>Char</a> from bytes in rerverse order.
--   
--   This function assumed all bytes are UTF-8 encoded, and the index param
--   point to the end of a codepoint, the decoded character and the
--   backward advancing offset are returned.
decodeCharReverse :: PrimArray Word8 -> Int -> (# Char, Int #)
decodeCharReverse_ :: PrimArray Word8 -> Int -> Char

-- | The unboxed version of <a>decodeCharReverse</a>
--   
--   This function is marked as <tt>NOINLINE</tt> to reduce code size, and
--   stop messing up simplifier due to too much branches.
decodeCharReverse# :: ByteArray# -> Int# -> (# Char#, Int# #)

-- | Decode a codepoint's length in bytes in reverse order.
--   
--   This function assumed all bytes are UTF-8 encoded, and the index param
--   point to the end of a codepoint.
decodeCharLenReverse :: PrimArray Word8 -> Int -> Int

-- | The unboxed version of <a>decodeCharLenReverse</a>
--   
--   This function is marked as <tt>NOINLINE</tt> to reduce code size, and
--   stop messing up simplifier due to too much branches.
decodeCharLenReverse# :: ByteArray# -> Int# -> Int#
between# :: Word# -> Word# -> Word# -> Bool
isContinueByte# :: Word# -> Bool
chr1# :: Word# -> Char#
chr2# :: Word# -> Word# -> Char#
chr3# :: Word# -> Word# -> Word# -> Char#
chr4# :: Word# -> Word# -> Word# -> Word# -> Char#

-- | Unrolled copy loop for copying a utf8-encoded codepoint from source
--   array to target array.
copyChar :: Int -> MutablePrimArray s Word8 -> Int -> PrimArray Word8 -> Int -> ST s ()

-- | Unrolled copy loop for copying a utf8-encoded codepoint from source
--   array to target array.
copyChar' :: Int -> MutablePrimArray s Word8 -> Int -> MutablePrimArray s Word8 -> Int -> ST s ()

-- | <tt>xFFFD</tt>, which will be encoded as <tt>0xEF 0xBF 0xBD</tt> 3
--   bytes.
replacementChar :: Char


-- | INTERNAL MODULE, provides utf8rewind constants
module Z.Data.Text.UTF8Rewind

-- | Locale for case mapping.
type Locale = CSize
pattern LocaleDefault :: Locale
pattern LocaleLithuanian :: Locale
pattern LocaleTurkishAndAzeriLatin :: Locale

-- | Get environment locale
envLocale :: IO Locale

-- | These are the Unicode Normalization Forms:
--   
--   <pre>
--   Form                         | Description
--   ---------------------------- | ---------------------------------------------
--   Normalization Form D (NFD)   | Canonical decomposition
--   Normalization Form C (NFC)   | Canonical decomposition, followed by canonical composition
--   Normalization Form KD (NFKD) | Compatibility decomposition
--   Normalization Form KC (NFKC) | Compatibility decomposition, followed by canonical composition
--   </pre>
data NormalizeMode
NFC :: NormalizeMode
NFKC :: NormalizeMode
NFD :: NormalizeMode
NFKD :: NormalizeMode
normalizeModeToFlag :: NormalizeMode -> CSize
data NormalizationResult
NormalizedYes :: NormalizationResult
NormalizedMaybe :: NormalizationResult
NormalizedNo :: NormalizationResult
toNormalizationResult :: Int -> NormalizationResult

-- | Unicode categories.
--   
--   See <a>isCategory</a>, you can combine categories with bitwise or.
type Category = CSize
pattern CategoryLetterUppercase :: Category
pattern CategoryLetterLowercase :: Category
pattern CategoryLetterTitlecase :: Category
pattern CategoryLetterOther :: Category
pattern CategoryLetter :: Category
pattern CategoryCaseMapped :: Category
pattern CategoryMarkNonSpacing :: Category
pattern CategoryMarkSpacing :: Category
pattern CategoryMarkEnclosing :: Category
pattern CategoryMark :: Category
pattern CategoryNumberDecimal :: Category
pattern CategoryNumberLetter :: Category
pattern CategoryNumberOther :: Category
pattern CategoryNumber :: Category
pattern CategoryPunctuationConnector :: Category
pattern CategoryPunctuationDash :: Category
pattern CategoryPunctuationOpen :: Category
pattern CategoryPunctuationClose :: Category
pattern CategoryPunctuationInitial :: Category
pattern CategoryPunctuationFinal :: Category
pattern CategoryPunctuationOther :: Category
pattern CategoryPunctuation :: Category
pattern CategorySymbolMath :: Category
pattern CategorySymbolCurrency :: Category
pattern CategorySymbolModifier :: Category
pattern CategorySymbolOther :: Category
pattern CategorySymbol :: Category
pattern CategorySeparatorSpace :: Category
pattern CategorySeparatorLine :: Category
pattern CategorySeparatorParagraph :: Category
pattern CategorySeparator :: Category
pattern CategoryControl :: Category
pattern CategoryFormat :: Category
pattern CategorySurrogate :: Category
pattern CategoryPrivateUse :: Category
pattern CategoryUnassigned :: Category
pattern CategoryCompatibility :: Category
pattern CategoryIgnoreGraphemeCluster :: Category
pattern CategoryIscntrl :: Category
pattern CategoryIsprint :: Category
pattern CategoryIsspace :: Category
pattern CategoryIsblank :: Category
pattern CategoryIsgraph :: Category
pattern CategoryIspunct :: Category
pattern CategoryIsalnum :: Category
pattern CategoryIsalpha :: Category
pattern CategoryIsupper :: Category
pattern CategoryIslower :: Category
pattern CategoryIsdigit :: Category
pattern CategoryIsxdigit :: Category
instance GHC.Generics.Generic Z.Data.Text.UTF8Rewind.NormalizeMode
instance GHC.Classes.Ord Z.Data.Text.UTF8Rewind.NormalizeMode
instance GHC.Classes.Eq Z.Data.Text.UTF8Rewind.NormalizeMode
instance GHC.Show.Show Z.Data.Text.UTF8Rewind.NormalizeMode
instance GHC.Generics.Generic Z.Data.Text.UTF8Rewind.NormalizationResult
instance GHC.Classes.Ord Z.Data.Text.UTF8Rewind.NormalizationResult
instance GHC.Classes.Eq Z.Data.Text.UTF8Rewind.NormalizationResult
instance GHC.Show.Show Z.Data.Text.UTF8Rewind.NormalizationResult


-- | This module provides unified vector interface. Conceptually a vector
--   is simply a slice of an array, for example this is the definition of
--   boxed vector:
--   
--   <pre>
--   data Vector a = Vector !(SmallArray a)   !Int    !Int
--                        -- payload           offset  length
--   </pre>
--   
--   The <a>Vec</a> class unified different type of vectors, and this
--   module provide operation over <a>Vec</a> instances, with all the
--   internal structures. Be careful on modifying internal slices,
--   otherwise segmentation fault await.
module Z.Data.Vector.Base

-- | Typeclass for box and unboxed vectors, which are created by slicing
--   arrays.
--   
--   Instead of providing a generalized vector with polymorphric array
--   field, we use this typeclass so that instances use concrete array type
--   can unpack their array payload.
--   
--   Vector types, e.g. <a>Vector</a>,<a>PrimVector</a>... are obivious
--   instances, with O(1) <a>toArr</a> and <a>fromArr</a>, which convert
--   slices to (array, offset, length) tuple back and forth.
--   
--   Array types can also be instances of this class, e.g. <a>Array</a>,
--   <a>PrimArray</a>..., in this case <a>toArr</a> will always return
--   offset 0 and whole array length, and <a>fromArr</a> is O(n)
--   <a>copyArr</a>.
class (Arr (IArray v) a) => Vec v a where {
    
    -- | Vector's immutable array type
    type family IArray v :: * -> *;
}

-- | Get underline array and slice range(offset and length).
toArr :: Vec v a => v a -> (IArray v a, Int, Int)

-- | Create a vector by slicing an array(with offset and length).
fromArr :: Vec v a => IArray v a -> Int -> Int -> v a

-- | A pattern synonyms for matching the underline array, offset and
--   length.
--   
--   This is a bidirectional pattern synonyms, but very unsafe if not use
--   properly. Make sure your slice is within array's bounds!
pattern Vec :: Vec v a => IArray v a -> Int -> Int -> v a

-- | Construct a <a>Vec</a> by slicing a whole array.
arrVec :: Vec v a => IArray v a -> v a

-- | <i>O(1)</i> Index vector's element.
--   
--   Return <a>Nothing</a> if index is out of bounds.
indexMaybe :: Vec v a => v a -> Int -> Maybe a

-- | Boxed vector
data Vector a
Vector :: {-# UNPACK #-} !SmallArray a -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Vector a

-- | Primitive vector
data PrimVector a
PrimVector :: {-# UNPACK #-} !PrimArray a -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> PrimVector a

-- | <a>Bytes</a> is just primitive word8 vectors.
type Bytes = PrimVector Word8

-- | <i>O(n)</i>, pack an ASCII <a>String</a>, multi-bytes char WILL BE
--   CHOPPED!
packASCII :: String -> Bytes

-- | Create a vector with size N.
create :: Vec v a => Int -> (forall s. MArr (IArray v) s a -> ST s ()) -> v a

-- | Create a vector with a initial size N array (which may not be the
--   final array).
create' :: Vec v a => Int -> (forall s. MArr (IArray v) s a -> ST s (IPair (MArr (IArray v) s a))) -> v a

-- | Create a vector with a initial size N array, return both the vector
--   and the monadic result during creating.
--   
--   The result is not demanded strictly while the returned vector will be
--   in normal form. It this is not desired, use <tt>return $!</tt> idiom
--   in your initialization function.
creating :: Vec v a => Int -> (forall s. MArr (IArray v) s a -> ST s b) -> (b, v a)

-- | Create a vector with a initial size N array (which may not be the
--   final array), return both the vector and the monadic result during
--   creating.
--   
--   The result is not demanded strictly while the returned vector will be
--   in normal form. It this is not desired, use <tt>return $!</tt> idiom
--   in your initialization function.
creating' :: Vec v a => Int -> (forall s. MArr (IArray v) s a -> ST s (b, IPair (MArr (IArray v) s a))) -> (b, v a)

-- | Create a vector up to a specific length.
--   
--   If the initialization function return a length larger than initial
--   size, an <a>IndexOutOfVectorRange</a> will be raised.
createN :: (Vec v a, HasCallStack) => Int -> (forall s. MArr (IArray v) s a -> ST s Int) -> v a

-- | Create two vector up to a specific length.
--   
--   If the initialization function return lengths larger than initial
--   sizes, an <a>IndexOutOfVectorRange</a> will be raised.
createN2 :: (Vec v a, Vec u b, HasCallStack) => Int -> Int -> (forall s. MArr (IArray v) s a -> MArr (IArray u) s b -> ST s (Int, Int)) -> (v a, u b)

-- | <i>O(1)</i>. The empty vector.
empty :: Vec v a => v a

-- | <i>O(1)</i>. Single element vector.
singleton :: Vec v a => a -> v a

-- | <i>O(n)</i>. Copy a vector from slice.
copy :: Vec v a => v a -> v a

-- | <i>O(n)</i> Convert a list into a vector
--   
--   Alias for <tt><a>packN</a> <a>defaultInitSize</a></tt>.
pack :: Vec v a => [a] -> v a

-- | <i>O(n)</i> Convert a list into a vector with an approximate size.
--   
--   If the list's length is large than the size given, we simply double
--   the buffer size and continue building.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Convert a list into a vector with given size.
--   
--   If the list's length is large than the size given, we drop the rest
--   elements.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN' :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Alias for <tt><a>packRN</a> <a>defaultInitSize</a></tt>.
packR :: Vec v a => [a] -> v a

-- | <i>O(n)</i> <a>packN</a> in reverse order.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> <a>packN'</a> in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; packRN' 3 [1,2,3,4,5]
--   
--   &gt;&gt;&gt; [3,2,1]
--   </pre>
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN' :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Convert vector to a list.
--   
--   Unpacking is done lazily. i.e. we will retain reference to the array
--   until all element are consumed.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpack :: Vec v a => v a -> [a]

-- | <i>O(n)</i> Convert vector to a list in reverse order.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpackR :: Vec v a => v a -> [a]

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Vec v a => v a -> Bool

-- | <i>O(1)</i> The length of a vector.
length :: Vec v a => v a -> Int

-- | <i>O(m+n)</i>
--   
--   There's no need to guard empty vector because we guard them for you,
--   so appending empty vectors are no-ops.
append :: Vec v a => v a -> v a -> v a

-- | Mapping between vectors (possiblely with two different vector types).
--   
--   NOTE, the result vector contain thunks in lifted <a>Vector</a> case,
--   use <a>map'</a> if that's not desired.
--   
--   For <a>PrimVector</a>, <a>map</a> and <a>map'</a> are same, since
--   <a>PrimVector</a>s never store thunks.
map :: forall u v a b. (Vec u a, Vec v b) => (a -> b) -> u a -> v b

-- | Mapping between vectors (possiblely with two different vector types).
--   
--   This is the strict version map. Note that the <a>Functor</a> instance
--   of lifted <a>Vector</a> is defined with <a>map</a> to statisfy laws,
--   which this strict version breaks (<tt>map' id arrayContainsBottom /=
--   arrayContainsBottom </tt>).
map' :: forall u v a b. (Vec u a, Vec v b) => (a -> b) -> u a -> v b

-- | Strict mapping with index.
imap' :: forall u v a b. (Vec u a, Vec v b) => (Int -> a -> b) -> u a -> v b

-- | Traverse vector and gather result in another vector,
traverseVec :: (Vec v a, Vec u b, Applicative f) => (a -> f b) -> v a -> f (u b)

-- | Traverse vector and gather result in another vector,
traverseWithIndex :: (Vec v a, Vec u b, Applicative f) => (Int -> a -> f b) -> v a -> f (u b)

-- | Traverse vector without gathering result.
traverseVec_ :: (Vec v a, Applicative f) => (a -> f b) -> v a -> f ()

-- | Traverse vector with index.
traverseWithIndex_ :: (Vec v a, Applicative f) => (Int -> a -> f b) -> v a -> f ()

-- | Strict left to right fold.
foldl' :: Vec v a => (b -> a -> b) -> b -> v a -> b

-- | Strict left to right fold with index.
ifoldl' :: Vec v a => (b -> Int -> a -> b) -> b -> v a -> b

-- | Strict left to right fold using first element as the initial value.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
foldl1' :: forall v a. (Vec v a, HasCallStack) => (a -> a -> a) -> v a -> a

-- | Strict left to right fold using first element as the initial value.
--   return <a>Nothing</a> when vector is empty.
foldl1Maybe' :: forall v a. Vec v a => (a -> a -> a) -> v a -> Maybe a

-- | Strict right to left fold
foldr' :: Vec v a => (a -> b -> b) -> b -> v a -> b

-- | Strict right to left fold with index
--   
--   NOTE: the index is counting from 0, not backwards
ifoldr' :: Vec v a => (Int -> a -> b -> b) -> b -> v a -> b

-- | Strict right to left fold using last element as the initial value.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
foldr1' :: forall v a. (Vec v a, HasCallStack) => (a -> a -> a) -> v a -> a

-- | Strict right to left fold using last element as the initial value,
--   return <a>Nothing</a> when vector is empty.
foldr1Maybe' :: forall v a. Vec v a => (a -> a -> a) -> v a -> Maybe a

-- | <i>O(n)</i> Concatenate a list of vector.
--   
--   Note: <a>concat</a> have to force the entire list to filter out empty
--   vector and calculate the length for allocation.
concat :: forall v a. Vec v a => [v a] -> v a

-- | Map a function over a vector and concatenate the results
concatMap :: Vec v a => (a -> v a) -> v a -> v a

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a vector
--   
--   It's defined with <a>foldl1'</a>, an <a>EmptyVector</a> exception will
--   be thrown in the case of an empty vector.
maximum :: (Vec v a, Ord a, HasCallStack) => v a -> a

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <tt>vector</tt>
--   
--   An <a>EmptyVector</a> exception will be thrown in the case of an empty
--   vector.
minimum :: (Vec v a, Ord a, HasCallStack) => v a -> a

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a vector,
--   return <a>Nothing</a> in the case of an empty vector.
maximumMaybe :: (Vec v a, Ord a) => v a -> Maybe a

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a vector,
--   return <a>Nothing</a> in the case of an empty vector.
minimumMaybe :: (Vec v a, Ord a) => v a -> Maybe a

-- | <i>O(n)</i> <a>sum</a> returns the sum value from a <tt>vector</tt>
sum :: (Vec v a, Num a) => v a -> a

-- | <i>O(n)</i> <a>count</a> returns count of an element from a
--   <tt>vector</tt>
count :: (Vec v a, Eq a) => a -> v a -> Int

-- | <i>O(n)</i> <a>product</a> returns the product value from a vector
product :: (Vec v a, Num a) => v a -> a

-- | <i>O(n)</i> <a>product</a> returns the product value from a vector
--   
--   This function will shortcut on zero. Note this behavior change the
--   semantics for lifted vector: <tt>product [1,0,undefined] /= product'
--   [1,0,undefined]</tt>.
product' :: (Vec v a, Num a, Eq a) => v a -> a

-- | <i>O(n)</i> Applied to a predicate and a vector, <a>all</a> determines
--   if all elements of the vector satisfy the predicate.
all :: Vec v a => (a -> Bool) -> v a -> Bool

-- | <i>O(n)</i> Applied to a predicate and a vector, <a>any</a> determines
--   if any elements of the vector satisfy the predicate.
any :: Vec v a => (a -> Bool) -> v a -> Bool

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <tt>foldl</tt>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new list.
--   
--   Note, this function will only force the result tuple, not the elements
--   inside, to prevent creating thunks during <a>mapAccumL</a>, <a>seq</a>
--   your accumulator and result with the result tuple.
mapAccumL :: forall u v a b c. (Vec u b, Vec v c) => (a -> b -> (a, c)) -> a -> u b -> (a, v c)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <tt>foldr</tt>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   The same strictness property with <a>mapAccumL</a> applys to
--   <a>mapAccumR</a> too.
mapAccumR :: forall u v a b c. (Vec u b, Vec v c) => (a -> b -> (a, c)) -> a -> u b -> (a, v c)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a vector of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
--   
--   Note: <a>replicate</a> will not force the element in boxed vector
--   case.
replicate :: Vec v a => Int -> a -> v a

-- | <i>O(n*m)</i> <a>cycleN</a> a vector n times.
cycleN :: forall v a. Vec v a => Int -> v a -> v 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 vector from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   vector 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 :: Vec u b => (a -> Maybe (b, a)) -> a -> u b

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a vector 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 :: forall v a b. Vec v b => Int -> (a -> Maybe (b, a)) -> a -> (v b, Maybe a)

-- | <i>O(n)</i> <a>elem</a> test if given element is in given vector.
elem :: (Vec v a, Eq a) => a -> v a -> Bool

-- | <i>O(n)</i> 'not . elem'
notElem :: (Vec v a, Eq a) => a -> v a -> Bool

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given vector which is equal to the query element,
--   or <a>Nothing</a> if there is no such element.
elemIndex :: (Vec v a, Eq a) => a -> v a -> Maybe Int

-- | Pair type to help GHC unpack in some loops, useful when write fast
--   folds.
data IPair a
IPair :: {-# UNPACK #-} !Int -> a -> IPair a
[ifst] :: IPair a -> {-# UNPACK #-} !Int
[isnd] :: IPair a -> a

-- | Unlike <a>Functor</a> instance, this mapping evaluate value inside
--   <a>IPair</a> strictly.
mapIPair' :: (a -> b) -> IPair a -> IPair b
fromIPair :: IPair a -> (Int, a)
toIPair :: (Int, a) -> IPair a

-- | <tt>defaultInitSize = 30</tt>, used as initialize size when packing
--   list of unknown size.
defaultInitSize :: Int

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

-- | The chunk size used for I/O. Currently set to <tt>16k -
--   chunkOverhead</tt>
defaultChunkSize :: Int

-- | The recommended chunk size. Currently set to <tt>4k -
--   chunkOverhead</tt>.
smallChunkSize :: Int

-- | All exception can be throw by using <a>Vec</a>.
data VectorException
IndexOutOfVectorRange :: {-# UNPACK #-} !Int -> CallStack -> VectorException
EmptyVector :: CallStack -> VectorException
errorEmptyVector :: HasCallStack => a
errorOutRange :: HasCallStack => Int -> a

-- | Cast between vectors
castVector :: (Vec v a, Cast a b) => v a -> v b
c_strcmp :: Addr# -> Addr# -> IO CInt
c_memchr :: ByteArray# -> Int -> Word8 -> Int -> Int
c_memrchr :: ByteArray# -> Int -> Word8 -> Int -> Int
c_strlen :: Addr# -> IO CSize
c_ascii_validate_addr :: Addr# -> Int -> IO Int
c_fnv_hash_addr :: Addr# -> Int -> Int -> IO Int
c_fnv_hash_ba :: ByteArray# -> Int -> Int -> Int -> IO Int
instance GHC.Classes.Ord a => GHC.Classes.Ord (Z.Data.Vector.Base.IPair a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Z.Data.Vector.Base.IPair a)
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Vector.Base.IPair a)
instance GHC.Show.Show Z.Data.Vector.Base.VectorException
instance GHC.Exception.Type.Exception Z.Data.Vector.Base.VectorException
instance Test.QuickCheck.Arbitrary.Arbitrary v => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.Base.IPair v)
instance Test.QuickCheck.Arbitrary.CoArbitrary v => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.Base.IPair v)
instance GHC.Base.Functor Z.Data.Vector.Base.IPair
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Z.Data.Vector.Base.IPair a)
instance Data.CaseInsensitive.Internal.FoldCase Z.Data.Vector.Base.Bytes
instance Data.Primitive.Types.Prim a => Z.Data.Vector.Base.Vec Z.Data.Vector.Base.PrimVector a
instance (Data.Primitive.Types.Prim a, GHC.Classes.Eq a) => GHC.Classes.Eq (Z.Data.Vector.Base.PrimVector a)
instance (Data.Primitive.Types.Prim a, GHC.Classes.Ord a) => GHC.Classes.Ord (Z.Data.Vector.Base.PrimVector a)
instance Data.Primitive.Types.Prim a => GHC.Base.Semigroup (Z.Data.Vector.Base.PrimVector a)
instance Data.Primitive.Types.Prim a => GHC.Base.Monoid (Z.Data.Vector.Base.PrimVector a)
instance Control.DeepSeq.NFData (Z.Data.Vector.Base.PrimVector a)
instance (Data.Primitive.Types.Prim a, GHC.Show.Show a) => GHC.Show.Show (Z.Data.Vector.Base.PrimVector a)
instance (Data.Primitive.Types.Prim a, GHC.Read.Read a) => GHC.Read.Read (Z.Data.Vector.Base.PrimVector a)
instance (Data.Primitive.Types.Prim a, Test.QuickCheck.Arbitrary.Arbitrary a) => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.Base.PrimVector a)
instance (Data.Primitive.Types.Prim a, Test.QuickCheck.Arbitrary.CoArbitrary a) => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.Base.PrimVector a)
instance (Data.Hashable.Class.Hashable a, Data.Primitive.Types.Prim a) => Data.Hashable.Class.Hashable (Z.Data.Vector.Base.PrimVector a)
instance (a GHC.Types.~ GHC.Word.Word8) => Data.String.IsString (Z.Data.Vector.Base.PrimVector a)
instance Data.Primitive.Types.Prim a => GHC.Exts.IsList (Z.Data.Vector.Base.PrimVector a)
instance Z.Data.Vector.Base.Vec Z.Data.Vector.Base.Vector a
instance GHC.Exts.IsList (Z.Data.Vector.Base.Vector a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Z.Data.Vector.Base.Vector a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Z.Data.Vector.Base.Vector a)
instance GHC.Base.Semigroup (Z.Data.Vector.Base.Vector a)
instance GHC.Base.Monoid (Z.Data.Vector.Base.Vector a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Z.Data.Vector.Base.Vector a)
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Vector.Base.Vector a)
instance GHC.Read.Read a => GHC.Read.Read (Z.Data.Vector.Base.Vector a)
instance GHC.Base.Functor Z.Data.Vector.Base.Vector
instance Data.Foldable.Foldable Z.Data.Vector.Base.Vector
instance Data.Traversable.Traversable Z.Data.Vector.Base.Vector
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.Base.Vector a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.Base.Vector a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Z.Data.Vector.Base.Vector a)
instance Data.Hashable.Class.Hashable1 Z.Data.Vector.Base.Vector
instance Z.Data.Vector.Base.Vec Data.Primitive.Array.Array a
instance Z.Data.Vector.Base.Vec Data.Primitive.SmallArray.SmallArray a
instance Data.Primitive.Types.Prim a => Z.Data.Vector.Base.Vec Data.Primitive.PrimArray.PrimArray a
instance Z.Data.Array.UnliftedArray.PrimUnlifted a => Z.Data.Vector.Base.Vec Z.Data.Array.UnliftedArray.UnliftedArray a


-- | This module provides functions for writing vector literals using
--   <tt>QuasiQuote</tt> similar to <a>Z.Data.Array.QQ</a> module.
--   
--   <pre>
--   &gt; :set -XQuasiQuotes
--   &gt; :t [vecASCII|asdfg|]
--   [vecASCII|asdfg|] :: Z.Data.Vector.Base.PrimVector GHC.Word.Word8
--   &gt; [vecASCII|asdfg|]
--   [97,115,100,102,103]
--   &gt; :t [vecI16|1,2,3,4,5|]
--   [vecI16|1,2,3,4,5|] :: Z.Data.Vector.Base.PrimVector GHC.Int.Int16
--   &gt; [vecI16|1,2,3,4,5|]
--   [1,2,3,4,5]
--   </pre>
module Z.Data.Vector.QQ
vecASCII :: QuasiQuoter
vecW8 :: QuasiQuoter
vecW16 :: QuasiQuoter
vecW32 :: QuasiQuoter
vecW64 :: QuasiQuoter
vecWord :: QuasiQuoter
vecI8 :: QuasiQuoter
vecI16 :: QuasiQuoter
vecI32 :: QuasiQuoter
vecI64 :: QuasiQuoter
vecInt :: QuasiQuoter


-- | This module provides:
--   
--   <ul>
--   <li>Element-wise searching within vectors</li>
--   <li>Fast sub-vector searching algorithm based on KMP string
--   searching.</li>
--   <li>A hybrid sub-vector searching algorithm for <a>Bytes</a>.</li>
--   <li>Rewrite rules to use <a>Bytes</a> specialized version if
--   possible.</li>
--   </ul>
module Z.Data.Vector.Search

-- | The <a>findIndex</a> function takes a predicate and a vector and
--   returns the index of the first element in the vector satisfying the
--   predicate.
findIndices :: Vec v a => (a -> Bool) -> v a -> [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.
elemIndices :: (Vec v a, Eq a) => a -> v a -> [Int]

-- | <i>O(n)</i> find the first index and element matching the predicate in
--   a vector from left to right, if there isn't one, return (length of the
--   vector, Nothing).
find :: Vec v a => (a -> Bool) -> v a -> (Int, Maybe a)

-- | <i>O(n)</i> Find the first index and element matching the predicate in
--   a vector from right to left, if there isn't one, return '(-1,
--   Nothing)'.
findR :: Vec v a => (a -> Bool) -> v a -> (Int, Maybe a)

-- | <pre>
--   findIndex f v = fst (find f v)
--   </pre>
findIndex :: Vec v a => (a -> Bool) -> v a -> Int

-- | <pre>
--   findIndexR f v = fst (findR f v)
--   </pre>
findIndexR :: Vec v a => (a -> Bool) -> v a -> Int

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a vector,
--   returns a vector containing those elements that satisfy the predicate.
filter :: forall v a. Vec v a => (a -> Bool) -> v a -> v a

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

-- | <i>O(n+m)</i> Find the offsets of all indices (possibly overlapping)
--   of <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm.
--   
--   The KMP algorithm need pre-calculate a shift table in <i>O(m)</i> time
--   and space, the worst case time complexity is <i>O(n+m)</i>. Partial
--   apply this function to reuse pre-calculated table between same
--   needles.
--   
--   Chunked input are support via partial match argument, if set we will
--   return an extra negative index in case of partial match at the end of
--   input chunk, e.g.
--   
--   <pre>
--   indicesOverlapping [ascii|ada|]  [ascii|adadad|] True == [0,2,-2]
--   </pre>
--   
--   Where <tt>-2</tt> is the length of the partial match part <tt>ad</tt>
--   's negation.
--   
--   If an empty pattern is supplied, we will return every possible index
--   of haystack, e.g.
--   
--   <pre>
--   indicesOverlapping "" "abc" = [0,1,2]
--   </pre>
--   
--   References:
--   
--   <ul>
--   <li>Knuth, Donald; Morris, James H.; Pratt, Vaughan: "Fast pattern
--   matching in strings" (1977)</li>
--   
--   <li><a>http://www-igm.univ-mlv.fr/~lecroq/string/node8.html#SECTION0080</a></li>
--   </ul>
indicesOverlapping :: (Vec v a, Eq a) => v a -> v a -> Bool -> [Int]

-- | <i>O(n+m)</i> Find the offsets of all non-overlapping indices of
--   <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm.
--   
--   If an empty pattern is supplied, we will return every possible index
--   of haystack, e.g.
--   
--   <pre>
--   indicesOverlapping "" "abc" = [0,1,2]
--   </pre>
indices :: (Vec v a, Eq a) => v a -> v a -> Bool -> [Int]

-- | <i>O(n)</i> Special <a>elemIndices</a> for <a>Bytes</a> using
--   <tt>memchr(3)</tt>
elemIndicesBytes :: Word8 -> Bytes -> [Int]

-- | <i>O(n)</i> Special <a>findByte</a> for <a>Word8</a> using
--   <tt>memchr(3)</tt>
findByte :: Word8 -> Bytes -> (Int, Maybe Word8)

-- | <i>O(n)</i> Special <a>findR</a> for <a>Bytes</a> with
--   <tt>memrchr</tt>.
findByteR :: Word8 -> Bytes -> (Int, Maybe Word8)

-- | <i>O(n/m)</i> Find the offsets of all indices (possibly overlapping)
--   of <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm,
--   combined with simplified sunday's rule to obtain <i>O(n/m)</i>
--   complexity in average use case.
--   
--   The hybrid algorithm need pre-calculate a shift table in <i>O(m)</i>
--   time and space, and a bad character bloom filter in <i>O(m)</i> time
--   and <i>O(1)</i> space, the worst case time complexity is
--   <i>O(n+m)</i>.
--   
--   References:
--   
--   <ul>
--   <li>Frantisek FranekChristopher G. JenningsWilliam F. Smyth A Simple
--   Fast Hybrid Pattern-Matching Algorithm (2005)</li>
--   <li>D. M. Sunday: A Very Fast Substring Search Algorithm.
--   Communications of the ACM, 33, 8, 132-142 (1990)</li>
--   <li>F. Lundh: The Fast Search Algorithm.
--   <a>http://effbot.org/zone/stringlib.htm</a> (2006)</li>
--   </ul>
indicesOverlappingBytes :: Bytes -> Bytes -> Bool -> [Int]

-- | <i>O(n/m)</i> Find the offsets of all non-overlapping indices of
--   <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm, combined
--   with simplified sunday's rule to obtain <i>O(m/n)</i> complexity in
--   average use case.
indicesBytes :: Bytes -> Bytes -> Bool -> [Int]

-- | <i>O(m)</i> Calculate the KMP next shift table.
--   
--   The shifting rules is: when a mismatch between <tt>needle[j]</tt> and
--   <tt>haystack[i]</tt> is found, check if <tt>next[j] == -1</tt>, if so
--   next search continue with <tt>needle[0]</tt> and
--   <tt>haystack[i+1]</tt>, otherwise continue with
--   <tt>needle[next[j]]</tt> and <tt>haystack[i]</tt>.
kmpNextTable :: (Vec v a, Eq a) => v a -> PrimArray Int

-- | <i>O(m)</i> Calculate a simple bloom filter for simplified sunday's
--   rule.
--   
--   The shifting rules is: when a mismatch between <tt>needle[j]</tt> and
--   <tt>haystack[i]</tt> is found, check if <tt>elemSundayBloom bloom
--   haystack[i+n-j]</tt>, where n is the length of needle, if not then
--   next search can be safely continued with <tt>haystack[i+n-j+1]</tt>
--   and <tt>needle[0]</tt>, otherwise next searh should continue with
--   <tt>haystack[i]</tt> and <tt>needle[0]</tt>, or fallback to other
--   shifting rules such as KMP.
--   
--   The algorithm is very simple: for a given <a>Word8</a> <tt>w</tt>, we
--   set the bloom's bit at <tt>unsafeShiftL 0x01 (w .&amp;. 0x3f)</tt>, so
--   there're three false positives per bit. This's particularly suitable
--   for search UTF-8 bytes since the significant bits of a beginning byte
--   is usually the same.
sundayBloom :: Bytes -> Word64

-- | O(1) Test if a bloom filter contain a certain <a>Word8</a>.
elemSundayBloom :: Word64 -> Word8 -> Bool


-- | Various combinators works on <a>Vec</a> class instances.
module Z.Data.Vector.Extra

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Vec v a => a -> v a -> v a

-- | <i>O(n)</i> Append a byte to the end of a vector
snoc :: Vec v a => v a -> a -> v a

-- | <i>O(1)</i> Extract the head and tail of a vector, return
--   <a>Nothing</a> if it is empty.
uncons :: Vec v a => v a -> Maybe (a, v a)

-- | <i>O(1)</i> Extract the init and last of a vector, return
--   <a>Nothing</a> if vector is empty.
unsnoc :: Vec v a => v a -> Maybe (v a, a)

-- | <i>O(1)</i> Extract the first element of a vector.
headMaybe :: Vec v a => v a -> Maybe a

-- | <i>O(1)</i> Extract the elements after the head of a vector.
--   
--   NOTE: <a>tailMayEmpty</a> return empty vector in the case of an empty
--   vector.
tailMayEmpty :: Vec v a => v a -> v a

-- | <i>O(1)</i> Extract the last element of a vector.
lastMaybe :: Vec v a => v a -> Maybe a

-- | <i>O(1)</i> Extract the elements before of the last one.
--   
--   NOTE: <a>initMayEmpty</a> return empty vector in the case of an empty
--   vector.
initMayEmpty :: Vec v a => v a -> v a

-- | <i>O(n)</i> Return all initial segments of the given vector, empty
--   first.
inits :: Vec v a => v a -> [v a]

-- | <i>O(n)</i> Return all final segments of the given vector, whole
--   vector first.
tails :: Vec v a => v a -> [v a]

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a vector <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 :: Vec v a => Int -> v a -> v a

-- | <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 :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> <a>takeR</a> <tt>n</tt>, applied to a vector <tt>xs</tt>,
--   returns the suffix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
takeR :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> <a>dropR</a> <tt>n xs</tt> returns the prefix of
--   <tt>xs</tt> before the last <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
dropR :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> Extract a sub-range vector with give start index and
--   length.
--   
--   This function is a total function just like 'take<i>drop',
--   index</i>length exceeds range will be ingored, e.g.
--   
--   <pre>
--   slice 1 3 "hello"   == "ell"
--   slice -1 -1 "hello" == ""
--   slice -2 2 "hello"  == ""
--   slice 2 10 "hello"  == "llo"
--   </pre>
--   
--   This holds for all x y: <tt>slice x y vs == drop x . take (x+y)
--   vs</tt>
slice :: Vec v a => Int -> Int -> v a -> v a

-- | <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 :: Vec v a => Int -> v a -> (v a, v a)

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the longest prefix (possibly empty) of
--   <tt>vs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the longest suffix (possibly empty) of
--   <tt>vs</tt> of elements that satisfy <tt>p</tt>.
takeWhileR :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the suffix (possibly empty) remaining after
--   <a>takeWhile</a> <tt>p vs</tt>.
dropWhile :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the prefix (possibly empty) remaining before
--   <a>takeWhileR</a> <tt>p vs</tt>.
dropWhileR :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> <tt>dropAround f = dropWhile f . dropWhileR f</tt>
dropAround :: Vec v a => (a -> Bool) -> 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.
--   
--   <tt>break (==x)</tt> will be rewritten using a <tt>memchr</tt>.
break :: Vec 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.
--   
--   <tt>span (/=x)</tt> will be rewritten using a <tt>memchr</tt>.
span :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | <a>breakR</a> behaves like <a>break</a> but from the end of the
--   vector.
--   
--   <pre>
--   breakR p == spanR (not.p)
--   </pre>
breakR :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | <a>spanR</a> behaves like <a>span</a> but from the end of the vector.
spanR :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | Break a vector on a subvector, returning a pair of the part of the
--   vector prior to the match, and the rest of the vector, e.g.
--   
--   <pre>
--   break "wor" "hello, world" = ("hello, ", "world")
--   </pre>
breakOn :: (Vec v a, Eq a) => v a -> v a -> (v a, v a)
group :: (Vec v a, Eq a) => v a -> [v a]
groupBy :: forall v a. Vec v a => (a -> a -> Bool) -> v a -> [v a]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two vectors and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: (Vec v a, Eq (v a)) => v a -> v a -> Maybe (v a)

-- | O(n) The <a>stripSuffix</a> function takes two vectors and returns
--   Just the remainder of the second iff the first is its suffix, and
--   otherwise Nothing.
stripSuffix :: (Vec v a, Eq (v a)) => v a -> v a -> Maybe (v a)

-- | <i>O(n)</i> Break a vector into pieces separated by the delimiter
--   element consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
split :: (Vec v a, Eq a) => a -> v a -> [v a]

-- | <i>O(n)</i> Splits a vector 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 (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == [""]
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
splitWith :: Vec v a => (a -> Bool) -> v a -> [v a]

-- | <i>O(m+n)</i> Break haystack into pieces separated by needle.
--   
--   Note: An empty needle will essentially split haystack element by
--   element.
--   
--   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>
splitOn :: (Vec v a, Eq a) => v a -> v a -> [v a]

-- | The <tt>isPrefix</tt> function returns <a>True</a> if the first
--   argument is a prefix of the second.
isPrefixOf :: forall v a. (Vec v a, Eq (v a)) => v a -> v a -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two vectors and
--   returns <a>True</a> if the first is a suffix of the second.
isSuffixOf :: forall v a. (Vec v a, Eq (v a)) => v a -> v a -> Bool

-- | Check whether one vector is a subvector of another.
--   
--   <tt>needle <a>isInfixOf</a> haystack === null haystack || indices
--   needle haystake /= []</tt>.
isInfixOf :: (Vec v a, Eq a) => v a -> v a -> Bool

-- | <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. e.g.
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "foobar" "fooquux"
--   ("foo","bar","quux")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "veeble" "fetzer"
--   ("","veeble","fetzer")
--   </pre>
commonPrefix :: (Vec v a, Eq a) => v a -> v a -> (v a, v a, v a)

-- | <i>O(n)</i> Breaks a <a>Bytes</a> up into a list of words, delimited
--   by ascii space.
words :: Bytes -> [Bytes]

-- | <i>O(n)</i> Breaks a <a>Bytes</a> up into a list of lines, delimited
--   by ascii <tt>n</tt>.
lines :: Bytes -> [Bytes]

-- | <i>O(n)</i> Joins words with ascii space.
unwords :: [Bytes] -> Bytes

-- | <i>O(n)</i> Joins lines with ascii <tt>n</tt>.
--   
--   NOTE: This functions is different from <a>unlines</a>, it DOES NOT add
--   a trailing <tt>n</tt>.
unlines :: [Bytes] -> Bytes

-- | Add padding to the left so that the whole vector's length is at least
--   n.
padLeft :: Vec v a => Int -> a -> v a -> v a

-- | Add padding to the right so that the whole vector's length is at least
--   n.
padRight :: Vec v a => Int -> a -> v a -> v a

-- | <i>O(n)</i> <a>reverse</a> <tt>vs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: forall v a. Vec v a => v a -> v a

-- | <i>O(n)</i> The <a>intersperse</a> function takes an element and a
--   vector and `intersperses' that element between the elements of the
--   vector. It is analogous to the intersperse function on Lists.
intersperse :: forall v a. Vec v a => a -> v a -> v a

-- | <i>O(n)</i> The <a>intercalate</a> function takes a vector and a list
--   of vectors and concatenates the list after interspersing the first
--   argument between each element of the list.
--   
--   Note: <a>intercalate</a> will force the entire vector list.
intercalate :: Vec v a => v a -> [v a] -> v a

-- | <i>O(n)</i> An efficient way to join vector with an element.
intercalateElem :: forall v a. Vec v a => a -> [v a] -> v a

-- | The <a>transpose</a> function transposes the rows and columns of its
--   vector argument.
transpose :: Vec v a => [v a] -> [v a]

-- | <a>zipWith'</a> zip two vector with a zipping function.
--   
--   For example, <tt><a>zipWith</a> (+)</tt> is applied to two vector to
--   produce a vector of corresponding sums, the result will be evaluated
--   strictly.
zipWith' :: forall v a u b w c. (Vec v a, Vec u b, Vec w c) => (a -> b -> c) -> v a -> u b -> w c

-- | <a>unzipWith'</a> disassemble a vector with a disassembling function,
--   
--   The results inside tuple will be evaluated strictly.
unzipWith' :: forall v a u b w c. (Vec v a, Vec u b, Vec w c) => (a -> (b, c)) -> v a -> (u b, w c)

-- | <a>scanl'</a> is similar to <tt>foldl</tt>, 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>
--   lastM (scanl' f z xs) == Just (foldl f z xs).
--   </pre>
scanl' :: forall v u a b. (Vec v a, Vec u b) => (b -> a -> b) -> b -> v a -> u b

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

-- | scanr' is the right-to-left dual of scanl'.
scanr' :: forall v u a b. (Vec v a, Vec u b) => (a -> b -> b) -> b -> v a -> u b

-- | <a>scanr1'</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1' :: forall v a. Vec v a => (a -> a -> a) -> v a -> v a

-- | <tt>x' = rangeCut x min max</tt> limit <tt>x'</tt> 's range to
--   <tt>min</tt> ~ <tt>max</tt>.
rangeCut :: Int -> Int -> Int -> Int

-- | <i>O(1)</i> Extract the first element of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
head :: (Vec v a, HasCallStack) => v a -> a

-- | <i>O(1)</i> Extract the elements after the head of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
tail :: (Vec v a, HasCallStack) => v a -> v a

-- | <i>O(1)</i> Extract the elements before of the last one.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
init :: (Vec v a, HasCallStack) => v a -> v a

-- | <i>O(1)</i> Extract the last element of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
last :: (Vec v a, HasCallStack) => v a -> a

-- | <i>O(1)</i> Index array element.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
index :: (Vec v a, HasCallStack) => v a -> Int -> a

-- | <i>O(1)</i> Index array element.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
indexM :: (Vec v a, Monad m, HasCallStack) => v a -> Int -> m a

-- | <i>O(n)</i> Modify vector's element under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
modifyIndex :: (Vec v a, HasCallStack) => v a -> Int -> (a -> a) -> v a

-- | <i>O(n)</i> Modify vector's element under given index.
--   
--   Return original vector if index outside of the vector.
modifyIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> (a -> a) -> v a

-- | <i>O(n)</i> insert element to vector under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
insertIndex :: (Vec v a, HasCallStack) => v a -> Int -> a -> v a

-- | <i>O(n)</i> insert element to vector under given index.
--   
--   Return original vector if index outside of the vector.
insertIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> a -> v a

-- | <i>O(n)</i> Delete vector's element under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
deleteIndex :: (Vec v a, HasCallStack) => v a -> Int -> v a

-- | <i>O(n)</i> Delete vector's element under given index.
--   
--   Return original vector if index outside of the vector.
deleteIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> v a

-- | <i>O(1)</i> Extract the first element of a vector.
--   
--   Make sure vector is non-empty, otherwise segmentation fault await!
unsafeHead :: Vec v a => v a -> a

-- | <i>O(1)</i> Extract the elements after the head of a vector.
--   
--   Make sure vector is non-empty, otherwise segmentation fault await!
unsafeTail :: Vec v a => v a -> v a

-- | <i>O(1)</i> Extract the elements before of the last one.
--   
--   Make sure vector is non-empty, otherwise segmentation fault await!
unsafeInit :: Vec v a => v a -> v a

-- | <i>O(1)</i> Extract the last element of a vector.
--   
--   Make sure vector is non-empty, otherwise segmentation fault await!
unsafeLast :: Vec v a => v a -> a

-- | <i>O(1)</i> Index array element.
--   
--   Make sure index is in bound, otherwise segmentation fault await!
unsafeIndex :: Vec v a => v a -> Int -> a

-- | <i>O(1)</i> Index array element.
--   
--   Make sure index is in bound, otherwise segmentation fault await!
unsafeIndexM :: (Vec v a, Monad m) => v a -> Int -> m a

-- | <i>O(n)</i> Modify vector's element under given index.
--   
--   Make sure index is in bound, otherwise segmentation fault await!
unsafeModifyIndex :: (Vec v a, HasCallStack) => v a -> Int -> (a -> a) -> v a

-- | <i>O(n)</i> Insert element to vector under given index.
--   
--   Make sure index is in bound, otherwise segmentation fault await!
unsafeInsertIndex :: (Vec v a, HasCallStack) => v a -> Int -> a -> v a

-- | <i>O(n)</i> Delete vector's element under given index.
--   
--   Make sure index is in bound, otherwise segmentation fault await!
unsafeDeleteIndex :: (Vec v a, HasCallStack) => v a -> Int -> v a

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a vector <tt>xs</tt>,
--   returns the prefix of <tt>xs</tt> of length <tt>n</tt>.
--   
--   Make sure n is smaller than vector's length, otherwise segmentation
--   fault await!
unsafeTake :: Vec v a => Int -> v a -> v a

-- | <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.
--   
--   Make sure n is smaller than vector's length, otherwise segmentation
--   fault await!
unsafeDrop :: Vec v a => Int -> v a -> v a


-- | A <a>Text</a> wrap a <a>Bytes</a> which will be interpreted using
--   UTF-8 encoding. User should always use <a>validate</a> to construt a
--   <a>Text</a> (instead of using construtor directly or coercing),
--   otherwise illegal UTF-8 encoded codepoints will cause undefined
--   behaviours.
module Z.Data.Text.Base

-- | <a>Text</a> represented as UTF-8 encoded <a>Bytes</a>
newtype Text
Text :: Bytes -> Text

-- | Extract UTF-8 encoded <a>Bytes</a> from <a>Text</a>
[getUTF8Bytes] :: Text -> Bytes

-- | <i>O(n)</i> Validate a sequence of bytes is UTF-8 encoded.
--   
--   Throw <a>InvalidUTF8Exception</a> in case of invalid codepoint.
validate :: HasCallStack => Bytes -> Text

-- | <i>O(n)</i> Validate a sequence of bytes is all ascii char
--   byte(&lt;128).
--   
--   Throw <a>InvalidASCIIException</a> in case of invalid byte, It's not
--   always faster than <a>validate</a>, use it only if you want to
--   validate ASCII char sequences.
validateASCII :: HasCallStack => Bytes -> Text

-- | <i>O(n)</i> Validate a sequence of bytes is UTF-8 encoded.
--   
--   Return <a>Nothing</a> in case of invalid codepoint.
validateMaybe :: Bytes -> Maybe Text

-- | <i>O(n)</i> Validate a sequence of bytes is all ascii char
--   byte(&lt;128).
--   
--   Return <a>Nothing</a> in case of invalid byte.
validateASCIIMaybe :: Bytes -> Maybe Text

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a>, throw
--   <a>IndexOutOfTextRange</a> when out of bound.
index :: HasCallStack => Text -> Int -> Char

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a>.
indexMaybe :: Text -> Int -> Maybe Char

-- | <i>O(n)</i> Find the nth codepoint's byte index (pointing to the nth
--   char's begining byte).
--   
--   The index is only meaningful to the whole byte slice, if there's less
--   than n codepoints, the index will point to next byte after the end.
charByteIndex :: Text -> Int -> Int

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a> counting from the
--   end, throw <tt>IndexOutOfVectorRange n callStack</tt> when out of
--   bound.
indexR :: HasCallStack => Text -> Int -> Char

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a> counting from the
--   end.
indexMaybeR :: Text -> Int -> Maybe Char

-- | <i>O(n)</i> Find the nth codepoint's byte index from the end (pointing
--   to the previous char's ending byte).
--   
--   The index is only meaningful to the whole byte slice, if there's less
--   than n codepoints, the index will point to previous byte before the
--   start.
charByteIndexR :: Text -> Int -> Int

-- | <i>O(1)</i>. Empty text.
empty :: Text

-- | <i>O(1)</i>. Single char text.
singleton :: Char -> Text

-- | <i>O(n)</i>. Copy a text from slice.
copy :: Text -> Text

-- | <i>O(n)</i> <a>replicate</a> char n time.
replicate :: Int -> Char -> Text

-- | <i>O(n*m)</i> <a>cycleN</a> a text n times.
cycleN :: Int -> Text -> Text

-- | <i>O(n)</i> Convert a string into a text
--   
--   Alias for <tt><a>packN</a> <tt>defaultInitSize</tt></tt>, will be
--   rewritten to a memcpy if possible.
pack :: String -> Text

-- | <i>O(n)</i> Convert a list into a text with an approximate size(in
--   bytes, not codepoints).
--   
--   If the encoded bytes length is larger than the size given, we simply
--   double the buffer size and continue building.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN :: Int -> String -> Text

-- | <i>O(n)</i> Alias for <tt><a>packRN</a> <tt>defaultInitSize</tt></tt>.
packR :: String -> Text

-- | <i>O(n)</i> <a>packN</a> in reverse order.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN :: Int -> String -> Text

-- | <i>O(n)</i> Convert text to a char list.
--   
--   Unpacking is done lazily. i.e. we will retain reference to the array
--   until all element are consumed.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpack :: Text -> String

-- | <i>O(n)</i> Convert text to a list in reverse order.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpackR :: Text -> String

-- | <i>O(n)</i> convert from a char vector.
fromVector :: PrimVector Char -> Text

-- | <i>O(n)</i> convert to a char vector.
toVector :: Text -> PrimVector Char

-- | <i>O(1)</i> Test whether a text is empty.
null :: Text -> Bool

-- | <i>O(n)</i> The char length of a text.
length :: Text -> Int

-- | <i>O(m+n)</i>
--   
--   There's no need to guard empty vector because we guard them for you,
--   so appending empty text are no-ops.
append :: Text -> Text -> Text

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

-- | Strict mapping with index.
imap' :: (Int -> Char -> Char) -> Text -> Text

-- | Strict left to right fold.
foldl' :: (b -> Char -> b) -> b -> Text -> b

-- | Strict left to right fold with index.
ifoldl' :: (b -> Int -> Char -> b) -> b -> Text -> b

-- | Strict right to left fold
foldr' :: (Char -> b -> b) -> b -> Text -> b

-- | Strict right to left fold with index
--   
--   NOTE: the index is counting from 0, not backwards
ifoldr' :: (Int -> Char -> b -> b) -> b -> Text -> b

-- | <i>O(n)</i> Concatenate a list of text.
--   
--   Note: <a>concat</a> have to force the entire list to filter out empty
--   text and calculate the length for allocation.
concat :: [Text] -> Text

-- | Map a function over a text and concatenate the results
concatMap :: (Char -> Text) -> Text -> Text

-- | <i>O(n)</i> <a>count</a> returns count of an element from a text.
count :: Char -> Text -> Int

-- | <i>O(n)</i> Applied to a predicate and text, <a>all</a> determines if
--   all chars of the text satisfy the predicate.
all :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> Applied to a predicate and a text, <a>any</a> determines
--   if any chars of the text satisfy the predicate.
any :: (Char -> Bool) -> Text -> Bool

-- | Get the display width of a piece of text.
--   
--   You shouldn't pass texts with control characters(&lt;0x20, \DEL),
--   which are counted with -1 width.
--   
--   <pre>
--   &gt;&gt;&gt; displayWidth "你好世界！"
--   
--   &gt;&gt;&gt; 10
--   
--   &gt;&gt;&gt; displayWidth "hello world!"
--   
--   &gt;&gt;&gt; 12
--   </pre>
displayWidth :: Text -> Int
data NormalizationResult
NormalizedYes :: NormalizationResult
NormalizedMaybe :: NormalizationResult
NormalizedNo :: NormalizationResult

-- | These are the Unicode Normalization Forms:
--   
--   <pre>
--   Form                         | Description
--   ---------------------------- | ---------------------------------------------
--   Normalization Form D (NFD)   | Canonical decomposition
--   Normalization Form C (NFC)   | Canonical decomposition, followed by canonical composition
--   Normalization Form KD (NFKD) | Compatibility decomposition
--   Normalization Form KC (NFKC) | Compatibility decomposition, followed by canonical composition
--   </pre>
data NormalizeMode
NFC :: NormalizeMode
NFKC :: NormalizeMode
NFD :: NormalizeMode
NFKD :: NormalizeMode

-- | Check if a string is stable in the NFC (Normalization Form C).
isNormalized :: Text -> NormalizationResult

-- | Check if a string is stable in the specified Unicode Normalization
--   Form.
--   
--   This function can be used as a preprocessing step, before attempting
--   to normalize a string. Normalization is a very expensive process, it
--   is often cheaper to first determine if the string is unstable in the
--   requested normalization form.
--   
--   The result of the check will be YES if the string is stable and MAYBE
--   or NO if it is unstable. If the result is MAYBE, the string does not
--   necessarily have to be normalized.
--   
--   For more information, please review
--   &lt;<a>http://www.unicode.org/reports/tr15/</a> Unicode Standard Annex
--   #15 - Unicode Normalization Forms&gt;.
isNormalizedTo :: NormalizeMode -> Text -> NormalizationResult

-- | Normalize a string to NFC (Normalization Form C).
normalize :: Text -> Text

-- | Normalize a string to the specified Unicode Normalization Form.
--   
--   The Unicode standard defines two standards for equivalence between
--   characters: canonical and compatibility equivalence. Canonically
--   equivalent characters and sequence represent the same abstract
--   character and must be rendered with the same appearance and behavior.
--   Compatibility equivalent characters have a weaker equivalence and may
--   be rendered differently.
--   
--   Unicode Normalization Forms are formally defined standards that can be
--   used to test whether any two strings of characters are equivalent to
--   each other. This equivalence may be canonical or compatibility.
--   
--   The algorithm puts all combining marks into a specified order and uses
--   the rules for decomposition and composition to transform the string
--   into one of four Unicode Normalization Forms. A binary comparison can
--   then be used to determine equivalence.
normalizeTo :: NormalizeMode -> Text -> Text

-- | Get environment locale
envLocale :: IO Locale

-- | Remove case distinction from UTF-8 encoded text with default locale.
caseFold :: Text -> Text

-- | Remove case distinction from UTF-8 encoded text.
--   
--   Case folding is the process of eliminating differences between code
--   points concerning case mapping. It is most commonly used for comparing
--   strings in a case-insensitive manner. Conversion is fully compliant
--   with the Unicode 7.0 standard.
--   
--   Although similar to lowercasing text, there are significant
--   differences. For one, case folding does _not_ take locale into account
--   when converting. In some cases, case folding can be up to 20% faster
--   than lowercasing the same text, but the result cannot be treated as
--   correct lowercased text.
--   
--   Only two locale-specific exception are made when case folding text. In
--   Turkish, U+0049 LATIN CAPITAL LETTER I maps to U+0131 LATIN SMALL
--   LETTER DOTLESS I and U+0130 LATIN CAPITAL LETTER I WITH DOT ABOVE maps
--   to U+0069 LATIN SMALL LETTER I.
--   
--   Although most code points can be case folded without changing length,
--   there are notable exceptions. For example, U+0130 (LATIN CAPITAL
--   LETTER I WITH DOT ABOVE) maps to "U+0069 U+0307" (LATIN SMALL LETTER I
--   and COMBINING DOT ABOVE) when converted to lowercase.
--   
--   Only a handful of scripts make a distinction between upper- and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
caseFoldWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to lowercase with default locale.
toLower :: Text -> Text

-- | Convert UTF-8 encoded text to lowercase.
--   
--   This function allows conversion of UTF-8 encoded strings to lowercase
--   without first changing the encoding to UTF-32. Conversion is fully
--   compliant with the Unicode 7.0 standard.
--   
--   Although most code points can be converted to lowercase with changing
--   length, there are notable exceptions. For example, U+0130 (LATIN
--   CAPITAL LETTER I WITH DOT ABOVE) maps to "U+0069 U+0307" (LATIN SMALL
--   LETTER I and COMBINING DOT ABOVE) when converted to lowercase.
--   
--   Only a handful of scripts make a distinction between upper- and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
--   
--   Case mapping is not reversible. That is, <tt>toUpper(toLower(x)) !=
--   toLower(toUpper(x))</tt>.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toLowerWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to uppercase with default locale.
toUpper :: Text -> Text

-- | Convert UTF-8 encoded text to uppercase.
--   
--   Conversion is fully compliant with the Unicode 7.0 standard.
--   
--   Although most code points can be converted without changing length,
--   there are notable exceptions. For example, U+00DF (LATIN SMALL LETTER
--   SHARP S) maps to "U+0053 U+0053" (LATIN CAPITAL LETTER S and LATIN
--   CAPITAL LETTER S) when converted to uppercase.
--   
--   Only a handful of scripts make a distinction between upper and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
--   
--   Case mapping is not reversible. That is, <tt>toUpper(toLower(x)) !=
--   toLower(toUpper(x))</tt>.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toUpperWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to titlecase with default locale.
toTitle :: Text -> Text

-- | Convert UTF-8 encoded text to titlecase.
--   
--   This function allows conversion of UTF-8 encoded strings to titlecase.
--   Conversion is fully compliant with the Unicode 7.0 standard.
--   
--   Titlecase requires a bit more explanation than uppercase and
--   lowercase, because it is not a common text transformation. Titlecase
--   uses uppercase for the first letter of each word and lowercase for the
--   rest. Words are defined as "collections of code points with general
--   category Lu, Ll, Lt, Lm or Lo according to the Unicode database".
--   
--   Effectively, any type of punctuation can break up a word, even if this
--   is not grammatically valid. This happens because the titlecasing
--   algorithm does not and cannot take grammar rules into account.
--   
--   <pre>
--   Text                                 | Titlecase
--   -------------------------------------|-------------------------------------
--   The running man                      | The Running Man
--   NATO Alliance                        | Nato Alliance
--   You're amazing at building libraries | You'Re Amazing At Building Libraries
--   </pre>
--   
--   Although most code points can be converted to titlecase without
--   changing length, there are notable exceptions. For example, U+00DF
--   (LATIN SMALL LETTER SHARP S) maps to "U+0053 U+0073" (LATIN CAPITAL
--   LETTER S and LATIN SMALL LETTER S) when converted to titlecase.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toTitleWith :: Locale -> Text -> Text

-- | Check if the input string conforms to the category specified by the
--   flags.
--   
--   This function can be used to check if the code points in a string are
--   part of a category. Valid flags are members of the "list of
--   categories". The category for a code point is defined as part of the
--   entry in UnicodeData.txt, the data file for the Unicode code point
--   database.
--   
--   By default, the function will treat grapheme clusters as a single code
--   point. This means that the following string:
--   
--   <pre>
--   Code point | Canonical combining class | General category      | Name
--   ---------- | ------------------------- | --------------------- | ----------------------
--   U+0045     | 0                         | Lu (Uppercase letter) | LATIN CAPITAL LETTER E
--   U+0300     | 230                       | Mn (Non-spacing mark) | COMBINING GRAVE ACCENT
--   </pre>
--   
--   Will match with <a>CategoryLetterUppercase</a> in its entirety,
--   because the COMBINING GRAVE ACCENT is treated as part of the grapheme
--   cluster. This is useful when e.g. creating a text parser, because you
--   do not have to normalize the text first.
--   
--   If this is undesired behavior, specify the
--   <a>CategoryIgnoreGraphemeCluster</a> flag.
--   
--   In order to maintain backwards compatibility with POSIX functions like
--   <tt>isdigit</tt> and <tt>isspace</tt>, compatibility flags have been
--   provided. Note, however, that the result is only guaranteed to be
--   correct for code points in the Basic Latin range, between U+0000 and
--   0+007F. Combining a compatibility flag with a regular category flag
--   will result in undefined behavior.
isCategory :: Category -> Text -> Bool

-- | Try to match as many code points with the matching category flags as
--   possible and return the prefix and suffix.
spanCategory :: Category -> Text -> (Text, Text)

-- | Locale for case mapping.
type Locale = CSize
pattern LocaleDefault :: Locale
pattern LocaleLithuanian :: Locale
pattern LocaleTurkishAndAzeriLatin :: Locale

-- | Unicode categories.
--   
--   See <a>isCategory</a>, you can combine categories with bitwise or.
type Category = CSize
pattern CategoryLetterUppercase :: Category
pattern CategoryLetterLowercase :: Category
pattern CategoryLetterTitlecase :: Category
pattern CategoryLetterOther :: Category
pattern CategoryLetter :: Category
pattern CategoryCaseMapped :: Category
pattern CategoryMarkNonSpacing :: Category
pattern CategoryMarkSpacing :: Category
pattern CategoryMarkEnclosing :: Category
pattern CategoryMark :: Category
pattern CategoryNumberDecimal :: Category
pattern CategoryNumberLetter :: Category
pattern CategoryNumberOther :: Category
pattern CategoryNumber :: Category
pattern CategoryPunctuationConnector :: Category
pattern CategoryPunctuationDash :: Category
pattern CategoryPunctuationOpen :: Category
pattern CategoryPunctuationClose :: Category
pattern CategoryPunctuationInitial :: Category
pattern CategoryPunctuationFinal :: Category
pattern CategoryPunctuationOther :: Category
pattern CategoryPunctuation :: Category
pattern CategorySymbolMath :: Category
pattern CategorySymbolCurrency :: Category
pattern CategorySymbolModifier :: Category
pattern CategorySymbolOther :: Category
pattern CategorySymbol :: Category
pattern CategorySeparatorSpace :: Category
pattern CategorySeparatorLine :: Category
pattern CategorySeparatorParagraph :: Category
pattern CategorySeparator :: Category
pattern CategoryControl :: Category
pattern CategoryFormat :: Category
pattern CategorySurrogate :: Category
pattern CategoryPrivateUse :: Category
pattern CategoryUnassigned :: Category
pattern CategoryCompatibility :: Category
pattern CategoryIgnoreGraphemeCluster :: Category
pattern CategoryIscntrl :: Category
pattern CategoryIsprint :: Category
pattern CategoryIsspace :: Category
pattern CategoryIsblank :: Category
pattern CategoryIsgraph :: Category
pattern CategoryIspunct :: Category
pattern CategoryIsalnum :: Category
pattern CategoryIsalpha :: Category
pattern CategoryIsupper :: Category
pattern CategoryIslower :: Category
pattern CategoryIsdigit :: Category
pattern CategoryIsxdigit :: Category
data TextException
InvalidUTF8Exception :: CallStack -> TextException
InvalidASCIIException :: CallStack -> TextException

-- | first payload is invalid char index
IndexOutOfTextRange :: Int -> CallStack -> TextException
EmptyText :: CallStack -> TextException
errorEmptyText :: HasCallStack => a
c_utf8_validate_ba :: ByteArray# -> Int# -> Int# -> Int
c_utf8_validate_addr :: Addr# -> Int -> IO Int
c_ascii_validate_ba :: ByteArray# -> Int# -> Int# -> Int
c_ascii_validate_addr :: Addr# -> Int -> IO Int
instance GHC.Base.Semigroup Z.Data.Text.Base.Text
instance GHC.Base.Monoid Z.Data.Text.Base.Text
instance GHC.Show.Show Z.Data.Text.Base.TextException
instance GHC.Exception.Type.Exception Z.Data.Text.Base.TextException
instance GHC.Exts.IsList Z.Data.Text.Base.Text
instance GHC.Classes.Eq Z.Data.Text.Base.Text
instance GHC.Classes.Ord Z.Data.Text.Base.Text
instance GHC.Show.Show Z.Data.Text.Base.Text
instance GHC.Read.Read Z.Data.Text.Base.Text
instance Control.DeepSeq.NFData Z.Data.Text.Base.Text
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.Text.Base.Text
instance Test.QuickCheck.Arbitrary.CoArbitrary Z.Data.Text.Base.Text
instance Data.Hashable.Class.Hashable Z.Data.Text.Base.Text
instance Data.String.IsString Z.Data.Text.Base.Text
instance Data.CaseInsensitive.Internal.FoldCase Z.Data.Text.Base.Text


module Z.Data.Text.Search

-- | <i>O(n)</i> <a>elem</a> test if given char is in given text.
elem :: Char -> Text -> Bool

-- | <i>O(n)</i> <tt>not . elem</tt>
notElem :: Char -> Text -> Bool

-- | find all char index matching the predicate.
findIndices :: (Char -> Bool) -> Text -> [Int]

-- | find all char's byte index matching the predicate.
findBytesIndices :: (Char -> Bool) -> Text -> [Int]

-- | <i>O(n)</i> find the first char matching the predicate in a text from
--   left to right, if there isn't one, return the text length.
find :: (Char -> Bool) -> Text -> (Int, Maybe Char)

-- | <i>O(n)</i> find the first char matching the predicate in a text from
--   right to left.
findR :: (Char -> Bool) -> Text -> (Int, Maybe Char)

-- | <i>O(n)</i> find the char index.
findIndex :: (Char -> Bool) -> Text -> Int

-- | <i>O(n)</i> find the char index in reverse order.
findIndexR :: (Char -> Bool) -> Text -> Int

-- | <i>O(n)</i> find the char's byte slice index.
findBytesIndex :: (Char -> Bool) -> Text -> Int

-- | <i>O(n)</i> find the char's byte slice index in reverse order(pointing
--   to the right char's first byte).
findBytesIndexR :: (Char -> Bool) -> Text -> Int

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

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


-- | Various combinators works on <a>Text</a>s.
module Z.Data.Text.Extra

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Char -> Text -> Text

-- | <i>O(n)</i> Append a char to the end of a text.
snoc :: Text -> Char -> Text

-- | <i>O(1)</i> Extract the head and tail of a text, return <a>Nothing</a>
--   if it is empty.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(1)</i> Extract the init and last of a text, return <a>Nothing</a>
--   if text is empty.
unsnoc :: Text -> Maybe (Text, Char)

-- | <i>O(1)</i> Extract the first char of a text.
headMaybe :: Text -> Maybe Char

-- | <i>O(1)</i> Extract the chars after the head of a text.
--   
--   NOTE: <a>tailMayEmpty</a> return empty text in the case of an empty
--   text.
tailMayEmpty :: Text -> Text

-- | <i>O(1)</i> Extract the last char of a text.
lastMaybe :: Text -> Maybe Char

-- | <i>O(1)</i> Extract the chars before of the last one.
--   
--   NOTE: <a>initMayEmpty</a> return empty text in the case of an empty
--   text.
initMayEmpty :: Text -> Text

-- | <i>O(1)</i> Extract the first char of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
head :: Text -> Char

-- | <i>O(1)</i> Extract the chars after the head of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
tail :: Text -> Text

-- | <i>O(1)</i> Extract the last char of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
last :: Text -> Char

-- | <i>O(1)</i> Extract the chars before of the last one.
--   
--   Throw <a>EmptyText</a> if text is empty.
init :: Text -> Text

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

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

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a text <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 -> Text -> Text

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> char, or <tt>[]</tt> if <tt>n
--   &gt; <a>length</a> xs</tt>.
drop :: Int -> Text -> Text

-- | <i>O(1)</i> <a>takeR</a> <tt>n</tt>, applied to a text <tt>xs</tt>,
--   returns the suffix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
takeR :: Int -> Text -> Text

-- | <i>O(1)</i> <a>dropR</a> <tt>n xs</tt> returns the prefix of
--   <tt>xs</tt> before the last <tt>n</tt> char, or <tt>[]</tt> if <tt>n
--   &gt; <a>length</a> xs</tt>.
dropR :: Int -> Text -> Text

-- | <i>O(1)</i> Extract a sub-range text with give start index and length.
--   
--   This function is a total function just like 'take<i>drop',
--   index</i>length exceeds range will be ingored, e.g.
--   
--   <pre>
--   slice 1 3 "hello"   == "ell"
--   slice -1 -1 "hello" == ""
--   slice -2 2 "hello"  == ""
--   slice 2 10 "hello"  == "llo"
--   </pre>
--   
--   This holds for all x y: <tt>slice x y vs == drop x . take (x+y)
--   vs</tt>
slice :: Int -> Int -> Text -> Text

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

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

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>t</tt>,
--   returns the longest suffix (possibly empty) of <tt>t</tt> of elements
--   that satisfy <tt>p</tt>.
takeWhileR :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>vs</tt>,
--   returns the suffix (possibly empty) remaining after <a>takeWhile</a>
--   <tt>p vs</tt>.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>vs</tt>,
--   returns the prefix (possibly empty) remaining before <a>takeWhileR</a>
--   <tt>p vs</tt>.
dropWhileR :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <tt>dropAround f = dropWhile f . dropWhileR f</tt>
dropAround :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Split the text into the longest prefix of elements that do
--   not satisfy the predicate and the rest without copying.
break :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> Split the text into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <a>breakR</a> behaves like <a>break</a> but from the end of the text.
--   
--   <pre>
--   breakR p == spanR (not.p)
--   </pre>
breakR :: (Char -> Bool) -> Text -> (Text, Text)

-- | <a>spanR</a> behaves like <a>span</a> but from the end of the text.
spanR :: (Char -> Bool) -> Text -> (Text, Text)

-- | Break a text on a subtext, returning a pair of the part of the text
--   prior to the match, and the rest of the text, e.g.
--   
--   <pre>
--   break "wor" "hello, world" = ("hello, ", "world")
--   </pre>
breakOn :: Text -> Text -> (Text, Text)

-- | O(n+m) Find all non-overlapping instances of needle in haystack. Each
--   element of the returned list consists of a pair:
--   
--   <ul>
--   <li>The entire string prior to the kth match (i.e. the prefix)</li>
--   <li>The kth match, followed by the remainder of the string</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   breakOnAll "::" ""
--   ==&gt; []
--   breakOnAll "<i>" "a</i>b<i>c</i>"
--   ==&gt; [("a", "<i>b</i>c<i>"), ("a</i>b", "<i>c</i>"), ("a<i>b</i>c", "/")]
--   </pre>
--   
--   The result list is lazy, search is performed when you force the list.
breakOnAll :: Text -> Text -> [(Text, Text)]

-- | The group function takes a text and returns a list of texts such that
--   the concatenation of the result is equal to the argument. Moreover,
--   each sublist in the result contains only equal elements. For example,
--   
--   <pre>
--   group <a>Mississippi</a> = [<a>M</a>,"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> The <a>stripPrefix</a> function takes two texts and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: Text -> Text -> Maybe Text

-- | O(n) The <a>stripSuffix</a> function takes two texts and returns Just
--   the remainder of the second iff the first is its suffix, and otherwise
--   Nothing.
stripSuffix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> Break a text into pieces separated by the delimiter
--   element consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
split :: Char -> Text -> [Text]

-- | <i>O(n)</i> Splits a text into components delimited by separators,
--   where the predicate returns True for a separator char. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == [""]
--   </pre>
splitWith :: (Char -> Bool) -> Text -> [Text]

-- | <i>O(m+n)</i> Break haystack into pieces separated by needle.
--   
--   Note: An empty needle will essentially split haystack element by
--   element.
--   
--   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>
splitOn :: Text -> Text -> [Text]

-- | The <tt>isPrefix</tt> function returns <a>True</a> if the first
--   argument is a prefix of the second.
isPrefixOf :: Text -> Text -> Bool

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

-- | Check whether one text is a subtext of another.
--   
--   <tt>needle <a>isInfixOf</a> haystack === null haystack || indices
--   needle haystake /= []</tt>.
isInfixOf :: Text -> Text -> Bool

-- | <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. e.g.
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "foobar" "fooquux"
--   ("foo","bar","quux")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "veeble" "fetzer"
--   ("","veeble","fetzer")
--   </pre>
commonPrefix :: Text -> Text -> (Text, Text, Text)

-- | <i>O(n)</i> Breaks a <tt>Bytes</tt> up into a list of words, delimited
--   by unicode space.
words :: Text -> [Text]

-- | <i>O(n)</i> Breaks a text up into a list of lines, delimited by ascii
--   <tt>n</tt>.
lines :: Text -> [Text]

-- | <i>O(n)</i> Joins words with ascii space.
unwords :: [Text] -> Text

-- | <i>O(n)</i> Joins lines with ascii <tt>n</tt>.
--   
--   NOTE: This functions is different from <a>unlines</a>, it DOES NOT add
--   a trailing <tt>n</tt>.
unlines :: [Text] -> Text

-- | Add padding to the left so that the whole text's length is at least n.
padLeft :: Int -> Char -> Text -> Text

-- | Add padding to the right so that the whole text's length is at least
--   n.
padRight :: Int -> Char -> Text -> Text

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

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

-- | <i>O(n)</i> The <a>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
intercalateElem :: Char -> [Text] -> Text

-- | The <a>transpose</a> function transposes the rows and columns of its
--   text argument.
transpose :: [Text] -> [Text]


-- | This module provide internal data types for a simple resumable
--   <a>Parser</a>, which is suitable for binary protocol and simple
--   textual protocol parsing. <a>Parser</a> extensively works on on
--   <a>Bytes</a>, which is same to <a>Text</a> representation.
module Z.Data.Parser.Base

-- | Simple parsing result, that represent respectively:
--   
--   <ul>
--   <li>Success: the remaining unparsed data and the parsed value</li>
--   <li>Failure: the remaining unparsed data and the error message</li>
--   <li>Partial: that need for more input data, supply empty bytes to
--   indicate <a>endOfInput</a></li>
--   </ul>
data Result a
Success :: a -> !Bytes -> Result a
Failure :: ParseError -> !Bytes -> Result a
Partial :: ParseStep a -> Result a

-- | Type alias for error message
type ParseError = [Text]

-- | A parse step consumes <a>Bytes</a> and produce <a>Result</a>.
type ParseStep r = Bytes -> Result r

-- | Simple CPSed parser
--   
--   A parser takes a failure continuation, and a success one, while the
--   success continuation is usually composed by <a>Monad</a> instance, the
--   failure one is more like a reader part, which can be modified via
--   <a>&lt;?&gt;</a>. If you build parsers from ground, a pattern like
--   this can be used:
--   
--   <pre>
--   xxParser = do
--     ensureN errMsg ...            -- make sure we have some bytes
--     Parser $  kf k inp -&gt;        -- fail continuation, success continuation and input
--       ...
--       ... kf errMsg (if input not OK)
--       ... k ... (if we get something useful for next parser)
--   
--   </pre>
newtype Parser a
Parser :: (forall r. (ParseError -> ParseStep r) -> (a -> ParseStep r) -> ParseStep r) -> Parser a
[runParser] :: Parser a -> forall r. (ParseError -> ParseStep r) -> (a -> ParseStep r) -> ParseStep r
(<?>) :: Text -> Parser a -> Parser a
infixr 0 <?>

-- | Parse the complete input, without resupplying, return the rest bytes
parse :: Parser a -> Bytes -> (Bytes, Either ParseError a)

-- | Parse the complete input, without resupplying
parse' :: Parser a -> Bytes -> Either ParseError a

-- | Parse an input chunk
parseChunk :: Parser a -> Bytes -> Result a

-- | Type alias for a streaming parser, draw chunk from Monad m (with a
--   initial chunk), return result in <tt>Either err x</tt>.
type ParseChunks m chunk err x = m chunk -> chunk -> m (chunk, Either err x)

-- | Run a parser with an initial input string, and a monadic action that
--   can supply more input if needed.
--   
--   Note, once the monadic action return empty bytes, parsers will stop
--   drawing more bytes (take it as <a>endOfInput</a>).
parseChunks :: Monad m => Parser a -> ParseChunks m Bytes ParseError a

-- | Finish parsing and fetch result, feed empty bytes if it's
--   <a>Partial</a> result.
finishParsing :: Result a -> (Bytes, Either ParseError a)

-- | Run a parser and keep track of all the input chunks it consumes. Once
--   it's finished, return the final result (always <a>Success</a> or
--   <a>Failure</a>) and all consumed chunks.
runAndKeepTrack :: Parser a -> Parser (Result a, [Bytes])

-- | Return both the result of a parse and the portion of the input that
--   was consumed while it was being parsed.
match :: Parser a -> Parser (Bytes, a)

-- | Ensure that there are at least <tt>n</tt> bytes available. If not, the
--   computation will escape with <a>Partial</a>.
--   
--   Since this parser is used in many other parsers, an extra error param
--   is provide to attach custom error info.
ensureN :: Int -> ParseError -> Parser ()

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes. Fail if not <a>atEnd</a>.
endOfInput :: Parser ()

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes.
atEnd :: Parser Bool

-- | Decode a primitive type in host byte order.
decodePrim :: forall a. Unaligned a => Parser a

-- | big endianess wrapper
newtype BE a
BE :: a -> BE a
[getBE] :: BE a -> a

-- | little endianess wrapper
newtype LE a
LE :: a -> LE a
[getLE] :: LE a -> a

-- | Decode a primitive type in little endian.
decodePrimLE :: forall a. Unaligned (LE a) => Parser a

-- | Decode a primitive type in big endian.
decodePrimBE :: forall a. Unaligned (BE a) => Parser a

-- | A stateful scanner. The predicate consumes and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each byte of the input until one
--   returns <a>Nothing</a> or the input ends.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>Nothing</a> on the first byte of input.
scan :: s -> (s -> Word8 -> Maybe s) -> Parser (Bytes, s)

-- | Similar to <a>scan</a>, but working on <a>Bytes</a> chunks, The
--   predicate consumes a <a>Bytes</a> chunk and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each chunk of the input until one
--   chunk got splited to <tt>Right (V.Bytes, V.Bytes)</tt> or the input
--   ends.
scanChunks :: forall s. s -> (s -> Bytes -> Either s (Bytes, Bytes, s)) -> Parser (Bytes, s)

-- | Match any byte, to perform lookahead. Returns <a>Nothing</a> if end of
--   input has been reached. Does not consume any input.
peekMaybe :: Parser (Maybe Word8)

-- | Match any byte, to perform lookahead. Does not consume any input, but
--   will fail if end of input has been reached.
peek :: Parser Word8

-- | The parser <tt>satisfy p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the byte that is
--   actually parsed.
--   
--   <pre>
--   digit = satisfy isDigit
--       where isDigit w = w &gt;= 48 &amp;&amp; w &lt;= 57
--   </pre>
satisfy :: (Word8 -> Bool) -> Parser Word8

-- | The parser <tt>satisfyWith f p</tt> transforms a byte, and succeeds if
--   the predicate <tt>p</tt> returns <a>True</a> on the transformed value.
--   The parser returns the transformed byte that was parsed.
satisfyWith :: (Word8 -> a) -> (a -> Bool) -> Parser a

-- | Return a byte, this is an alias to <tt>decodePrim </tt>Word8@.
anyWord8 :: Parser Word8

-- | Match a specific byte.
word8 :: Word8 -> Parser ()

-- | Take a byte and return as a 8bit char.
anyChar8 :: Parser Char

-- | Match a specific 8bit char.
char8 :: Char -> Parser ()

-- | Skip a byte.
skipWord8 :: Parser ()

-- | Match either a single newline byte <tt>'\n'</tt>, or a carriage return
--   followed by a newline byte <tt>"\r\n"</tt>.
endOfLine :: Parser ()

-- | <a>skip</a> N bytes.
skip :: Int -> Parser ()

-- | Skip past input for as long as the predicate returns <a>True</a>.
skipWhile :: (Word8 -> Bool) -> Parser ()

-- | Skip over white space using <a>isSpace</a>.
skipSpaces :: Parser ()
take :: Int -> Parser Bytes

-- | Similar to <a>take</a>, but requires the predicate to succeed on next
--   N bytes of input, and take N bytes(no matter if N+1 byte satisfy
--   predicate or not).
takeN :: (Word8 -> Bool) -> Int -> Parser Bytes

-- | Consume input as long as the predicate returns <a>False</a> or reach
--   the end of input, and return the consumed input.
takeTill :: (Word8 -> Bool) -> Parser Bytes

-- | Consume input as long as the predicate returns <a>True</a> or reach
--   the end of input, and return the consumed input.
takeWhile :: (Word8 -> Bool) -> Parser Bytes

-- | Similar to <a>takeWhile</a>, but requires the predicate to succeed on
--   at least one byte of input: it will fail if the predicate never
--   returns <a>True</a> or reach the end of input
takeWhile1 :: (Word8 -> Bool) -> Parser Bytes

-- | Take all the remaining input chunks and return as <a>Bytes</a>.
takeRemaining :: Parser Bytes

-- | <tt>bytes s</tt> parses a sequence of bytes that identically match
--   <tt>s</tt>.
bytes :: Bytes -> Parser ()

-- | Same as <a>bytes</a> but ignoring case.
bytesCI :: Bytes -> Parser ()

-- | <tt>text s</tt> parses a sequence of UTF8 bytes that identically match
--   <tt>s</tt>.
text :: Text -> Parser ()

-- | <a>Text</a> version of <a>fail</a>.
fail' :: Text -> Parser a
instance GHC.Base.Functor Z.Data.Parser.Base.Parser
instance GHC.Base.Applicative Z.Data.Parser.Base.Parser
instance GHC.Base.Monad Z.Data.Parser.Base.Parser
instance Control.Monad.Fail.MonadFail Z.Data.Parser.Base.Parser
instance GHC.Base.MonadPlus Z.Data.Parser.Base.Parser
instance GHC.Base.Alternative Z.Data.Parser.Base.Parser
instance GHC.Base.Functor Z.Data.Parser.Base.Result
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Parser.Base.Result a)


-- | Textual numeric parsers.
module Z.Data.Parser.Numeric

-- | Parse and decode an unsigned decimal number.
--   
--   Will fail in case of overflow.
uint :: forall a. (Integral a, Bounded a) => Parser a

-- | Parse a decimal number with an optional leading <tt>'+'</tt> or
--   <tt>'-'</tt> sign character.
--   
--   This parser will fail if overflow happens.
int :: forall a. (Integral a, Bounded a) => Parser a

-- | Parser specifically optimized for <a>Integer</a>.
integer :: Parser Integer

-- | Same with <a>uint</a>, but sliently cast in case of overflow.
uint_ :: forall a. (Integral a, Bounded a) => Parser a

-- | Same with <a>int</a>, but sliently cast if overflow happens.
int_ :: (Integral a, Bounded a) => Parser a

-- | Take a single decimal digit and return as <a>Int</a>.
digit :: Parser Int

-- | Parse and decode an unsigned hex number, fail if input length is
--   larger than (bit_size/4). The hex digits <tt>'a'</tt> through
--   <tt>'f'</tt> may be upper or lower case.
--   
--   This parser does not accept a leading <tt>"0x"</tt> string, and
--   consider sign bit part of the binary hex nibbles, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Left ["Z.Data.Parser.Numeric.hex","hex numeric number overflow"]
--   </pre>
hex :: forall a. (Integral a, FiniteBits a) => Parser a

-- | Same with <a>hex</a>, but only take as many as (bit_size/4) bytes.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Right (127 :: Int8)
--   </pre>
hex' :: forall a. (Integral a, FiniteBits a) => Parser a

-- | Same with <a>hex</a>, but silently cast in case of overflow.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Right (-1 :: Int8)
--   </pre>
hex_ :: (Integral a, Bits a) => Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
--   
--   <i>Note</i>: this parser is not safe for use with inputs from
--   untrusted sources. An input with a suitably large exponent such as
--   <tt>"1e1000000000"</tt> will cause a huge <a>Integer</a> to be
--   allocated, resulting in what is effectively a denial-of-service
--   attack.
--   
--   In most cases, it is better to use <a>double</a> or <a>scientific</a>
--   instead.
rational :: Fractional a => Parser a

-- | Parse a rational number and round to <a>Float</a>.
--   
--   Single precision version of <a>double</a>.
float :: Parser Float

-- | Parse a rational number and round to <a>Double</a>.
--   
--   This parser accepts an optional leading sign character, followed by at
--   least one decimal digit. The syntax similar to that accepted by the
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples with behaviour identical to <a>read</a>:
--   
--   <pre>
--   parse' double "3"     == ("", Right 3.0)
--   parse' double "3.1"   == ("", Right 3.1)
--   parse' double "3e4"   == ("", Right 30000.0)
--   parse' double "3.1e4" == ("", Right 31000.0)
--   </pre>
--   
--   <pre>
--   parse' double ".3"    == (".3", Left ParserError)
--   parse' double "e3"    == ("e3", Left ParserError)
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   parse' double "3.foo" == (".foo", Right 3.0)
--   parse' double "3e"    == ("e",    Right 3.0)
--   parse' double "-3e"   == ("e",    Right -3.0)
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
double :: Parser Double

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
scientific :: Parser Scientific

-- | Parse a scientific number and convert to result using a user supply
--   function.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
scientifically :: (Scientific -> a) -> Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
--   
--   <i>Note</i>: this parser is not safe for use with inputs from
--   untrusted sources. An input with a suitably large exponent such as
--   <tt>"1e1000000000"</tt> will cause a huge <a>Integer</a> to be
--   allocated, resulting in what is effectively a denial-of-service
--   attack.
--   
--   In most cases, it is better to use <a>double'</a> or
--   <a>scientific'</a> instead.
rational' :: Fractional a => Parser a

-- | Parse a rational number and round to <a>Float</a> using stricter
--   grammer.
--   
--   Single precision version of <a>double'</a>.
float' :: Parser Float

-- | More strict number parsing(rfc8259).
--   
--   <a>scientific</a> support parse <tt>2314.</tt> and <tt>21321exyz</tt>
--   without eating extra dot or <tt>e</tt> via backtrack, this is not
--   allowed in some strict grammer such as JSON, so we make an
--   non-backtrack strict number parser separately using LL(1) lookahead.
--   This parser also agree with <a>read</a> on extra dot or e handling:
--   
--   <pre>
--   parse' double "3.foo" == Left ParseError
--   parse' double "3e"    == Left ParseError
--   </pre>
--   
--   Leading zeros or <tt>+</tt> sign is also not allowed:
--   
--   <pre>
--   parse' double "+3.14" == Left ParseError
--   parse' double "0014" == Left ParseError
--   </pre>
--   
--   If you have a similar grammer, you can use this parser to save
--   considerable time.
--   
--   <pre>
--   number = [ minus ] int [ frac ] [ exp ]
--   decimal-point = %x2E       ; .
--   digit1-9 = %x31-39         ; 1-9
--   e = %x65 / %x45            ; e E
--   exp = e [ minus / plus ] 1*DIGIT
--   frac = decimal-point 1*DIGIT
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity". reference:
--   <a>https://tools.ietf.org/html/rfc8259#section-6</a>
double' :: Parser Double

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
scientific' :: Parser Scientific

-- | Parse a scientific number and convert to result using a user supply
--   function.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
scientifically' :: (Scientific -> a) -> Parser a

-- | Convert A ASCII hex digit to <a>Int</a> value.
w2iHex :: Integral a => Word8 -> a

-- | Convert A ASCII decimal digit to <a>Int</a> value.
w2iDec :: Integral a => Word8 -> a

-- | decode hex digits sequence within an array.
hexLoop :: forall a. (Integral a, Bits a) => a -> Bytes -> a

-- | Decode digits sequence within an array.
--   
--   This function may overflow if result can't fit into type.
decLoop :: Integral a => a -> Bytes -> a

-- | decode digits sequence within an array.
--   
--   A fast version to decode <a>Integer</a> using machine word as much as
--   possible.
decLoopIntegerFast :: Bytes -> Integer


-- | This module provide three stable sorting algorithms, which are:
--   
--   <ul>
--   <li><a>mergeSort</a>, a <i>O(log(n))</i> general-purpose sorting
--   algorithms for all different size vectors.</li>
--   <li><a>insertSort</a> a <i>O(n^2)</i> sorting algorithms suitable for
--   very small vectors.</li>
--   <li><a>radixSort</a> a <i>O(n)</i> sorting algorithms based on
--   <a>Radix</a> instance, which is prefered on large vectors.</li>
--   </ul>
--   
--   Sorting is always performed in ascending order. To reverse the order,
--   either use <tt>XXSortBy</tt> or use <a>Down</a>, <a>RadixDown</a>
--   newtypes. In general changing comparing functions can be done by
--   creating auxiliary newtypes and <a>Ord</a> instances (make sure you
--   inline instance's method for performence!). Or <a>Radix</a> instances
--   in <a>radixSort</a> case, for example:
--   
--   <pre>
--   data Foo = Foo { key :: Int16, ... }
--   
--   instance Radix Foo where
--       -- You should add INLINE pragmas to following methods
--       bucketSize = bucketSize . key
--       passes = passes . key
--       radixLSB = radixLSB . key
--       radix i = radix i . key
--       radixMSB = radixMSB . key
--   </pre>
module Z.Data.Vector.Sort

-- | <i>O(n*log(n))</i> Sort vector based on element's <a>Ord</a> instance
--   with classic <a>mergesort</a> algorithm.
--   
--   This is a stable sort, During sorting two O(n) worker arrays are
--   needed, one of them will be freezed into the result vector. The merge
--   sort only begin at tile size larger than <a>mergeTileSize</a>, each
--   tile will be sorted with <a>insertSort</a>, then iteratively merged
--   into larger array, until all elements are sorted.
mergeSort :: forall v a. (Vec v a, Ord a) => v a -> v a
mergeSortBy :: forall v a. Vec v a => (a -> a -> Ordering) -> v a -> v a

-- | The mergesort tile size, <tt>mergeTileSize = 8</tt>.
mergeTileSize :: Int

-- | <i>O(n^2)</i> Sort vector based on element's <a>Ord</a> instance with
--   simple <a>insertion-sort</a> algorithm.
--   
--   This is a stable sort. O(n) extra space are needed, which will be
--   freezed into result vector.
insertSort :: (Vec v a, Ord a) => v a -> v a
insertSortBy :: Vec v a => (a -> a -> Ordering) -> v a -> v a

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

-- | <i>O(n)</i> Sort vector based on element's <a>Radix</a> instance with
--   <a>radix-sort</a>, (Least significant digit radix sorts variation).
--   
--   This is a stable sort, one or two extra O(n) worker array are need
--   depend on how many <a>passes</a> shall be performed, and a
--   <a>bucketSize</a> counting bucket are also needed. This sort
--   algorithms performed extremly well on small byte size types such as
--   <a>Int8</a> or <a>Word8</a>, while on larger type, constant passes may
--   render this algorithm not suitable for small vectors (turning point
--   around 2^(2*passes)).
radixSort :: forall v a. (Vec v a, Radix a) => v a -> v a

-- | Types contain radixs, which can be inspected with <a>radix</a> during
--   different <a>passes</a>.
--   
--   The default instances share a same <a>bucketSize</a> 256, which seems
--   to be a good default.
class Radix a

-- | The size of an auxiliary array, i.e. the counting bucket
bucketSize :: Radix a => a -> Int

-- | The number of passes necessary to sort an array of es, it equals to
--   the key's byte number.
passes :: Radix a => a -> Int

-- | The radix function used in the first pass, works on the least
--   significant bit.
radixLSB :: Radix a => a -> Int

-- | The radix function parameterized by the current pass (0 &lt; pass &lt;
--   passes e-1).
radix :: Radix a => Int -> a -> Int

-- | The radix function used in the last pass, works on the most
--   significant bit.
radixMSB :: Radix a => a -> Int

-- | Similar to <a>Down</a> newtype for <a>Ord</a>, this newtype can
--   inverse the order of a <a>Radix</a> instance when used in
--   <a>radixSort</a>.
newtype RadixDown a
RadixDown :: a -> RadixDown a

-- | merge duplicated adjacent element, prefer left element.
--   
--   Use this function on a sorted vector will have the same effects as
--   <tt>nub</tt>.
mergeDupAdjacent :: forall v a. (Vec v a, Eq a) => v a -> v a

-- | Merge duplicated adjacent element, prefer left element.
mergeDupAdjacentLeft :: forall v a. Vec v a => (a -> a -> Bool) -> v a -> v a

-- | Merge duplicated adjacent element, prefer right element.
mergeDupAdjacentRight :: forall v a. Vec v a => (a -> a -> Bool) -> v a -> v a

-- | Merge duplicated adjacent element, based on a equality tester and a
--   merger function.
mergeDupAdjacentBy :: forall v a. Vec v a => (a -> a -> Bool) -> (a -> a -> a) -> v a -> v a
instance Z.Data.Array.Unaligned.Unaligned a => Z.Data.Array.Unaligned.Unaligned (Z.Data.Vector.Sort.RadixDown a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Z.Data.Vector.Sort.RadixDown a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Z.Data.Vector.Sort.RadixDown a)
instance GHC.Show.Show a => GHC.Show.Show (Z.Data.Vector.Sort.RadixDown a)
instance Z.Data.Vector.Sort.Radix a => Z.Data.Vector.Sort.Radix (Z.Data.Vector.Sort.RadixDown a)
instance Z.Data.Vector.Sort.Radix GHC.Int.Int8
instance Z.Data.Vector.Sort.Radix GHC.Types.Int
instance Z.Data.Vector.Sort.Radix GHC.Int.Int16
instance Z.Data.Vector.Sort.Radix GHC.Int.Int32
instance Z.Data.Vector.Sort.Radix GHC.Int.Int64
instance Z.Data.Vector.Sort.Radix GHC.Word.Word8
instance Z.Data.Vector.Sort.Radix GHC.Types.Word
instance Z.Data.Vector.Sort.Radix GHC.Word.Word16
instance Z.Data.Vector.Sort.Radix GHC.Word.Word32
instance Z.Data.Vector.Sort.Radix GHC.Word.Word64


-- | This module provides fast boxed and unboxed vector with unified
--   interface. The API is similar to bytestring and vector. If you find
--   missing functions, please report!
--   
--   Performance consideration:
--   
--   <ul>
--   <li>Use <a>PrimVector</a> for <tt>Prim</tt> types, it stores content
--   in packed memory, and it's strict on its elements</li>
--   <li>Many functions DO NOT NEED result vectors's type to be the same
--   with source one, e.g. <tt>map :: (Vec v a, Vec u b) =&gt; (a -&gt; b)
--   -&gt; v a -&gt; u b</tt>.</li>
--   <li>There're some specialized functions only works on <a>Bytes</a>,
--   which is enabled by rewrite rules, if you want to use specialized
--   versions directly, import <a>Z.Data.Vector.Base</a> and
--   <a>Std.Data.Vector.Extra</a> module. Doing so will also enable vector
--   internals, which is useful for working on the underlying arrays.</li>
--   <li>The <tt>Functor</tt> instance for <a>Vector</a> are lazy in order
--   to abid <tt>Functor</tt> law. namely <tt>fmap id vectorConatinBottom
--   == vectorContainBottom</tt>, if you need strict mapping for lifted
--   <a>Vector</a>, use <a>map'</a> (<a>PrimVector</a> will never contain
--   bottom thus it's not a problem). THIS MAY COME AS A SURPRISE SO MAKE
--   SURE YOU USE THE CORRECT <a>map</a>.</li>
--   <li>The <tt>Foldable</tt> instance for <a>Vector</a> is fine, you can
--   use <tt>Prelude</tt> functions such as <a>null</a>, <a>length</a>,
--   etc. without incurring performance overhead, though there're partial
--   functions you should avoid, i.e. <tt>foldl1</tt>, <tt>foldr1</tt>,
--   <a>maximum</a>, <a>minimum</a>. Use <a>foldl1Maybe'</a>,
--   <a>foldr1Maybe'</a>, <a>maximumMaybe</a>, <tt>minmumMaybe</tt>
--   instead.</li>
--   <li>The <tt>Traversable</tt> instance have specialized implementations
--   for <tt>ST</tt> and <tt>IO</tt>, if you don't want to write thunks
--   into result vector, use <tt>return <a>$!</a></tt> idiom.</li>
--   <li>When use stateful generating functions like <a>mapAccumL</a>,
--   <a>mapAccumR</a> ,etc. force both the accumulator and value with
--   <tt>acc <tt>seq</tt> v <tt>seq</tt> (acc, v)</tt> idiom to avoid
--   thunks inside result vector.</li>
--   <li>The <a>unpack</a>, <a>unpackR</a> and <a>pack</a>, <a>packN</a>,
--   <a>packR</a>, <a>packRN</a> are designed to work with
--   <tt>build/foldr</tt> streaming fusion in base, thus it's OK to expect
--   idioms like<pre>pack . List filter f . List.map . unpack</pre>to work
--   in contant space. While<pre>Vector.filter . Vector.map</pre>will
--   create intermediate vectors on the fly, which have different
--   time/space characteristic.</li>
--   </ul>
--   
--   Since all functions works on more general types, inlining and
--   specialization are the keys to achieve high performance, e.g. the
--   performance gap between running in GHCi and compiled binary may be
--   huge due to dictionary passing. If there're cases that GHC fail to
--   specialized these functions, it should be regarded as a bug either in
--   this library or GHC.
module Z.Data.Vector

-- | Typeclass for box and unboxed vectors, which are created by slicing
--   arrays.
--   
--   Instead of providing a generalized vector with polymorphric array
--   field, we use this typeclass so that instances use concrete array type
--   can unpack their array payload.
--   
--   Vector types, e.g. <a>Vector</a>,<a>PrimVector</a>... are obivious
--   instances, with O(1) <a>toArr</a> and <a>fromArr</a>, which convert
--   slices to (array, offset, length) tuple back and forth.
--   
--   Array types can also be instances of this class, e.g. <a>Array</a>,
--   <a>PrimArray</a>..., in this case <a>toArr</a> will always return
--   offset 0 and whole array length, and <a>fromArr</a> is O(n)
--   <a>copyArr</a>.
class (Arr (IArray v) a) => Vec v a where {
    
    -- | Vector's immutable array type
    type family IArray v :: * -> *;
}

-- | Get underline array and slice range(offset and length).
toArr :: Vec v a => v a -> (IArray v a, Int, Int)

-- | Construct a <a>Vec</a> by slicing a whole array.
arrVec :: Vec v a => IArray v a -> v a

-- | <i>O(1)</i> Index vector's element.
--   
--   Return <a>Nothing</a> if index is out of bounds.
indexMaybe :: Vec v a => v a -> Int -> Maybe a

-- | <i>O(1)</i> Index array element.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
index :: (Vec v a, HasCallStack) => v a -> Int -> a

-- | <i>O(1)</i> Index array element.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
indexM :: (Vec v a, Monad m, HasCallStack) => v a -> Int -> m a

-- | <i>O(n)</i> Modify vector's element under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
modifyIndex :: (Vec v a, HasCallStack) => v a -> Int -> (a -> a) -> v a

-- | <i>O(n)</i> Modify vector's element under given index.
--   
--   Return original vector if index outside of the vector.
modifyIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> (a -> a) -> v a

-- | <i>O(n)</i> insert element to vector under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
insertIndex :: (Vec v a, HasCallStack) => v a -> Int -> a -> v a

-- | <i>O(n)</i> insert element to vector under given index.
--   
--   Return original vector if index outside of the vector.
insertIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> a -> v a

-- | <i>O(n)</i> Delete vector's element under given index.
--   
--   Throw <a>IndexOutOfVectorRange</a> if index outside of the vector.
deleteIndex :: (Vec v a, HasCallStack) => v a -> Int -> v a

-- | <i>O(n)</i> Delete vector's element under given index.
--   
--   Return original vector if index outside of the vector.
deleteIndexMaybe :: (Vec v a, HasCallStack) => v a -> Int -> v a

-- | Boxed vector
data Vector a

-- | Primitive vector
data PrimVector a

-- | <a>Bytes</a> is just primitive word8 vectors.
type Bytes = PrimVector Word8

-- | <i>O(n)</i>, pack an ASCII <a>String</a>, multi-bytes char WILL BE
--   CHOPPED!
packASCII :: String -> Bytes

-- | <i>O(1)</i>. The empty vector.
empty :: Vec v a => v a

-- | <i>O(1)</i>. Single element vector.
singleton :: Vec v a => a -> v a

-- | <i>O(n)</i>. Copy a vector from slice.
copy :: Vec v a => v a -> v a

-- | <i>O(n)</i> Convert a list into a vector
--   
--   Alias for <tt><a>packN</a> <a>defaultInitSize</a></tt>.
pack :: Vec v a => [a] -> v a

-- | <i>O(n)</i> Convert a list into a vector with an approximate size.
--   
--   If the list's length is large than the size given, we simply double
--   the buffer size and continue building.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Convert a list into a vector with given size.
--   
--   If the list's length is large than the size given, we drop the rest
--   elements.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN' :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Alias for <tt><a>packRN</a> <a>defaultInitSize</a></tt>.
packR :: Vec v a => [a] -> v a

-- | <i>O(n)</i> <a>packN</a> in reverse order.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> <a>packN'</a> in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; packRN' 3 [1,2,3,4,5]
--   
--   &gt;&gt;&gt; [3,2,1]
--   </pre>
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN' :: forall v a. Vec v a => Int -> [a] -> v a

-- | <i>O(n)</i> Convert vector to a list.
--   
--   Unpacking is done lazily. i.e. we will retain reference to the array
--   until all element are consumed.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpack :: Vec v a => v a -> [a]

-- | <i>O(n)</i> Convert vector to a list in reverse order.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpackR :: Vec v a => v a -> [a]

-- | <i>O(1)</i> Test whether a vector is empty.
null :: Vec v a => v a -> Bool

-- | <i>O(1)</i> The length of a vector.
length :: Vec v a => v a -> Int

-- | <i>O(m+n)</i>
--   
--   There's no need to guard empty vector because we guard them for you,
--   so appending empty vectors are no-ops.
append :: Vec v a => v a -> v a -> v a

-- | Mapping between vectors (possiblely with two different vector types).
--   
--   NOTE, the result vector contain thunks in lifted <a>Vector</a> case,
--   use <a>map'</a> if that's not desired.
--   
--   For <a>PrimVector</a>, <a>map</a> and <a>map'</a> are same, since
--   <a>PrimVector</a>s never store thunks.
map :: forall u v a b. (Vec u a, Vec v b) => (a -> b) -> u a -> v b

-- | Mapping between vectors (possiblely with two different vector types).
--   
--   This is the strict version map. Note that the <a>Functor</a> instance
--   of lifted <a>Vector</a> is defined with <a>map</a> to statisfy laws,
--   which this strict version breaks (<tt>map' id arrayContainsBottom /=
--   arrayContainsBottom </tt>).
map' :: forall u v a b. (Vec u a, Vec v b) => (a -> b) -> u a -> v b

-- | Strict mapping with index.
imap' :: forall u v a b. (Vec u a, Vec v b) => (Int -> a -> b) -> u a -> v b

-- | Traverse vector and gather result in another vector,
traverseVec :: (Vec v a, Vec u b, Applicative f) => (a -> f b) -> v a -> f (u b)

-- | Traverse vector and gather result in another vector,
traverseWithIndex :: (Vec v a, Vec u b, Applicative f) => (Int -> a -> f b) -> v a -> f (u b)

-- | Traverse vector without gathering result.
traverseVec_ :: (Vec v a, Applicative f) => (a -> f b) -> v a -> f ()

-- | Traverse vector with index.
traverseWithIndex_ :: (Vec v a, Applicative f) => (Int -> a -> f b) -> v a -> f ()

-- | Strict left to right fold.
foldl' :: Vec v a => (b -> a -> b) -> b -> v a -> b

-- | Strict left to right fold with index.
ifoldl' :: Vec v a => (b -> Int -> a -> b) -> b -> v a -> b

-- | Strict left to right fold using first element as the initial value.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
foldl1' :: forall v a. (Vec v a, HasCallStack) => (a -> a -> a) -> v a -> a

-- | Strict left to right fold using first element as the initial value.
--   return <a>Nothing</a> when vector is empty.
foldl1Maybe' :: forall v a. Vec v a => (a -> a -> a) -> v a -> Maybe a

-- | Strict right to left fold
foldr' :: Vec v a => (a -> b -> b) -> b -> v a -> b

-- | Strict right to left fold with index
--   
--   NOTE: the index is counting from 0, not backwards
ifoldr' :: Vec v a => (Int -> a -> b -> b) -> b -> v a -> b

-- | Strict right to left fold using last element as the initial value.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
foldr1' :: forall v a. (Vec v a, HasCallStack) => (a -> a -> a) -> v a -> a

-- | Strict right to left fold using last element as the initial value,
--   return <a>Nothing</a> when vector is empty.
foldr1Maybe' :: forall v a. Vec v a => (a -> a -> a) -> v a -> Maybe a

-- | <i>O(n)</i> Concatenate a list of vector.
--   
--   Note: <a>concat</a> have to force the entire list to filter out empty
--   vector and calculate the length for allocation.
concat :: forall v a. Vec v a => [v a] -> v a

-- | Map a function over a vector and concatenate the results
concatMap :: Vec v a => (a -> v a) -> v a -> v a

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a vector
--   
--   It's defined with <a>foldl1'</a>, an <a>EmptyVector</a> exception will
--   be thrown in the case of an empty vector.
maximum :: (Vec v a, Ord a, HasCallStack) => v a -> a

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <tt>vector</tt>
--   
--   An <a>EmptyVector</a> exception will be thrown in the case of an empty
--   vector.
minimum :: (Vec v a, Ord a, HasCallStack) => v a -> a

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a vector,
--   return <a>Nothing</a> in the case of an empty vector.
maximumMaybe :: (Vec v a, Ord a) => v a -> Maybe a

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a vector,
--   return <a>Nothing</a> in the case of an empty vector.
minimumMaybe :: (Vec v a, Ord a) => v a -> Maybe a

-- | <i>O(n)</i> <a>sum</a> returns the sum value from a <tt>vector</tt>
sum :: (Vec v a, Num a) => v a -> a

-- | <i>O(n)</i> <a>count</a> returns count of an element from a
--   <tt>vector</tt>
count :: (Vec v a, Eq a) => a -> v a -> Int

-- | <i>O(n)</i> <a>product</a> returns the product value from a vector
product :: (Vec v a, Num a) => v a -> a

-- | <i>O(n)</i> <a>product</a> returns the product value from a vector
--   
--   This function will shortcut on zero. Note this behavior change the
--   semantics for lifted vector: <tt>product [1,0,undefined] /= product'
--   [1,0,undefined]</tt>.
product' :: (Vec v a, Num a, Eq a) => v a -> a

-- | <i>O(n)</i> Applied to a predicate and a vector, <a>all</a> determines
--   if all elements of the vector satisfy the predicate.
all :: Vec v a => (a -> Bool) -> v a -> Bool

-- | <i>O(n)</i> Applied to a predicate and a vector, <a>any</a> determines
--   if any elements of the vector satisfy the predicate.
any :: Vec v a => (a -> Bool) -> v a -> Bool

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <tt>foldl</tt>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new list.
--   
--   Note, this function will only force the result tuple, not the elements
--   inside, to prevent creating thunks during <a>mapAccumL</a>, <a>seq</a>
--   your accumulator and result with the result tuple.
mapAccumL :: forall u v a b c. (Vec u b, Vec v c) => (a -> b -> (a, c)) -> a -> u b -> (a, v c)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <tt>foldr</tt>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   The same strictness property with <a>mapAccumL</a> applys to
--   <a>mapAccumR</a> too.
mapAccumR :: forall u v a b c. (Vec u b, Vec v c) => (a -> b -> (a, c)) -> a -> u b -> (a, v c)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a vector of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
--   
--   Note: <a>replicate</a> will not force the element in boxed vector
--   case.
replicate :: Vec v a => Int -> a -> v a

-- | <i>O(n*m)</i> <a>cycleN</a> a vector n times.
cycleN :: forall v a. Vec v a => Int -> v a -> v 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 vector from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   vector 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 :: Vec u b => (a -> Maybe (b, a)) -> a -> u b

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a vector 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 :: forall v a b. Vec v b => Int -> (a -> Maybe (b, a)) -> a -> (v b, Maybe a)

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Vec v a => a -> v a -> v a

-- | <i>O(n)</i> Append a byte to the end of a vector
snoc :: Vec v a => v a -> a -> v a

-- | <i>O(1)</i> Extract the head and tail of a vector, return
--   <a>Nothing</a> if it is empty.
uncons :: Vec v a => v a -> Maybe (a, v a)

-- | <i>O(1)</i> Extract the init and last of a vector, return
--   <a>Nothing</a> if vector is empty.
unsnoc :: Vec v a => v a -> Maybe (v a, a)

-- | <i>O(1)</i> Extract the first element of a vector.
headMaybe :: Vec v a => v a -> Maybe a

-- | <i>O(1)</i> Extract the elements after the head of a vector.
--   
--   NOTE: <a>tailMayEmpty</a> return empty vector in the case of an empty
--   vector.
tailMayEmpty :: Vec v a => v a -> v a

-- | <i>O(1)</i> Extract the last element of a vector.
lastMaybe :: Vec v a => v a -> Maybe a

-- | <i>O(1)</i> Extract the elements before of the last one.
--   
--   NOTE: <a>initMayEmpty</a> return empty vector in the case of an empty
--   vector.
initMayEmpty :: Vec v a => v a -> v a

-- | <i>O(1)</i> Extract the first element of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
head :: (Vec v a, HasCallStack) => v a -> a

-- | <i>O(1)</i> Extract the elements after the head of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
tail :: (Vec v a, HasCallStack) => v a -> v a

-- | <i>O(1)</i> Extract the last element of a vector.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
last :: (Vec v a, HasCallStack) => v a -> a

-- | <i>O(1)</i> Extract the elements before of the last one.
--   
--   Throw <a>EmptyVector</a> if vector is empty.
init :: (Vec v a, HasCallStack) => v a -> v a

-- | <i>O(n)</i> Return all initial segments of the given vector, empty
--   first.
inits :: Vec v a => v a -> [v a]

-- | <i>O(n)</i> Return all final segments of the given vector, whole
--   vector first.
tails :: Vec v a => v a -> [v a]

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a vector <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 :: Vec v a => Int -> v a -> v a

-- | <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 :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> <a>takeR</a> <tt>n</tt>, applied to a vector <tt>xs</tt>,
--   returns the suffix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
takeR :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> <a>dropR</a> <tt>n xs</tt> returns the prefix of
--   <tt>xs</tt> before the last <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
dropR :: Vec v a => Int -> v a -> v a

-- | <i>O(1)</i> Extract a sub-range vector with give start index and
--   length.
--   
--   This function is a total function just like 'take<i>drop',
--   index</i>length exceeds range will be ingored, e.g.
--   
--   <pre>
--   slice 1 3 "hello"   == "ell"
--   slice -1 -1 "hello" == ""
--   slice -2 2 "hello"  == ""
--   slice 2 10 "hello"  == "llo"
--   </pre>
--   
--   This holds for all x y: <tt>slice x y vs == drop x . take (x+y)
--   vs</tt>
slice :: Vec v a => Int -> Int -> v a -> v a

-- | <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 :: Vec v a => Int -> v a -> (v a, v a)

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the longest prefix (possibly empty) of
--   <tt>vs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the longest suffix (possibly empty) of
--   <tt>vs</tt> of elements that satisfy <tt>p</tt>.
takeWhileR :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the suffix (possibly empty) remaining after
--   <a>takeWhile</a> <tt>p vs</tt>.
dropWhile :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a vector
--   <tt>vs</tt>, returns the prefix (possibly empty) remaining before
--   <a>takeWhileR</a> <tt>p vs</tt>.
dropWhileR :: Vec v a => (a -> Bool) -> v a -> v a

-- | <i>O(n)</i> <tt>dropAround f = dropWhile f . dropWhileR f</tt>
dropAround :: Vec v a => (a -> Bool) -> 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.
--   
--   <tt>break (==x)</tt> will be rewritten using a <tt>memchr</tt>.
break :: Vec 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.
--   
--   <tt>span (/=x)</tt> will be rewritten using a <tt>memchr</tt>.
span :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | <a>breakR</a> behaves like <a>break</a> but from the end of the
--   vector.
--   
--   <pre>
--   breakR p == spanR (not.p)
--   </pre>
breakR :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | <a>spanR</a> behaves like <a>span</a> but from the end of the vector.
spanR :: Vec v a => (a -> Bool) -> v a -> (v a, v a)

-- | Break a vector on a subvector, returning a pair of the part of the
--   vector prior to the match, and the rest of the vector, e.g.
--   
--   <pre>
--   break "wor" "hello, world" = ("hello, ", "world")
--   </pre>
breakOn :: (Vec v a, Eq a) => v a -> v a -> (v a, v a)
group :: (Vec v a, Eq a) => v a -> [v a]
groupBy :: forall v a. Vec v a => (a -> a -> Bool) -> v a -> [v a]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two vectors and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: (Vec v a, Eq (v a)) => v a -> v a -> Maybe (v a)

-- | O(n) The <a>stripSuffix</a> function takes two vectors and returns
--   Just the remainder of the second iff the first is its suffix, and
--   otherwise Nothing.
stripSuffix :: (Vec v a, Eq (v a)) => v a -> v a -> Maybe (v a)

-- | <i>O(n)</i> Break a vector into pieces separated by the delimiter
--   element consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
split :: (Vec v a, Eq a) => a -> v a -> [v a]

-- | <i>O(n)</i> Splits a vector 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 (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == [""]
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
splitWith :: Vec v a => (a -> Bool) -> v a -> [v a]

-- | <i>O(m+n)</i> Break haystack into pieces separated by needle.
--   
--   Note: An empty needle will essentially split haystack element by
--   element.
--   
--   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>
splitOn :: (Vec v a, Eq a) => v a -> v a -> [v a]

-- | The <tt>isPrefix</tt> function returns <a>True</a> if the first
--   argument is a prefix of the second.
isPrefixOf :: forall v a. (Vec v a, Eq (v a)) => v a -> v a -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two vectors and
--   returns <a>True</a> if the first is a suffix of the second.
isSuffixOf :: forall v a. (Vec v a, Eq (v a)) => v a -> v a -> Bool

-- | Check whether one vector is a subvector of another.
--   
--   <tt>needle <a>isInfixOf</a> haystack === null haystack || indices
--   needle haystake /= []</tt>.
isInfixOf :: (Vec v a, Eq a) => v a -> v a -> Bool

-- | <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. e.g.
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "foobar" "fooquux"
--   ("foo","bar","quux")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "veeble" "fetzer"
--   ("","veeble","fetzer")
--   </pre>
commonPrefix :: (Vec v a, Eq a) => v a -> v a -> (v a, v a, v a)

-- | <i>O(n)</i> Breaks a <a>Bytes</a> up into a list of words, delimited
--   by ascii space.
words :: Bytes -> [Bytes]

-- | <i>O(n)</i> Breaks a <a>Bytes</a> up into a list of lines, delimited
--   by ascii <tt>n</tt>.
lines :: Bytes -> [Bytes]

-- | <i>O(n)</i> Joins words with ascii space.
unwords :: [Bytes] -> Bytes

-- | <i>O(n)</i> Joins lines with ascii <tt>n</tt>.
--   
--   NOTE: This functions is different from <a>unlines</a>, it DOES NOT add
--   a trailing <tt>n</tt>.
unlines :: [Bytes] -> Bytes

-- | Add padding to the left so that the whole vector's length is at least
--   n.
padLeft :: Vec v a => Int -> a -> v a -> v a

-- | Add padding to the right so that the whole vector's length is at least
--   n.
padRight :: Vec v a => Int -> a -> v a -> v a

-- | <i>O(n)</i> <a>reverse</a> <tt>vs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: forall v a. Vec v a => v a -> v a

-- | <i>O(n)</i> The <a>intersperse</a> function takes an element and a
--   vector and `intersperses' that element between the elements of the
--   vector. It is analogous to the intersperse function on Lists.
intersperse :: forall v a. Vec v a => a -> v a -> v a

-- | <i>O(n)</i> The <a>intercalate</a> function takes a vector and a list
--   of vectors and concatenates the list after interspersing the first
--   argument between each element of the list.
--   
--   Note: <a>intercalate</a> will force the entire vector list.
intercalate :: Vec v a => v a -> [v a] -> v a

-- | <i>O(n)</i> An efficient way to join vector with an element.
intercalateElem :: forall v a. Vec v a => a -> [v a] -> v a

-- | The <a>transpose</a> function transposes the rows and columns of its
--   vector argument.
transpose :: Vec v a => [v a] -> [v a]

-- | <a>zipWith'</a> zip two vector with a zipping function.
--   
--   For example, <tt><a>zipWith</a> (+)</tt> is applied to two vector to
--   produce a vector of corresponding sums, the result will be evaluated
--   strictly.
zipWith' :: forall v a u b w c. (Vec v a, Vec u b, Vec w c) => (a -> b -> c) -> v a -> u b -> w c

-- | <a>unzipWith'</a> disassemble a vector with a disassembling function,
--   
--   The results inside tuple will be evaluated strictly.
unzipWith' :: forall v a u b w c. (Vec v a, Vec u b, Vec w c) => (a -> (b, c)) -> v a -> (u b, w c)

-- | <a>scanl'</a> is similar to <tt>foldl</tt>, 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>
--   lastM (scanl' f z xs) == Just (foldl f z xs).
--   </pre>
scanl' :: forall v u a b. (Vec v a, Vec u b) => (b -> a -> b) -> b -> v a -> u b

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

-- | scanr' is the right-to-left dual of scanl'.
scanr' :: forall v u a b. (Vec v a, Vec u b) => (a -> b -> b) -> b -> v a -> u b

-- | <a>scanr1'</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1' :: forall v a. Vec v a => (a -> a -> a) -> v a -> v a

-- | <i>O(n)</i> <a>elem</a> test if given element is in given vector.
elem :: (Vec v a, Eq a) => a -> v a -> Bool

-- | <i>O(n)</i> 'not . elem'
notElem :: (Vec v a, Eq a) => a -> v a -> Bool

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given vector which is equal to the query element,
--   or <a>Nothing</a> if there is no such element.
elemIndex :: (Vec v a, Eq a) => a -> v a -> Maybe Int

-- | <i>O(n)</i> find the first index and element matching the predicate in
--   a vector from left to right, if there isn't one, return (length of the
--   vector, Nothing).
find :: Vec v a => (a -> Bool) -> v a -> (Int, Maybe a)

-- | <i>O(n)</i> Find the first index and element matching the predicate in
--   a vector from right to left, if there isn't one, return '(-1,
--   Nothing)'.
findR :: Vec v a => (a -> Bool) -> v a -> (Int, Maybe a)

-- | The <a>findIndex</a> function takes a predicate and a vector and
--   returns the index of the first element in the vector satisfying the
--   predicate.
findIndices :: Vec v a => (a -> Bool) -> v a -> [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.
elemIndices :: (Vec v a, Eq a) => a -> v a -> [Int]

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a vector,
--   returns a vector containing those elements that satisfy the predicate.
filter :: forall v a. Vec v a => (a -> Bool) -> v a -> v a

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

-- | <i>O(n+m)</i> Find the offsets of all indices (possibly overlapping)
--   of <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm.
--   
--   The KMP algorithm need pre-calculate a shift table in <i>O(m)</i> time
--   and space, the worst case time complexity is <i>O(n+m)</i>. Partial
--   apply this function to reuse pre-calculated table between same
--   needles.
--   
--   Chunked input are support via partial match argument, if set we will
--   return an extra negative index in case of partial match at the end of
--   input chunk, e.g.
--   
--   <pre>
--   indicesOverlapping [ascii|ada|]  [ascii|adadad|] True == [0,2,-2]
--   </pre>
--   
--   Where <tt>-2</tt> is the length of the partial match part <tt>ad</tt>
--   's negation.
--   
--   If an empty pattern is supplied, we will return every possible index
--   of haystack, e.g.
--   
--   <pre>
--   indicesOverlapping "" "abc" = [0,1,2]
--   </pre>
--   
--   References:
--   
--   <ul>
--   <li>Knuth, Donald; Morris, James H.; Pratt, Vaughan: "Fast pattern
--   matching in strings" (1977)</li>
--   
--   <li><a>http://www-igm.univ-mlv.fr/~lecroq/string/node8.html#SECTION0080</a></li>
--   </ul>
indicesOverlapping :: (Vec v a, Eq a) => v a -> v a -> Bool -> [Int]

-- | <i>O(n+m)</i> Find the offsets of all non-overlapping indices of
--   <tt>needle</tt> within <tt>haystack</tt> using KMP algorithm.
--   
--   If an empty pattern is supplied, we will return every possible index
--   of haystack, e.g.
--   
--   <pre>
--   indicesOverlapping "" "abc" = [0,1,2]
--   </pre>
indices :: (Vec v a, Eq a) => v a -> v a -> Bool -> [Int]

-- | <i>O(n*log(n))</i> Sort vector based on element's <a>Ord</a> instance
--   with classic <a>mergesort</a> algorithm.
--   
--   This is a stable sort, During sorting two O(n) worker arrays are
--   needed, one of them will be freezed into the result vector. The merge
--   sort only begin at tile size larger than <a>mergeTileSize</a>, each
--   tile will be sorted with <a>insertSort</a>, then iteratively merged
--   into larger array, until all elements are sorted.
mergeSort :: forall v a. (Vec v a, Ord a) => v a -> v a
mergeSortBy :: forall v a. Vec v a => (a -> a -> Ordering) -> v a -> v a

-- | The mergesort tile size, <tt>mergeTileSize = 8</tt>.
mergeTileSize :: Int

-- | <i>O(n^2)</i> Sort vector based on element's <a>Ord</a> instance with
--   simple <a>insertion-sort</a> algorithm.
--   
--   This is a stable sort. O(n) extra space are needed, which will be
--   freezed into result vector.
insertSort :: (Vec v a, Ord a) => v a -> v a
insertSortBy :: Vec v a => (a -> a -> Ordering) -> v a -> v a

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

-- | <i>O(n)</i> Sort vector based on element's <a>Radix</a> instance with
--   <a>radix-sort</a>, (Least significant digit radix sorts variation).
--   
--   This is a stable sort, one or two extra O(n) worker array are need
--   depend on how many <a>passes</a> shall be performed, and a
--   <a>bucketSize</a> counting bucket are also needed. This sort
--   algorithms performed extremly well on small byte size types such as
--   <a>Int8</a> or <a>Word8</a>, while on larger type, constant passes may
--   render this algorithm not suitable for small vectors (turning point
--   around 2^(2*passes)).
radixSort :: forall v a. (Vec v a, Radix a) => v a -> v a

-- | Types contain radixs, which can be inspected with <a>radix</a> during
--   different <a>passes</a>.
--   
--   The default instances share a same <a>bucketSize</a> 256, which seems
--   to be a good default.
class Radix a

-- | The size of an auxiliary array, i.e. the counting bucket
bucketSize :: Radix a => a -> Int

-- | The number of passes necessary to sort an array of es, it equals to
--   the key's byte number.
passes :: Radix a => a -> Int

-- | The radix function used in the first pass, works on the least
--   significant bit.
radixLSB :: Radix a => a -> Int

-- | The radix function parameterized by the current pass (0 &lt; pass &lt;
--   passes e-1).
radix :: Radix a => Int -> a -> Int

-- | The radix function used in the last pass, works on the most
--   significant bit.
radixMSB :: Radix a => a -> Int

-- | Similar to <a>Down</a> newtype for <a>Ord</a>, this newtype can
--   inverse the order of a <a>Radix</a> instance when used in
--   <a>radixSort</a>.
newtype RadixDown a
RadixDown :: a -> RadixDown a
vecASCII :: QuasiQuoter
vecW8 :: QuasiQuoter
vecW16 :: QuasiQuoter
vecW32 :: QuasiQuoter
vecW64 :: QuasiQuoter
vecWord :: QuasiQuoter
vecI8 :: QuasiQuoter
vecI16 :: QuasiQuoter
vecI32 :: QuasiQuoter
vecI64 :: QuasiQuoter
vecInt :: QuasiQuoter

-- | Pair type to help GHC unpack in some loops, useful when write fast
--   folds.
data IPair a
IPair :: {-# UNPACK #-} !Int -> a -> IPair a
[ifst] :: IPair a -> {-# UNPACK #-} !Int
[isnd] :: IPair a -> a

-- | Unlike <a>Functor</a> instance, this mapping evaluate value inside
--   <a>IPair</a> strictly.
mapIPair' :: (a -> b) -> IPair a -> IPair b

-- | <tt>defaultInitSize = 30</tt>, used as initialize size when packing
--   list of unknown size.
defaultInitSize :: Int

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

-- | The chunk size used for I/O. Currently set to <tt>16k -
--   chunkOverhead</tt>
defaultChunkSize :: Int

-- | The recommended chunk size. Currently set to <tt>4k -
--   chunkOverhead</tt>.
smallChunkSize :: Int

-- | All exception can be throw by using <a>Vec</a>.
data VectorException
IndexOutOfVectorRange :: {-# UNPACK #-} !Int -> CallStack -> VectorException
EmptyVector :: CallStack -> VectorException

-- | Cast between vectors
castVector :: (Vec v a, Cast a b) => v a -> v b


-- | Parsers for parsing dates and times.
module Z.Data.Parser.Time

-- | Parse a date of the form <tt>[+,-]YYYY-MM-DD</tt>.
day :: Parser Day

-- | Parse a date and time, of the form <tt>YYYY-MM-DD
--   HH:MM[:SS[.SSS]]</tt>. The space may be replaced with a <tt>T</tt>.
--   The number of seconds is optional and may be followed by a fractional
--   component.
localTime :: Parser LocalTime

-- | Parse a time of the form <tt>HH:MM[:SS[.SSS]]</tt>.
timeOfDay :: Parser TimeOfDay

-- | Parse a time zone, and return <a>Nothing</a> if the offset from UTC is
--   zero. (This makes some speedups possible.)
timeZone :: Parser (Maybe TimeZone)

-- | Behaves as <a>zonedTime</a>, but converts any time zone offset into a
--   -- UTC time.
utcTime :: Parser UTCTime

-- | Parse a date with time zone info. Acceptable formats:
--   
--   <pre>
--   YYYY-MM-DD HH:MM Z
--   YYYY-MM-DD HH:MM:SS Z
--   YYYY-MM-DD HH:MM:SS.SSS Z
--   </pre>
--   
--   The first space may instead be a <tt>T</tt>, and the second space is
--   optional. The <tt>Z</tt> represents UTC. The <tt>Z</tt> may be
--   replaced with a time zone offset of the form <tt>+0000</tt> or
--   <tt>-08:00</tt>, where the first two digits are hours, the <tt>:</tt>
--   is optional and the second two digits (also optional) are minutes.
zonedTime :: Parser ZonedTime


-- | This module provide a simple resumable <a>Parser</a>, which is
--   suitable for binary protocol and simple textual protocol parsing. Both
--   binary parsers (<a>decodePrim</a> ,etc) and textual parsers are
--   provided, and they all work on <a>Bytes</a>.
--   
--   You can use <tt>Alternative</tt> instance to do backtracking, each
--   branch will either succeed and may consume some input, or fail without
--   consume anything. It's recommend to use <a>peek</a> or
--   <a>peekMaybe</a> to avoid backtracking if possible to get high
--   performance.
--   
--   Error message can be attached using <a>&lt;?&gt;</a>, which have very
--   small overhead, so it's recommended to attach a message in front of a
--   composed parser like <tt>xPacket = "Foo.Bar.xPacket" <a>?</a> do
--   ...</tt>, following is an example message when parsing an integer
--   failed:
--   
--   <pre>
--   &gt;parse int "foo"
--   ([102,111,111],Left ["Z.Data.Parser.Numeric.int","Std.Data.Parser.Base.takeWhile1: no satisfied byte"])
--   -- It's easy to see we're trying to match a leading sign or digit here
--   </pre>
--   
--   Use <a>parser-combinators</a> to get combinators based on
--   <a>Applicative</a> or <a>Monad</a> instance, such as
--   <tt>manyTill</tt>, <tt>sepBy</tt>, etc.
module Z.Data.Parser

-- | Simple parsing result, that represent respectively:
--   
--   <ul>
--   <li>Success: the remaining unparsed data and the parsed value</li>
--   <li>Failure: the remaining unparsed data and the error message</li>
--   <li>Partial: that need for more input data, supply empty bytes to
--   indicate <a>endOfInput</a></li>
--   </ul>
data Result a
Success :: a -> !Bytes -> Result a
Failure :: ParseError -> !Bytes -> Result a
Partial :: ParseStep a -> Result a

-- | Type alias for error message
type ParseError = [Text]

-- | Simple CPSed parser
--   
--   A parser takes a failure continuation, and a success one, while the
--   success continuation is usually composed by <a>Monad</a> instance, the
--   failure one is more like a reader part, which can be modified via
--   <a>&lt;?&gt;</a>. If you build parsers from ground, a pattern like
--   this can be used:
--   
--   <pre>
--   xxParser = do
--     ensureN errMsg ...            -- make sure we have some bytes
--     Parser $  kf k inp -&gt;        -- fail continuation, success continuation and input
--       ...
--       ... kf errMsg (if input not OK)
--       ... k ... (if we get something useful for next parser)
--   
--   </pre>
data Parser a
(<?>) :: Text -> Parser a -> Parser a
infixr 0 <?>

-- | Parse the complete input, without resupplying, return the rest bytes
parse :: Parser a -> Bytes -> (Bytes, Either ParseError a)

-- | Parse the complete input, without resupplying
parse' :: Parser a -> Bytes -> Either ParseError a

-- | Parse an input chunk
parseChunk :: Parser a -> Bytes -> Result a

-- | Type alias for a streaming parser, draw chunk from Monad m (with a
--   initial chunk), return result in <tt>Either err x</tt>.
type ParseChunks m chunk err x = m chunk -> chunk -> m (chunk, Either err x)

-- | Run a parser with an initial input string, and a monadic action that
--   can supply more input if needed.
--   
--   Note, once the monadic action return empty bytes, parsers will stop
--   drawing more bytes (take it as <a>endOfInput</a>).
parseChunks :: Monad m => Parser a -> ParseChunks m Bytes ParseError a

-- | Finish parsing and fetch result, feed empty bytes if it's
--   <a>Partial</a> result.
finishParsing :: Result a -> (Bytes, Either ParseError a)

-- | Run a parser and keep track of all the input chunks it consumes. Once
--   it's finished, return the final result (always <a>Success</a> or
--   <a>Failure</a>) and all consumed chunks.
runAndKeepTrack :: Parser a -> Parser (Result a, [Bytes])

-- | Return both the result of a parse and the portion of the input that
--   was consumed while it was being parsed.
match :: Parser a -> Parser (Bytes, a)

-- | Ensure that there are at least <tt>n</tt> bytes available. If not, the
--   computation will escape with <a>Partial</a>.
--   
--   Since this parser is used in many other parsers, an extra error param
--   is provide to attach custom error info.
ensureN :: Int -> ParseError -> Parser ()

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes. Fail if not <a>atEnd</a>.
endOfInput :: Parser ()

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes.
atEnd :: Parser Bool

-- | Decode a primitive type in host byte order.
decodePrim :: forall a. Unaligned a => Parser a

-- | big endianess wrapper
newtype BE a
BE :: a -> BE a
[getBE] :: BE a -> a

-- | little endianess wrapper
newtype LE a
LE :: a -> LE a
[getLE] :: LE a -> a

-- | Decode a primitive type in little endian.
decodePrimLE :: forall a. Unaligned (LE a) => Parser a

-- | Decode a primitive type in big endian.
decodePrimBE :: forall a. Unaligned (BE a) => Parser a

-- | A stateful scanner. The predicate consumes and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each byte of the input until one
--   returns <a>Nothing</a> or the input ends.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>Nothing</a> on the first byte of input.
scan :: s -> (s -> Word8 -> Maybe s) -> Parser (Bytes, s)

-- | Similar to <a>scan</a>, but working on <a>Bytes</a> chunks, The
--   predicate consumes a <a>Bytes</a> chunk and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each chunk of the input until one
--   chunk got splited to <tt>Right (V.Bytes, V.Bytes)</tt> or the input
--   ends.
scanChunks :: forall s. s -> (s -> Bytes -> Either s (Bytes, Bytes, s)) -> Parser (Bytes, s)

-- | Match any byte, to perform lookahead. Returns <a>Nothing</a> if end of
--   input has been reached. Does not consume any input.
peekMaybe :: Parser (Maybe Word8)

-- | Match any byte, to perform lookahead. Does not consume any input, but
--   will fail if end of input has been reached.
peek :: Parser Word8

-- | The parser <tt>satisfy p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the byte that is
--   actually parsed.
--   
--   <pre>
--   digit = satisfy isDigit
--       where isDigit w = w &gt;= 48 &amp;&amp; w &lt;= 57
--   </pre>
satisfy :: (Word8 -> Bool) -> Parser Word8

-- | The parser <tt>satisfyWith f p</tt> transforms a byte, and succeeds if
--   the predicate <tt>p</tt> returns <a>True</a> on the transformed value.
--   The parser returns the transformed byte that was parsed.
satisfyWith :: (Word8 -> a) -> (a -> Bool) -> Parser a

-- | Return a byte, this is an alias to <tt>decodePrim </tt>Word8@.
anyWord8 :: Parser Word8

-- | Match a specific byte.
word8 :: Word8 -> Parser ()

-- | Take a byte and return as a 8bit char.
anyChar8 :: Parser Char

-- | Match a specific 8bit char.
char8 :: Char -> Parser ()

-- | Skip a byte.
skipWord8 :: Parser ()

-- | Match either a single newline byte <tt>'\n'</tt>, or a carriage return
--   followed by a newline byte <tt>"\r\n"</tt>.
endOfLine :: Parser ()

-- | <a>skip</a> N bytes.
skip :: Int -> Parser ()

-- | Skip past input for as long as the predicate returns <a>True</a>.
skipWhile :: (Word8 -> Bool) -> Parser ()

-- | Skip over white space using <a>isSpace</a>.
skipSpaces :: Parser ()
take :: Int -> Parser Bytes

-- | Consume input as long as the predicate returns <a>False</a> or reach
--   the end of input, and return the consumed input.
takeTill :: (Word8 -> Bool) -> Parser Bytes

-- | Consume input as long as the predicate returns <a>True</a> or reach
--   the end of input, and return the consumed input.
takeWhile :: (Word8 -> Bool) -> Parser Bytes

-- | Similar to <a>takeWhile</a>, but requires the predicate to succeed on
--   at least one byte of input: it will fail if the predicate never
--   returns <a>True</a> or reach the end of input
takeWhile1 :: (Word8 -> Bool) -> Parser Bytes

-- | Take all the remaining input chunks and return as <a>Bytes</a>.
takeRemaining :: Parser Bytes

-- | <tt>bytes s</tt> parses a sequence of bytes that identically match
--   <tt>s</tt>.
bytes :: Bytes -> Parser ()

-- | Same as <a>bytes</a> but ignoring case.
bytesCI :: Bytes -> Parser ()

-- | <tt>text s</tt> parses a sequence of UTF8 bytes that identically match
--   <tt>s</tt>.
text :: Text -> Parser ()

-- | Parse and decode an unsigned decimal number.
--   
--   Will fail in case of overflow.
uint :: forall a. (Integral a, Bounded a) => Parser a

-- | Parse a decimal number with an optional leading <tt>'+'</tt> or
--   <tt>'-'</tt> sign character.
--   
--   This parser will fail if overflow happens.
int :: forall a. (Integral a, Bounded a) => Parser a

-- | Parser specifically optimized for <a>Integer</a>.
integer :: Parser Integer

-- | Same with <a>uint</a>, but sliently cast in case of overflow.
uint_ :: forall a. (Integral a, Bounded a) => Parser a

-- | Same with <a>int</a>, but sliently cast if overflow happens.
int_ :: (Integral a, Bounded a) => Parser a

-- | Take a single decimal digit and return as <a>Int</a>.
digit :: Parser Int

-- | Parse and decode an unsigned hex number, fail if input length is
--   larger than (bit_size/4). The hex digits <tt>'a'</tt> through
--   <tt>'f'</tt> may be upper or lower case.
--   
--   This parser does not accept a leading <tt>"0x"</tt> string, and
--   consider sign bit part of the binary hex nibbles, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Left ["Z.Data.Parser.Numeric.hex","hex numeric number overflow"]
--   </pre>
hex :: forall a. (Integral a, FiniteBits a) => Parser a

-- | Same with <a>hex</a>, but only take as many as (bit_size/4) bytes.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Right (127 :: Int8)
--   </pre>
hex' :: forall a. (Integral a, FiniteBits a) => Parser a

-- | Same with <a>hex</a>, but silently cast in case of overflow.
--   
--   <pre>
--   &gt;&gt;&gt; parse' hex "FF" == Right (-1 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7F" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7Ft" == Right (127 :: Int8)
--   
--   &gt;&gt;&gt; parse' hex "7FF" == Right (-1 :: Int8)
--   </pre>
hex_ :: (Integral a, Bits a) => Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
--   
--   <i>Note</i>: this parser is not safe for use with inputs from
--   untrusted sources. An input with a suitably large exponent such as
--   <tt>"1e1000000000"</tt> will cause a huge <a>Integer</a> to be
--   allocated, resulting in what is effectively a denial-of-service
--   attack.
--   
--   In most cases, it is better to use <a>double</a> or <a>scientific</a>
--   instead.
rational :: Fractional a => Parser a

-- | Parse a rational number and round to <a>Float</a>.
--   
--   Single precision version of <a>double</a>.
float :: Parser Float

-- | Parse a rational number and round to <a>Double</a>.
--   
--   This parser accepts an optional leading sign character, followed by at
--   least one decimal digit. The syntax similar to that accepted by the
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples with behaviour identical to <a>read</a>:
--   
--   <pre>
--   parse' double "3"     == ("", Right 3.0)
--   parse' double "3.1"   == ("", Right 3.1)
--   parse' double "3e4"   == ("", Right 30000.0)
--   parse' double "3.1e4" == ("", Right 31000.0)
--   </pre>
--   
--   <pre>
--   parse' double ".3"    == (".3", Left ParserError)
--   parse' double "e3"    == ("e3", Left ParserError)
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   parse' double "3.foo" == (".foo", Right 3.0)
--   parse' double "3e"    == ("e",    Right 3.0)
--   parse' double "-3e"   == ("e",    Right -3.0)
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
double :: Parser Double

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
scientific :: Parser Scientific

-- | Parse a scientific number and convert to result using a user supply
--   function.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
scientifically :: (Scientific -> a) -> Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
--   
--   <i>Note</i>: this parser is not safe for use with inputs from
--   untrusted sources. An input with a suitably large exponent such as
--   <tt>"1e1000000000"</tt> will cause a huge <a>Integer</a> to be
--   allocated, resulting in what is effectively a denial-of-service
--   attack.
--   
--   In most cases, it is better to use <a>double'</a> or
--   <a>scientific'</a> instead.
rational' :: Fractional a => Parser a

-- | Parse a rational number and round to <a>Float</a> using stricter
--   grammer.
--   
--   Single precision version of <a>double'</a>.
float' :: Parser Float

-- | More strict number parsing(rfc8259).
--   
--   <a>scientific</a> support parse <tt>2314.</tt> and <tt>21321exyz</tt>
--   without eating extra dot or <tt>e</tt> via backtrack, this is not
--   allowed in some strict grammer such as JSON, so we make an
--   non-backtrack strict number parser separately using LL(1) lookahead.
--   This parser also agree with <a>read</a> on extra dot or e handling:
--   
--   <pre>
--   parse' double "3.foo" == Left ParseError
--   parse' double "3e"    == Left ParseError
--   </pre>
--   
--   Leading zeros or <tt>+</tt> sign is also not allowed:
--   
--   <pre>
--   parse' double "+3.14" == Left ParseError
--   parse' double "0014" == Left ParseError
--   </pre>
--   
--   If you have a similar grammer, you can use this parser to save
--   considerable time.
--   
--   <pre>
--   number = [ minus ] int [ frac ] [ exp ]
--   decimal-point = %x2E       ; .
--   digit1-9 = %x31-39         ; 1-9
--   e = %x65 / %x45            ; e E
--   exp = e [ minus / plus ] 1*DIGIT
--   frac = decimal-point 1*DIGIT
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity". reference:
--   <a>https://tools.ietf.org/html/rfc8259#section-6</a>
double' :: Parser Double

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
scientific' :: Parser Scientific

-- | Parse a scientific number and convert to result using a user supply
--   function.
--   
--   The syntax accepted by this parser is the same as for <a>double'</a>.
scientifically' :: (Scientific -> a) -> Parser a

-- | Parse a date of the form <tt>[+,-]YYYY-MM-DD</tt>.
day :: Parser Day

-- | Parse a date and time, of the form <tt>YYYY-MM-DD
--   HH:MM[:SS[.SSS]]</tt>. The space may be replaced with a <tt>T</tt>.
--   The number of seconds is optional and may be followed by a fractional
--   component.
localTime :: Parser LocalTime

-- | Parse a time of the form <tt>HH:MM[:SS[.SSS]]</tt>.
timeOfDay :: Parser TimeOfDay

-- | Parse a time zone, and return <a>Nothing</a> if the offset from UTC is
--   zero. (This makes some speedups possible.)
timeZone :: Parser (Maybe TimeZone)

-- | Behaves as <a>zonedTime</a>, but converts any time zone offset into a
--   -- UTC time.
utcTime :: Parser UTCTime

-- | Parse a date with time zone info. Acceptable formats:
--   
--   <pre>
--   YYYY-MM-DD HH:MM Z
--   YYYY-MM-DD HH:MM:SS Z
--   YYYY-MM-DD HH:MM:SS.SSS Z
--   </pre>
--   
--   The first space may instead be a <tt>T</tt>, and the second space is
--   optional. The <tt>Z</tt> represents UTC. The <tt>Z</tt> may be
--   replaced with a time zone offset of the form <tt>+0000</tt> or
--   <tt>-08:00</tt>, where the first two digits are hours, the <tt>:</tt>
--   is optional and the second two digits (also optional) are minutes.
zonedTime :: Parser ZonedTime

-- | <a>Text</a> version of <a>fail</a>.
fail' :: Text -> Parser a


-- | This module provide functions for using <a>PrimArray</a> and
--   <a>PrimVector</a> with GHC FFI(Foreign function interface), Some
--   functions are designed to be used with <a>UnliftedFFITypes</a>
--   extension.
--   
--   GHC runtime is garbaged collected, there're two types of primitive
--   array in GHC, with the objective to minimize overall memory management
--   cost:
--   
--   <ul>
--   <li>Small primitive arrays created with <a>newPrimArray</a> are
--   directly allocated on GHC heap, which can be moved by GHC garbage
--   collector, we call these arrays <tt>unpinned</tt>. Allocating these
--   array is cheap, we only need to check heap limit and bump heap pointer
--   just like any other haskell heap objects. But we will pay GC cost ,
--   which is OK for small arrays.</li>
--   <li>Large primitive array and those created with
--   <a>newPinnedPrimArray</a> are allocated on GHC managed memory blocks,
--   which is also traced by garbage collector, but will never moved before
--   freed, thus are called <tt>pinned</tt>. Allocating these arrays are
--   bit more expensive since it's more like how <tt>malloc</tt> works, but
--   we don't have to pay for GC cost.</li>
--   </ul>
--   
--   Beside the <tt>pinned/unpinned</tt> difference, we have two types of
--   FFI calls in GHC:
--   
--   <ul>
--   <li>Safe FFI call annotated with <tt>safe</tt> keyword. These calls
--   are executed on separated OS thread, which can be running concurrently
--   with GHC garbage collector, thus we want to make sure only pinned
--   arrays are passed. The main use case for <tt>safe</tt> FFIs are long
--   running functions, for example, doing IO polling. Since these calls
--   are running on separated OS thread, haskell thread on original OS
--   thread will not be affected.</li>
--   <li>Unsafe FFI call annotated with <tt>unsafe</tt> keyword. These
--   calls are executed on the same OS thread which is running the haskell
--   side FFI code, which will in turn stop GHC from doing a garbage
--   collection. We can pass both <tt>pinned</tt> and <tt>unpinned</tt>
--   arrays in this case. The use case for <tt>unsafe</tt> FFIs are
--   short/small functions, which can be treated like a fat primitive
--   operations, such as <tt>memcpy</tt>, <tt>memcmp</tt>. Using
--   <tt>unsafe</tt> FFI with long running functions will effectively block
--   GHC runtime thread from running any other haskell threads, which is
--   dangerous. Even if you use threaded runtime and expect your haskell
--   thread can be stolen by other OS threads, but this will not work since
--   GHC garbage collector will refuse to run if one of the OS thread is
--   blocked by FFI calls.</li>
--   </ul>
--   
--   Base on above analysis, we have following FFI strategy table.
--   
--   TODO: table
--   
--   In this module, we separate safe and unsafe FFI handling due to the
--   strategy difference: if the user can guarantee a FFI call is unsafe,
--   we can save an extra copy and pinned allocation. Mistakenly using
--   unsafe function with safe FFI will result in segfault.
module Z.Foreign

-- | Pass primitive array to unsafe FFI as pointer.
--   
--   Enable <tt>UnliftedFFITypes</tt> extension in your haskell code, use
--   proper pointer type and <tt>HsInt</tt> to marshall <tt>ByteArray#</tt>
--   and <tt>Int</tt> arguments on C side.
--   
--   The second <a>Int</a> arguement is the element size not the bytes
--   size.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withPrimArrayUnsafe :: Prim a => PrimArray a -> (BA# a -> Int -> IO b) -> IO b

-- | Allocate some bytes and pass to FFI as pointer, freeze result into a
--   <a>PrimArray</a>.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
allocPrimArrayUnsafe :: forall a b. Prim a => Int -> (MBA# a -> IO b) -> IO (PrimArray a, b)

-- | Pass <a>PrimVector</a> to unsafe FFI as pointer
--   
--   The <a>PrimVector</a> version of <a>withPrimArrayUnsafe</a>.
--   
--   The second <a>Int</a> arguement is the first element offset, the third
--   <a>Int</a> argument is the element length.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withPrimVectorUnsafe :: Prim a => PrimVector a -> (BA# a -> Int -> Int -> IO b) -> IO b

-- | Allocate a prim array and pass to FFI as pointer, freeze result into a
--   <a>PrimVector</a>.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
allocPrimVectorUnsafe :: forall a b. Prim a => Int -> (MBA# a -> IO b) -> IO (PrimVector a, b)

-- | Allocate some bytes and pass to FFI as pointer, freeze result into a
--   <a>Bytes</a>.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
allocBytesUnsafe :: Int -> (MBA# a -> IO b) -> IO (Bytes, b)

-- | Create an one element primitive array and use it as a pointer to the
--   primitive element.
--   
--   Return the element and the computation result.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withPrimUnsafe :: Prim a => a -> (MBA# a -> IO b) -> IO (a, b)

-- | like <a>withPrimUnsafe</a>, but don't write initial value.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
allocPrimUnsafe :: Prim a => (MBA# a -> IO b) -> IO (a, b)

-- | Pass primitive array list to unsafe FFI as <tt>StgArrBytes**</tt>.
--   
--   Enable <tt>UnliftedFFITypes</tt> extension in your haskell code, use
--   <tt>StgArrBytes**</tt>(&gt;=8.10) or <tt>StgMutArrPtrs*</tt>(&lt;8.10)
--   pointer type and <tt>HsInt</tt> to marshall <tt>BAArray#</tt> and
--   <tt>Int</tt> arguments on C side, check the example with
--   <a>BAArray#</a>.
--   
--   The second <a>Int</a> arguement is the list size.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withPrimArrayListUnsafe :: [PrimArray a] -> (BAArray# a -> Int -> IO b) -> IO b

-- | Pass primitive array to safe FFI as pointer.
--   
--   Use proper pointer type and <tt>HsInt</tt> to marshall <tt>Ptr a</tt>
--   and <tt>Int</tt> arguments on C side. The memory pointed by 'Ptr a'
--   will not moved during call. After call returned, pointer is no longer
--   valid.
--   
--   The second <a>Int</a> arguement is the element size not the bytes
--   size.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimArraySafe :: Prim a => PrimArray a -> (Ptr a -> Int -> IO b) -> IO b

-- | Allocate a prim array and pass to FFI as pointer, freeze result into a
--   <a>PrimVector</a>.
allocPrimArraySafe :: forall a b. Prim a => Int -> (Ptr a -> IO b) -> IO (PrimArray a, b)

-- | Pass <a>PrimVector</a> to safe FFI as pointer
--   
--   The <a>PrimVector</a> version of <a>withPrimArraySafe</a>. The
--   <a>Ptr</a> is already pointed to the first element, thus no offset is
--   provided. After call returned, pointer is no longer valid.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimVectorSafe :: forall a b. Prim a => PrimVector a -> (Ptr a -> Int -> IO b) -> IO b

-- | Allocate a prim array and pass to FFI as pointer, freeze result into a
--   <a>PrimVector</a>.
allocPrimVectorSafe :: forall a b. Prim a => Int -> (Ptr a -> IO b) -> IO (PrimVector a, b)

-- | Allocate some bytes and pass to FFI as pointer, freeze result into a
--   <a>PrimVector</a>.
allocBytesSafe :: Int -> (Ptr Word8 -> IO b) -> IO (Bytes, b)

-- | Create an one element primitive array and use it as a pointer to the
--   primitive element.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimSafe :: forall a b. Prim a => a -> (Ptr a -> IO b) -> IO (a, b)

-- | like <a>withPrimSafe</a>, but don't write initial value.
allocPrimSafe :: forall a b. Prim a => (Ptr a -> IO b) -> IO (a, b)

-- | Pass primitive array list to safe FFI as pointer.
--   
--   Use proper pointer type and <tt>HsInt</tt> to marshall <tt>Ptr (Ptr
--   a)</tt> and <tt>Int</tt> arguments on C side. The memory pointed by
--   'Ptr a' will not moved during call. After call returned, pointer is no
--   longer valid.
--   
--   The second <a>Int</a> arguement is the list size.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withPrimArrayListSafe :: Prim a => [PrimArray a] -> (Ptr (Ptr a) -> Int -> IO b) -> IO b

-- | Convert a <a>PrimArray</a> to a pinned one(memory won't moved by GC)
--   if necessary.
pinPrimArray :: Prim a => PrimArray a -> IO (PrimArray a)

-- | Convert a <a>PrimVector</a> to a pinned one(memory won't moved by GC)
--   if necessary.
pinPrimVector :: Prim a => PrimVector a -> IO (PrimVector a)

-- | Type alias for <a>ByteArray#</a>.
--   
--   Describe a <a>ByteArray#</a> which we are going to pass across FFI.
--   Use this type with <tt>UnliftedFFITypes</tt> extension, At C side you
--   should use a proper const pointer type.
--   
--   Don't cast <a>BA#</a> to <a>Addr#</a> since the heap object offset is
--   hard-coded in code generator: <a>Note [Unlifted boxed arguments to
--   foreign calls]</a>
--   
--   In haskell side we use type system to distinguish immutable / mutable
--   arrays, but in C side we can't. So it's users' responsibility to make
--   sure the array content is not mutated (a const pointer type may help).
--   
--   USE THIS TYPE WITH UNSAFE FFI CALL ONLY. A <a>ByteArray#</a> COULD BE
--   MOVED BY GC DURING SAFE FFI CALL.
type BA# a = ByteArray#

-- | Type alias for <a>MutableByteArray#</a> <a>RealWorld</a>.
--   
--   Describe a <a>MutableByteArray#</a> which we are going to pass across
--   FFI. Use this type with <tt>UnliftedFFITypes</tt> extension, At C side
--   you should use a proper pointer type.
--   
--   Don't cast <a>MBA#</a> to <a>Addr#</a> since the heap object offset is
--   hard-coded in code generator: <a>Note [Unlifted boxed arguments to
--   foreign calls]</a>
--   
--   USE THIS TYPE WITH UNSAFE FFI CALL ONLY. A <a>MutableByteArray#</a>
--   COULD BE MOVED BY GC DURING SAFE FFI CALL.
type MBA# a = MutableByteArray# RealWorld

-- | Type alias for <a>ArrayArray#</a>.
--   
--   Describe a array of <a>ByteArray#</a> which we are going to pass
--   across FFI. Use this type with <tt>UnliftedFFITypes</tt> extension, At
--   C side you should use <tt>StgArrBytes**</tt>(&gt;=8.10) or
--   <tt>StgMutArrPtrs*</tt>(&lt;8.10) type from "Rts.h", example code
--   modified from <a>GHC manual</a>:
--   
--   <pre>
--   // C source, must include the RTS to make the struct StgArrBytes
--   // available along with its fields: ptrs and payload.
--   #include "Rts.h"
--   // GHC 8.10 changes the way how ArrayArray# is passed to C, so...
--   #if __GLASGOW_HASKELL__ &lt; 810
--   HsInt sum_first (StgMutArrPtrs *arr, HsInt len) {
--     StgArrBytes **bufs = (StgArrBytes**)arr-&gt;payload;
--   #else
--   HsInt sum_first (StgArrBytes **bufs, HsInt len) {
--   #endif
--     int res = 0;
--     for(StgWord ix = 0;ix &lt; len;ix++) {
--        // payload pointer type is StgWord*, cast it before use!
--        res = res + ((HsInt*)(bufs[ix]-&gt;payload))[0];
--     }
--     return res;
--   }
--   
--   -- Haskell source, all elements in the argument array must be
--   -- either ByteArray# or MutableByteArray#. This is not enforced
--   -- by the type system in this example since ArrayArray is untyped.
--   foreign import ccall unsafe "sum_first" sumFirst :: BAArray# Int -&gt; Int -&gt; IO CInt
--   </pre>
type BAArray# a = ArrayArray#

-- | Clear <a>MBA#</a> with given length to zero.
clearMBA :: MBA# a -> Int -> IO ()

-- | Zero a structure.
--   
--   There's no <tt>Storable</tt> or <a>Prim</a> constraint on <tt>a</tt>
--   type, the length should be given in bytes.
clearPtr :: Ptr a -> Int -> IO ()

-- | The <a>castPtr</a> function casts a pointer from one type to another.
castPtr :: Ptr a -> Ptr b

-- | Copy some bytes from a null terminated pointer(without copying the
--   null terminator).
--   
--   You should consider using <a>CBytes</a> type for storing NULL
--   terminated bytes first, This method is provided if you really need to
--   read <a>Bytes</a>, there's no encoding guarantee, result could be any
--   bytes sequence.
fromNullTerminated :: Ptr a -> IO Bytes

-- | Copy some bytes from a pointer.
--   
--   There's no encoding guarantee, result could be any bytes sequence.
fromPtr :: Ptr a -> Int -> IO Bytes

-- | Copy some bytes from a pointer.
--   
--   There's no encoding guarantee, result could be any bytes sequence.
fromPrimPtr :: forall a. Prim a => Ptr a -> Int -> IO (PrimVector a)

-- | <tt>std::string</tt> Pointer tag.
data StdString

-- | Run FFI in bracket and marshall <tt>std::string*</tt> result into
--   Haskell heap bytes, memory pointed by <tt>std::string*</tt> will be
--   <tt>delete</tt> ed.
fromStdString :: IO (Ptr StdString) -> IO Bytes

-- | O(n), Convert from <a>ByteString</a>.
fromByteString :: ByteString -> Bytes

-- | O(n), Convert tp <a>ByteString</a>.
toByteString :: Bytes -> ByteString

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld
touch :: PrimMonad m => a -> m ()
hs_std_string_size :: Ptr StdString -> IO Int
hs_copy_std_string :: Ptr StdString -> Int -> MBA# Word8 -> IO ()
hs_delete_std_string :: Ptr StdString -> IO ()


-- | A <a>Builder</a> records a buffer writing function, which can be
--   <a>mappend</a> in O(1) via composition.
--   
--   <ul>
--   <li>When building a short strict <tt>Bytes</tt> with
--   <a>build</a>/<a>buildWith</a>, we double the buffer each time buffer
--   is full.</li>
--   <li>When building a large lazy <tt>[Bytes]</tt> with
--   <a>buildChunks</a>/<a>buildChunksWith</a>, we insert a new chunk when
--   buffer is full.</li>
--   </ul>
--   
--   Most of the time using combinators from this module to build
--   <a>Builder</a> s is enough, but in case of rolling something shining
--   from the ground, keep an eye on correct <a>BuildResult</a> handling.
module Z.Data.Builder.Base

-- | <tt>Builder</tt> is a monad to help compose <tt>BuilderStep</tt>. With
--   next <tt>BuilderStep</tt> continuation, we can do interesting things
--   like perform some action, or interleave the build process.
--   
--   Notes on <a>IsString</a> instance: <tt>Builder ()</tt>'s
--   <a>IsString</a> instance use <a>stringModifiedUTF8</a>, which is
--   different from <a>stringUTF8</a> in that it DOES NOT PROVIDE UTF8
--   GUARANTEES! :
--   
--   <ul>
--   <li><tt>\NUL</tt> will be written as <tt>\xC0 \x80</tt>.</li>
--   <li><tt>\xD800</tt> ~ <tt>\xDFFF</tt> will be encoded in three bytes
--   as normal UTF-8 codepoints.</li>
--   </ul>
newtype Builder a
Builder :: ((a -> BuildStep) -> BuildStep) -> Builder a
[runBuilder] :: Builder a -> (a -> BuildStep) -> BuildStep
append :: Builder a -> Builder b -> Builder b

-- | Helper type to help ghc unpack
data Buffer
Buffer :: {-# UNPACK #-} !MutablePrimArray RealWorld Word8 -> {-# UNPACK #-} !Int -> Buffer

-- | Freeze buffer and return a <a>Bytes</a>.
--   
--   Note the mutable buffer array will be shrinked with
--   <a>shrinkMutablePrimArray</a>, which may not able to be reused.
freezeBuffer :: Buffer -> IO Bytes

-- | <tt>BuildSignal</tt>s abstract signals to the caller of a
--   <a>BuildStep</a>. There are three signals: <a>Done</a>,
--   <a>BufferFull</a>, or <a>InsertBytes</a> signals
data BuildResult
Done :: {-# UNPACK #-} !Buffer -> BuildResult
BufferFull :: {-# UNPACK #-} !Buffer -> {-# UNPACK #-} !Int -> BuildStep -> BuildResult
InsertBytes :: {-# UNPACK #-} !Buffer -> Bytes -> BuildStep -> BuildResult

-- | <tt>BuilderStep</tt> is a function that fill buffer under given
--   conditions.
type BuildStep = Buffer -> IO BuildResult

-- | Shortcut to <a>buildWith</a> <a>defaultInitSize</a>.
build :: Builder a -> Bytes

-- | Run Builder with doubling buffer strategy, which is suitable for
--   building short bytes.
buildWith :: Int -> Builder a -> Bytes

-- | Shortcut to <a>buildChunksWith</a> <a>defaultChunkSize</a>.
buildChunks :: Builder a -> [Bytes]

-- | Run Builder with inserting chunk strategy, which is suitable for
--   building a list of bytes chunks and processing them in a streaming
--   ways.
--   
--   Note the building process is lazy, building happens when list chunks
--   are consumed.
buildChunksWith :: Int -> Int -> Builder a -> [Bytes]

-- | Build some bytes and validate if it's UTF8 bytes.
buildText :: HasCallStack => Builder a -> Text

-- | Build some bytes assuming it's UTF8 encoding.
--   
--   Be carefully use this function because you could constrcut illegal
--   <a>Text</a> values. Check <a>ShowT</a> for UTF8 encoding builders.
--   This functions is intended to be used in debug only.
unsafeBuildText :: Builder a -> Text

-- | Write a <a>Bytes</a>.
bytes :: Bytes -> Builder ()
ensureN :: Int -> (MutablePrimArray RealWorld Word8 -> Int -> IO Int) -> Builder ()
writeN :: Int -> (MutablePrimArray RealWorld Word8 -> Int -> IO ()) -> Builder ()

-- | Write a primitive type in host byte order.
--   
--   <pre>
--   &gt; encodePrim (256 :: Word16, BE 256 :: BE Word16)
--   &gt; [0,1,1,0]
--   </pre>
encodePrim :: forall a. Unaligned a => a -> Builder ()

-- | big endianess wrapper
newtype BE a
BE :: a -> BE a
[getBE] :: BE a -> a

-- | little endianess wrapper
newtype LE a
LE :: a -> LE a
[getLE] :: LE a -> a

-- | Write a primitive type with little endianess.
encodePrimLE :: forall a. Unaligned (LE a) => a -> Builder ()

-- | Write a primitive type with big endianess.
encodePrimBE :: forall a. Unaligned (BE a) => a -> Builder ()

-- | Encode string with modified UTF-8 encoding, will be rewritten to a
--   memcpy if possible.
stringModifiedUTF8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with Modified UTF8 encoding
--   
--   <tt>\NUL</tt> is encoded as two bytes <tt>C0 80</tt> , <tt>\xD800</tt>
--   ~ <tt>\xDFFF</tt> is encoded as a three bytes normal UTF-8 codepoint.
charModifiedUTF8 :: Char -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
--   
--   This is different from writing string literals builders via
--   <tt>OverloadedStrings</tt>, because string literals do not provide
--   UTF8 guarantees.
--   
--   This function will be rewritten into a memcpy if possible, (running a
--   fast UTF-8 validation at runtime first).
stringUTF8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
charUTF8 :: Char -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
string7 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
char7 :: Char -> Builder ()

-- | Turn <a>Word8</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
word7 :: Word8 -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with ASCII8 encoding
--   
--   Codepoints beyond <tt>'xFF'</tt> will be chopped. Note, this encoding
--   is NOT compatible with UTF8 encoding, i.e. bytes written by this
--   builder may not be legal UTF8 encoding bytes.
string8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with ASCII8 encoding
--   
--   Codepoints beyond <tt>'xFF'</tt> will be chopped. Note, this encoding
--   is NOT compatible with UTF8 encoding, i.e. bytes written by this
--   builder may not be legal UTF8 encoding bytes.
char8 :: Char -> Builder ()

-- | Turn <a>Word8</a> into <a>Builder</a> with ASCII8 encoding, (alias to
--   <a>encodePrim</a>).
--   
--   Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes
--   written by this builder may not be legal UTF8 encoding bytes.
word8 :: Word8 -> Builder ()

-- | Faster version of <tt>replicateM x . word8</tt> by using
--   <tt>memset</tt>.
--   
--   Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes
--   written by this builder may not be legal UTF8 encoding bytes.
word8N :: Int -> Word8 -> Builder ()

-- | Write UTF8 encoded <tt>Text</tt> using <a>Builder</a>.
--   
--   Note, if you're trying to write string literals builders, please open
--   <tt>OverloadedStrings</tt> and use <a>Builder</a>s <a>IsString</a>
--   instance, it will be rewritten into a memcpy.
text :: Text -> Builder ()

-- | add <tt>(...)</tt> to original builder.
paren :: Builder () -> Builder ()

-- | add <tt>{...}</tt> to original builder.
curly :: Builder () -> Builder ()

-- | add <tt>[...]</tt> to original builder.
square :: Builder () -> Builder ()

-- | add <tt><i>&lt;...</i>&gt;</tt> to original builder.
angle :: Builder () -> Builder ()

-- | add <tt><i>"...</i>"</tt> to original builder.
quotes :: Builder () -> Builder ()

-- | add <tt><i>'...</i>'</tt> to original builder.
squotes :: Builder () -> Builder ()

-- | write an ASCII <tt>:</tt>
colon :: Builder ()

-- | write an ASCII <tt>,</tt>
comma :: Builder ()

-- | Use separator to connect a vector of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   &gt; T.validate . B.build $ B.intercalateVec "," B.int (V.pack [1,2,3,4] :: V.PrimVector Int)
--   "1,2,3,4"
--   </pre>
intercalateVec :: Vec v a => Builder () -> (a -> Builder ()) -> v a -> Builder ()

-- | Use separator to connect list of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   T.validate . B.build $ B.intercalateList "," B.int ([1,2,3,4] :: [Int])
--   "1,2,3,4"
--   </pre>
intercalateList :: Builder () -> (a -> Builder ()) -> [a] -> Builder ()
instance GHC.Show.Show (Z.Data.Builder.Base.Builder a)
instance GHC.Base.Functor Z.Data.Builder.Base.Builder
instance GHC.Base.Applicative Z.Data.Builder.Base.Builder
instance GHC.Base.Monad Z.Data.Builder.Base.Builder
instance GHC.Base.Semigroup (Z.Data.Builder.Base.Builder ())
instance GHC.Base.Monoid (Z.Data.Builder.Base.Builder ())
instance (a GHC.Types.~ ()) => Data.String.IsString (Z.Data.Builder.Base.Builder a)
instance Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Builder.Base.Builder ())
instance Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Builder.Base.Builder ())


-- | This module provides base64 encoding &amp; decoding tools, as well as
--   <tt>Base64Bytes</tt> newtype with base64 textual instances.
module Z.Data.Vector.Base64

-- | Encode <a>Bytes</a> using base64 encoding.
base64Encode :: Bytes -> Bytes

-- | Return the encoded length of a given input length, always a multipler
--   of 4.
base64EncodeLength :: Int -> Int

-- | Text version of <a>base64Encode</a>.
base64EncodeText :: Bytes -> Text

-- | <a>Builder</a> version of <a>base64Encode</a>.
base64EncodeBuilder :: Bytes -> Builder ()

-- | Decode a base64 encoding string, return Nothing on illegal bytes or
--   incomplete input.
base64Decode :: Bytes -> Maybe Bytes

-- | Decode a base64 encoding string, throw <a>Base64DecodeException</a> on
--   error.
base64Decode' :: HasCallStack => Bytes -> Bytes

-- | Return the upper bound of decoded length of a given input length ,
--   return -1 if illegal(not a multipler of 4).
base64DecodeLength :: Int -> Int

-- | Exception during base64 decoding.
data Base64DecodeException
IllegalBase64Bytes :: Bytes -> CallStack -> Base64DecodeException
IncompleteBase64Bytes :: Bytes -> CallStack -> Base64DecodeException
hs_base64_encode :: MBA# Word8 -> Int -> BA# Word8 -> Int -> Int -> IO ()
hs_base64_decode :: MBA# Word8 -> BA# Word8 -> Int -> Int -> IO Int
instance GHC.Show.Show Z.Data.Vector.Base64.Base64DecodeException
instance GHC.Exception.Type.Exception Z.Data.Vector.Base64.Base64DecodeException


-- | Textual numeric builders.
module Z.Data.Builder.Numeric

-- | Integral formatting options.
data IFormat
IFormat :: Int -> Padding -> Bool -> IFormat

-- | total width, only effective with padding options
[width] :: IFormat -> Int

-- | padding options
[padding] :: IFormat -> Padding

-- | show <tt>+</tt> when the number is positive
[posSign] :: IFormat -> Bool

-- | <pre>
--   defaultIFormat = IFormat 0 NoPadding False
--   </pre>
defaultIFormat :: IFormat
data Padding
NoPadding :: Padding
RightSpacePadding :: Padding
LeftSpacePadding :: Padding
ZeroPadding :: Padding

-- | <pre>
--   int = intWith defaultIFormat
--   </pre>
int :: (Integral a, Bounded a) => a -> Builder ()

-- | Format a <a>Bounded</a> <a>Integral</a> type like <tt>Int</tt> or
--   <tt>Word16</tt> into decimal ASCII digits.
--   
--   <pre>
--   import Z.Data.Builder as B
--   
--   &gt; B.buildText $ B.intWith defaultIFormat  (12345 :: Int)
--   "12345"
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=RightSpacePadding} (12345 :: Int)
--   "12345     "
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=ZeroPadding} (12345 :: Int)
--   "0000012345"
--   </pre>
intWith :: (Integral a, Bounded a) => IFormat -> a -> Builder ()

-- | Format a <a>Integer</a> into decimal ASCII digits.
integer :: Integer -> Builder ()

-- | Format a <a>FiniteBits</a> <a>Integral</a> type into hex nibbles.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Data.Word
--   import Data.Int
--   
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Int8)
--   "7d"
--   &gt; T.validate . B.buildBytes $ B.hex (-1 :: Int8)
--   "ff"
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Word16)
--   "007d"
--   </pre>
hex :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

-- | The UPPERCASED version of <a>hex</a>.
hexUpper :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

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

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

-- | Standard decimal notation.
Fixed :: FFormat

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

-- | Decimal encoding of an IEEE <a>Double</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
double :: Double -> Builder ()

-- | Format double-precision float using drisu3 with dragon4 fallback.
doubleWith :: FFormat -> Maybe Int -> Double -> Builder ()

-- | Decimal encoding of an IEEE <a>Float</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
float :: Float -> Builder ()

-- | Format single-precision float using drisu3 with dragon4 fallback.
floatWith :: FFormat -> Maybe Int -> Float -> Builder ()

-- | A <tt>Builder</tt> which renders a scientific number to full
--   precision, using standard decimal notation for arguments whose
--   absolute value lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and
--   scientific notation otherwise.
scientific :: Scientific -> Builder ()

-- | Like <a>scientific</a> but provides rendering options.
scientificWith :: FFormat -> Maybe Int -> Scientific -> Builder ()

-- | Decimal encoding of a <a>Double</a>, note grisu only handles strictly
--   positive finite numbers.
grisu3 :: Double -> ([Int], Int)

-- | Decimal encoding of a <a>Float</a>, note grisu3_sp only handles
--   strictly positive finite numbers.
grisu3_sp :: Float -> ([Int], Int)

-- | Decimal digit to ASCII digit.
i2wDec :: Integral a => a -> Word8

-- | Hexadecimal digit to ASCII char.
i2wHex :: Integral a => a -> Word8

-- | Hexadecimal digit to UPPERCASED ASCII char.
i2wHexUpper :: Integral a => a -> Word8

-- | Count how many decimal digits an integer has.
countDigits :: Integral a => a -> Int

-- | Internal formatting backed by C FFI, it must be used with type smaller
--   than <a>Word64</a>.
--   
--   We use rewrite rules to rewrite most of the integral types formatting
--   to this function.
c_intWith :: (Integral a, Bits a) => IFormat -> a -> Builder ()

-- | Internal formatting in haskell, it can be used with any bounded
--   integral type.
--   
--   Other than provide fallback for the c version, this function is also
--   used to check the c version's formatting result.
hs_intWith :: (Integral a, Bounded a) => IFormat -> a -> Builder ()
instance GHC.Enum.Enum Z.Data.Builder.Numeric.Padding
instance GHC.Classes.Ord Z.Data.Builder.Numeric.Padding
instance GHC.Classes.Eq Z.Data.Builder.Numeric.Padding
instance GHC.Show.Show Z.Data.Builder.Numeric.Padding
instance GHC.Classes.Ord Z.Data.Builder.Numeric.IFormat
instance GHC.Classes.Eq Z.Data.Builder.Numeric.IFormat
instance GHC.Show.Show Z.Data.Builder.Numeric.IFormat
instance GHC.Show.Show Z.Data.Builder.Numeric.FFormat
instance GHC.Read.Read Z.Data.Builder.Numeric.FFormat
instance GHC.Enum.Enum Z.Data.Builder.Numeric.FFormat
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.Builder.Numeric.IFormat
instance Test.QuickCheck.Arbitrary.CoArbitrary Z.Data.Builder.Numeric.IFormat
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.Builder.Numeric.Padding
instance Test.QuickCheck.Arbitrary.CoArbitrary Z.Data.Builder.Numeric.Padding


-- | This module re-exports some UTF8 compatible textual builders from
--   <a>Builder</a>.
--   
--   We also provide a faster alternative to <a>Show</a> class, i.e.
--   <a>Print</a>, which can be deriving using <a>Generic</a>. For example
--   to use <a>Print</a> class:
--   
--   <pre>
--   import qualified Z.Data.Text.Print as T
--   
--   data Foo = Bar Bytes | Qux Text Int deriving Generic
--                                       deriving anyclass T.Print
--   </pre>
module Z.Data.Text.Print

-- | A class similar to <a>Show</a>, serving the purpose that quickly
--   convert a data type to a <a>Text</a> value.
--   
--   You can use newtype or generic deriving to implement instance of this
--   class quickly:
--   
--   <pre>
--    {-# LANGUAGE GeneralizedNewtypeDeriving #-}
--    {-# LANGUAGE DeriveAnyClass #-}
--    {-# LANGUAGE DeriveGeneric #-}
--    {-# LANGUAGE DerivingStrategies #-}
--   
--    import GHC.Generics
--   
--    newtype FooInt = FooInt Int deriving (Generic)
--                              deriving anyclass Print
--   
--   &gt; toText (FooInt 3)
--   &gt; "FooInt 3"
--   
--    newtype FooInt = FooInt Int deriving (Generic)
--                              deriving newtype Print
--   
--   &gt; toText (FooInt 3)
--   &gt; "3"
--   </pre>
class Print a

-- | Convert data to <a>Builder</a> with precendence.
--   
--   You should return a <a>Builder</a> writing in UTF8 encoding only, i.e.
--   
--   <pre>
--   Z.Data.Text.validateMaybe (Z.Data.Builder.buildBytes (toUTF8BuilderP p a)) /= Nothing
--   </pre>
toUTF8BuilderP :: Print a => Int -> a -> Builder ()

-- | Convert data to <a>Builder</a> with precendence.
--   
--   You should return a <a>Builder</a> writing in UTF8 encoding only, i.e.
--   
--   <pre>
--   Z.Data.Text.validateMaybe (Z.Data.Builder.buildBytes (toUTF8BuilderP p a)) /= Nothing
--   </pre>
toUTF8BuilderP :: (Print a, Generic a, GToText (Rep a)) => Int -> a -> Builder ()

-- | Convert data to <a>Text</a>.
toText :: Print a => a -> Text

-- | Convert data to <a>String</a>, faster <a>show</a> replacement.
toString :: Print a => a -> String

-- | Convert data to <a>Builder</a>.
toUTF8Builder :: Print a => a -> Builder ()

-- | Convert data to <a>Bytes</a> in UTF8 encoding.
toUTF8Bytes :: Print a => a -> Bytes

-- | Escape text using JSON string escaping rules and add double quotes,
--   escaping rules:
--   
--   <pre>
--   '\b':  "\b"
--   '\f':  "\f"
--   '\n':  "\n"
--   '\r':  "\r"
--   '\t':  "\t"
--   '"':  "\""
--   '\':  "\\"
--   other chars &lt;= 0x1F: "\u00XX"
--   </pre>
escapeTextJSON :: Text -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
--   
--   This is different from writing string literals builders via
--   <tt>OverloadedStrings</tt>, because string literals do not provide
--   UTF8 guarantees.
--   
--   This function will be rewritten into a memcpy if possible, (running a
--   fast UTF-8 validation at runtime first).
stringUTF8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
charUTF8 :: Char -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
string7 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
char7 :: Char -> Builder ()

-- | Write UTF8 encoded <tt>Text</tt> using <a>Builder</a>.
--   
--   Note, if you're trying to write string literals builders, please open
--   <tt>OverloadedStrings</tt> and use <a>Builder</a>s <a>IsString</a>
--   instance, it will be rewritten into a memcpy.
text :: Text -> Builder ()

-- | Integral formatting options.
data IFormat
IFormat :: Int -> Padding -> Bool -> IFormat

-- | total width, only effective with padding options
[width] :: IFormat -> Int

-- | padding options
[padding] :: IFormat -> Padding

-- | show <tt>+</tt> when the number is positive
[posSign] :: IFormat -> Bool

-- | <pre>
--   defaultIFormat = IFormat 0 NoPadding False
--   </pre>
defaultIFormat :: IFormat
data Padding
NoPadding :: Padding
RightSpacePadding :: Padding
LeftSpacePadding :: Padding
ZeroPadding :: Padding

-- | <pre>
--   int = intWith defaultIFormat
--   </pre>
int :: (Integral a, Bounded a) => a -> Builder ()

-- | Format a <a>Bounded</a> <a>Integral</a> type like <tt>Int</tt> or
--   <tt>Word16</tt> into decimal ASCII digits.
--   
--   <pre>
--   import Z.Data.Builder as B
--   
--   &gt; B.buildText $ B.intWith defaultIFormat  (12345 :: Int)
--   "12345"
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=RightSpacePadding} (12345 :: Int)
--   "12345     "
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=ZeroPadding} (12345 :: Int)
--   "0000012345"
--   </pre>
intWith :: (Integral a, Bounded a) => IFormat -> a -> Builder ()

-- | Format a <a>Integer</a> into decimal ASCII digits.
integer :: Integer -> Builder ()

-- | Format a <a>FiniteBits</a> <a>Integral</a> type into hex nibbles.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Data.Word
--   import Data.Int
--   
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Int8)
--   "7d"
--   &gt; T.validate . B.buildBytes $ B.hex (-1 :: Int8)
--   "ff"
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Word16)
--   "007d"
--   </pre>
hex :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

-- | The UPPERCASED version of <a>hex</a>.
hexUpper :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

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

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

-- | Standard decimal notation.
Fixed :: FFormat

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

-- | Decimal encoding of an IEEE <a>Double</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
double :: Double -> Builder ()

-- | Format double-precision float using drisu3 with dragon4 fallback.
doubleWith :: FFormat -> Maybe Int -> Double -> Builder ()

-- | Decimal encoding of an IEEE <a>Float</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
float :: Float -> Builder ()

-- | Format single-precision float using drisu3 with dragon4 fallback.
floatWith :: FFormat -> Maybe Int -> Float -> Builder ()

-- | A <tt>Builder</tt> which renders a scientific number to full
--   precision, using standard decimal notation for arguments whose
--   absolute value lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and
--   scientific notation otherwise.
scientific :: Scientific -> Builder ()

-- | Like <a>scientific</a> but provides rendering options.
scientificWith :: FFormat -> Maybe Int -> Scientific -> Builder ()

-- | add <tt>(...)</tt> to original builder.
paren :: Builder () -> Builder ()

-- | add <tt>{...}</tt> to original builder.
curly :: Builder () -> Builder ()

-- | add <tt>[...]</tt> to original builder.
square :: Builder () -> Builder ()

-- | add <tt><i>&lt;...</i>&gt;</tt> to original builder.
angle :: Builder () -> Builder ()

-- | add <tt><i>"...</i>"</tt> to original builder.
quotes :: Builder () -> Builder ()

-- | add <tt><i>'...</i>'</tt> to original builder.
squotes :: Builder () -> Builder ()

-- | write an ASCII <tt>:</tt>
colon :: Builder ()

-- | write an ASCII <tt>,</tt>
comma :: Builder ()

-- | Use separator to connect a vector of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   &gt; T.validate . B.build $ B.intercalateVec "," B.int (V.pack [1,2,3,4] :: V.PrimVector Int)
--   "1,2,3,4"
--   </pre>
intercalateVec :: Vec v a => Builder () -> (a -> Builder ()) -> v a -> Builder ()

-- | Use separator to connect list of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   T.validate . B.build $ B.intercalateList "," B.int ([1,2,3,4] :: [Int])
--   "1,2,3,4"
--   </pre>
intercalateList :: Builder () -> (a -> Builder ()) -> [a] -> Builder ()

-- | Add "(..)" around builders when condition is met, otherwise add
--   nothing.
--   
--   This is useful when defining <a>Print</a> instances.
parenWhen :: Bool -> Builder () -> Builder ()
instance Z.Data.Text.Print.Print Foreign.C.Types.CChar
instance Z.Data.Text.Print.Print Foreign.C.Types.CSChar
instance Z.Data.Text.Print.Print Foreign.C.Types.CUChar
instance Z.Data.Text.Print.Print Foreign.C.Types.CShort
instance Z.Data.Text.Print.Print Foreign.C.Types.CUShort
instance Z.Data.Text.Print.Print Foreign.C.Types.CInt
instance Z.Data.Text.Print.Print Foreign.C.Types.CUInt
instance Z.Data.Text.Print.Print Foreign.C.Types.CLong
instance Z.Data.Text.Print.Print Foreign.C.Types.CULong
instance Z.Data.Text.Print.Print Foreign.C.Types.CPtrdiff
instance Z.Data.Text.Print.Print Foreign.C.Types.CSize
instance Z.Data.Text.Print.Print Foreign.C.Types.CWchar
instance Z.Data.Text.Print.Print Foreign.C.Types.CSigAtomic
instance Z.Data.Text.Print.Print Foreign.C.Types.CLLong
instance Z.Data.Text.Print.Print Foreign.C.Types.CULLong
instance Z.Data.Text.Print.Print Foreign.C.Types.CBool
instance Z.Data.Text.Print.Print Foreign.C.Types.CIntPtr
instance Z.Data.Text.Print.Print Foreign.C.Types.CUIntPtr
instance Z.Data.Text.Print.Print Foreign.C.Types.CIntMax
instance Z.Data.Text.Print.Print Foreign.C.Types.CUIntMax
instance Z.Data.Text.Print.Print Foreign.C.Types.CClock
instance Z.Data.Text.Print.Print Foreign.C.Types.CTime
instance Z.Data.Text.Print.Print Foreign.C.Types.CUSeconds
instance Z.Data.Text.Print.Print Foreign.C.Types.CSUSeconds
instance Z.Data.Text.Print.Print Foreign.C.Types.CFloat
instance Z.Data.Text.Print.Print Foreign.C.Types.CDouble
instance Z.Data.Text.Print.Print GHC.IO.Exception.ExitCode
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.Min a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.Max a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.First a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.Last a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.WrappedMonoid a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Semigroup.Internal.Dual a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Monoid.First a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Monoid.Last a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (GHC.Base.NonEmpty a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Functor.Identity.Identity a)
instance forall k a (b :: k). Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Functor.Const.Const a b)
instance forall k (a :: k). Z.Data.Text.Print.Print (Data.Proxy.Proxy a)
instance forall k b (a :: k). Z.Data.Text.Print.Print b => Z.Data.Text.Print.Print (Data.Tagged.Tagged a b)
instance forall k k1 (f :: k -> *) (g :: k1 -> k) (a :: k1). Z.Data.Text.Print.Print (f (g a)) => Z.Data.Text.Print.Print (Data.Functor.Compose.Compose f g a)
instance forall k (f :: k -> *) (a :: k) (g :: k -> *). (Z.Data.Text.Print.Print (f a), Z.Data.Text.Print.Print (g a)) => Z.Data.Text.Print.Print (Data.Functor.Product.Product f g a)
instance (Z.Data.Text.Print.Print (f a), Z.Data.Text.Print.Print (g a), Z.Data.Text.Print.Print a) => Z.Data.Text.Print.Print (Data.Functor.Sum.Sum f g a)
instance forall k (a :: k -> *) (b :: k -> *). (Z.Data.Text.Print.GFieldToText a, Z.Data.Text.Print.GFieldToText b) => Z.Data.Text.Print.GFieldToText (a GHC.Generics.:*: b)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.Text.Print.GToText f => Z.Data.Text.Print.GFieldToText (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.Text.Print.GToText f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.Text.Print.GFieldToText (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance forall k (sc :: GHC.Generics.Meta) (f :: k -> *) (c :: GHC.Generics.Meta). (Z.Data.Text.Print.GFieldToText (GHC.Generics.S1 sc f), GHC.Generics.Constructor c) => Z.Data.Text.Print.GToText (GHC.Generics.C1 c (GHC.Generics.S1 sc f))
instance forall k (a :: k -> *) (b :: k -> *) (c :: GHC.Generics.Meta). (Z.Data.Text.Print.GFieldToText (a GHC.Generics.:*: b), GHC.Generics.Constructor c) => Z.Data.Text.Print.GToText (GHC.Generics.C1 c (a GHC.Generics.:*: b))
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.GToText (GHC.Generics.K1 i a)
instance Z.Data.Text.Print.Print GHC.Types.Bool
instance Z.Data.Text.Print.Print GHC.Types.Char
instance Z.Data.Text.Print.Print GHC.Types.Double
instance Z.Data.Text.Print.Print GHC.Types.Float
instance Z.Data.Text.Print.Print GHC.Types.Int
instance Z.Data.Text.Print.Print GHC.Int.Int8
instance Z.Data.Text.Print.Print GHC.Int.Int16
instance Z.Data.Text.Print.Print GHC.Int.Int32
instance Z.Data.Text.Print.Print GHC.Int.Int64
instance Z.Data.Text.Print.Print GHC.Types.Word
instance Z.Data.Text.Print.Print GHC.Word.Word8
instance Z.Data.Text.Print.Print GHC.Word.Word16
instance Z.Data.Text.Print.Print GHC.Word.Word32
instance Z.Data.Text.Print.Print GHC.Word.Word64
instance Z.Data.Text.Print.Print GHC.Integer.Type.Integer
instance Z.Data.Text.Print.Print GHC.Natural.Natural
instance Z.Data.Text.Print.Print GHC.Types.Ordering
instance Z.Data.Text.Print.Print ()
instance Z.Data.Text.Print.Print Data.Version.Version
instance Z.Data.Text.Print.Print Z.Data.Text.Base.Text
instance Z.Data.Text.Print.Print Data.Scientific.Scientific
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print [a]
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Primitive.Array.Array a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Data.Primitive.SmallArray.SmallArray a)
instance (Z.Data.Array.UnliftedArray.PrimUnlifted a, Z.Data.Text.Print.Print a) => Z.Data.Text.Print.Print (Z.Data.Array.UnliftedArray.UnliftedArray a)
instance (Data.Primitive.Types.Prim a, Z.Data.Text.Print.Print a) => Z.Data.Text.Print.Print (Data.Primitive.PrimArray.PrimArray a)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (Z.Data.Vector.Base.Vector a)
instance (Data.Primitive.Types.Prim a, Z.Data.Text.Print.Print a) => Z.Data.Text.Print.Print (Z.Data.Vector.Base.PrimVector a)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b) => Z.Data.Text.Print.Print (a, b)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b, Z.Data.Text.Print.Print c) => Z.Data.Text.Print.Print (a, b, c)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b, Z.Data.Text.Print.Print c, Z.Data.Text.Print.Print d) => Z.Data.Text.Print.Print (a, b, c, d)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b, Z.Data.Text.Print.Print c, Z.Data.Text.Print.Print d, Z.Data.Text.Print.Print e) => Z.Data.Text.Print.Print (a, b, c, d, e)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b, Z.Data.Text.Print.Print c, Z.Data.Text.Print.Print d, Z.Data.Text.Print.Print e, Z.Data.Text.Print.Print f) => Z.Data.Text.Print.Print (a, b, c, d, e, f)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b, Z.Data.Text.Print.Print c, Z.Data.Text.Print.Print d, Z.Data.Text.Print.Print e, Z.Data.Text.Print.Print f, Z.Data.Text.Print.Print g) => Z.Data.Text.Print.Print (a, b, c, d, e, f, g)
instance Z.Data.Text.Print.Print a => Z.Data.Text.Print.Print (GHC.Maybe.Maybe a)
instance (Z.Data.Text.Print.Print a, Z.Data.Text.Print.Print b) => Z.Data.Text.Print.Print (Data.Either.Either a b)
instance (Z.Data.Text.Print.Print a, GHC.Real.Integral a) => Z.Data.Text.Print.Print (GHC.Real.Ratio a)
instance forall k (a :: k). Data.Fixed.HasResolution a => Z.Data.Text.Print.Print (Data.Fixed.Fixed a)
instance Z.Data.Text.Print.Print GHC.Stack.Types.CallStack
instance Z.Data.Text.Print.Print (GHC.Ptr.Ptr a)
instance Z.Data.Text.Print.Print (GHC.ForeignPtr.ForeignPtr a)
instance Z.Data.Text.Print.GToText GHC.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Z.Data.Text.Print.GToText f, Z.Data.Text.Print.GToText g) => Z.Data.Text.Print.GToText (f GHC.Generics.:+: g)
instance GHC.Generics.Constructor c => Z.Data.Text.Print.GToText (GHC.Generics.C1 c GHC.Generics.U1)
instance forall k (f :: k -> *) (c :: GHC.Generics.Meta). Z.Data.Text.Print.GToText f => Z.Data.Text.Print.GToText (GHC.Generics.D1 c f)


-- | This module provides a simple value set based on sorted vector and
--   binary search. It's particularly suitable for small sized value
--   collections such as deserializing intermediate representation. But can
--   also used in various place where insertion and deletion is rare but
--   require fast elem.
module Z.Data.Vector.FlatSet
data FlatSet v
sortedValues :: FlatSet v -> Vector v
size :: FlatSet v -> Int
null :: FlatSet v -> Bool

-- | <i>O(1)</i> empty flat set.
empty :: FlatSet v

-- | Mapping values of within a set, the result size may change if there're
--   duplicated values after mapping.
map' :: forall v. Ord v => (v -> v) -> FlatSet v -> FlatSet v

-- | <i>O(N*logN)</i> Pack list of values, on duplication prefer left one.
pack :: Ord v => [v] -> FlatSet v

-- | <i>O(N*logN)</i> Pack list of values with suggested size, on
--   duplication prefer left one.
packN :: Ord v => Int -> [v] -> FlatSet v

-- | <i>O(N*logN)</i> Pack list of values, on duplication prefer right one.
packR :: Ord v => [v] -> FlatSet v

-- | <i>O(N*logN)</i> Pack list of values with suggested size, on
--   duplication prefer right one.
packRN :: Ord v => Int -> [v] -> FlatSet v

-- | <i>O(N)</i> Unpack a set of values to a list s in ascending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpack :: FlatSet v -> [v]

-- | <i>O(N)</i> Unpack a set of values to a list s in descending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpackR :: FlatSet v -> [v]

-- | <i>O(N*logN)</i> Pack vector of values, on duplication prefer left
--   one.
packVector :: Ord v => Vector v -> FlatSet v

-- | <i>O(N*logN)</i> Pack vector of values, on duplication prefer right
--   one.
packVectorR :: Ord v => Vector v -> FlatSet v

-- | <i>O(logN)</i> Binary search on flat set.
elem :: Ord v => v -> FlatSet v -> Bool

-- | <i>O(N)</i> Delete a value from set.
delete :: Ord v => v -> FlatSet v -> FlatSet v

-- | <i>O(N)</i> Insert new value into set.
insert :: Ord v => v -> FlatSet v -> FlatSet v

-- | <i>O(n+m)</i> Merge two <a>FlatSet</a>, prefer right value on value
--   duplication.
merge :: forall v. Ord v => FlatSet v -> FlatSet v -> FlatSet v

-- | Find the value's index in the vector, if value exists return
--   <a>Right</a>, otherwise <a>Left</a>, i.e. the insert index
--   
--   This function only works on ascending sorted vectors.
binarySearch :: Ord v => Vector v -> v -> Either Int Int
instance Data.Foldable.Foldable Z.Data.Vector.FlatSet.FlatSet
instance GHC.Classes.Ord v => GHC.Classes.Ord (Z.Data.Vector.FlatSet.FlatSet v)
instance GHC.Classes.Eq v => GHC.Classes.Eq (Z.Data.Vector.FlatSet.FlatSet v)
instance GHC.Show.Show v => GHC.Show.Show (Z.Data.Vector.FlatSet.FlatSet v)
instance Z.Data.Text.Print.Print v => Z.Data.Text.Print.Print (Z.Data.Vector.FlatSet.FlatSet v)
instance GHC.Classes.Ord v => GHC.Base.Semigroup (Z.Data.Vector.FlatSet.FlatSet v)
instance GHC.Classes.Ord v => GHC.Base.Monoid (Z.Data.Vector.FlatSet.FlatSet v)
instance Control.DeepSeq.NFData v => Control.DeepSeq.NFData (Z.Data.Vector.FlatSet.FlatSet v)
instance (GHC.Classes.Ord v, Test.QuickCheck.Arbitrary.Arbitrary v) => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.FlatSet.FlatSet v)
instance Test.QuickCheck.Arbitrary.CoArbitrary v => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.FlatSet.FlatSet v)


-- | This module provides a simple key value map based on sorted vector and
--   binary search. It's particularly suitable for small sized key value
--   collections such as deserializing intermediate representation. But can
--   also used in various place where insertion and deletion is rare but
--   require fast lookup.
module Z.Data.Vector.FlatMap
data FlatMap k v
sortedKeyValues :: FlatMap k v -> Vector (k, v)
size :: FlatMap k v -> Int
null :: FlatMap k v -> Bool

-- | <i>O(1)</i> empty flat map.
empty :: FlatMap k v
map' :: (v -> v') -> FlatMap k v -> FlatMap k v'
kmap' :: (k -> v -> v') -> FlatMap k v -> FlatMap k v'

-- | <i>O(N*logN)</i> Pack list of key values, on key duplication prefer
--   left one.
pack :: Ord k => [(k, v)] -> FlatMap k v

-- | <i>O(N*logN)</i> Pack list of key values with suggested size, on key
--   duplication prefer left one.
packN :: Ord k => Int -> [(k, v)] -> FlatMap k v

-- | <i>O(N*logN)</i> Pack list of key values, on key duplication prefer
--   right one.
packR :: Ord k => [(k, v)] -> FlatMap k v

-- | <i>O(N*logN)</i> Pack list of key values with suggested size, on key
--   duplication prefer right one.
packRN :: Ord k => Int -> [(k, v)] -> FlatMap k v

-- | <i>O(N)</i> Unpack key value pairs to a list sorted by keys in
--   ascending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpack :: FlatMap k v -> [(k, v)]

-- | <i>O(N)</i> Unpack key value pairs to a list sorted by keys in
--   descending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpackR :: FlatMap k v -> [(k, v)]

-- | <i>O(N*logN)</i> Pack vector of key values, on key duplication prefer
--   left one.
packVector :: Ord k => Vector (k, v) -> FlatMap k v

-- | <i>O(N*logN)</i> Pack vector of key values, on key duplication prefer
--   right one.
packVectorR :: Ord k => Vector (k, v) -> FlatMap k v

-- | <i>O(logN)</i> Binary search on flat map.
lookup :: Ord k => k -> FlatMap k v -> Maybe v

-- | <i>O(N)</i> Delete a key value pair by key.
delete :: Ord k => k -> FlatMap k v -> FlatMap k v

-- | <i>O(N)</i> Insert new key value into map, replace old one if key
--   exists.
insert :: Ord k => k -> v -> FlatMap k v -> FlatMap k v

-- | <i>O(N)</i> Modify a value by key.
--   
--   The value is evaluated to WHNF before writing into map.
adjust' :: Ord k => (v -> v) -> k -> FlatMap k v -> FlatMap k v

-- | <i>O(n+m)</i> Merge two <a>FlatMap</a>, prefer right value on key
--   duplication.
merge :: forall k v. Ord k => FlatMap k v -> FlatMap k v -> FlatMap k v

-- | <i>O(n+m)</i> Merge two <a>FlatMap</a> with a merge function.
mergeWithKey' :: forall k v. Ord k => (k -> v -> v -> v) -> FlatMap k v -> FlatMap k v -> FlatMap k v

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding k is in descending order.
foldrWithKey :: (k -> v -> a -> a) -> a -> FlatMap k v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding k is in descending order.
foldrWithKey' :: (k -> v -> a -> a) -> a -> FlatMap k v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding k is in ascending order.
foldlWithKey :: (a -> k -> v -> a) -> a -> FlatMap k v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding k is in ascending order.
foldlWithKey' :: (a -> k -> v -> a) -> a -> FlatMap k v -> a

-- | <i>O(n)</i>.
--   
--   <tt><a>traverseWithKey</a> f s == <a>pack</a> &lt;$&gt;
--   <a>traverse</a> ((k, v) -&gt; (,) k &lt;$&gt; f k v) (<a>unpack</a>
--   m)</tt> That is, behaves exactly like a regular <a>traverse</a> except
--   that the traversing function also has access to the key associated
--   with a value.
traverseWithKey :: Applicative t => (k -> a -> t b) -> FlatMap k a -> t (FlatMap k b)

-- | Find the key's index in the vector slice, if key exists return
--   <a>Right</a>, otherwise <a>Left</a>, i.e. the insert index
--   
--   This function only works on ascending sorted vectors.
binarySearch :: Ord k => Vector (k, v) -> k -> Either Int Int
instance (GHC.Classes.Ord k, GHC.Classes.Ord v) => GHC.Classes.Ord (Z.Data.Vector.FlatMap.FlatMap k v)
instance (GHC.Classes.Eq k, GHC.Classes.Eq v) => GHC.Classes.Eq (Z.Data.Vector.FlatMap.FlatMap k v)
instance (GHC.Show.Show k, GHC.Show.Show v) => GHC.Show.Show (Z.Data.Vector.FlatMap.FlatMap k v)
instance (Z.Data.Text.Print.Print k, Z.Data.Text.Print.Print v) => Z.Data.Text.Print.Print (Z.Data.Vector.FlatMap.FlatMap k v)
instance (GHC.Classes.Ord k, Test.QuickCheck.Arbitrary.Arbitrary k, Test.QuickCheck.Arbitrary.Arbitrary v) => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.FlatMap.FlatMap k v)
instance (Test.QuickCheck.Arbitrary.CoArbitrary k, Test.QuickCheck.Arbitrary.CoArbitrary v) => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.FlatMap.FlatMap k v)
instance GHC.Classes.Ord k => GHC.Base.Semigroup (Z.Data.Vector.FlatMap.FlatMap k v)
instance GHC.Classes.Ord k => GHC.Base.Monoid (Z.Data.Vector.FlatMap.FlatMap k v)
instance (Control.DeepSeq.NFData k, Control.DeepSeq.NFData v) => Control.DeepSeq.NFData (Z.Data.Vector.FlatMap.FlatMap k v)
instance GHC.Base.Functor (Z.Data.Vector.FlatMap.FlatMap k)
instance Data.Foldable.Foldable (Z.Data.Vector.FlatMap.FlatMap k)
instance Data.Traversable.Traversable (Z.Data.Vector.FlatMap.FlatMap k)


-- | This module provides a simple int set based on sorted vector and
--   binary search. It's particularly suitable for small sized value
--   collections such as deserializing intermediate representation. But can
--   also used in various place where insertion and deletion is rare but
--   require fast elem.
module Z.Data.Vector.FlatIntSet
data FlatIntSet
sortedValues :: FlatIntSet -> PrimVector Int
size :: FlatIntSet -> Int
null :: FlatIntSet -> Bool

-- | <i>O(1)</i> empty flat set.
empty :: FlatIntSet

-- | Mapping values of within a set, the result size may change if there're
--   duplicated values after mapping.
map' :: (Int -> Int) -> FlatIntSet -> FlatIntSet

-- | <i>O(N*logN)</i> Pack list of values, on duplication prefer left one.
pack :: [Int] -> FlatIntSet

-- | <i>O(N*logN)</i> Pack list of values with suggested size, on
--   duplication prefer left one.
packN :: Int -> [Int] -> FlatIntSet

-- | <i>O(N*logN)</i> Pack list of values, on duplication prefer right one.
packR :: [Int] -> FlatIntSet

-- | <i>O(N*logN)</i> Pack list of values with suggested size, on
--   duplication prefer right one.
packRN :: Int -> [Int] -> FlatIntSet

-- | <i>O(N)</i> Unpack a set of values to a list s in ascending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpack :: FlatIntSet -> [Int]

-- | <i>O(N)</i> Unpack a set of values to a list s in descending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpackR :: FlatIntSet -> [Int]

-- | <i>O(N*logN)</i> Pack vector of values, on duplication prefer left
--   one.
packVector :: PrimVector Int -> FlatIntSet

-- | <i>O(N*logN)</i> Pack vector of values, on duplication prefer right
--   one.
packVectorR :: PrimVector Int -> FlatIntSet

-- | <i>O(logN)</i> Binary search on flat set.
elem :: Int -> FlatIntSet -> Bool

-- | <i>O(N)</i> Delete a value.
delete :: Int -> FlatIntSet -> FlatIntSet

-- | <i>O(N)</i> Insert new value into set.
insert :: Int -> FlatIntSet -> FlatIntSet

-- | <i>O(n+m)</i> Merge two <a>FlatIntSet</a>, prefer right value on value
--   duplication.
merge :: FlatIntSet -> FlatIntSet -> FlatIntSet

-- | Find the value's index in the vector slice, if value exists return
--   <a>Right</a>, otherwise <a>Left</a>, i.e. the insert index
--   
--   This function only works on ascending sorted vectors.
binarySearch :: PrimVector Int -> Int -> Either Int Int
instance GHC.Classes.Ord Z.Data.Vector.FlatIntSet.FlatIntSet
instance GHC.Classes.Eq Z.Data.Vector.FlatIntSet.FlatIntSet
instance GHC.Show.Show Z.Data.Vector.FlatIntSet.FlatIntSet
instance Z.Data.Text.Print.Print Z.Data.Vector.FlatIntSet.FlatIntSet
instance GHC.Base.Semigroup Z.Data.Vector.FlatIntSet.FlatIntSet
instance GHC.Base.Monoid Z.Data.Vector.FlatIntSet.FlatIntSet
instance Control.DeepSeq.NFData Z.Data.Vector.FlatIntSet.FlatIntSet
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.Vector.FlatIntSet.FlatIntSet
instance Test.QuickCheck.Arbitrary.CoArbitrary Z.Data.Vector.FlatIntSet.FlatIntSet


-- | This module provides a simple int key value map based on sorted vector
--   and binary search. It's particularly suitable for small sized key
--   value collections such as deserializing intermediate representation.
--   But can also used in various place where insertion and deletion is
--   rare but require fast lookup.
module Z.Data.Vector.FlatIntMap
data FlatIntMap v
sortedKeyValues :: FlatIntMap v -> Vector (IPair v)
size :: FlatIntMap v -> Int
null :: FlatIntMap v -> Bool

-- | <i>O(1)</i> empty flat map.
empty :: FlatIntMap v
map' :: (v -> v') -> FlatIntMap v -> FlatIntMap v'
imap' :: (Int -> v -> v') -> FlatIntMap v -> FlatIntMap v'

-- | <i>O(N*logN)</i> Pack list of key values, on key duplication prefer
--   left one.
pack :: [IPair v] -> FlatIntMap v

-- | <i>O(N*logN)</i> Pack list of key values with suggested size, on key
--   duplication prefer left one.
packN :: Int -> [IPair v] -> FlatIntMap v

-- | <i>O(N*logN)</i> Pack list of key values, on key duplication prefer
--   right one.
packR :: [IPair v] -> FlatIntMap v

-- | <i>O(N*logN)</i> Pack list of key values with suggested size, on key
--   duplication prefer right one.
packRN :: Int -> [IPair v] -> FlatIntMap v

-- | <i>O(N)</i> Unpack key value pairs to a list sorted by keys in
--   ascending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpack :: FlatIntMap v -> [IPair v]

-- | <i>O(N)</i> Unpack key value pairs to a list sorted by keys in
--   descending order.
--   
--   This function works with <tt>foldr/build</tt> fusion in base.
unpackR :: FlatIntMap v -> [IPair v]

-- | <i>O(N*logN)</i> Pack vector of key values, on key duplication prefer
--   left one.
packVector :: Vector (IPair v) -> FlatIntMap v

-- | <i>O(N*logN)</i> Pack vector of key values, on key duplication prefer
--   right one.
packVectorR :: Vector (IPair v) -> FlatIntMap v

-- | <i>O(logN)</i> Binary search on flat map.
lookup :: Int -> FlatIntMap v -> Maybe v

-- | <i>O(N)</i> Delete a key value pair by key.
delete :: Int -> FlatIntMap v -> FlatIntMap v

-- | <i>O(N)</i> Insert new key value into map, replace old one if key
--   exists.
insert :: Int -> v -> FlatIntMap v -> FlatIntMap v

-- | <i>O(N)</i> Modify a value by key.
--   
--   The value is evaluated to WHNF before writing into map.
adjust' :: (v -> v) -> Int -> FlatIntMap v -> FlatIntMap v

-- | <i>O(n+m)</i> Merge two <a>FlatIntMap</a>, prefer right value on key
--   duplication.
merge :: forall v. FlatIntMap v -> FlatIntMap v -> FlatIntMap v

-- | <i>O(n+m)</i> Merge two <a>FlatIntMap</a> with a merge function.
mergeWithKey' :: forall v. (Int -> v -> v -> v) -> FlatIntMap v -> FlatIntMap v -> FlatIntMap v

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding k is in descending order.
foldrWithKey :: (Int -> v -> a -> a) -> a -> FlatIntMap v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding Int is in descending order.
foldrWithKey' :: (Int -> v -> a -> a) -> a -> FlatIntMap v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding Int is in ascending order.
foldlWithKey :: (a -> Int -> v -> a) -> a -> FlatIntMap v -> a

-- | <i>O(n)</i> Reduce this map by applying a binary operator to all
--   elements, using the given starting value (typically the right-identity
--   of the operator).
--   
--   During folding Int is in ascending order.
foldlWithKey' :: (a -> Int -> v -> a) -> a -> FlatIntMap v -> a

-- | <i>O(n)</i>.
--   
--   <tt><a>traverseWithKey</a> f s == <a>pack</a> &lt;$&gt;
--   <a>traverse</a> ((k, v) -&gt; (,) k &lt;$&gt; f k v) (<a>unpack</a>
--   m)</tt> That is, behaves exactly like a regular <a>traverse</a> except
--   that the traversing function also has access to the key associated
--   with a value.
traverseWithKey :: Applicative t => (Int -> a -> t b) -> FlatIntMap a -> t (FlatIntMap b)

-- | Find the key's index in the vector slice, if key exists return
--   <a>Right</a>, otherwise <a>Left</a>, i.e. the insert index
--   
--   This function only works on ascending sorted vectors.
binarySearch :: Vector (IPair v) -> Int -> Either Int Int
instance GHC.Classes.Ord v => GHC.Classes.Ord (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance GHC.Classes.Eq v => GHC.Classes.Eq (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance GHC.Show.Show v => GHC.Show.Show (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance Z.Data.Text.Print.Print v => Z.Data.Text.Print.Print (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance Test.QuickCheck.Arbitrary.Arbitrary v => Test.QuickCheck.Arbitrary.Arbitrary (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance Test.QuickCheck.Arbitrary.CoArbitrary v => Test.QuickCheck.Arbitrary.CoArbitrary (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance GHC.Base.Semigroup (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance GHC.Base.Monoid (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance Control.DeepSeq.NFData v => Control.DeepSeq.NFData (Z.Data.Vector.FlatIntMap.FlatIntMap v)
instance GHC.Base.Functor Z.Data.Vector.FlatIntMap.FlatIntMap
instance Data.Foldable.Foldable Z.Data.Vector.FlatIntMap.FlatIntMap
instance Data.Traversable.Traversable Z.Data.Vector.FlatIntMap.FlatIntMap


-- | Binding to google's <a>RE2</a>, microsoft did a nice job on RE2 regex
--   syntaxs:
--   <a>https://docs.microsoft.com/en-us/deployedge/edge-learnmore-regex</a>.
--   Note GHC string literals need <tt>\</tt> to be escaped, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; match (regex "([a-z0-9_\\.-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})") "please end email to hello@world.com, foo@bar.com"
--   
--   &gt;&gt;&gt; ("hello@world.com",[Just "hello",Just "world",Just "com"],", foo@bar.com")
--   </pre>
module Z.Data.Text.Regex

-- | A compiled RE2 regex.
data Regex

-- | Compile a regex pattern, throw <a>InvalidRegexPattern</a> in case of
--   illegal patterns.
regex :: HasCallStack => Text -> Regex

-- | RE2 Regex options.
--   
--   The options are (<a>defaultRegexOpts</a> in parentheses):
--   
--   <pre>
--   posix_syntax     (false) restrict regexps to POSIX egrep syntax
--   longest_match    (false) search for longest match, not first match
--   log_errors       (true)  log syntax and execution errors to ERROR
--   max_mem          (8&lt;&lt;20)  approx. max memory footprint of RE2
--   literal          (false) interpret string as literal, not regexp
--   never_nl         (false) never match \n, even if it is in regexp
--   dot_nl           (false) dot matches everything including new line
--   never_capture    (false) parse all parens as non-capturing
--   case_sensitive   (true)  match is case-sensitive (regexp can override
--                              with (?i) unless in posix_syntax mode)
--   </pre>
--   
--   The following options are only consulted when posix_syntax == true.
--   When posix_syntax == false, these features are always enabled and
--   cannot be turned off; to perform multi-line matching in that case,
--   begin the regexp with <tt>(?m)</tt>.
--   
--   <pre>
--   perl_classes     (false) allow Perl's \d \s \w \D \S \W
--   word_boundary    (false) allow Perl's \b \B (word boundary and not)
--   one_line         (false) ^ and $ only match beginning and end of text
--   </pre>
data RegexOpts
RegexOpts :: Bool -> Bool -> {-# UNPACK #-} !Int64 -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> RegexOpts
[posix_syntax] :: RegexOpts -> Bool
[longest_match] :: RegexOpts -> Bool
[max_mem] :: RegexOpts -> {-# UNPACK #-} !Int64
[literal] :: RegexOpts -> Bool
[never_nl] :: RegexOpts -> Bool
[dot_nl] :: RegexOpts -> Bool
[never_capture] :: RegexOpts -> Bool
[case_sensitive] :: RegexOpts -> Bool
[perl_classes] :: RegexOpts -> Bool
[word_boundary] :: RegexOpts -> Bool
[one_line] :: RegexOpts -> Bool

-- | Default regex options, see <a>RegexOpts</a>.
defaultRegexOpts :: RegexOpts

-- | Compile a regex pattern withOptions, throw <a>InvalidRegexPattern</a>
--   in case of illegal patterns.
regexOpts :: HasCallStack => RegexOpts -> Text -> Regex

-- | Escape a piece of text literal so that it can be safely used in regex
--   pattern.
--   
--   <pre>
--   &gt;&gt;&gt; escape "(\\d+)"
--   
--   &gt;&gt;&gt; "\\(\\\\d\\+\\)"
--   </pre>
escape :: Text -> Text

-- | capturing group number(including <tt>\0</tt>)
regexCaptureNum :: Regex -> Int

-- | Get back regex's pattern.
regexPattern :: Regex -> Text

-- | Exception thrown when using regex.
data RegexException
InvalidRegexPattern :: Text -> CallStack -> RegexException

-- | Check if text matched regex pattern.
test :: Regex -> Text -> Bool

-- | Check if text matched regex pattern, if so return matched part, all
--   capturing groups(from <tt>\1</tt>) and the text after matched part.
--   
--   <tt>Nothing</tt> indicate a non-matching capturing group, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; match (regex "(foo)|(bar)baz") "barbazbla"
--   
--   &gt;&gt;&gt; ("barbaz",[Nothing,Just "bar"], "bla")
--   </pre>
match :: Regex -> Text -> (Text, [Maybe Text], Text)

-- | Replace matched part in input with a rewrite pattern. If no matched
--   part found, return the original input.
--   
--   <pre>
--   &gt;&gt;&gt; replace (regex "red") False "A red fox with red fur" "yellow"
--   
--   &gt;&gt;&gt; "A yellow fox with red fur"
--   
--   &gt;&gt;&gt; replace (regex "red") True  "A red fox with red fur" "yellow"
--   
--   &gt;&gt;&gt; "A yellow fox with yellow fur"
--   </pre>
replace :: Regex -> Bool -> Text -> Text -> Text

-- | Extract capturing group to an extract pattern. If no matched capturing
--   group found, return an empty string.
--   
--   <pre>
--   &gt;&gt;&gt; extract (regex "(\\d{4})-(\\d{2})-(\\d{2})") "Today is 2020-12-15" "month: \\2, date: \\3"
--   
--   &gt;&gt;&gt; "month: 12, date: 15"
--   </pre>
extract :: Regex -> Text -> Text -> Text
instance Z.Data.Text.Print.Print Z.Data.Text.Regex.Regex
instance GHC.Generics.Generic Z.Data.Text.Regex.Regex
instance GHC.Show.Show Z.Data.Text.Regex.Regex
instance Z.Data.Text.Print.Print Z.Data.Text.Regex.RegexOpts
instance GHC.Generics.Generic Z.Data.Text.Regex.RegexOpts
instance GHC.Show.Show Z.Data.Text.Regex.RegexOpts
instance GHC.Classes.Ord Z.Data.Text.Regex.RegexOpts
instance GHC.Classes.Eq Z.Data.Text.Regex.RegexOpts
instance GHC.Show.Show Z.Data.Text.Regex.RegexException
instance GHC.Exception.Type.Exception Z.Data.Text.Regex.RegexException


-- | A <a>Text</a> wrap a <tt>Bytes</tt> which will be interpreted using
--   UTF-8 encoding. User should always use <a>validate</a> /
--   <a>validateMaybe</a> to construt a <a>Text</a> (instead of using
--   construtor directly or coercing), otherwise illegal UTF-8 encoded
--   codepoints will cause undefined behaviours.
--   
--   This library also provide simple unicode processing based on
--   <a>utf8rewind</a>, see <a>normalize</a>, <a>caseFold</a> (current
--   using unicode 13 databases).
module Z.Data.Text

-- | <a>Text</a> represented as UTF-8 encoded <a>Bytes</a>
data Text

-- | Extract UTF-8 encoded <a>Bytes</a> from <a>Text</a>
getUTF8Bytes :: Text -> Bytes

-- | <i>O(n)</i> Validate a sequence of bytes is UTF-8 encoded.
--   
--   Throw <a>InvalidUTF8Exception</a> in case of invalid codepoint.
validate :: HasCallStack => Bytes -> Text

-- | <i>O(n)</i> Validate a sequence of bytes is all ascii char
--   byte(&lt;128).
--   
--   Throw <a>InvalidASCIIException</a> in case of invalid byte, It's not
--   always faster than <a>validate</a>, use it only if you want to
--   validate ASCII char sequences.
validateASCII :: HasCallStack => Bytes -> Text

-- | <i>O(n)</i> Validate a sequence of bytes is UTF-8 encoded.
--   
--   Return <a>Nothing</a> in case of invalid codepoint.
validateMaybe :: Bytes -> Maybe Text

-- | <i>O(n)</i> Validate a sequence of bytes is all ascii char
--   byte(&lt;128).
--   
--   Return <a>Nothing</a> in case of invalid byte.
validateASCIIMaybe :: Bytes -> Maybe Text
data TextException
InvalidUTF8Exception :: CallStack -> TextException
InvalidASCIIException :: CallStack -> TextException

-- | first payload is invalid char index
IndexOutOfTextRange :: Int -> CallStack -> TextException
EmptyText :: CallStack -> TextException

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a>, throw
--   <a>IndexOutOfTextRange</a> when out of bound.
index :: HasCallStack => Text -> Int -> Char

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a>.
indexMaybe :: Text -> Int -> Maybe Char

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a> counting from the
--   end, throw <tt>IndexOutOfVectorRange n callStack</tt> when out of
--   bound.
indexR :: HasCallStack => Text -> Int -> Char

-- | <i>O(n)</i> Get the nth codepoint from <a>Text</a> counting from the
--   end.
indexMaybeR :: Text -> Int -> Maybe Char

-- | <i>O(1)</i>. Empty text.
empty :: Text

-- | <i>O(1)</i>. Single char text.
singleton :: Char -> Text

-- | <i>O(n)</i>. Copy a text from slice.
copy :: Text -> Text

-- | <i>O(n)</i> <a>replicate</a> char n time.
replicate :: Int -> Char -> Text

-- | <i>O(n*m)</i> <a>cycleN</a> a text n times.
cycleN :: Int -> Text -> Text

-- | <i>O(n)</i> Convert a string into a text
--   
--   Alias for <tt><a>packN</a> <tt>defaultInitSize</tt></tt>, will be
--   rewritten to a memcpy if possible.
pack :: String -> Text

-- | <i>O(n)</i> Convert a list into a text with an approximate size(in
--   bytes, not codepoints).
--   
--   If the encoded bytes length is larger than the size given, we simply
--   double the buffer size and continue building.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packN :: Int -> String -> Text

-- | <i>O(n)</i> Alias for <tt><a>packRN</a> <tt>defaultInitSize</tt></tt>.
packR :: String -> Text

-- | <i>O(n)</i> <a>packN</a> in reverse order.
--   
--   This function is a <i>good consumer</i> in the sense of build/foldr
--   fusion.
packRN :: Int -> String -> Text

-- | <i>O(n)</i> Convert text to a char list.
--   
--   Unpacking is done lazily. i.e. we will retain reference to the array
--   until all element are consumed.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpack :: Text -> String

-- | <i>O(n)</i> Convert text to a list in reverse order.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpackR :: Text -> String

-- | <i>O(n)</i> convert from a char vector.
fromVector :: PrimVector Char -> Text

-- | <i>O(n)</i> convert to a char vector.
toVector :: Text -> PrimVector Char

-- | A class similar to <a>Show</a>, serving the purpose that quickly
--   convert a data type to a <a>Text</a> value.
--   
--   You can use newtype or generic deriving to implement instance of this
--   class quickly:
--   
--   <pre>
--    {-# LANGUAGE GeneralizedNewtypeDeriving #-}
--    {-# LANGUAGE DeriveAnyClass #-}
--    {-# LANGUAGE DeriveGeneric #-}
--    {-# LANGUAGE DerivingStrategies #-}
--   
--    import GHC.Generics
--   
--    newtype FooInt = FooInt Int deriving (Generic)
--                              deriving anyclass Print
--   
--   &gt; toText (FooInt 3)
--   &gt; "FooInt 3"
--   
--    newtype FooInt = FooInt Int deriving (Generic)
--                              deriving newtype Print
--   
--   &gt; toText (FooInt 3)
--   &gt; "3"
--   </pre>
class Print a

-- | Convert data to <a>Builder</a> with precendence.
--   
--   You should return a <a>Builder</a> writing in UTF8 encoding only, i.e.
--   
--   <pre>
--   Z.Data.Text.validateMaybe (Z.Data.Builder.buildBytes (toUTF8BuilderP p a)) /= Nothing
--   </pre>
toUTF8BuilderP :: Print a => Int -> a -> Builder ()

-- | Convert data to <a>Builder</a> with precendence.
--   
--   You should return a <a>Builder</a> writing in UTF8 encoding only, i.e.
--   
--   <pre>
--   Z.Data.Text.validateMaybe (Z.Data.Builder.buildBytes (toUTF8BuilderP p a)) /= Nothing
--   </pre>
toUTF8BuilderP :: (Print a, Generic a, GToText (Rep a)) => Int -> a -> Builder ()

-- | Convert data to <a>Text</a>.
toText :: Print a => a -> Text

-- | Convert data to <a>String</a>, faster <a>show</a> replacement.
toString :: Print a => a -> String

-- | Convert data to <a>Builder</a>.
toUTF8Builder :: Print a => a -> Builder ()

-- | Convert data to <a>Bytes</a> in UTF8 encoding.
toUTF8Bytes :: Print a => a -> Bytes

-- | <i>O(1)</i> Test whether a text is empty.
null :: Text -> Bool

-- | <i>O(n)</i> The char length of a text.
length :: Text -> Int

-- | <i>O(m+n)</i>
--   
--   There's no need to guard empty vector because we guard them for you,
--   so appending empty text are no-ops.
append :: Text -> Text -> Text

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

-- | Strict mapping with index.
imap' :: (Int -> Char -> Char) -> Text -> Text

-- | Strict left to right fold.
foldl' :: (b -> Char -> b) -> b -> Text -> b

-- | Strict left to right fold with index.
ifoldl' :: (b -> Int -> Char -> b) -> b -> Text -> b

-- | Strict right to left fold
foldr' :: (Char -> b -> b) -> b -> Text -> b

-- | Strict right to left fold with index
--   
--   NOTE: the index is counting from 0, not backwards
ifoldr' :: (Int -> Char -> b -> b) -> b -> Text -> b

-- | <i>O(n)</i> Concatenate a list of text.
--   
--   Note: <a>concat</a> have to force the entire list to filter out empty
--   text and calculate the length for allocation.
concat :: [Text] -> Text

-- | Map a function over a text and concatenate the results
concatMap :: (Char -> Text) -> Text -> Text

-- | <i>O(n)</i> <a>count</a> returns count of an element from a text.
count :: Char -> Text -> Int

-- | <i>O(n)</i> Applied to a predicate and text, <a>all</a> determines if
--   all chars of the text satisfy the predicate.
all :: (Char -> Bool) -> Text -> Bool

-- | <i>O(n)</i> Applied to a predicate and a text, <a>any</a> determines
--   if any chars of the text satisfy the predicate.
any :: (Char -> Bool) -> Text -> Bool

-- | Get the display width of a piece of text.
--   
--   You shouldn't pass texts with control characters(&lt;0x20, \DEL),
--   which are counted with -1 width.
--   
--   <pre>
--   &gt;&gt;&gt; displayWidth "你好世界！"
--   
--   &gt;&gt;&gt; 10
--   
--   &gt;&gt;&gt; displayWidth "hello world!"
--   
--   &gt;&gt;&gt; 12
--   </pre>
displayWidth :: Text -> Int

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Char -> Text -> Text

-- | <i>O(n)</i> Append a char to the end of a text.
snoc :: Text -> Char -> Text

-- | <i>O(1)</i> Extract the head and tail of a text, return <a>Nothing</a>
--   if it is empty.
uncons :: Text -> Maybe (Char, Text)

-- | <i>O(1)</i> Extract the init and last of a text, return <a>Nothing</a>
--   if text is empty.
unsnoc :: Text -> Maybe (Text, Char)

-- | <i>O(1)</i> Extract the first char of a text.
headMaybe :: Text -> Maybe Char

-- | <i>O(1)</i> Extract the chars after the head of a text.
--   
--   NOTE: <a>tailMayEmpty</a> return empty text in the case of an empty
--   text.
tailMayEmpty :: Text -> Text

-- | <i>O(1)</i> Extract the last char of a text.
lastMaybe :: Text -> Maybe Char

-- | <i>O(1)</i> Extract the chars before of the last one.
--   
--   NOTE: <a>initMayEmpty</a> return empty text in the case of an empty
--   text.
initMayEmpty :: Text -> Text

-- | <i>O(1)</i> Extract the first char of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
head :: Text -> Char

-- | <i>O(1)</i> Extract the chars after the head of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
tail :: Text -> Text

-- | <i>O(1)</i> Extract the last char of a text.
--   
--   Throw <a>EmptyText</a> if text is empty.
last :: Text -> Char

-- | <i>O(1)</i> Extract the chars before of the last one.
--   
--   Throw <a>EmptyText</a> if text is empty.
init :: Text -> Text

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

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

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a text <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 -> Text -> Text

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> char, or <tt>[]</tt> if <tt>n
--   &gt; <a>length</a> xs</tt>.
drop :: Int -> Text -> Text

-- | <i>O(1)</i> <a>takeR</a> <tt>n</tt>, applied to a text <tt>xs</tt>,
--   returns the suffix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
takeR :: Int -> Text -> Text

-- | <i>O(1)</i> <a>dropR</a> <tt>n xs</tt> returns the prefix of
--   <tt>xs</tt> before the last <tt>n</tt> char, or <tt>[]</tt> if <tt>n
--   &gt; <a>length</a> xs</tt>.
dropR :: Int -> Text -> Text

-- | <i>O(1)</i> Extract a sub-range text with give start index and length.
--   
--   This function is a total function just like 'take<i>drop',
--   index</i>length exceeds range will be ingored, e.g.
--   
--   <pre>
--   slice 1 3 "hello"   == "ell"
--   slice -1 -1 "hello" == ""
--   slice -2 2 "hello"  == ""
--   slice 2 10 "hello"  == "llo"
--   </pre>
--   
--   This holds for all x y: <tt>slice x y vs == drop x . take (x+y)
--   vs</tt>
slice :: Int -> Int -> Text -> Text

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

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

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>t</tt>,
--   returns the longest suffix (possibly empty) of <tt>t</tt> of elements
--   that satisfy <tt>p</tt>.
takeWhileR :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>vs</tt>,
--   returns the suffix (possibly empty) remaining after <a>takeWhile</a>
--   <tt>p vs</tt>.
dropWhile :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Applied to a predicate <tt>p</tt> and a text <tt>vs</tt>,
--   returns the prefix (possibly empty) remaining before <a>takeWhileR</a>
--   <tt>p vs</tt>.
dropWhileR :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> <tt>dropAround f = dropWhile f . dropWhileR f</tt>
dropAround :: (Char -> Bool) -> Text -> Text

-- | <i>O(n)</i> Split the text into the longest prefix of elements that do
--   not satisfy the predicate and the rest without copying.
break :: (Char -> Bool) -> Text -> (Text, Text)

-- | <i>O(n)</i> Split the text into the longest prefix of elements that
--   satisfy the predicate and the rest without copying.
span :: (Char -> Bool) -> Text -> (Text, Text)

-- | <a>breakR</a> behaves like <a>break</a> but from the end of the text.
--   
--   <pre>
--   breakR p == spanR (not.p)
--   </pre>
breakR :: (Char -> Bool) -> Text -> (Text, Text)

-- | <a>spanR</a> behaves like <a>span</a> but from the end of the text.
spanR :: (Char -> Bool) -> Text -> (Text, Text)

-- | Break a text on a subtext, returning a pair of the part of the text
--   prior to the match, and the rest of the text, e.g.
--   
--   <pre>
--   break "wor" "hello, world" = ("hello, ", "world")
--   </pre>
breakOn :: Text -> Text -> (Text, Text)

-- | O(n+m) Find all non-overlapping instances of needle in haystack. Each
--   element of the returned list consists of a pair:
--   
--   <ul>
--   <li>The entire string prior to the kth match (i.e. the prefix)</li>
--   <li>The kth match, followed by the remainder of the string</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   breakOnAll "::" ""
--   ==&gt; []
--   breakOnAll "<i>" "a</i>b<i>c</i>"
--   ==&gt; [("a", "<i>b</i>c<i>"), ("a</i>b", "<i>c</i>"), ("a<i>b</i>c", "/")]
--   </pre>
--   
--   The result list is lazy, search is performed when you force the list.
breakOnAll :: Text -> Text -> [(Text, Text)]

-- | The group function takes a text and returns a list of texts such that
--   the concatenation of the result is equal to the argument. Moreover,
--   each sublist in the result contains only equal elements. For example,
--   
--   <pre>
--   group <a>Mississippi</a> = [<a>M</a>,"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> The <a>stripPrefix</a> function takes two texts and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: Text -> Text -> Maybe Text

-- | O(n) The <a>stripSuffix</a> function takes two texts and returns Just
--   the remainder of the second iff the first is its suffix, and otherwise
--   Nothing.
stripSuffix :: Text -> Text -> Maybe Text

-- | <i>O(n)</i> Break a text into pieces separated by the delimiter
--   element consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   NOTE, this function behavior different with bytestring's. see
--   <a>#56</a>.
split :: Char -> Text -> [Text]

-- | <i>O(n)</i> Splits a text into components delimited by separators,
--   where the predicate returns True for a separator char. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == [""]
--   </pre>
splitWith :: (Char -> Bool) -> Text -> [Text]

-- | <i>O(m+n)</i> Break haystack into pieces separated by needle.
--   
--   Note: An empty needle will essentially split haystack element by
--   element.
--   
--   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>
splitOn :: Text -> Text -> [Text]

-- | The <tt>isPrefix</tt> function returns <a>True</a> if the first
--   argument is a prefix of the second.
isPrefixOf :: Text -> Text -> Bool

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

-- | Check whether one text is a subtext of another.
--   
--   <tt>needle <a>isInfixOf</a> haystack === null haystack || indices
--   needle haystake /= []</tt>.
isInfixOf :: Text -> Text -> Bool

-- | <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. e.g.
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "foobar" "fooquux"
--   ("foo","bar","quux")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; commonPrefix "veeble" "fetzer"
--   ("","veeble","fetzer")
--   </pre>
commonPrefix :: Text -> Text -> (Text, Text, Text)

-- | <i>O(n)</i> Breaks a <tt>Bytes</tt> up into a list of words, delimited
--   by unicode space.
words :: Text -> [Text]

-- | <i>O(n)</i> Breaks a text up into a list of lines, delimited by ascii
--   <tt>n</tt>.
lines :: Text -> [Text]

-- | <i>O(n)</i> Joins words with ascii space.
unwords :: [Text] -> Text

-- | <i>O(n)</i> Joins lines with ascii <tt>n</tt>.
--   
--   NOTE: This functions is different from <a>unlines</a>, it DOES NOT add
--   a trailing <tt>n</tt>.
unlines :: [Text] -> Text

-- | Add padding to the left so that the whole text's length is at least n.
padLeft :: Int -> Char -> Text -> Text

-- | Add padding to the right so that the whole text's length is at least
--   n.
padRight :: Int -> Char -> Text -> Text

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

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

-- | <i>O(n)</i> The <a>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
intercalateElem :: Char -> [Text] -> Text

-- | The <a>transpose</a> function transposes the rows and columns of its
--   text argument.
transpose :: [Text] -> [Text]

-- | <i>O(n)</i> <a>elem</a> test if given char is in given text.
elem :: Char -> Text -> Bool

-- | <i>O(n)</i> <tt>not . elem</tt>
notElem :: Char -> Text -> Bool

-- | <i>O(n)</i> find the first char matching the predicate in a text from
--   left to right, if there isn't one, return the text length.
find :: (Char -> Bool) -> Text -> (Int, Maybe Char)

-- | <i>O(n)</i> find the first char matching the predicate in a text from
--   right to left.
findR :: (Char -> Bool) -> Text -> (Int, Maybe Char)

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

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate, a text,
--   returns a pair of text with codepoints which do and do not satisfy the
--   predicate, respectively; i.e.,
--   
--   <pre>
--   partition p txt == (filter p txt, filter (not . p) txt)
--   </pre>
partition :: (Char -> Bool) -> Text -> (Text, Text)
data NormalizationResult
NormalizedYes :: NormalizationResult
NormalizedMaybe :: NormalizationResult
NormalizedNo :: NormalizationResult

-- | These are the Unicode Normalization Forms:
--   
--   <pre>
--   Form                         | Description
--   ---------------------------- | ---------------------------------------------
--   Normalization Form D (NFD)   | Canonical decomposition
--   Normalization Form C (NFC)   | Canonical decomposition, followed by canonical composition
--   Normalization Form KD (NFKD) | Compatibility decomposition
--   Normalization Form KC (NFKC) | Compatibility decomposition, followed by canonical composition
--   </pre>
data NormalizeMode
NFC :: NormalizeMode
NFKC :: NormalizeMode
NFD :: NormalizeMode
NFKD :: NormalizeMode

-- | Check if a string is stable in the NFC (Normalization Form C).
isNormalized :: Text -> NormalizationResult

-- | Check if a string is stable in the specified Unicode Normalization
--   Form.
--   
--   This function can be used as a preprocessing step, before attempting
--   to normalize a string. Normalization is a very expensive process, it
--   is often cheaper to first determine if the string is unstable in the
--   requested normalization form.
--   
--   The result of the check will be YES if the string is stable and MAYBE
--   or NO if it is unstable. If the result is MAYBE, the string does not
--   necessarily have to be normalized.
--   
--   For more information, please review
--   &lt;<a>http://www.unicode.org/reports/tr15/</a> Unicode Standard Annex
--   #15 - Unicode Normalization Forms&gt;.
isNormalizedTo :: NormalizeMode -> Text -> NormalizationResult

-- | Normalize a string to NFC (Normalization Form C).
normalize :: Text -> Text

-- | Normalize a string to the specified Unicode Normalization Form.
--   
--   The Unicode standard defines two standards for equivalence between
--   characters: canonical and compatibility equivalence. Canonically
--   equivalent characters and sequence represent the same abstract
--   character and must be rendered with the same appearance and behavior.
--   Compatibility equivalent characters have a weaker equivalence and may
--   be rendered differently.
--   
--   Unicode Normalization Forms are formally defined standards that can be
--   used to test whether any two strings of characters are equivalent to
--   each other. This equivalence may be canonical or compatibility.
--   
--   The algorithm puts all combining marks into a specified order and uses
--   the rules for decomposition and composition to transform the string
--   into one of four Unicode Normalization Forms. A binary comparison can
--   then be used to determine equivalence.
normalizeTo :: NormalizeMode -> Text -> Text

-- | Get environment locale
envLocale :: IO Locale

-- | Remove case distinction from UTF-8 encoded text with default locale.
caseFold :: Text -> Text

-- | Remove case distinction from UTF-8 encoded text.
--   
--   Case folding is the process of eliminating differences between code
--   points concerning case mapping. It is most commonly used for comparing
--   strings in a case-insensitive manner. Conversion is fully compliant
--   with the Unicode 7.0 standard.
--   
--   Although similar to lowercasing text, there are significant
--   differences. For one, case folding does _not_ take locale into account
--   when converting. In some cases, case folding can be up to 20% faster
--   than lowercasing the same text, but the result cannot be treated as
--   correct lowercased text.
--   
--   Only two locale-specific exception are made when case folding text. In
--   Turkish, U+0049 LATIN CAPITAL LETTER I maps to U+0131 LATIN SMALL
--   LETTER DOTLESS I and U+0130 LATIN CAPITAL LETTER I WITH DOT ABOVE maps
--   to U+0069 LATIN SMALL LETTER I.
--   
--   Although most code points can be case folded without changing length,
--   there are notable exceptions. For example, U+0130 (LATIN CAPITAL
--   LETTER I WITH DOT ABOVE) maps to "U+0069 U+0307" (LATIN SMALL LETTER I
--   and COMBINING DOT ABOVE) when converted to lowercase.
--   
--   Only a handful of scripts make a distinction between upper- and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
caseFoldWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to lowercase with default locale.
toLower :: Text -> Text

-- | Convert UTF-8 encoded text to lowercase.
--   
--   This function allows conversion of UTF-8 encoded strings to lowercase
--   without first changing the encoding to UTF-32. Conversion is fully
--   compliant with the Unicode 7.0 standard.
--   
--   Although most code points can be converted to lowercase with changing
--   length, there are notable exceptions. For example, U+0130 (LATIN
--   CAPITAL LETTER I WITH DOT ABOVE) maps to "U+0069 U+0307" (LATIN SMALL
--   LETTER I and COMBINING DOT ABOVE) when converted to lowercase.
--   
--   Only a handful of scripts make a distinction between upper- and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
--   
--   Case mapping is not reversible. That is, <tt>toUpper(toLower(x)) !=
--   toLower(toUpper(x))</tt>.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toLowerWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to uppercase with default locale.
toUpper :: Text -> Text

-- | Convert UTF-8 encoded text to uppercase.
--   
--   Conversion is fully compliant with the Unicode 7.0 standard.
--   
--   Although most code points can be converted without changing length,
--   there are notable exceptions. For example, U+00DF (LATIN SMALL LETTER
--   SHARP S) maps to "U+0053 U+0053" (LATIN CAPITAL LETTER S and LATIN
--   CAPITAL LETTER S) when converted to uppercase.
--   
--   Only a handful of scripts make a distinction between upper and
--   lowercase. In addition to modern scripts, such as Latin, Greek,
--   Armenian and Cyrillic, a few historic or archaic scripts have case.
--   The vast majority of scripts do not have case distinctions.
--   
--   Case mapping is not reversible. That is, <tt>toUpper(toLower(x)) !=
--   toLower(toUpper(x))</tt>.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toUpperWith :: Locale -> Text -> Text

-- | Convert UTF-8 encoded text to titlecase with default locale.
toTitle :: Text -> Text

-- | Convert UTF-8 encoded text to titlecase.
--   
--   This function allows conversion of UTF-8 encoded strings to titlecase.
--   Conversion is fully compliant with the Unicode 7.0 standard.
--   
--   Titlecase requires a bit more explanation than uppercase and
--   lowercase, because it is not a common text transformation. Titlecase
--   uses uppercase for the first letter of each word and lowercase for the
--   rest. Words are defined as "collections of code points with general
--   category Lu, Ll, Lt, Lm or Lo according to the Unicode database".
--   
--   Effectively, any type of punctuation can break up a word, even if this
--   is not grammatically valid. This happens because the titlecasing
--   algorithm does not and cannot take grammar rules into account.
--   
--   <pre>
--   Text                                 | Titlecase
--   -------------------------------------|-------------------------------------
--   The running man                      | The Running Man
--   NATO Alliance                        | Nato Alliance
--   You're amazing at building libraries | You'Re Amazing At Building Libraries
--   </pre>
--   
--   Although most code points can be converted to titlecase without
--   changing length, there are notable exceptions. For example, U+00DF
--   (LATIN SMALL LETTER SHARP S) maps to "U+0053 U+0073" (LATIN CAPITAL
--   LETTER S and LATIN SMALL LETTER S) when converted to titlecase.
--   
--   Certain code points (or combinations of code points) apply rules based
--   on the locale. For more information about these exceptional code
--   points, please refer to the Unicode standard:
--   <a>ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt</a>
toTitleWith :: Locale -> Text -> Text

-- | Check if the input string conforms to the category specified by the
--   flags.
--   
--   This function can be used to check if the code points in a string are
--   part of a category. Valid flags are members of the "list of
--   categories". The category for a code point is defined as part of the
--   entry in UnicodeData.txt, the data file for the Unicode code point
--   database.
--   
--   By default, the function will treat grapheme clusters as a single code
--   point. This means that the following string:
--   
--   <pre>
--   Code point | Canonical combining class | General category      | Name
--   ---------- | ------------------------- | --------------------- | ----------------------
--   U+0045     | 0                         | Lu (Uppercase letter) | LATIN CAPITAL LETTER E
--   U+0300     | 230                       | Mn (Non-spacing mark) | COMBINING GRAVE ACCENT
--   </pre>
--   
--   Will match with <a>CategoryLetterUppercase</a> in its entirety,
--   because the COMBINING GRAVE ACCENT is treated as part of the grapheme
--   cluster. This is useful when e.g. creating a text parser, because you
--   do not have to normalize the text first.
--   
--   If this is undesired behavior, specify the
--   <a>CategoryIgnoreGraphemeCluster</a> flag.
--   
--   In order to maintain backwards compatibility with POSIX functions like
--   <tt>isdigit</tt> and <tt>isspace</tt>, compatibility flags have been
--   provided. Note, however, that the result is only guaranteed to be
--   correct for code points in the Basic Latin range, between U+0000 and
--   0+007F. Combining a compatibility flag with a regular category flag
--   will result in undefined behavior.
isCategory :: Category -> Text -> Bool

-- | Try to match as many code points with the matching category flags as
--   possible and return the prefix and suffix.
spanCategory :: Category -> Text -> (Text, Text)

-- | Locale for case mapping.
type Locale = CSize
pattern LocaleDefault :: Locale
pattern LocaleLithuanian :: Locale
pattern LocaleTurkishAndAzeriLatin :: Locale

-- | Unicode categories.
--   
--   See <a>isCategory</a>, you can combine categories with bitwise or.
type Category = CSize
pattern CategoryLetterUppercase :: Category
pattern CategoryLetterLowercase :: Category
pattern CategoryLetterTitlecase :: Category
pattern CategoryLetterOther :: Category
pattern CategoryLetter :: Category
pattern CategoryCaseMapped :: Category
pattern CategoryMarkNonSpacing :: Category
pattern CategoryMarkSpacing :: Category
pattern CategoryMarkEnclosing :: Category
pattern CategoryMark :: Category
pattern CategoryNumberDecimal :: Category
pattern CategoryNumberLetter :: Category
pattern CategoryNumberOther :: Category
pattern CategoryNumber :: Category
pattern CategoryPunctuationConnector :: Category
pattern CategoryPunctuationDash :: Category
pattern CategoryPunctuationOpen :: Category
pattern CategoryPunctuationClose :: Category
pattern CategoryPunctuationInitial :: Category
pattern CategoryPunctuationFinal :: Category
pattern CategoryPunctuationOther :: Category
pattern CategoryPunctuation :: Category
pattern CategorySymbolMath :: Category
pattern CategorySymbolCurrency :: Category
pattern CategorySymbolModifier :: Category
pattern CategorySymbolOther :: Category
pattern CategorySymbol :: Category
pattern CategorySeparatorSpace :: Category
pattern CategorySeparatorLine :: Category
pattern CategorySeparatorParagraph :: Category
pattern CategorySeparator :: Category
pattern CategoryControl :: Category
pattern CategoryFormat :: Category
pattern CategorySurrogate :: Category
pattern CategoryPrivateUse :: Category
pattern CategoryUnassigned :: Category
pattern CategoryCompatibility :: Category
pattern CategoryIgnoreGraphemeCluster :: Category
pattern CategoryIscntrl :: Category
pattern CategoryIsprint :: Category
pattern CategoryIsspace :: Category
pattern CategoryIsblank :: Category
pattern CategoryIsgraph :: Category
pattern CategoryIspunct :: Category
pattern CategoryIsalnum :: Category
pattern CategoryIsalpha :: Category
pattern CategoryIsupper :: Category
pattern CategoryIslower :: Category
pattern CategoryIsdigit :: Category
pattern CategoryIsxdigit :: Category


-- | This module provides definition and parsers for JSON <a>Value</a>s, a
--   Haskell JSON representation. The parsers is designed to comply with
--   <a>rfc8258</a>, notable pitfalls are:
--   
--   <ul>
--   <li>The numeric representation use <a>Scientific</a>, which impose a
--   limit on number's exponent part(limited to <a>Int</a>).</li>
--   <li>Unescaped control characters(&lt;=0x1F) are NOT accepted,
--   (different from aeson).</li>
--   <li>Only <tt>0x20, 0x09, 0x0A, 0x0D</tt> are valid JSON whitespaces,
--   <a>skipSpaces</a> from this module is different from
--   <a>skipSpaces</a>.</li>
--   <li>A JSON document shouldn't have trailing characters except
--   whitespaces describe above, see <a>parseValue'</a> and
--   <tt>parseValueChunks'</tt>.</li>
--   <li>Objects are represented as key-value vectors, key order and
--   duplicated keys are preserved for further processing.</li>
--   </ul>
--   
--   Note that rfc8258 doesn't enforce unique key in objects, it's up to
--   users to decided how to deal with key duplication, e.g. prefer first
--   or last key, see <a>withFlatMap</a> or <a>withFlatMapR</a> for
--   example.
--   
--   There's no lazy parsers here, every pieces of JSON document will be
--   parsed into a normal form <a>Value</a>. <a>Object</a> and
--   <a>Array</a>s payloads are packed into <a>Vector</a>s to avoid
--   accumulating lists in memory. Read more about <a>why no lazy parsing
--   is needed</a>.
module Z.Data.JSON.Value

-- | A JSON value represented as a Haskell value.
--   
--   The <tt>Object'</tt>s payload is a key-value vector instead of a map,
--   which parsed directly from JSON document. This design choice has
--   following advantages:
--   
--   <ul>
--   <li>Allow different strategies handling duplicated keys.</li>
--   <li>Allow different <tt>Map</tt> type to do further parsing, e.g.
--   <a>FlatMap</a></li>
--   <li>Roundtrip without touching the original key-value order.</li>
--   <li>Save time if constructing map is not neccessary, e.g. using a
--   linear scan to find a key if only that key is needed.</li>
--   </ul>
data Value
Object :: {-# UNPACK #-} !Vector (Text, Value) -> Value
Array :: {-# UNPACK #-} !Vector Value -> Value
String :: {-# UNPACK #-} !Text -> Value
Number :: {-# UNPACK #-} !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value

-- | Lense for <a>Object</a> element
--   
--   <ol>
--   <li>return <a>Null</a> if <a>Value</a> is not an <a>Object</a> or key
--   not exist.</li>
--   <li>Modify will have no effect if <a>Value</a> is not an <a>Object</a>
--   or key not exist.</li>
--   <li>On duplicated keys prefer the last one.</li>
--   </ol>
key :: Functor f => Text -> (Value -> f Value) -> Value -> f Value

-- | Lense for <a>Array</a> element.
--   
--   <ol>
--   <li>return <a>Null</a> if <a>Value</a> is not an <a>Array</a> or index
--   not exist.</li>
--   <li>Modify will have no effect if <a>Value</a> is not an <a>Array</a>
--   or index not exist.</li>
--   </ol>
nth :: Functor f => Int -> (Value -> f Value) -> Value -> f Value

-- | Parse <a>Value</a> without consuming trailing bytes.
parseValue :: Bytes -> (Bytes, Either ParseError Value)

-- | Parse <a>Value</a>, and consume all trailing JSON white spaces, if
--   there're bytes left, parsing will fail.
parseValue' :: Bytes -> Either ParseError Value

-- | Increamental parse <a>Value</a> without consuming trailing bytes.
parseValueChunks :: Monad m => ParseChunks m Bytes ParseError Value

-- | JSON <a>Value</a> parser.
value :: Parser Value

-- | parse json array with leading 123.
object :: Parser (Vector (Text, Value))

-- | parse json array with leading 91.
array :: Parser (Vector Value)
string :: Parser Text

-- | The only valid whitespace in a JSON document is space, newline,
--   carriage pure, and tab.
skipSpaces :: Parser ()

-- | Convert IEEE float to scientific notition.
floatToScientific :: Float -> Scientific

-- | Convert IEEE double to scientific notition.
doubleToScientific :: Double -> Scientific
instance Z.Data.Text.Print.Print Z.Data.JSON.Value.Value
instance GHC.Generics.Generic Z.Data.JSON.Value.Value
instance GHC.Show.Show Z.Data.JSON.Value.Value
instance GHC.Classes.Ord Z.Data.JSON.Value.Value
instance GHC.Classes.Eq Z.Data.JSON.Value.Value
instance Control.DeepSeq.NFData Z.Data.JSON.Value.Value
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.JSON.Value.Value


-- | Builders for dates and times.
module Z.Data.Builder.Time

-- | <tt>YYYY-mm-dd</tt>.
day :: Day -> Builder ()

-- | <tt>HH-MM-SS</tt>.
timeOfDay :: TimeOfDay -> Builder ()

-- | Timezone format in <tt>+HH:MM</tt>, with single letter <tt>Z</tt> for
--   <tt>+00:00</tt>.
timeZone :: TimeZone -> Builder ()

-- | Write <a>UTCTime</a> in ISO8061 <tt>YYYY-MM-DDTHH:MM:SS.SSSZ</tt>(time
--   zone will always be <tt>Z</tt>).
utcTime :: UTCTime -> Builder ()

-- | Write <a>LocalTime</a> in ISO8061 <tt>YYYY-MM-DDTHH:MM:SS.SSS</tt>.
localTime :: LocalTime -> Builder ()

-- | Write <a>ZonedTime</a> in ISO8061 <tt>YYYY-MM-DD HH:MM:SS.SSSZ</tt>.
zonedTime :: ZonedTime -> Builder ()


-- | A <a>Builder</a> records a buffer writing function, which can be
--   <a>mappend</a> in O(1) via composition. This module provides many
--   functions to turn basic data types into <a>Builder</a>s, which can
--   used to build strict <tt>Bytes</tt> or list of <tt>Bytes</tt> chunks.
module Z.Data.Builder

-- | <tt>Builder</tt> is a monad to help compose <tt>BuilderStep</tt>. With
--   next <tt>BuilderStep</tt> continuation, we can do interesting things
--   like perform some action, or interleave the build process.
--   
--   Notes on <a>IsString</a> instance: <tt>Builder ()</tt>'s
--   <a>IsString</a> instance use <a>stringModifiedUTF8</a>, which is
--   different from <a>stringUTF8</a> in that it DOES NOT PROVIDE UTF8
--   GUARANTEES! :
--   
--   <ul>
--   <li><tt>\NUL</tt> will be written as <tt>\xC0 \x80</tt>.</li>
--   <li><tt>\xD800</tt> ~ <tt>\xDFFF</tt> will be encoded in three bytes
--   as normal UTF-8 codepoints.</li>
--   </ul>
data Builder a
append :: Builder a -> Builder b -> Builder b

-- | Shortcut to <a>buildWith</a> <a>defaultInitSize</a>.
build :: Builder a -> Bytes

-- | Run Builder with doubling buffer strategy, which is suitable for
--   building short bytes.
buildWith :: Int -> Builder a -> Bytes

-- | Shortcut to <a>buildChunksWith</a> <a>defaultChunkSize</a>.
buildChunks :: Builder a -> [Bytes]

-- | Run Builder with inserting chunk strategy, which is suitable for
--   building a list of bytes chunks and processing them in a streaming
--   ways.
--   
--   Note the building process is lazy, building happens when list chunks
--   are consumed.
buildChunksWith :: Int -> Int -> Builder a -> [Bytes]

-- | Build some bytes and validate if it's UTF8 bytes.
buildText :: HasCallStack => Builder a -> Text

-- | Build some bytes assuming it's UTF8 encoding.
--   
--   Be carefully use this function because you could constrcut illegal
--   <a>Text</a> values. Check <a>ShowT</a> for UTF8 encoding builders.
--   This functions is intended to be used in debug only.
unsafeBuildText :: Builder a -> Text

-- | Write a <a>Bytes</a>.
bytes :: Bytes -> Builder ()
ensureN :: Int -> (MutablePrimArray RealWorld Word8 -> Int -> IO Int) -> Builder ()
writeN :: Int -> (MutablePrimArray RealWorld Word8 -> Int -> IO ()) -> Builder ()

-- | Write a primitive type in host byte order.
--   
--   <pre>
--   &gt; encodePrim (256 :: Word16, BE 256 :: BE Word16)
--   &gt; [0,1,1,0]
--   </pre>
encodePrim :: forall a. Unaligned a => a -> Builder ()

-- | big endianess wrapper
newtype BE a
BE :: a -> BE a
[getBE] :: BE a -> a

-- | little endianess wrapper
newtype LE a
LE :: a -> LE a
[getLE] :: LE a -> a

-- | Write a primitive type with little endianess.
encodePrimLE :: forall a. Unaligned (LE a) => a -> Builder ()

-- | Write a primitive type with big endianess.
encodePrimBE :: forall a. Unaligned (BE a) => a -> Builder ()

-- | Encode string with modified UTF-8 encoding, will be rewritten to a
--   memcpy if possible.
stringModifiedUTF8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with Modified UTF8 encoding
--   
--   <tt>\NUL</tt> is encoded as two bytes <tt>C0 80</tt> , <tt>\xD800</tt>
--   ~ <tt>\xDFFF</tt> is encoded as a three bytes normal UTF-8 codepoint.
charModifiedUTF8 :: Char -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
--   
--   This is different from writing string literals builders via
--   <tt>OverloadedStrings</tt>, because string literals do not provide
--   UTF8 guarantees.
--   
--   This function will be rewritten into a memcpy if possible, (running a
--   fast UTF-8 validation at runtime first).
stringUTF8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with UTF8 encoding
--   
--   Illegal codepoints will be written as <a>replacementChar</a>s.
charUTF8 :: Char -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
string7 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
char7 :: Char -> Builder ()

-- | Turn <a>Word8</a> into <a>Builder</a> with ASCII7 encoding
--   
--   Codepoints beyond <tt>'x7F'</tt> will be chopped.
word7 :: Word8 -> Builder ()

-- | Turn <a>String</a> into <a>Builder</a> with ASCII8 encoding
--   
--   Codepoints beyond <tt>'xFF'</tt> will be chopped. Note, this encoding
--   is NOT compatible with UTF8 encoding, i.e. bytes written by this
--   builder may not be legal UTF8 encoding bytes.
string8 :: String -> Builder ()

-- | Turn <a>Char</a> into <a>Builder</a> with ASCII8 encoding
--   
--   Codepoints beyond <tt>'xFF'</tt> will be chopped. Note, this encoding
--   is NOT compatible with UTF8 encoding, i.e. bytes written by this
--   builder may not be legal UTF8 encoding bytes.
char8 :: Char -> Builder ()

-- | Turn <a>Word8</a> into <a>Builder</a> with ASCII8 encoding, (alias to
--   <a>encodePrim</a>).
--   
--   Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes
--   written by this builder may not be legal UTF8 encoding bytes.
word8 :: Word8 -> Builder ()

-- | Faster version of <tt>replicateM x . word8</tt> by using
--   <tt>memset</tt>.
--   
--   Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes
--   written by this builder may not be legal UTF8 encoding bytes.
word8N :: Int -> Word8 -> Builder ()

-- | Write UTF8 encoded <tt>Text</tt> using <a>Builder</a>.
--   
--   Note, if you're trying to write string literals builders, please open
--   <tt>OverloadedStrings</tt> and use <a>Builder</a>s <a>IsString</a>
--   instance, it will be rewritten into a memcpy.
text :: Text -> Builder ()

-- | Integral formatting options.
data IFormat
IFormat :: Int -> Padding -> Bool -> IFormat

-- | total width, only effective with padding options
[width] :: IFormat -> Int

-- | padding options
[padding] :: IFormat -> Padding

-- | show <tt>+</tt> when the number is positive
[posSign] :: IFormat -> Bool

-- | <pre>
--   defaultIFormat = IFormat 0 NoPadding False
--   </pre>
defaultIFormat :: IFormat
data Padding
NoPadding :: Padding
RightSpacePadding :: Padding
LeftSpacePadding :: Padding
ZeroPadding :: Padding

-- | <pre>
--   int = intWith defaultIFormat
--   </pre>
int :: (Integral a, Bounded a) => a -> Builder ()

-- | Format a <a>Bounded</a> <a>Integral</a> type like <tt>Int</tt> or
--   <tt>Word16</tt> into decimal ASCII digits.
--   
--   <pre>
--   import Z.Data.Builder as B
--   
--   &gt; B.buildText $ B.intWith defaultIFormat  (12345 :: Int)
--   "12345"
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=RightSpacePadding} (12345 :: Int)
--   "12345     "
--   &gt; B.buildText $ B.intWith defaultIFormat{width=10, padding=ZeroPadding} (12345 :: Int)
--   "0000012345"
--   </pre>
intWith :: (Integral a, Bounded a) => IFormat -> a -> Builder ()

-- | Format a <a>Integer</a> into decimal ASCII digits.
integer :: Integer -> Builder ()

-- | Format a <a>FiniteBits</a> <a>Integral</a> type into hex nibbles.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Data.Word
--   import Data.Int
--   
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Int8)
--   "7d"
--   &gt; T.validate . B.buildBytes $ B.hex (-1 :: Int8)
--   "ff"
--   &gt; T.validate . B.buildBytes $ B.hex (125 :: Word16)
--   "007d"
--   </pre>
hex :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

-- | The UPPERCASED version of <a>hex</a>.
hexUpper :: forall a. (FiniteBits a, Integral a) => a -> Builder ()

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

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

-- | Standard decimal notation.
Fixed :: FFormat

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

-- | Decimal encoding of an IEEE <a>Double</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
double :: Double -> Builder ()

-- | Format double-precision float using drisu3 with dragon4 fallback.
doubleWith :: FFormat -> Maybe Int -> Double -> Builder ()

-- | Decimal encoding of an IEEE <a>Float</a>.
--   
--   Using standard decimal notation for arguments whose absolute value
--   lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific
--   notation otherwise.
float :: Float -> Builder ()

-- | Format single-precision float using drisu3 with dragon4 fallback.
floatWith :: FFormat -> Maybe Int -> Float -> Builder ()

-- | A <tt>Builder</tt> which renders a scientific number to full
--   precision, using standard decimal notation for arguments whose
--   absolute value lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and
--   scientific notation otherwise.
scientific :: Scientific -> Builder ()

-- | Like <a>scientific</a> but provides rendering options.
scientificWith :: FFormat -> Maybe Int -> Scientific -> Builder ()

-- | add <tt>(...)</tt> to original builder.
paren :: Builder () -> Builder ()

-- | add <tt>{...}</tt> to original builder.
curly :: Builder () -> Builder ()

-- | add <tt>[...]</tt> to original builder.
square :: Builder () -> Builder ()

-- | add <tt><i>&lt;...</i>&gt;</tt> to original builder.
angle :: Builder () -> Builder ()

-- | add <tt><i>"...</i>"</tt> to original builder.
quotes :: Builder () -> Builder ()

-- | add <tt><i>'...</i>'</tt> to original builder.
squotes :: Builder () -> Builder ()

-- | write an ASCII <tt>:</tt>
colon :: Builder ()

-- | write an ASCII <tt>,</tt>
comma :: Builder ()

-- | Use separator to connect a vector of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   &gt; T.validate . B.build $ B.intercalateVec "," B.int (V.pack [1,2,3,4] :: V.PrimVector Int)
--   "1,2,3,4"
--   </pre>
intercalateVec :: Vec v a => Builder () -> (a -> Builder ()) -> v a -> Builder ()

-- | Use separator to connect list of builders.
--   
--   <pre>
--   import Z.Data.Builder as B
--   import Z.Data.Text    as T
--   import Z.Data.Vector  as V
--   
--   T.validate . B.build $ B.intercalateList "," B.int ([1,2,3,4] :: [Int])
--   "1,2,3,4"
--   </pre>
intercalateList :: Builder () -> (a -> Builder ()) -> [a] -> Builder ()

-- | <tt>YYYY-mm-dd</tt>.
day :: Day -> Builder ()

-- | <tt>HH-MM-SS</tt>.
timeOfDay :: TimeOfDay -> Builder ()

-- | Timezone format in <tt>+HH:MM</tt>, with single letter <tt>Z</tt> for
--   <tt>+00:00</tt>.
timeZone :: TimeZone -> Builder ()

-- | Write <a>UTCTime</a> in ISO8061 <tt>YYYY-MM-DDTHH:MM:SS.SSSZ</tt>(time
--   zone will always be <tt>Z</tt>).
utcTime :: UTCTime -> Builder ()

-- | Write <a>LocalTime</a> in ISO8061 <tt>YYYY-MM-DDTHH:MM:SS.SSS</tt>.
localTime :: LocalTime -> Builder ()

-- | Write <a>ZonedTime</a> in ISO8061 <tt>YYYY-MM-DD HH:MM:SS.SSSZ</tt>.
zonedTime :: ZonedTime -> Builder ()


-- | This module provides builders for JSON <a>Value</a>s, a Haskell JSON
--   representation. These builders are designed to comply with
--   <a>rfc8258</a>. Only control characters are escaped, other unicode
--   codepoints are directly written instead of being escaped.
module Z.Data.JSON.Builder

-- | Encode a <a>Value</a>, you can use this function with <tt>toValue</tt>
--   to get <tt>encodeJSON</tt> with a small overhead.
value :: Value -> Builder ()
object :: Vector (Text, Value) -> Builder ()
object' :: (a -> Builder ()) -> Vector (Text, a) -> Builder ()
array :: Vector Value -> Builder ()
array' :: (a -> Builder ()) -> Vector a -> Builder ()

-- | Escape text into JSON string and add double quotes, escaping rules:
--   
--   <pre>
--   '\b':  "\b"
--   '\f':  "\f"
--   '\n':  "\n"
--   '\r':  "\r"
--   '\t':  "\t"
--   '"':  "\""
--   '\':  "\\"
--   'DEL':  "\u007f"
--   other chars &lt;= 0x1F: "\u00XX"
--   </pre>
string :: Text -> Builder ()

-- | This builder try to render integer when (0 &lt;= e &lt; 16), and
--   scientific notation otherwise.
scientific :: Scientific -> Builder ()

-- | 'ValuePretty'' with 4 spaces indentation per level, e.g.
--   
--   <pre>
--   {
--       "results":
--       [
--           {
--               "from_user_id_str":"80430860",
--               "profile_image_url":"<a>http://a2.twimg.com/profile_images/536455139/icon32_normal.png"</a>,
--               "created_at":"Wed, 26 Jan 2011 07:07:02 +0000",
--               "from_user":"kazu_yamamoto",
--               "id_str":"30159761706061824",
--               "metadata":
--               {
--                   "result_type":"recent"
--               },
--               "to_user_id":null,
--               "text":"Haskell Server Pages って、まだ続いていたのか！",
--               "id":30159761706061824,
--               "from_user_id":80430860,
--               "geo":null,
--               "iso_language_code":"no",
--               "to_user_id_str":null,
--               "source":"&amp;lt;a href=&amp;quot;http:/<i>twitter.com</i>&amp;quot;&amp;gt;web&amp;lt;/a&amp;gt;"
--           }
--       ],
--       "max_id":30159761706061824,
--       "since_id":0,
--       "refresh_url":"?since_id=30159761706061824&amp;q=haskell",
--       "next_page":"?page=2&amp;max_id=30159761706061824&amp;rpp=1&amp;q=haskell",
--       "results_per_page":1,
--       "page":1,
--       "completed_in":1.2606e-2,
--       "since_id_str":"0",
--       "max_id_str":"30159761706061824",
--       "query":"haskell"
--   }
--   </pre>
prettyValue :: Value -> Builder ()

-- | Encode a <a>Value</a> with indentation and linefeed.
prettyValue' :: Int -> Int -> Value -> Builder ()

-- | Use <tt>:</tt> as separator to connect a label(no escape, only add
--   quotes) with field builders.
--   
--   Don't use chars which need escaped in label.
kv :: Text -> Builder () -> Builder ()

-- | Use <tt>:</tt> as separator to connect a label(escape the label and
--   add quotes) with field builders.
kv' :: Text -> Builder () -> Builder ()

-- | A JSON value represented as a Haskell value.
--   
--   The <tt>Object'</tt>s payload is a key-value vector instead of a map,
--   which parsed directly from JSON document. This design choice has
--   following advantages:
--   
--   <ul>
--   <li>Allow different strategies handling duplicated keys.</li>
--   <li>Allow different <tt>Map</tt> type to do further parsing, e.g.
--   <a>FlatMap</a></li>
--   <li>Roundtrip without touching the original key-value order.</li>
--   <li>Save time if constructing map is not neccessary, e.g. using a
--   linear scan to find a key if only that key is needed.</li>
--   </ul>
data Value
Object :: {-# UNPACK #-} !Vector (Text, Value) -> Value
Array :: {-# UNPACK #-} !Vector Value -> Value
String :: {-# UNPACK #-} !Text -> Value
Number :: {-# UNPACK #-} !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value


-- | This module provides tools for converting protocol IR (e.g.
--   <tt>Value</tt>) to Haskell ADTs:
module Z.Data.JSON.Converter

-- | Run a <a>Converter</a> with input value.
convert :: (a -> Converter r) -> a -> Either ConvertError r

-- | Elements of a (JSON) Value path used to describe the location of an
--   error.
data PathElement

-- | Path element of a key into an object, "object.key".
Key :: {-# UNPACK #-} !Text -> PathElement

-- | Path element of an index into an array, "array[index]".
Index :: {-# UNPACK #-} !Int -> PathElement

-- | path of a embedded (JSON) String
Embedded :: PathElement

-- | Error info with (JSON) Path info.
data ConvertError
ConvertError :: [PathElement] -> Text -> ConvertError
[errPath] :: ConvertError -> [PathElement]
[errMsg] :: ConvertError -> Text

-- | <a>Converter</a> provides a monadic interface to convert protocol IR
--   (e.g.<tt>Value</tt>) to Haskell ADT.
newtype Converter a
Converter :: (forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r) -> Converter a
[runConverter] :: Converter a -> forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r

-- | <a>Text</a> version of <a>fail</a>.
fail' :: Text -> Converter a

-- | Add (JSON) Path context to a converter
--   
--   When converting a complex structure, it helps to annotate
--   (sub)converters with context, so that if an error occurs, you can find
--   its location.
--   
--   <pre>
--   withFlatMapR "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age" &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a (JSON) Path
--   location of that error.
(<?>) :: Converter a -> PathElement -> Converter a
infixl 9 <?>

-- | Add context to a failure message, indicating the name of the structure
--   being converted.
--   
--   <pre>
--   prependContext "MyType" (fail "[error message]")
--   -- Error: "converting MyType failed, [error message]"
--   </pre>
prependContext :: Text -> Converter a -> Converter a
instance Control.DeepSeq.NFData Z.Data.JSON.Converter.PathElement
instance GHC.Generics.Generic Z.Data.JSON.Converter.PathElement
instance GHC.Classes.Ord Z.Data.JSON.Converter.PathElement
instance GHC.Show.Show Z.Data.JSON.Converter.PathElement
instance GHC.Classes.Eq Z.Data.JSON.Converter.PathElement
instance Control.DeepSeq.NFData Z.Data.JSON.Converter.ConvertError
instance GHC.Generics.Generic Z.Data.JSON.Converter.ConvertError
instance GHC.Classes.Ord Z.Data.JSON.Converter.ConvertError
instance GHC.Classes.Eq Z.Data.JSON.Converter.ConvertError
instance GHC.Base.Functor Z.Data.JSON.Converter.Converter
instance GHC.Base.Applicative Z.Data.JSON.Converter.Converter
instance GHC.Base.Alternative Z.Data.JSON.Converter.Converter
instance GHC.Base.MonadPlus Z.Data.JSON.Converter.Converter
instance GHC.Base.Monad Z.Data.JSON.Converter.Converter
instance Control.Monad.Fail.MonadFail Z.Data.JSON.Converter.Converter
instance GHC.Show.Show Z.Data.JSON.Converter.ConvertError
instance Z.Data.Text.Print.Print Z.Data.JSON.Converter.ConvertError


-- | This module provides <a>Converter</a> to convert <a>Value</a> to
--   haskell data types, and various tools to help user define <a>JSON</a>
--   instance. It's recommended to use <a>Z.Data.JSON</a> instead since it
--   contain more instances.
module Z.Data.JSON.Base

-- | Type class for encode &amp; decode JSON.
class JSON a
fromValue :: JSON a => Value -> Converter a
fromValue :: (JSON a, Generic a, GFromValue (Rep a)) => Value -> Converter a
toValue :: JSON a => a -> Value
toValue :: (JSON a, Generic a, GToValue (Rep a)) => a -> Value
encodeJSON :: JSON a => a -> Builder ()
encodeJSON :: (JSON a, Generic a, GEncodeJSON (Rep a)) => a -> Builder ()

-- | A JSON value represented as a Haskell value.
--   
--   The <tt>Object'</tt>s payload is a key-value vector instead of a map,
--   which parsed directly from JSON document. This design choice has
--   following advantages:
--   
--   <ul>
--   <li>Allow different strategies handling duplicated keys.</li>
--   <li>Allow different <tt>Map</tt> type to do further parsing, e.g.
--   <a>FlatMap</a></li>
--   <li>Roundtrip without touching the original key-value order.</li>
--   <li>Save time if constructing map is not neccessary, e.g. using a
--   linear scan to find a key if only that key is needed.</li>
--   </ul>
data Value
Object :: {-# UNPACK #-} !Vector (Text, Value) -> Value
Array :: {-# UNPACK #-} !Vector Value -> Value
String :: {-# UNPACK #-} !Text -> Value
Number :: {-# UNPACK #-} !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value

-- | <pre>
--   Settings T.pack T.pack False
--   </pre>
defaultSettings :: Settings

-- | Generic encode/decode Settings
--   
--   There should be no control characters in formatted texts since we
--   don't escaping those field names or constructor names
--   (<a>defaultSettings</a> relys on Haskell's lexical property).
--   Otherwise <a>encodeJSON</a> will output illegal JSON string.
data Settings
Settings :: (String -> Text) -> (String -> Text) -> Bool -> Settings

-- | format field labels
[fieldFmt] :: Settings -> String -> Text

-- | format constructor names
[constrFmt] :: Settings -> String -> Text

-- | take missing field as <a>Null</a>?
[missingKeyAsNull] :: Settings -> Bool
type DecodeError = Either ParseError ConvertError

-- | Decode a JSON bytes, return any trailing bytes.
decode :: JSON a => Bytes -> (Bytes, Either DecodeError a)

-- | Decode a JSON doc, only trailing JSON whitespace are allowed.
decode' :: JSON a => Bytes -> Either DecodeError a

-- | Decode a JSON text, return any trailing text.
decodeText :: JSON a => Text -> (Text, Either DecodeError a)

-- | Decode a JSON doc, only trailing JSON whitespace are allowed.
decodeText' :: JSON a => Text -> Either DecodeError a

-- | Type alias for a streaming parser, draw chunk from Monad m (with a
--   initial chunk), return result in <tt>Either err x</tt>.
type ParseChunks m chunk err x = m chunk -> chunk -> m (chunk, Either err x)

-- | Decode JSON doc chunks, return trailing bytes.
decodeChunks :: (JSON a, Monad m) => ParseChunks m Bytes DecodeError a

-- | Directly encode data to JSON bytes.
encode :: JSON a => a -> Bytes

-- | Encode data to JSON bytes chunks.
encodeChunks :: JSON a => a -> [Bytes]

-- | Text version <a>encode</a>.
encodeText :: JSON a => a -> Text

-- | Directly encode data to JSON bytes.
prettyJSON :: JSON a => a -> Builder ()

-- | 'ValuePretty'' with 4 spaces indentation per level, e.g.
--   
--   <pre>
--   {
--       "results":
--       [
--           {
--               "from_user_id_str":"80430860",
--               "profile_image_url":"<a>http://a2.twimg.com/profile_images/536455139/icon32_normal.png"</a>,
--               "created_at":"Wed, 26 Jan 2011 07:07:02 +0000",
--               "from_user":"kazu_yamamoto",
--               "id_str":"30159761706061824",
--               "metadata":
--               {
--                   "result_type":"recent"
--               },
--               "to_user_id":null,
--               "text":"Haskell Server Pages って、まだ続いていたのか！",
--               "id":30159761706061824,
--               "from_user_id":80430860,
--               "geo":null,
--               "iso_language_code":"no",
--               "to_user_id_str":null,
--               "source":"&amp;lt;a href=&amp;quot;http:/<i>twitter.com</i>&amp;quot;&amp;gt;web&amp;lt;/a&amp;gt;"
--           }
--       ],
--       "max_id":30159761706061824,
--       "since_id":0,
--       "refresh_url":"?since_id=30159761706061824&amp;q=haskell",
--       "next_page":"?page=2&amp;max_id=30159761706061824&amp;rpp=1&amp;q=haskell",
--       "results_per_page":1,
--       "page":1,
--       "completed_in":1.2606e-2,
--       "since_id_str":"0",
--       "max_id_str":"30159761706061824",
--       "query":"haskell"
--   }
--   </pre>
prettyValue :: Value -> Builder ()

-- | Parse <a>Value</a> without consuming trailing bytes.
parseValue :: Bytes -> (Bytes, Either ParseError Value)

-- | Parse <a>Value</a>, and consume all trailing JSON white spaces, if
--   there're bytes left, parsing will fail.
parseValue' :: Bytes -> Either ParseError Value

-- | Increamental parse <a>Value</a> without consuming trailing bytes.
parseValueChunks :: Monad m => ParseChunks m Bytes ParseError Value
gToValue :: GToValue f => Settings -> f a -> Value
gFromValue :: GFromValue f => Settings -> Value -> Converter (f a)
gEncodeJSON :: GEncodeJSON f => Settings -> f a -> Builder ()

-- | Run a <a>Converter</a> with input value.
convertValue :: JSON a => Value -> Either ConvertError a

-- | <a>Converter</a> provides a monadic interface to convert protocol IR
--   (e.g.<tt>Value</tt>) to Haskell ADT.
newtype Converter a
Converter :: (forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r) -> Converter a
[runConverter] :: Converter a -> forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r

-- | <a>Text</a> version of <a>fail</a>.
fail' :: Text -> Converter a

-- | Add (JSON) Path context to a converter
--   
--   When converting a complex structure, it helps to annotate
--   (sub)converters with context, so that if an error occurs, you can find
--   its location.
--   
--   <pre>
--   withFlatMapR "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age" &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a (JSON) Path
--   location of that error.
(<?>) :: Converter a -> PathElement -> Converter a
infixl 9 <?>

-- | Add context to a failure message, indicating the name of the structure
--   being converted.
--   
--   <pre>
--   prependContext "MyType" (fail "[error message]")
--   -- Error: "converting MyType failed, [error message]"
--   </pre>
prependContext :: Text -> Converter a -> Converter a

-- | Elements of a (JSON) Value path used to describe the location of an
--   error.
data PathElement

-- | Path element of a key into an object, "object.key".
Key :: {-# UNPACK #-} !Text -> PathElement

-- | Path element of an index into an array, "array[index]".
Index :: {-# UNPACK #-} !Int -> PathElement

-- | path of a embedded (JSON) String
Embedded :: PathElement

-- | Error info with (JSON) Path info.
data ConvertError
ConvertError :: [PathElement] -> Text -> ConvertError
[errPath] :: ConvertError -> [PathElement]
[errMsg] :: ConvertError -> Text

-- | Produce an error message like <tt>converting XXX failed, expected XXX,
--   encountered XXX</tt>.
typeMismatch :: Text -> Text -> Value -> Converter a
fromNull :: Text -> a -> Value -> Converter a
withBool :: Text -> (Bool -> Converter a) -> Value -> Converter a

-- | <tt><a>withScientific</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a> and
--   fails using <a>typeMismatch</a> otherwise.
--   
--   <i>Warning</i>: If you are converting from a scientific to an
--   unbounded type such as <a>Integer</a> you may want to add a
--   restriction on the size of the exponent (see
--   <a>withBoundedScientific</a>) to prevent malicious input from filling
--   up the memory of the target system.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withScientific "MyType" f (String "oops")
--   -- Error: "converting MyType failed, expected Number, but encountered String"
--   </pre>
withScientific :: Text -> (Scientific -> Converter a) -> Value -> Converter a

-- | <tt><a>withBoundedScientific</a> name f value</tt> applies <tt>f</tt>
--   to the <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a>
--   with exponent less than or equal to 1024.
withBoundedScientific :: Text -> (Scientific -> Converter a) -> Value -> Converter a

-- | @<a>withRealFloat</a> try to convert floating number with following
--   rules:
--   
--   <ul>
--   <li>Use <tt>±Infinity</tt> to represent out of range numbers.</li>
--   <li>Convert <tt>Null</tt> as <tt>NaN</tt></li>
--   </ul>
withRealFloat :: RealFloat a => Text -> (a -> Converter r) -> Value -> Converter r

-- | <tt><a>withBoundedScientific</a> name f value</tt> applies <tt>f</tt>
--   to the <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a>
--   and value is within <tt>minBound ~ maxBound</tt>.
withBoundedIntegral :: (Bounded a, Integral a) => Text -> (a -> Converter r) -> Value -> Converter r
withText :: Text -> (Text -> Converter a) -> Value -> Converter a
withArray :: Text -> (Vector Value -> Converter a) -> Value -> Converter a

-- | Directly use <a>Object</a> as key-values for further converting.
withKeyValues :: Text -> (Vector (Text, Value) -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'FM.FlatMap T.Text Value', on key
--   duplication prefer first one.
withFlatMap :: Text -> (FlatMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'FM.FlatMap T.Text Value', on key
--   duplication prefer last one.
withFlatMapR :: Text -> (FlatMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'HM.HashMap T.Text Value', on key
--   duplication prefer first one.
withHashMap :: Text -> (HashMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'HM.HashMap T.Text Value', on key
--   duplication prefer last one.
withHashMapR :: Text -> (HashMap Text Value -> Converter a) -> Value -> Converter a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: Text -> (Value -> Converter a) -> Value -> Converter a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>empty</a> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: JSON a => FlatMap Text Value -> Text -> Converter a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or fail if the value cannot be converted to the
--   desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: JSON a => FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or fail if the
--   value cannot be converted to the desired type.
--   
--   This differs from <a>.:?</a> by attempting to convert <a>Null</a> the
--   same as any other JSON value, instead of interpreting it as
--   <a>Nothing</a>.
(.:!) :: JSON a => FlatMap Text Value -> Text -> Converter (Maybe a)
convertField :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter a

-- | Variant of <a>.:?</a> with explicit converter function.
convertFieldMaybe :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Variant of <a>.:!</a> with explicit converter function.
convertFieldMaybe' :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Connect key and value to a tuple to be used with <a>object</a>.
(.=) :: JSON v => Text -> v -> (Text, Value)
infixr 8 .=

-- | Alias for <tt>Object . pack</tt>.
object :: [(Text, Value)] -> Value

-- | Connect key and value to a <a>KVItem</a> using <a>colon</a>, key will
--   be escaped.
(.!) :: JSON v => Text -> v -> KVItem
infixr 8 .!

-- | Add curly for comma connected <a>KVItem</a>s.
object' :: KVItem -> Builder ()

-- | A newtype for <a>Builder</a>, whose semigroup's instance is to connect
--   two builder with <a>comma</a>.
data KVItem

-- | Use <tt>:</tt> as separator to connect a label(no escape, only add
--   quotes) with field builders.
--   
--   Don't use chars which need escaped in label.
kv :: Text -> Builder () -> Builder ()

-- | Use <tt>:</tt> as separator to connect a label(escape the label and
--   add quotes) with field builders.
kv' :: Text -> Builder () -> Builder ()

-- | Escape text into JSON string and add double quotes, escaping rules:
--   
--   <pre>
--   '\b':  "\b"
--   '\f':  "\f"
--   '\n':  "\n"
--   '\r':  "\r"
--   '\t':  "\t"
--   '"':  "\""
--   '\':  "\\"
--   'DEL':  "\u007f"
--   other chars &lt;= 0x1F: "\u00XX"
--   </pre>
string :: Text -> Builder ()

-- | add <tt>{...}</tt> to original builder.
curly :: Builder () -> Builder ()

-- | add <tt>[...]</tt> to original builder.
square :: Builder () -> Builder ()

-- | Use <tt>,</tt> as separator to connect list of builders.
commaSepList :: JSON a => [a] -> Builder ()

-- | Use <tt>,</tt> as separator to connect a vector of builders.
commaSepVec :: (JSON a, Vec v a) => v a -> Builder ()
instance Z.Data.JSON.Base.GConstrFromValue GHC.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Z.Data.JSON.Base.GConstrFromValue f, Z.Data.JSON.Base.GConstrFromValue g) => Z.Data.JSON.Base.GConstrFromValue (f GHC.Generics.:+: g)
instance GHC.Generics.Constructor c => Z.Data.JSON.Base.GConstrFromValue (GHC.Generics.C1 c GHC.Generics.U1)
instance forall k (c :: GHC.Generics.Meta) (sc :: GHC.Generics.Meta) (f :: k -> *). (GHC.Generics.Constructor c, Z.Data.JSON.Base.GFromValue (GHC.Generics.S1 sc f)) => Z.Data.JSON.Base.GConstrFromValue (GHC.Generics.C1 c (GHC.Generics.S1 sc f))
instance (Z.Data.Generics.Utils.ProductSize (a GHC.Generics.:*: b), Z.Data.JSON.Base.GFromFields (a GHC.Generics.:*: b), Z.Data.JSON.Base.GBuildLookup (a GHC.Generics.:*: b), GHC.Generics.Constructor c) => Z.Data.JSON.Base.GConstrFromValue (GHC.Generics.C1 c (a GHC.Generics.:*: b))
instance forall k (f :: k -> *) (c :: GHC.Generics.Meta). Z.Data.JSON.Base.GConstrFromValue f => Z.Data.JSON.Base.GFromValue (GHC.Generics.D1 c f)
instance forall k (a :: k -> *) (b :: k -> *). (Z.Data.JSON.Base.GBuildLookup a, Z.Data.JSON.Base.GBuildLookup b) => Z.Data.JSON.Base.GBuildLookup (a GHC.Generics.:*: b)
instance forall k (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). Z.Data.JSON.Base.GBuildLookup (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). Z.Data.JSON.Base.GBuildLookup (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance (Z.Data.Generics.Utils.ProductSize a, Z.Data.JSON.Base.GFromFields a, Z.Data.JSON.Base.GFromFields b, Z.Data.JSON.Base.LookupTable a GHC.Types.~ Z.Data.JSON.Base.LookupTable b) => Z.Data.JSON.Base.GFromFields (a GHC.Generics.:*: b)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.JSON.Base.GFromValue f => Z.Data.JSON.Base.GFromFields (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.JSON.Base.GFromValue f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.JSON.Base.GFromFields (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.GToValue (GHC.Generics.K1 i a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.K1 i a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.GFromValue (GHC.Generics.K1 i a)
instance Z.Data.JSON.Base.JSON Z.Data.JSON.Value.Value
instance Z.Data.JSON.Base.JSON Z.Data.Text.Base.Text
instance Z.Data.JSON.Base.JSON Data.Scientific.Scientific
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Z.Data.Vector.FlatMap.FlatMap Z.Data.Text.Base.Text a)
instance (GHC.Classes.Ord a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Z.Data.Vector.FlatSet.FlatSet a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.HashMap.Internal.HashMap Z.Data.Text.Base.Text a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Map.Internal.Map Z.Data.Text.Base.Text a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Z.Data.Vector.FlatIntMap.FlatIntMap a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.IntMap.Internal.IntMap a)
instance Z.Data.JSON.Base.JSON Z.Data.Vector.FlatIntSet.FlatIntSet
instance Z.Data.JSON.Base.JSON Data.IntSet.Internal.IntSet
instance (GHC.Classes.Ord a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Data.Set.Internal.Set a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Sequence.Internal.Seq a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Tree.Tree a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Primitive.Array.Array a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Primitive.SmallArray.SmallArray a)
instance (Data.Primitive.Types.Prim a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Data.Primitive.PrimArray.PrimArray a)
instance Z.Data.JSON.Base.JSON Data.Primitive.ByteArray.ByteArray
instance (Z.Data.Array.UnliftedArray.PrimUnlifted a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Z.Data.Array.UnliftedArray.UnliftedArray a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Z.Data.Vector.Base.Vector a)
instance (Data.Primitive.Types.Prim a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Z.Data.Vector.Base.PrimVector a)
instance Z.Data.JSON.Base.JSON Z.Data.Vector.Base.Bytes
instance (GHC.Classes.Eq a, Data.Hashable.Class.Hashable a, Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Data.HashSet.Internal.HashSet a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON [a]
instance Z.Data.JSON.Base.JSON [GHC.Types.Char]
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (GHC.Base.NonEmpty a)
instance Z.Data.JSON.Base.JSON GHC.Types.Bool
instance Z.Data.JSON.Base.JSON GHC.Types.Char
instance Z.Data.JSON.Base.JSON GHC.Types.Double
instance Z.Data.JSON.Base.JSON GHC.Types.Float
instance Z.Data.JSON.Base.JSON GHC.Types.Int
instance Z.Data.JSON.Base.JSON GHC.Int.Int8
instance Z.Data.JSON.Base.JSON GHC.Int.Int16
instance Z.Data.JSON.Base.JSON GHC.Int.Int32
instance Z.Data.JSON.Base.JSON GHC.Int.Int64
instance Z.Data.JSON.Base.JSON GHC.Types.Word
instance Z.Data.JSON.Base.JSON GHC.Word.Word8
instance Z.Data.JSON.Base.JSON GHC.Word.Word16
instance Z.Data.JSON.Base.JSON GHC.Word.Word32
instance Z.Data.JSON.Base.JSON GHC.Word.Word64
instance Z.Data.JSON.Base.JSON GHC.Integer.Type.Integer
instance Z.Data.JSON.Base.JSON GHC.Natural.Natural
instance Z.Data.JSON.Base.JSON GHC.Types.Ordering
instance Z.Data.JSON.Base.JSON ()
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (GHC.Maybe.Maybe a)
instance (Z.Data.JSON.Base.JSON a, GHC.Real.Integral a) => Z.Data.JSON.Base.JSON (GHC.Real.Ratio a)
instance forall k (a :: k). Data.Fixed.HasResolution a => Z.Data.JSON.Base.JSON (Data.Fixed.Fixed a)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.JSON.Base.GFromValue f => Z.Data.JSON.Base.GFromValue (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.JSON.Base.GFromValue f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.JSON.Base.GFromValue (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance Z.Data.JSON.Base.GConstrEncodeJSON GHC.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Z.Data.JSON.Base.GConstrEncodeJSON f, Z.Data.JSON.Base.GConstrEncodeJSON g) => Z.Data.JSON.Base.GConstrEncodeJSON (f GHC.Generics.:+: g)
instance GHC.Generics.Constructor c => Z.Data.JSON.Base.GConstrEncodeJSON (GHC.Generics.C1 c GHC.Generics.U1)
instance forall k (c :: GHC.Generics.Meta) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). (GHC.Generics.Constructor c, Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)) => Z.Data.JSON.Base.GConstrEncodeJSON (GHC.Generics.C1 c (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f))
instance forall k (c :: GHC.Generics.Meta) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). (GHC.Generics.Constructor c, Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)) => Z.Data.JSON.Base.GConstrEncodeJSON (GHC.Generics.C1 c (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f))
instance (Z.Data.JSON.Base.GEncodeJSON (a GHC.Generics.:*: b), Z.Data.JSON.Base.GAddPunctuation (a GHC.Generics.:*: b), GHC.Generics.Constructor c) => Z.Data.JSON.Base.GConstrEncodeJSON (GHC.Generics.C1 c (a GHC.Generics.:*: b))
instance forall k (f :: k -> *) (c :: GHC.Generics.Meta). Z.Data.JSON.Base.GConstrEncodeJSON f => Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.D1 c f)
instance Z.Data.JSON.Base.GAddPunctuation a => Z.Data.JSON.Base.GAddPunctuation (a GHC.Generics.:*: b)
instance Z.Data.JSON.Base.GAddPunctuation (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance Z.Data.JSON.Base.GAddPunctuation (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.JSON.Base.GEncodeJSON f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.JSON.Base.GEncodeJSON f => Z.Data.JSON.Base.GEncodeJSON (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (a :: k -> *) (b :: k -> *). (Z.Data.JSON.Base.GEncodeJSON a, Z.Data.JSON.Base.GEncodeJSON b) => Z.Data.JSON.Base.GEncodeJSON (a GHC.Generics.:*: b)
instance Z.Data.JSON.Base.GConstrToValue GHC.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Z.Data.JSON.Base.GConstrToValue f, Z.Data.JSON.Base.GConstrToValue g) => Z.Data.JSON.Base.GConstrToValue (f GHC.Generics.:+: g)
instance GHC.Generics.Constructor c => Z.Data.JSON.Base.GConstrToValue (GHC.Generics.C1 c GHC.Generics.U1)
instance forall k (c :: GHC.Generics.Meta) (sc :: GHC.Generics.Meta) (f :: k -> *). (GHC.Generics.Constructor c, Z.Data.JSON.Base.GToValue (GHC.Generics.S1 sc f)) => Z.Data.JSON.Base.GConstrToValue (GHC.Generics.C1 c (GHC.Generics.S1 sc f))
instance (Z.Data.Generics.Utils.ProductSize (a GHC.Generics.:*: b), Z.Data.JSON.Base.GWriteFields (a GHC.Generics.:*: b), Z.Data.JSON.Base.GMergeFields (a GHC.Generics.:*: b), GHC.Generics.Constructor c) => Z.Data.JSON.Base.GConstrToValue (GHC.Generics.C1 c (a GHC.Generics.:*: b))
instance forall k (f :: k -> *) (c :: GHC.Generics.Meta). Z.Data.JSON.Base.GConstrToValue f => Z.Data.JSON.Base.GToValue (GHC.Generics.D1 c f)
instance forall k (a :: k -> *) (b :: k -> *). Z.Data.JSON.Base.GMergeFields a => Z.Data.JSON.Base.GMergeFields (a GHC.Generics.:*: b)
instance forall k (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). Z.Data.JSON.Base.GMergeFields (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness) (f :: k -> *). Z.Data.JSON.Base.GMergeFields (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance (Z.Data.Generics.Utils.ProductSize a, Z.Data.JSON.Base.GWriteFields a, Z.Data.JSON.Base.GWriteFields b, Z.Data.JSON.Base.Field a GHC.Types.~ Z.Data.JSON.Base.Field b) => Z.Data.JSON.Base.GWriteFields (a GHC.Generics.:*: b)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.JSON.Base.GToValue f => Z.Data.JSON.Base.GWriteFields (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.JSON.Base.GToValue f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.JSON.Base.GWriteFields (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance forall k (f :: k -> *) (l :: GHC.Types.Symbol) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). (Z.Data.JSON.Base.GToValue f, GHC.Generics.Selector ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds)) => Z.Data.JSON.Base.GToValue (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just l) u ss ds) f)
instance forall k (f :: k -> *) (u :: GHC.Generics.SourceUnpackedness) (ss :: GHC.Generics.SourceStrictness) (ds :: GHC.Generics.DecidedStrictness). Z.Data.JSON.Base.GToValue f => Z.Data.JSON.Base.GToValue (GHC.Generics.S1 ('GHC.Generics.MetaSel 'GHC.Maybe.Nothing u ss ds) f)
instance GHC.Base.Semigroup Z.Data.JSON.Base.KVItem


-- | Types and functions for working efficiently with JSON data, the design
--   is quite similar to <tt>aeson</tt> or <tt>json</tt>:
--   
--   <ul>
--   <li>Encode to bytes can be done directly via <a>encodeJSON</a>.</li>
--   <li>Decode are split in two step, first we parse JSON doc into
--   <a>Value</a>, then convert to haskell data via <a>fromValue</a>.</li>
--   <li><tt>ToValue</tt> are provided so that other doc formats can be
--   easily supported, such as <tt>YAML</tt>.</li>
--   </ul>
--   
--   Note this module also provides many (orphan)instances to reduce the
--   compilation stress of a gaint <a>Base</a> module.
module Z.Data.JSON

-- | Type class for encode &amp; decode JSON.
class JSON a
fromValue :: JSON a => Value -> Converter a
fromValue :: (JSON a, Generic a, GFromValue (Rep a)) => Value -> Converter a
toValue :: JSON a => a -> Value
toValue :: (JSON a, Generic a, GToValue (Rep a)) => a -> Value
encodeJSON :: JSON a => a -> Builder ()
encodeJSON :: (JSON a, Generic a, GEncodeJSON (Rep a)) => a -> Builder ()

-- | A JSON value represented as a Haskell value.
--   
--   The <tt>Object'</tt>s payload is a key-value vector instead of a map,
--   which parsed directly from JSON document. This design choice has
--   following advantages:
--   
--   <ul>
--   <li>Allow different strategies handling duplicated keys.</li>
--   <li>Allow different <tt>Map</tt> type to do further parsing, e.g.
--   <a>FlatMap</a></li>
--   <li>Roundtrip without touching the original key-value order.</li>
--   <li>Save time if constructing map is not neccessary, e.g. using a
--   linear scan to find a key if only that key is needed.</li>
--   </ul>
data Value
Object :: {-# UNPACK #-} !Vector (Text, Value) -> Value
Array :: {-# UNPACK #-} !Vector Value -> Value
String :: {-# UNPACK #-} !Text -> Value
Number :: {-# UNPACK #-} !Scientific -> Value
Bool :: !Bool -> Value
Null :: Value

-- | <pre>
--   Settings T.pack T.pack False
--   </pre>
defaultSettings :: Settings

-- | Generic encode/decode Settings
--   
--   There should be no control characters in formatted texts since we
--   don't escaping those field names or constructor names
--   (<a>defaultSettings</a> relys on Haskell's lexical property).
--   Otherwise <a>encodeJSON</a> will output illegal JSON string.
data Settings
Settings :: (String -> Text) -> (String -> Text) -> Bool -> Settings

-- | format field labels
[fieldFmt] :: Settings -> String -> Text

-- | format constructor names
[constrFmt] :: Settings -> String -> Text

-- | take missing field as <a>Null</a>?
[missingKeyAsNull] :: Settings -> Bool

-- | Snake casing a pascal cased constructor name or camel cased field
--   name, words are always lower cased and separated by an underscore.
snakeCase :: String -> Text

-- | Train casing a pascal cased constructor name or camel cased field
--   name, words are always lower cased and separated by a hyphen.
trainCase :: String -> Text
type DecodeError = Either ParseError ConvertError

-- | Decode a JSON bytes, return any trailing bytes.
decode :: JSON a => Bytes -> (Bytes, Either DecodeError a)

-- | Decode a JSON doc, only trailing JSON whitespace are allowed.
decode' :: JSON a => Bytes -> Either DecodeError a

-- | Decode a JSON text, return any trailing text.
decodeText :: JSON a => Text -> (Text, Either DecodeError a)

-- | Decode a JSON doc, only trailing JSON whitespace are allowed.
decodeText' :: JSON a => Text -> Either DecodeError a

-- | Type alias for a streaming parser, draw chunk from Monad m (with a
--   initial chunk), return result in <tt>Either err x</tt>.
type ParseChunks m chunk err x = m chunk -> chunk -> m (chunk, Either err x)

-- | Decode JSON doc chunks, return trailing bytes.
decodeChunks :: (JSON a, Monad m) => ParseChunks m Bytes DecodeError a

-- | Directly encode data to JSON bytes.
encode :: JSON a => a -> Bytes

-- | Encode data to JSON bytes chunks.
encodeChunks :: JSON a => a -> [Bytes]

-- | Text version <a>encode</a>.
encodeText :: JSON a => a -> Text

-- | Directly encode data to JSON bytes.
prettyJSON :: JSON a => a -> Builder ()

-- | 'ValuePretty'' with 4 spaces indentation per level, e.g.
--   
--   <pre>
--   {
--       "results":
--       [
--           {
--               "from_user_id_str":"80430860",
--               "profile_image_url":"<a>http://a2.twimg.com/profile_images/536455139/icon32_normal.png"</a>,
--               "created_at":"Wed, 26 Jan 2011 07:07:02 +0000",
--               "from_user":"kazu_yamamoto",
--               "id_str":"30159761706061824",
--               "metadata":
--               {
--                   "result_type":"recent"
--               },
--               "to_user_id":null,
--               "text":"Haskell Server Pages って、まだ続いていたのか！",
--               "id":30159761706061824,
--               "from_user_id":80430860,
--               "geo":null,
--               "iso_language_code":"no",
--               "to_user_id_str":null,
--               "source":"&amp;lt;a href=&amp;quot;http:/<i>twitter.com</i>&amp;quot;&amp;gt;web&amp;lt;/a&amp;gt;"
--           }
--       ],
--       "max_id":30159761706061824,
--       "since_id":0,
--       "refresh_url":"?since_id=30159761706061824&amp;q=haskell",
--       "next_page":"?page=2&amp;max_id=30159761706061824&amp;rpp=1&amp;q=haskell",
--       "results_per_page":1,
--       "page":1,
--       "completed_in":1.2606e-2,
--       "since_id_str":"0",
--       "max_id_str":"30159761706061824",
--       "query":"haskell"
--   }
--   </pre>
prettyValue :: Value -> Builder ()

-- | Parse <a>Value</a> without consuming trailing bytes.
parseValue :: Bytes -> (Bytes, Either ParseError Value)

-- | Parse <a>Value</a>, and consume all trailing JSON white spaces, if
--   there're bytes left, parsing will fail.
parseValue' :: Bytes -> Either ParseError Value

-- | Increamental parse <a>Value</a> without consuming trailing bytes.
parseValueChunks :: Monad m => ParseChunks m Bytes ParseError Value
gToValue :: GToValue f => Settings -> f a -> Value
gFromValue :: GFromValue f => Settings -> Value -> Converter (f a)
gEncodeJSON :: GEncodeJSON f => Settings -> f a -> Builder ()

-- | Run a <a>Converter</a> with input value.
convertValue :: JSON a => Value -> Either ConvertError a

-- | <a>Converter</a> provides a monadic interface to convert protocol IR
--   (e.g.<tt>Value</tt>) to Haskell ADT.
newtype Converter a
Converter :: (forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r) -> Converter a
[runConverter] :: Converter a -> forall r. ([PathElement] -> Text -> r) -> (a -> r) -> r

-- | <a>Text</a> version of <a>fail</a>.
fail' :: Text -> Converter a

-- | Add (JSON) Path context to a converter
--   
--   When converting a complex structure, it helps to annotate
--   (sub)converters with context, so that if an error occurs, you can find
--   its location.
--   
--   <pre>
--   withFlatMapR "Person" $ \o -&gt;
--     Person
--       &lt;$&gt; o .: "name" &lt;?&gt; Key "name"
--       &lt;*&gt; o .: "age" &lt;?&gt; Key "age"
--   </pre>
--   
--   (Standard methods like <tt>(.:)</tt> already do this.)
--   
--   With such annotations, if an error occurs, you will get a (JSON) Path
--   location of that error.
(<?>) :: Converter a -> PathElement -> Converter a
infixl 9 <?>

-- | Add context to a failure message, indicating the name of the structure
--   being converted.
--   
--   <pre>
--   prependContext "MyType" (fail "[error message]")
--   -- Error: "converting MyType failed, [error message]"
--   </pre>
prependContext :: Text -> Converter a -> Converter a

-- | Elements of a (JSON) Value path used to describe the location of an
--   error.
data PathElement

-- | Path element of a key into an object, "object.key".
Key :: {-# UNPACK #-} !Text -> PathElement

-- | Path element of an index into an array, "array[index]".
Index :: {-# UNPACK #-} !Int -> PathElement

-- | path of a embedded (JSON) String
Embedded :: PathElement

-- | Error info with (JSON) Path info.
data ConvertError
ConvertError :: [PathElement] -> Text -> ConvertError
[errPath] :: ConvertError -> [PathElement]
[errMsg] :: ConvertError -> Text

-- | Produce an error message like <tt>converting XXX failed, expected XXX,
--   encountered XXX</tt>.
typeMismatch :: Text -> Text -> Value -> Converter a
fromNull :: Text -> a -> Value -> Converter a
withBool :: Text -> (Bool -> Converter a) -> Value -> Converter a

-- | <tt><a>withScientific</a> name f value</tt> applies <tt>f</tt> to the
--   <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a> and
--   fails using <a>typeMismatch</a> otherwise.
--   
--   <i>Warning</i>: If you are converting from a scientific to an
--   unbounded type such as <a>Integer</a> you may want to add a
--   restriction on the size of the exponent (see
--   <a>withBoundedScientific</a>) to prevent malicious input from filling
--   up the memory of the target system.
--   
--   <h4>Error message example</h4>
--   
--   <pre>
--   withScientific "MyType" f (String "oops")
--   -- Error: "converting MyType failed, expected Number, but encountered String"
--   </pre>
withScientific :: Text -> (Scientific -> Converter a) -> Value -> Converter a

-- | <tt><a>withBoundedScientific</a> name f value</tt> applies <tt>f</tt>
--   to the <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a>
--   with exponent less than or equal to 1024.
withBoundedScientific :: Text -> (Scientific -> Converter a) -> Value -> Converter a

-- | @<a>withRealFloat</a> try to convert floating number with following
--   rules:
--   
--   <ul>
--   <li>Use <tt>±Infinity</tt> to represent out of range numbers.</li>
--   <li>Convert <tt>Null</tt> as <tt>NaN</tt></li>
--   </ul>
withRealFloat :: RealFloat a => Text -> (a -> Converter r) -> Value -> Converter r

-- | <tt><a>withBoundedScientific</a> name f value</tt> applies <tt>f</tt>
--   to the <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a>
--   and value is within <tt>minBound ~ maxBound</tt>.
withBoundedIntegral :: (Bounded a, Integral a) => Text -> (a -> Converter r) -> Value -> Converter r
withText :: Text -> (Text -> Converter a) -> Value -> Converter a
withArray :: Text -> (Vector Value -> Converter a) -> Value -> Converter a

-- | Directly use <a>Object</a> as key-values for further converting.
withKeyValues :: Text -> (Vector (Text, Value) -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'FM.FlatMap T.Text Value', on key
--   duplication prefer first one.
withFlatMap :: Text -> (FlatMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'FM.FlatMap T.Text Value', on key
--   duplication prefer last one.
withFlatMapR :: Text -> (FlatMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'HM.HashMap T.Text Value', on key
--   duplication prefer first one.
withHashMap :: Text -> (HashMap Text Value -> Converter a) -> Value -> Converter a

-- | Take a <a>Object</a> as an 'HM.HashMap T.Text Value', on key
--   duplication prefer last one.
withHashMapR :: Text -> (HashMap Text Value -> Converter a) -> Value -> Converter a

-- | Decode a nested JSON-encoded string.
withEmbeddedJSON :: Text -> (Value -> Converter a) -> Value -> Converter a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>empty</a> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: JSON a => FlatMap Text Value -> Text -> Converter a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or fail if the value cannot be converted to the
--   desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: JSON a => FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or fail if the
--   value cannot be converted to the desired type.
--   
--   This differs from <a>.:?</a> by attempting to convert <a>Null</a> the
--   same as any other JSON value, instead of interpreting it as
--   <a>Nothing</a>.
(.:!) :: JSON a => FlatMap Text Value -> Text -> Converter (Maybe a)
convertField :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter a

-- | Variant of <a>.:?</a> with explicit converter function.
convertFieldMaybe :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Variant of <a>.:!</a> with explicit converter function.
convertFieldMaybe' :: (Value -> Converter a) -> FlatMap Text Value -> Text -> Converter (Maybe a)

-- | Connect key and value to a tuple to be used with <a>object</a>.
(.=) :: JSON v => Text -> v -> (Text, Value)
infixr 8 .=

-- | Alias for <tt>Object . pack</tt>.
object :: [(Text, Value)] -> Value

-- | Connect key and value to a <a>KVItem</a> using <a>colon</a>, key will
--   be escaped.
(.!) :: JSON v => Text -> v -> KVItem
infixr 8 .!

-- | Add curly for comma connected <a>KVItem</a>s.
object' :: KVItem -> Builder ()

-- | A newtype for <a>Builder</a>, whose semigroup's instance is to connect
--   two builder with <a>comma</a>.
data KVItem
instance forall k k1 (f :: k -> *) (g :: k1 -> k) (a :: k1). Z.Data.JSON.Base.JSON (f (g a)) => Z.Data.JSON.Base.JSON (Data.Functor.Compose.Compose f g a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.Min a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.Max a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.First a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.Last a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.WrappedMonoid a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Semigroup.Internal.Dual a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Monoid.First a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Monoid.Last a)
instance Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Functor.Identity.Identity a)
instance forall k a (b :: k). Z.Data.JSON.Base.JSON a => Z.Data.JSON.Base.JSON (Data.Functor.Const.Const a b)
instance forall k b (a :: k). Z.Data.JSON.Base.JSON b => Z.Data.JSON.Base.JSON (Data.Tagged.Tagged a b)
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CChar
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CSChar
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUChar
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CShort
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUShort
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CInt
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUInt
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CLong
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CULong
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CPtrdiff
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CSize
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CWchar
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CSigAtomic
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CLLong
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CULLong
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CBool
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CIntPtr
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUIntPtr
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CIntMax
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUIntMax
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CClock
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CTime
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CUSeconds
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CSUSeconds
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CFloat
instance Z.Data.JSON.Base.JSON Foreign.C.Types.CDouble
instance (Z.Data.JSON.Base.JSON (f a), Z.Data.JSON.Base.JSON (g a), Z.Data.JSON.Base.JSON a) => Z.Data.JSON.Base.JSON (Data.Functor.Sum.Sum f g a)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b) => Z.Data.JSON.Base.JSON (Data.Either.Either a b)
instance forall k (f :: k -> *) (a :: k) (g :: k -> *). (Z.Data.JSON.Base.JSON (f a), Z.Data.JSON.Base.JSON (g a)) => Z.Data.JSON.Base.JSON (Data.Functor.Product.Product f g a)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b) => Z.Data.JSON.Base.JSON (a, b)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b, Z.Data.JSON.Base.JSON c) => Z.Data.JSON.Base.JSON (a, b, c)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b, Z.Data.JSON.Base.JSON c, Z.Data.JSON.Base.JSON d) => Z.Data.JSON.Base.JSON (a, b, c, d)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b, Z.Data.JSON.Base.JSON c, Z.Data.JSON.Base.JSON d, Z.Data.JSON.Base.JSON e) => Z.Data.JSON.Base.JSON (a, b, c, d, e)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b, Z.Data.JSON.Base.JSON c, Z.Data.JSON.Base.JSON d, Z.Data.JSON.Base.JSON e, Z.Data.JSON.Base.JSON f) => Z.Data.JSON.Base.JSON (a, b, c, d, e, f)
instance (Z.Data.JSON.Base.JSON a, Z.Data.JSON.Base.JSON b, Z.Data.JSON.Base.JSON c, Z.Data.JSON.Base.JSON d, Z.Data.JSON.Base.JSON e, Z.Data.JSON.Base.JSON f, Z.Data.JSON.Base.JSON g) => Z.Data.JSON.Base.JSON (a, b, c, d, e, f, g)
instance Z.Data.JSON.Base.JSON GHC.IO.Exception.ExitCode
instance Z.Data.JSON.Base.JSON Data.Version.Version
instance Z.Data.JSON.Base.JSON Data.Time.Clock.Internal.UTCTime.UTCTime
instance Z.Data.JSON.Base.JSON Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Z.Data.JSON.Base.JSON Data.Time.Calendar.Days.Day
instance Z.Data.JSON.Base.JSON Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Z.Data.JSON.Base.JSON Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Z.Data.JSON.Base.JSON Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Z.Data.JSON.Base.JSON Data.Time.Clock.Internal.DiffTime.DiffTime
instance Z.Data.JSON.Base.JSON Data.Time.Clock.Internal.SystemTime.SystemTime
instance Z.Data.JSON.Base.JSON Data.Time.LocalTime.Internal.CalendarDiffTime.CalendarDiffTime
instance Z.Data.JSON.Base.JSON Data.Time.Calendar.CalendarDiffDays.CalendarDiffDays
instance Z.Data.JSON.Base.JSON Data.Time.Calendar.Week.DayOfWeek
instance forall k (a :: k). Z.Data.JSON.Base.JSON (Data.Proxy.Proxy a)


-- | This module provides hex encoding &amp; decoding tools, as well as
--   <a>HexBytes</a> newtype with hex textual instances.
module Z.Data.Vector.Hex

-- | New type wrapper for <a>Bytes</a> with hex encoding(uppercase)
--   Show/JSON instances.
newtype HexBytes
HexBytes :: Bytes -> HexBytes
[unHexBytes] :: HexBytes -> Bytes

-- | Encode <a>Bytes</a> using hex(base16) encoding.
hexEncode :: Bool -> Bytes -> Bytes

-- | Text version of <a>hexEncode</a>.
hexEncodeText :: Bool -> Bytes -> Text

-- | <a>Builder</a> version of <a>hexEncode</a>.
hexEncodeBuilder :: Bool -> Bytes -> Builder ()

-- | Decode a hex encoding string, return Nothing on illegal bytes or
--   incomplete input.
hexDecode :: Bytes -> Maybe Bytes

-- | Decode a hex encoding string, throw <a>HexDecodeException</a> on
--   error.
hexDecode' :: HasCallStack => Bytes -> Bytes

-- | Exception during hex decoding.
data HexDecodeException
IllegalHexBytes :: Bytes -> CallStack -> HexDecodeException
IncompleteHexBytes :: Bytes -> CallStack -> HexDecodeException
hs_hex_encode :: MBA# Word8 -> Int -> BA# Word8 -> Int -> Int -> IO ()
hs_hex_encode_upper :: MBA# Word8 -> Int -> BA# Word8 -> Int -> Int -> IO ()
hs_hex_decode :: MBA# Word8 -> BA# Word8 -> Int -> Int -> IO Int
instance Data.Hashable.Class.Hashable Z.Data.Vector.Hex.HexBytes
instance GHC.Base.Semigroup Z.Data.Vector.Hex.HexBytes
instance GHC.Base.Monoid Z.Data.Vector.Hex.HexBytes
instance GHC.Classes.Ord Z.Data.Vector.Hex.HexBytes
instance GHC.Classes.Eq Z.Data.Vector.Hex.HexBytes
instance GHC.Show.Show Z.Data.Vector.Hex.HexDecodeException
instance GHC.Exception.Type.Exception Z.Data.Vector.Hex.HexDecodeException
instance GHC.Show.Show Z.Data.Vector.Hex.HexBytes
instance Z.Data.Text.Print.Print Z.Data.Vector.Hex.HexBytes
instance Z.Data.JSON.Base.JSON Z.Data.Vector.Hex.HexBytes


-- | This module provides <a>CBytes</a> with some useful instances / tools
--   for retrieving, storing or processing short byte sequences, such as
--   file path, environment variables, etc.
module Z.Data.CBytes

-- | A efficient wrapper for short immutable null-terminated byte sequences
--   which can be automatically freed by ghc garbage collector.
--   
--   The main use case of this type is to ease the bridging of C FFI APIs,
--   since most of the unix APIs use null-terminated string. On windows
--   you're encouraged to use a compatibility layer like
--   'WideCharToMultiByte/MultiByteToWideChar' and keep the same interface,
--   e.g. libuv do this when deal with file paths.
--   
--   <a>CBytes</a> don't support O(1) slicing, it's not suitable to use it
--   to store large byte chunk, If you need advance editing, convert
--   <a>CBytes</a> to/from <a>Bytes</a> with <a>CB</a> pattern or
--   <a>toBytes</a> / <a>fromBytes</a>, then use vector combinators.
--   
--   When textual represatation is needed e.g. converting to <a>String</a>,
--   <a>Text</a>, <a>Show</a> instance, etc., we assume <a>CBytes</a> using
--   UTF-8 encodings, <a>CBytes</a> can be used with
--   <tt>OverloadedString</tt>, literal encoding is UTF-8 with some
--   modifications: <tt>\NUL</tt> is encoded to 'C0 80', and
--   <tt>\xD800</tt> ~ <tt>\xDFFF</tt> is encoded as a three bytes normal
--   utf-8 codepoint.
--   
--   Note most of the unix API is not unicode awared though, you may find a
--   <tt>scandir</tt> call return a filename which is not proper encoded in
--   any unicode encoding at all. But still, UTF-8 is recommanded to be
--   used when text represatation is needed.
data CBytes

-- | Use this pattern to match or construct <a>CBytes</a>, result will be
--   trimmed down to first <tt>\NUL</tt> byte if there's any.
pattern CB :: Bytes -> CBytes

-- | Convert to a <tt>\NUL</tt> terminated <a>PrimArray</a>,
--   
--   There's an invariance that this array never contains extra
--   <tt>\NUL</tt> except terminator.
rawPrimArray :: CBytes -> PrimArray Word8

-- | Constuctor a <a>CBytes</a> from arbitrary array, result will be
--   trimmed down to first <tt>\NUL</tt> byte if there's any.
fromPrimArray :: PrimArray Word8 -> CBytes

-- | <i>O(1)</i>, convert to <a>Bytes</a>, which can be processed by vector
--   combinators.
toBytes :: CBytes -> Bytes

-- | <i>O(n)</i>, convert from <a>Bytes</a>
--   
--   Result will be trimmed down to first <tt>\NUL</tt> byte if there's
--   any.
fromBytes :: Bytes -> CBytes

-- | <i>O(n)</i>, convert to <a>Text</a> using UTF8 encoding assumption.
--   
--   Throw <a>InvalidUTF8Exception</a> in case of invalid codepoint.
toText :: HasCallStack => CBytes -> Text

-- | <i>O(n)</i>, convert to <a>Text</a> using UTF8 encoding assumption.
--   
--   Return <a>Nothing</a> in case of invalid codepoint.
toTextMaybe :: CBytes -> Maybe Text

-- | <i>O(n)</i>, convert from <a>Text</a>,
--   
--   Result will be trimmed down to first <tt>\NUL</tt> byte if there's
--   any.
fromText :: Text -> CBytes

-- | Write <a>CBytes</a> 's byte sequence to buffer.
--   
--   This function is different from <a>Print</a> instance in that it
--   directly write byte sequence without checking if it's UTF8 encoded.
toBuilder :: CBytes -> Builder ()

-- | Build a <a>CBytes</a> with builder, result will be trimmed down to
--   first <tt>\NUL</tt> byte if there's any.
buildCBytes :: Builder a -> CBytes

-- | Pack a <a>String</a> into <a>CBytes</a>.
--   
--   <tt>\NUL</tt> is encoded as two bytes <tt>C0 80</tt> , <tt>\xD800</tt>
--   ~ <tt>\xDFFF</tt> is encoded as a three bytes normal UTF-8 codepoint.
pack :: String -> CBytes

-- | <i>O(n)</i> Convert cbytes to a char list using UTF8 encoding
--   assumption.
--   
--   This function is much tolerant than <a>toText</a>, it simply decoding
--   codepoints using UTF8 <a>decodeChar</a> without checking errors such
--   as overlong or invalid range.
--   
--   Unpacking is done lazily. i.e. we will retain reference to the array
--   until all element are consumed.
--   
--   This function is a <i>good producer</i> in the sense of build/foldr
--   fusion.
unpack :: CBytes -> String

-- | Return <a>True</a> if <a>CBytes</a> is empty.
null :: CBytes -> Bool

-- | <i>O(1)</i>, Return the BTYE length of <a>CBytes</a>.
length :: CBytes -> Int

-- | Empty <a>CBytes</a>
empty :: CBytes

-- | Singleton <a>CBytes</a>.
singleton :: Word8 -> CBytes

-- | Concatenate two <a>CBytes</a>.
append :: CBytes -> CBytes -> CBytes

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

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

-- | <i>O(n)</i> An efficient way to join <tt>CByte</tt> s with a byte.
--   
--   Intercalate bytes list with <tt>\NUL</tt> will effectively leave the
--   first bytes in the list.
intercalateElem :: Word8 -> [CBytes] -> CBytes

-- | Copy a <a>CString</a> type into a <a>CBytes</a>, return <a>empty</a>
--   if the pointer is NULL.
--   
--   After copying you're free to free the <a>CString</a> 's memory.
fromCString :: CString -> IO CBytes

-- | Same with <a>fromCString</a>, but only take at most N bytes.
--   
--   Result will be trimmed down to first <tt>\NUL</tt> byte if there's
--   any.
fromCStringN :: CString -> Int -> IO CBytes

-- | Run FFI in bracket and marshall <tt>std::string*</tt> result into
--   <a>CBytes</a>, memory pointed by <tt>std::string*</tt> will be
--   <tt>delete</tt> ed.
fromStdString :: IO (Ptr StdString) -> IO CBytes

-- | Pass <a>CBytes</a> to foreign function as a <tt>const char*</tt>.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withCBytesUnsafe :: CBytes -> (BA# Word8 -> IO a) -> IO a

-- | Pass <a>CBytes</a> to foreign function as a <tt>const char*</tt>.
--   
--   Don't pass a forever loop to this function, see <a>#14346</a>.
withCBytes :: CBytes -> (Ptr Word8 -> IO a) -> IO a

-- | Create a <a>CBytes</a> with IO action.
--   
--   If (&lt;=0) capacity is provided, a pointer pointing to <tt>\NUL</tt>
--   is passed to initialize function and <a>empty</a> will be returned.
--   This behavior is different from <a>allocCBytes</a>, which may cause
--   trouble for some FFI functions.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
allocCBytesUnsafe :: HasCallStack => Int -> (MBA# Word8 -> IO a) -> IO (CBytes, a)

-- | Create a <a>CBytes</a> with IO action.
--   
--   If (&lt;=0) capacity is provided, a <a>nullPtr</a> is passed to
--   initialize function and <a>empty</a> will be returned. Other than
--   that, User have to make sure a <tt>\NUL</tt> ternimated string will be
--   written.
allocCBytes :: HasCallStack => Int -> (CString -> IO a) -> IO (CBytes, a)

-- | Pass <a>CBytes</a> list to foreign function as a
--   <tt>StgArrBytes**</tt>.
--   
--   Enable <tt>UnliftedFFITypes</tt> extension in your haskell code, use
--   <tt>StgArrBytes**</tt>(&gt;=8.10) or <tt>StgMutArrPtrs*</tt>(&lt;8.10)
--   pointer type and <tt>HsInt</tt> to marshall <tt>BAArray#</tt> and
--   <tt>Int</tt> arguments on C side, check the example with
--   <a>BAArray#</a>.
--   
--   USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.
withCBytesListUnsafe :: [CBytes] -> (BAArray# Word8 -> Int -> IO a) -> IO a

-- | Pass <a>CBytes</a> list to foreign function as a <tt>const
--   char**</tt>.
--   
--   Check <a>Z.Foreign</a> module for more detail on how to marshall
--   params in C side.
withCBytesList :: [CBytes] -> (Ptr (Ptr Word8) -> Int -> IO a) -> IO a

-- | Poke <a>CBytes</a> with \NUL terminator.
pokeMBACBytes :: MBA# Word8 -> Int -> CBytes -> IO ()

-- | Poke <a>CBytes</a> until a \NUL terminator(or to the end of the array
--   if there's none).
peekMBACBytes :: MBA# Word8 -> Int -> IO CBytes
indexBACBytes :: BA# Word8 -> Int -> CBytes

-- | A C string is a reference to an array of C characters terminated by
--   NUL.
type CString = Ptr CChar
instance GHC.Show.Show Z.Data.CBytes.CBytes
instance GHC.Read.Read Z.Data.CBytes.CBytes
instance Control.DeepSeq.NFData Z.Data.CBytes.CBytes
instance GHC.Classes.Eq Z.Data.CBytes.CBytes
instance GHC.Classes.Ord Z.Data.CBytes.CBytes
instance GHC.Base.Semigroup Z.Data.CBytes.CBytes
instance GHC.Base.Monoid Z.Data.CBytes.CBytes
instance Data.Hashable.Class.Hashable Z.Data.CBytes.CBytes
instance Test.QuickCheck.Arbitrary.Arbitrary Z.Data.CBytes.CBytes
instance Test.QuickCheck.Arbitrary.CoArbitrary Z.Data.CBytes.CBytes
instance Z.Data.Text.Print.Print Z.Data.CBytes.CBytes
instance Z.Data.JSON.Base.JSON Z.Data.CBytes.CBytes
instance Data.String.IsString Z.Data.CBytes.CBytes