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


-- | Slicing managed and unmanaged memory
--   
--   This library provides types that allow the user to talk about a slice
--   of a ByteArray or a MutableByteArray. It also offers UnmanagedBytes,
--   which is kind of like a slice into unmanaged memory. However, it is
--   just an address and a length.
@package byteslice
@version 0.2.0.0

module Data.Bytes.Types

-- | A slice of a <a>ByteArray</a>.
data Bytes
Bytes :: {-# UNPACK #-} !ByteArray -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Bytes
[$sel:array:Bytes] :: Bytes -> {-# UNPACK #-} !ByteArray
[$sel:offset:Bytes] :: Bytes -> {-# UNPACK #-} !Int
[$sel:length:Bytes] :: Bytes -> {-# UNPACK #-} !Int

-- | A slice of a <a>MutableByteArray</a>.
data MutableBytes s
MutableBytes :: {-# UNPACK #-} !MutableByteArray s -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> MutableBytes s
[$sel:array:MutableBytes] :: MutableBytes s -> {-# UNPACK #-} !MutableByteArray s
[$sel:offset:MutableBytes] :: MutableBytes s -> {-# UNPACK #-} !Int
[$sel:length:MutableBytes] :: MutableBytes s -> {-# UNPACK #-} !Int

-- | A slice of unmanaged memory.
data UnmanagedBytes
UnmanagedBytes :: {-# UNPACK #-} !Addr -> {-# UNPACK #-} !Int -> UnmanagedBytes
[$sel:address:UnmanagedBytes] :: UnmanagedBytes -> {-# UNPACK #-} !Addr
[$sel:length:UnmanagedBytes] :: UnmanagedBytes -> {-# UNPACK #-} !Int
instance GHC.Exts.IsList Data.Bytes.Types.Bytes
instance GHC.Show.Show Data.Bytes.Types.Bytes
instance GHC.Classes.Eq Data.Bytes.Types.Bytes
instance GHC.Classes.Ord Data.Bytes.Types.Bytes
instance GHC.Base.Semigroup Data.Bytes.Types.Bytes
instance GHC.Base.Monoid Data.Bytes.Types.Bytes

module Data.Bytes.Mutable

-- | A slice of a <a>MutableByteArray</a>.
data MutableBytes s

-- | Take bytes while the predicate is true, aliasing the argument array.
takeWhile :: PrimMonad m => (Word8 -> m Bool) -> MutableBytes (PrimState m) -> m (MutableBytes (PrimState m))

-- | Drop bytes while the predicate is true, aliasing the argument array.
dropWhile :: PrimMonad m => (Word8 -> m Bool) -> MutableBytes (PrimState m) -> m (MutableBytes (PrimState m))

-- | Take the first <tt>n</tt> bytes from the argument, aliasing it.
unsafeTake :: Int -> MutableBytes s -> MutableBytes s

-- | Drop the first <tt>n</tt> bytes from the argument, aliasing it. The
--   new length will be <tt>len - n</tt>.
unsafeDrop :: Int -> MutableBytes s -> MutableBytes s

-- | Create a slice of <a>MutableBytes</a> that spans the entire argument
--   array. This aliases the argument.
fromMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m (MutableBytes (PrimState m))

module Data.Bytes

-- | A slice of a <a>ByteArray</a>.
data Bytes

-- | The empty byte sequence.
empty :: Bytes

-- | Is the byte sequence empty?
null :: Bytes -> Bool

-- | The length of a slice of bytes.
length :: Bytes -> Int

-- | Extract the head and tail of the <a>Bytes</a>, returning
--   <a>Nothing</a> if it is empty.
uncons :: Bytes -> Maybe (Word8, Bytes)

-- | Extract the <tt>init</tt> and <tt>last</tt> of the <a>Bytes</a>,
--   returning <a>Nothing</a> if it is empty.
unsnoc :: Bytes -> Maybe (Bytes, Word8)

-- | Create a byte sequence with one byte.
singleton :: Word8 -> Bytes

-- | Create a byte sequence with two bytes.
doubleton :: Word8 -> Word8 -> Bytes

-- | Create a byte sequence with three bytes.
tripleton :: Word8 -> Word8 -> Word8 -> Bytes

-- | Replicate a byte <tt>n</tt> times.
replicate :: Int -> Word8 -> Bytes

-- | Create an unsliced byte sequence with one byte.
singletonU :: Word8 -> ByteArray

-- | Create an unsliced byte sequence with two bytes.
doubletonU :: Word8 -> Word8 -> ByteArray

-- | Create an unsliced byte sequence with three bytes.
tripletonU :: Word8 -> Word8 -> Word8 -> ByteArray

-- | Variant of <a>replicate</a> that returns a unsliced byte array.
replicateU :: Int -> Word8 -> ByteArray

-- | Take bytes while the predicate is true.
takeWhile :: (Word8 -> Bool) -> Bytes -> Bytes

-- | Drop bytes while the predicate is true.
dropWhile :: (Word8 -> Bool) -> Bytes -> Bytes

-- | <i>O(n)</i> <a>takeWhileEnd</a> <tt>p</tt> <tt>b</tt> returns the
--   longest suffix of elements that satisfy predicate <tt>p</tt>.
takeWhileEnd :: (Word8 -> Bool) -> Bytes -> Bytes

-- | <i>O(n)</i> <a>dropWhileEnd</a> <tt>p</tt> <tt>b</tt> returns the
--   prefix remaining after dropping characters that satisfy the predicate
--   <tt>p</tt> from the end of <tt>t</tt>.
dropWhileEnd :: (Word8 -> Bool) -> Bytes -> Bytes

-- | Left fold over bytes, non-strict in the accumulator.
foldl :: (a -> Word8 -> a) -> a -> Bytes -> a

-- | Left fold over bytes, strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> Bytes -> a

-- | Right fold over bytes, non-strict in the accumulator.
foldr :: (Word8 -> a -> a) -> a -> Bytes -> a

-- | Right fold over bytes, strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> Bytes -> a

-- | Left fold over bytes, strict in the accumulator. The reduction
--   function is applied to each element along with its index.
ifoldl' :: (a -> Int -> Word8 -> a) -> a -> Bytes -> a

-- | Is the byte a member of the byte sequence?
elem :: Word8 -> Bytes -> Bool

-- | Break a byte sequence into pieces separated by the byte argument,
--   consuming the delimiter. This function is a good producer for list
--   fusion. It is common to immidiately consume the results of
--   <tt>split</tt> with <tt>foldl'</tt>, <tt>traverse_</tt>,
--   <tt>foldlM</tt>, and being a good producer helps in this situation.
--   
--   Note: this function differs from its counterpart in
--   <tt>bytestring</tt>. If the byte sequence is empty, this returns a
--   singleton list with the empty byte sequence.
split :: Word8 -> Bytes -> [Bytes]

-- | Variant of <a>split</a> that returns an array of unsliced byte
--   sequences. Unlike <a>split</a>, this is not a good producer for list
--   fusion. (It does not return a list, so it could not be.) Prefer
--   <a>split</a> if the result is going to be consumed exactly once by a
--   good consumer. Prefer <a>splitU</a> if the result of the split is
--   going to be around for a while and inspected multiple times.
splitU :: Word8 -> Bytes -> UnliftedArray ByteArray

-- | Variant of <a>split</a> that drops the trailing element. This behaves
--   correctly even if the byte sequence is empty. This is a good producer
--   for list fusion. This is useful when splitting a text file into lines.
--   <a>POSIX</a> mandates that text files end with a newline, so the list
--   resulting from <a>split</a> always has an empty byte sequence as its
--   last element. With <a>splitInit</a>, that unwanted element is
--   discarded.
splitInit :: Word8 -> Bytes -> [Bytes]

-- | Variant of <a>splitU</a> that drops the trailing element. See
--   <a>splitInit</a> for an explanation of why this may be useful.
splitInitU :: Word8 -> Bytes -> UnliftedArray ByteArray

-- | Variant of <a>split</a> that returns the result as a <a>NonEmpty</a>
--   instead of <tt>[]</tt>. This is also eligible for stream fusion.
splitNonEmpty :: Word8 -> Bytes -> NonEmpty Bytes

-- | Split a byte sequence on the first occurrence of the target byte. The
--   target is removed from the result. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split1 0xA [0x1,0x2,0xA,0xB]
--   Just ([0x1,0x2],[0xB])
--   </pre>
split1 :: Word8 -> Bytes -> Maybe (Bytes, Bytes)

-- | Split a byte sequence on the first and second occurrences of the
--   target byte. The target is removed from the result. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split2 0xA [0x1,0x2,0xA,0xB,0xA,0xA,0xA]
--   Just ([0x1,0x2],[0xB],[0xA,0xA])
--   </pre>
split2 :: Word8 -> Bytes -> Maybe (Bytes, Bytes, Bytes)

-- | Split a byte sequence on the first, second, and third occurrences of
--   the target byte. The target is removed from the result. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split3 0xA [0x1,0x2,0xA,0xB,0xA,0xA,0xA]
--   Just ([0x1,0x2],[0xB],[],[0xA])
--   </pre>
split3 :: Word8 -> Bytes -> Maybe (Bytes, Bytes, Bytes, Bytes)

-- | Count the number of times the byte appears in the sequence.
count :: Word8 -> Bytes -> Int

-- | Is the first argument a prefix of the second argument?
isPrefixOf :: Bytes -> Bytes -> Bool

-- | Is the first argument a suffix of the second argument?
isSuffixOf :: Bytes -> Bytes -> Bool

-- | <i>O(n)</i> Return the suffix of the second string if its prefix
--   matches the entire first string.
stripPrefix :: Bytes -> Bytes -> Maybe Bytes

-- | <i>O(n)</i> Return the suffix of the second string if its prefix
--   matches the entire first string. Otherwise, return the second string
--   unchanged.
stripOptionalPrefix :: Bytes -> Bytes -> Bytes

-- | <i>O(n)</i> Return the prefix of the second string if its suffix
--   matches the entire first string.
stripSuffix :: Bytes -> Bytes -> Maybe Bytes

-- | <i>O(n)</i> Return the prefix of the second string if its suffix
--   matches the entire first string. Otherwise, return the second string
--   unchanged.
stripOptionalSuffix :: Bytes -> Bytes -> Bytes

-- | Does the byte sequence begin with the given byte? False if the byte
--   sequence is empty.
isBytePrefixOf :: Word8 -> Bytes -> Bool

-- | Does the byte sequence end with the given byte? False if the byte
--   sequence is empty.
isByteSuffixOf :: Word8 -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   singleton whose element matches the character?
equalsLatin1 :: Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   doubleton whose elements match the characters?
equalsLatin2 :: Char -> Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   tripleton whose elements match the characters?
equalsLatin3 :: Char -> Char -> Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   quadrupleton whose elements match the characters?
equalsLatin4 :: Char -> Char -> Char -> Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   quintupleton whose elements match the characters?
equalsLatin5 :: Char -> Char -> Char -> Char -> Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   sextupleton whose elements match the characters?
equalsLatin6 :: Char -> Char -> Char -> Char -> Char -> Char -> Bytes -> Bool

-- | Is the byte sequence, when interpreted as ISO-8859-1-encoded text, a
--   septupleton whose elements match the characters?
equalsLatin7 :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Bytes -> Bool

-- | Take the first <tt>n</tt> bytes from the argument. Precondition: <tt>n
--   ≤ len</tt>
unsafeTake :: Int -> Bytes -> Bytes

-- | Drop the first <tt>n</tt> bytes from the argument. Precondition: <tt>n
--   ≤ len</tt>
unsafeDrop :: Int -> Bytes -> Bytes

-- | Index into the byte sequence at the given position. This index must be
--   less than the length.
unsafeIndex :: Bytes -> Int -> Word8

-- | Copy the byte sequence into a mutable buffer. The buffer must have
--   enough space to accomodate the byte sequence, but this this is not
--   checked.
unsafeCopy :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Bytes -> m ()

-- | Yields a pinned byte sequence whose contents are identical to those of
--   the original byte sequence. If the <tt>ByteArray</tt> backing the
--   argument was already pinned, this simply aliases the argument and does
--   not perform any copying.
pin :: Bytes -> Bytes

-- | Yields a pointer to the beginning of the byte sequence. It is only
--   safe to call this on a <a>Bytes</a> backed by a pinned
--   <tt>ByteArray</tt>.
contents :: Bytes -> Ptr Word8

-- | Touch the byte array backing the byte sequence. This sometimes needed
--   after calling <a>contents</a> so that the <tt>ByteArray</tt> does not
--   get garbage collected.
touch :: PrimMonad m => Bytes -> m ()

-- | Convert the sliced <a>Bytes</a> to an unsliced <a>ByteArray</a>. This
--   reuses the array backing the sliced <a>Bytes</a> if the slicing
--   metadata implies that all of the bytes are used. Otherwise, it makes a
--   copy.
toByteArray :: Bytes -> ByteArray

-- | Variant of <a>toByteArray</a> that unconditionally makes a copy of the
--   array backing the sliced <a>Bytes</a> even if the original array could
--   be reused. Prefer <a>toByteArray</a>.
toByteArrayClone :: Bytes -> ByteArray

-- | Convert a <a>String</a> consisting of only characters in the ASCII
--   block to a byte sequence. Any character with a codepoint above
--   <tt>U+007F</tt> is replaced by <tt>U+0000</tt>.
fromAsciiString :: String -> Bytes

-- | Convert a <a>String</a> consisting of only characters representable by
--   ISO-8859-1. These are encoded with ISO-8859-1. Any character with a
--   codepoint above <tt>U+00FF</tt> is replace an unspecified byte.
fromLatinString :: String -> Bytes

-- | Create a slice of <a>Bytes</a> that spans the entire argument array.
fromByteArray :: ByteArray -> Bytes

-- | Interpret a byte sequence as text encoded by ISO-8859-1.
toLatinString :: Bytes -> String

-- | Read <a>Bytes</a> directly from the specified <a>Handle</a>. The
--   resulting <a>Bytes</a> are pinned. This is implemented with
--   <tt>hGetBuf</tt>.
hGet :: Handle -> Int -> IO Bytes

-- | Outputs <a>Bytes</a> to the specified <a>Handle</a>. This is
--   implemented with <tt>hPutBuf</tt>.
hPut :: Handle -> Bytes -> IO ()


-- | Chunks of bytes. This is useful as a target for a builder or as a way
--   to read a large amount of whose size is unknown in advance.
--   Structurally, this type is similar to
--   <tt>Data.ByteString.Lazy.ByteString</tt>. However, the type in this
--   module is strict in its spine. Additionally, none of the
--   <tt>Handle</tt> functions perform lazy I/O.
module Data.Bytes.Chunks

-- | A cons-list of byte sequences.
data Chunks
ChunksCons :: {-# UNPACK #-} !Bytes -> !Chunks -> Chunks
ChunksNil :: Chunks

-- | The total number of bytes in all the chunks.
length :: Chunks -> Int

-- | Concatenate chunks into a single contiguous byte sequence.
concat :: Chunks -> Bytes

-- | Variant of <a>concat</a> that returns an unsliced byte sequence.
concatU :: Chunks -> ByteArray

-- | Reverse chunks but not the bytes within each chunk.
reverse :: Chunks -> Chunks

-- | Variant of <a>reverse</a> that allows the caller to provide an initial
--   list of chunks that the reversed chunks will be pushed onto.
reverseOnto :: Chunks -> Chunks -> Chunks

-- | Create a list of chunks with a single chunk.
fromBytes :: Bytes -> Chunks

-- | Variant of <a>fromBytes</a> where the single chunk is unsliced.
fromByteArray :: ByteArray -> Chunks

-- | Copy the contents of the chunks into a mutable array. Precondition:
--   The destination must have enough space to house the contents. This is
--   not checked.
unsafeCopy :: MutableByteArray s -> Int -> Chunks -> ST s Int

-- | Read a handle's entire contents strictly into chunks.
hGetContents :: Handle -> IO Chunks
instance GHC.Show.Show Data.Bytes.Chunks.Chunks
instance GHC.Base.Semigroup Data.Bytes.Chunks.Chunks
instance GHC.Base.Monoid Data.Bytes.Chunks.Chunks
instance GHC.Classes.Eq Data.Bytes.Chunks.Chunks