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

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

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

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

-- | 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
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.
split :: Word8 -> Bytes -> [Bytes]

-- | Variant of <a>split</a> that drops the trailing element. This behaves
--   correctly even if the byte sequence is empty.
splitInit :: Word8 -> Bytes -> [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; splitOnce 0xA [0x1,0x2,0xA,0xB]
--   Just ([0x1,0x2],[0xB])
--   </pre>
splitFirst :: Word8 -> Bytes -> Maybe (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

-- | 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.
copy :: 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.
fromAsciiString :: 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