{-# LANGUAGE CPP #-}
{-# LANGUAGE DeriveDataTypeable #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MagicHash #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE RoleAnnotations #-}
{-# LANGUAGE ScopedTypeVariables #-}
-- |
-- Module      : Data.Vector.Storable.Mutable
-- Copyright   : (c) Roman Leshchinskiy 2009-2010
--                   Alexey Kuleshevich 2020-2022
--                   Aleksey Khudyakov 2020-2022
--                   Andrew Lelechenko 2020-2022
-- License     : BSD-style
--
-- Maintainer  : Haskell Libraries Team <libraries@haskell.org>
-- Stability   : experimental
-- Portability : non-portable
--
-- Mutable vectors based on Storable.

module Data.Vector.Storable.Mutable(
  -- * Mutable vectors of 'Storable' types
  MVector(..), IOVector, STVector,

  -- * Accessors

  -- ** Length information
  length, null,

  -- ** Extracting subvectors
  slice, init, tail, take, drop, splitAt,
  unsafeSlice, unsafeInit, unsafeTail, unsafeTake, unsafeDrop,

  -- ** Overlapping
  overlaps,

  -- * Construction

  -- ** Initialisation
  new, unsafeNew, replicate, replicateM, generate, generateM, clone,

  -- ** Growing
  grow, unsafeGrow,

  -- ** Restricting memory usage
  clear,

  -- * Accessing individual elements
  read, readMaybe, write, modify, modifyM, swap, exchange,
  unsafeRead, unsafeWrite, unsafeModify, unsafeModifyM, unsafeSwap, unsafeExchange,

  -- * Folds
  mapM_, imapM_, forM_, iforM_,
  foldl, foldl', foldM, foldM',
  foldr, foldr', foldrM, foldrM',
  ifoldl, ifoldl', ifoldM, ifoldM',
  ifoldr, ifoldr', ifoldrM, ifoldrM',

  -- * Modifying vectors
  nextPermutation,

  -- ** Filling and copying
  set, copy, move, unsafeCopy, unsafeMove,

  -- * Unsafe conversions
  unsafeCast,
  unsafeCoerceMVector,

  -- * Raw pointers
  unsafeFromForeignPtr, unsafeFromForeignPtr0,
  unsafeToForeignPtr,   unsafeToForeignPtr0,
  unsafeWith,
  -- * Re-exports
  Storable, PrimMonad, PrimState, RealWorld
) where

import Control.DeepSeq ( NFData(rnf)
#if MIN_VERSION_deepseq(1,4,3)
                       , NFData1(liftRnf)
#endif
                       )

import qualified Data.Vector.Generic.Mutable as G
import Data.Vector.Storable.Internal

import Foreign.Storable
import Foreign.ForeignPtr

import GHC.ForeignPtr (mallocPlainForeignPtrAlignedBytes)
import GHC.Base ( Int(..) )

import Foreign.Ptr (castPtr,plusPtr)
import Foreign.Marshal.Array ( advancePtr, copyArray, moveArray )

import Control.Monad.Primitive
import Data.Primitive.Types (Prim)
import qualified Data.Primitive.Types as DPT

import GHC.Word (Word8, Word16, Word32, Word64)
import GHC.Ptr (Ptr(..))

import Prelude
  ( Ord, Bool, Maybe, IO
  , return, otherwise, error, undefined, max, div, quot, maxBound, show
  , (-), (*), (<), (>), (>=), (==), (&&), (||), (.), ($), (++) )

import Data.Typeable ( Typeable )

import Data.Coerce
import Unsafe.Coerce

-- Data.Vector.Internal.Check is not needed
#define NOT_VECTOR_MODULE
#include "vector.h"

type role MVector nominal nominal

-- | /O(1)/ Unsafely coerce a mutable vector from one element type to another,
-- representationally equal type. The operation just changes the type of the
-- underlying pointer and does not modify the elements.
--
-- This is marginally safer than 'unsafeCast', since this function imposes an
-- extra 'Coercible' constraint. This function is still not safe, however,
-- since it cannot guarantee that the two types have memory-compatible
-- 'Storable' instances.
unsafeCoerceMVector :: Coercible a b => MVector s a -> MVector s b
unsafeCoerceMVector :: forall a b s. Coercible a b => MVector s a -> MVector s b
unsafeCoerceMVector = forall a b. a -> b
unsafeCoerce

-- | Mutable 'Storable'-based vectors.
data MVector s a = MVector {-# UNPACK #-} !Int
                           {-# UNPACK #-} !(ForeignPtr a)
        deriving ( Typeable )

type IOVector = MVector RealWorld
type STVector s = MVector s

instance NFData (MVector s a) where
  rnf :: MVector s a -> ()
rnf (MVector Int
_ ForeignPtr a
_) = ()

#if MIN_VERSION_deepseq(1,4,3)
instance NFData1 (MVector s) where
  liftRnf :: forall a. (a -> ()) -> MVector s a -> ()
liftRnf a -> ()
_ (MVector Int
_ ForeignPtr a
_) = ()
#endif

instance Storable a => G.MVector MVector a where
  {-# INLINE basicLength #-}
  basicLength :: forall s. MVector s a -> Int
basicLength (MVector Int
n ForeignPtr a
_) = Int
n

  {-# INLINE basicUnsafeSlice #-}
  basicUnsafeSlice :: forall s. Int -> Int -> MVector s a -> MVector s a
basicUnsafeSlice Int
j Int
m (MVector Int
_ ForeignPtr a
fp) = forall s a. Int -> ForeignPtr a -> MVector s a
MVector Int
m (forall a. (Ptr a -> Ptr a) -> ForeignPtr a -> ForeignPtr a
updPtr (forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
j) ForeignPtr a
fp)

  -- FIXME: this relies on non-portable pointer comparisons
  {-# INLINE basicOverlaps #-}
  basicOverlaps :: forall s. MVector s a -> MVector s a -> Bool
basicOverlaps (MVector Int
m ForeignPtr a
fp) (MVector Int
n ForeignPtr a
fq)
    = forall {a}. Ord a => a -> a -> a -> Bool
between Ptr a
p Ptr a
q (Ptr a
q forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
n) Bool -> Bool -> Bool
|| forall {a}. Ord a => a -> a -> a -> Bool
between Ptr a
q Ptr a
p (Ptr a
p forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
m)
    where
      between :: a -> a -> a -> Bool
between a
x a
y a
z = a
x forall a. Ord a => a -> a -> Bool
>= a
y Bool -> Bool -> Bool
&& a
x forall a. Ord a => a -> a -> Bool
< a
z
      p :: Ptr a
p = forall a. ForeignPtr a -> Ptr a
getPtr ForeignPtr a
fp
      q :: Ptr a
q = forall a. ForeignPtr a -> Ptr a
getPtr ForeignPtr a
fq

  {-# INLINE basicUnsafeNew #-}
  basicUnsafeNew :: forall s. Int -> ST s (MVector s a)
basicUnsafeNew Int
n
    | Int
n forall a. Ord a => a -> a -> Bool
< Int
0 = forall a. HasCallStack => [Char] -> a
error forall a b. (a -> b) -> a -> b
$ [Char]
"Storable.basicUnsafeNew: negative length: " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> [Char]
show Int
n
    | Int
n forall a. Ord a => a -> a -> Bool
> Int
mx = forall a. HasCallStack => [Char] -> a
error forall a b. (a -> b) -> a -> b
$ [Char]
"Storable.basicUnsafeNew: length too large: " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> [Char]
show Int
n
    | Bool
otherwise = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim forall a b. (a -> b) -> a -> b
$ do
        ForeignPtr a
fp <- forall a. Storable a => Int -> IO (ForeignPtr a)
mallocVector Int
n
        forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ forall s a. Int -> ForeignPtr a -> MVector s a
MVector Int
n ForeignPtr a
fp
    where
      size :: Int
size = forall a. Storable a => a -> Int
sizeOf (forall a. HasCallStack => a
undefined :: a) forall a. Ord a => a -> a -> a
`max` Int
1
      mx :: Int
mx = forall a. Bounded a => a
maxBound forall a. Integral a => a -> a -> a
`quot` Int
size :: Int

  {-# INLINE basicInitialize #-}
  basicInitialize :: forall s. MVector s a -> ST s ()
basicInitialize = forall a (m :: * -> *).
(Storable a, PrimMonad m) =>
MVector (PrimState m) a -> m ()
storableZero

  {-# INLINE basicUnsafeRead #-}
  basicUnsafeRead :: forall s. MVector s a -> Int -> ST s a
basicUnsafeRead (MVector Int
_ ForeignPtr a
fp) Int
i
    = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim
    forall a b. (a -> b) -> a -> b
$ forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp (forall a. Storable a => Ptr a -> Int -> IO a
`peekElemOff` Int
i)

  {-# INLINE basicUnsafeWrite #-}
  basicUnsafeWrite :: forall s. MVector s a -> Int -> a -> ST s ()
basicUnsafeWrite (MVector Int
_ ForeignPtr a
fp) Int
i a
x
    = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim
    forall a b. (a -> b) -> a -> b
$ forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \Ptr a
p -> forall a. Storable a => Ptr a -> Int -> a -> IO ()
pokeElemOff Ptr a
p Int
i a
x

  {-# INLINE basicSet #-}
  basicSet :: forall s. MVector s a -> a -> ST s ()
basicSet = forall a (m :: * -> *).
(Storable a, PrimMonad m) =>
MVector (PrimState m) a -> a -> m ()
storableSet

  {-# INLINE basicUnsafeCopy #-}
  basicUnsafeCopy :: forall s. MVector s a -> MVector s a -> ST s ()
basicUnsafeCopy (MVector Int
n ForeignPtr a
fp) (MVector Int
_ ForeignPtr a
fq)
    = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim
    forall a b. (a -> b) -> a -> b
$ forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \Ptr a
p ->
      forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fq forall a b. (a -> b) -> a -> b
$ \Ptr a
q ->
      forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
copyArray Ptr a
p Ptr a
q Int
n

  {-# INLINE basicUnsafeMove #-}
  basicUnsafeMove :: forall s. MVector s a -> MVector s a -> ST s ()
basicUnsafeMove (MVector Int
n ForeignPtr a
fp) (MVector Int
_ ForeignPtr a
fq)
    = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim
    forall a b. (a -> b) -> a -> b
$ forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \Ptr a
p ->
      forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fq forall a b. (a -> b) -> a -> b
$ \Ptr a
q ->
      forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
moveArray Ptr a
p Ptr a
q Int
n

storableZero :: forall a m. (Storable a, PrimMonad m) => MVector (PrimState m) a -> m ()
{-# INLINE storableZero #-}
storableZero :: forall a (m :: * -> *).
(Storable a, PrimMonad m) =>
MVector (PrimState m) a -> m ()
storableZero (MVector Int
n ForeignPtr a
fp) = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \Ptr a
ptr-> do
  forall a c (m :: * -> *).
(Prim c, PrimMonad m) =>
Ptr a -> Int -> c -> m ()
memsetPrimPtr_vector (forall a b. Ptr a -> Ptr b
castPtr Ptr a
ptr) Int
byteSize (Word8
0 :: Word8)
 where
 x :: a
 x :: a
x = forall a. HasCallStack => a
undefined
 byteSize :: Int
 byteSize :: Int
byteSize = Int
n forall a. Num a => a -> a -> a
* forall a. Storable a => a -> Int
sizeOf a
x

storableSet :: (Storable a, PrimMonad m) => MVector (PrimState m) a -> a -> m ()
{-# INLINE storableSet #-}
storableSet :: forall a (m :: * -> *).
(Storable a, PrimMonad m) =>
MVector (PrimState m) a -> a -> m ()
storableSet (MVector Int
n ForeignPtr a
fp) a
x
  | Int
n forall a. Eq a => a -> a -> Bool
== Int
0 = forall (m :: * -> *) a. Monad m => a -> m a
return ()
  | Bool
otherwise = forall (m1 :: * -> *) (m2 :: * -> *) a.
(PrimBase m1, PrimMonad m2) =>
m1 a -> m2 a
unsafePrimToPrim forall a b. (a -> b) -> a -> b
$
                case forall a. Storable a => a -> Int
sizeOf a
x of
                  Int
1 -> forall a b.
(Storable a, Prim b) =>
Int -> ForeignPtr a -> a -> b -> IO ()
storableSetAsPrim Int
n ForeignPtr a
fp a
x (forall a. HasCallStack => a
undefined :: Word8)
                  Int
2 -> forall a b.
(Storable a, Prim b) =>
Int -> ForeignPtr a -> a -> b -> IO ()
storableSetAsPrim Int
n ForeignPtr a
fp a
x (forall a. HasCallStack => a
undefined :: Word16)
                  Int
4 -> forall a b.
(Storable a, Prim b) =>
Int -> ForeignPtr a -> a -> b -> IO ()
storableSetAsPrim Int
n ForeignPtr a
fp a
x (forall a. HasCallStack => a
undefined :: Word32)
#if !defined(ghcjs_HOST_OS)
                  Int
8 -> forall a b.
(Storable a, Prim b) =>
Int -> ForeignPtr a -> a -> b -> IO ()
storableSetAsPrim Int
n ForeignPtr a
fp a
x (forall a. HasCallStack => a
undefined :: Word64)
#endif
                  Int
_ -> forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \Ptr a
p -> do
                       forall a. Storable a => Ptr a -> a -> IO ()
poke Ptr a
p a
x

                       let do_set :: Int -> IO ()
do_set Int
i
                             | Int
2forall a. Num a => a -> a -> a
*Int
i forall a. Ord a => a -> a -> Bool
< Int
n = do
                                 forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
copyArray (Ptr a
p forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
i) Ptr a
p Int
i
                                 Int -> IO ()
do_set (Int
2forall a. Num a => a -> a -> a
*Int
i)
                             | Bool
otherwise = forall a. Storable a => Ptr a -> Ptr a -> Int -> IO ()
copyArray (Ptr a
p forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
i) Ptr a
p (Int
nforall a. Num a => a -> a -> a
-Int
i)

                       Int -> IO ()
do_set Int
1

storableSetAsPrim
  :: forall a b . (Storable a, Prim b) => Int -> ForeignPtr a -> a -> b -> IO ()
{-# INLINE [0] storableSetAsPrim #-}
storableSetAsPrim :: forall a b.
(Storable a, Prim b) =>
Int -> ForeignPtr a -> a -> b -> IO ()
storableSetAsPrim Int
n ForeignPtr a
fp a
x b
_y = forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtr ForeignPtr a
fp forall a b. (a -> b) -> a -> b
$ \ Ptr a
ptr  -> do
    forall a. Storable a => Ptr a -> a -> IO ()
poke Ptr a
ptr a
x
     -- we don't equate storable and prim reps, so we need to write to a slot
     -- in storable
     -- then read it back as a prim
    b
w<- forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
Ptr a -> Int -> m a
peakPrimPtr_vector (forall a b. Ptr a -> Ptr b
castPtr Ptr a
ptr :: Ptr  b) Int
0
    forall a c (m :: * -> *).
(Prim c, PrimMonad m) =>
Ptr a -> Int -> c -> m ()
memsetPrimPtr_vector (forall a b. Ptr a -> Ptr b
castPtr Ptr a
ptr forall a b. Ptr a -> Int -> Ptr b
`plusPtr` forall a. Storable a => a -> Int
sizeOf a
x ) (Int
nforall a. Num a => a -> a -> a
-Int
1)  b
w



{-
AFTER primitive 0.7 is pretty old, move to using setPtr. which is really
a confusing misnomer for whats often called memset (intialize)
-}
-- Fill a memory block with the given value. The length is in
-- elements of type @a@ rather than in bytes.
memsetPrimPtr_vector :: forall a c m. (Prim c, PrimMonad m) => Ptr a -> Int -> c -> m ()
memsetPrimPtr_vector :: forall a c (m :: * -> *).
(Prim c, PrimMonad m) =>
Ptr a -> Int -> c -> m ()
memsetPrimPtr_vector (Ptr Addr#
addr#) (I# Int#
n#) c
x = forall (m :: * -> *).
PrimMonad m =>
(State# (PrimState m) -> State# (PrimState m)) -> m ()
primitive_ (forall a s.
Prim a =>
Addr# -> Int# -> Int# -> a -> State# s -> State# s
DPT.setOffAddr# Addr#
addr# Int#
0# Int#
n# c
x)
{-# INLINE memsetPrimPtr_vector #-}


-- Read a value from a memory position given by an address and an offset.
-- The offset is in elements of type @a@ rather than in bytes.
peakPrimPtr_vector :: (Prim a, PrimMonad m) => Ptr a -> Int -> m a
peakPrimPtr_vector :: forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
Ptr a -> Int -> m a
peakPrimPtr_vector (Ptr Addr#
addr#) (I# Int#
i#) = forall (m :: * -> *) a.
PrimMonad m =>
(State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
primitive (forall a s.
Prim a =>
Addr# -> Int# -> State# s -> (# State# s, a #)
DPT.readOffAddr# Addr#
addr# Int#
i#)
{-# INLINE peakPrimPtr_vector #-}

{-# INLINE mallocVector #-}
mallocVector :: Storable a => Int -> IO (ForeignPtr a)
mallocVector :: forall a. Storable a => Int -> IO (ForeignPtr a)
mallocVector =
  forall b. Storable b => b -> Int -> IO (ForeignPtr b)
doMalloc forall a. HasCallStack => a
undefined
  where
    doMalloc :: Storable b => b -> Int -> IO (ForeignPtr b)
    doMalloc :: forall b. Storable b => b -> Int -> IO (ForeignPtr b)
doMalloc b
dummy Int
size =
      forall a. Int -> Int -> IO (ForeignPtr a)
mallocPlainForeignPtrAlignedBytes (Int
size forall a. Num a => a -> a -> a
* forall a. Storable a => a -> Int
sizeOf b
dummy) (forall a. Storable a => a -> Int
alignment b
dummy)

-- Length information
-- ------------------

-- | Length of the mutable vector.
length :: Storable a => MVector s a -> Int
{-# INLINE length #-}
length :: forall a s. Storable a => MVector s a -> Int
length = forall (v :: * -> * -> *) a s. MVector v a => v s a -> Int
G.length

-- | Check whether the vector is empty.
null :: Storable a => MVector s a -> Bool
{-# INLINE null #-}
null :: forall a s. Storable a => MVector s a -> Bool
null = forall (v :: * -> * -> *) a s. MVector v a => v s a -> Bool
G.null

-- Extracting subvectors
-- ---------------------

-- | Yield a part of the mutable vector without copying it. The vector must
-- contain at least @i+n@ elements.
slice :: Storable a
      => Int  -- ^ @i@ starting index
      -> Int  -- ^ @n@ length
      -> MVector s a
      -> MVector s a
{-# INLINE slice #-}
slice :: forall a s. Storable a => Int -> Int -> MVector s a -> MVector s a
slice = forall (v :: * -> * -> *) a s.
(HasCallStack, MVector v a) =>
Int -> Int -> v s a -> v s a
G.slice

-- | Take the @n@ first elements of the mutable vector without making a
-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
-- than the vector's length, the vector is returned unchanged.
take :: Storable a => Int -> MVector s a -> MVector s a
{-# INLINE take #-}
take :: forall a s. Storable a => Int -> MVector s a -> MVector s a
take = forall (v :: * -> * -> *) a s. MVector v a => Int -> v s a -> v s a
G.take

-- | Drop the @n@ first element of the mutable vector without making a
-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
-- larger than the vector's length, the empty vector is returned.
drop :: Storable a => Int -> MVector s a -> MVector s a
{-# INLINE drop #-}
drop :: forall a s. Storable a => Int -> MVector s a -> MVector s a
drop = forall (v :: * -> * -> *) a s. MVector v a => Int -> v s a -> v s a
G.drop

-- | /O(1)/ Split the mutable vector into the first @n@ elements
-- and the remainder, without copying.
--
-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
-- but slightly more efficient.
splitAt :: Storable a => Int -> MVector s a -> (MVector s a, MVector s a)
{-# INLINE splitAt #-}
splitAt :: forall a s.
Storable a =>
Int -> MVector s a -> (MVector s a, MVector s a)
splitAt = forall (v :: * -> * -> *) a s.
MVector v a =>
Int -> v s a -> (v s a, v s a)
G.splitAt

-- | Drop the last element of the mutable vector without making a copy.
-- If the vector is empty, an exception is thrown.
init :: Storable a => MVector s a -> MVector s a
{-# INLINE init #-}
init :: forall a s. Storable a => MVector s a -> MVector s a
init = forall (v :: * -> * -> *) a s. MVector v a => v s a -> v s a
G.init

-- | Drop the first element of the mutable vector without making a copy.
-- If the vector is empty, an exception is thrown.
tail :: Storable a => MVector s a -> MVector s a
{-# INLINE tail #-}
tail :: forall a s. Storable a => MVector s a -> MVector s a
tail = forall (v :: * -> * -> *) a s. MVector v a => v s a -> v s a
G.tail

-- | Yield a part of the mutable vector without copying it. No bounds checks
-- are performed.
unsafeSlice :: Storable a
            => Int  -- ^ starting index
            -> Int  -- ^ length of the slice
            -> MVector s a
            -> MVector s a
{-# INLINE unsafeSlice #-}
unsafeSlice :: forall a s. Storable a => Int -> Int -> MVector s a -> MVector s a
unsafeSlice = forall (v :: * -> * -> *) a s.
MVector v a =>
Int -> Int -> v s a -> v s a
G.unsafeSlice

-- | Unsafe variant of 'take'. If @n@ is out of range, it will
-- simply create an invalid slice that likely violate memory safety.
unsafeTake :: Storable a => Int -> MVector s a -> MVector s a
{-# INLINE unsafeTake #-}
unsafeTake :: forall a s. Storable a => Int -> MVector s a -> MVector s a
unsafeTake = forall (v :: * -> * -> *) a s. MVector v a => Int -> v s a -> v s a
G.unsafeTake

-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
-- simply create an invalid slice that likely violate memory safety.
unsafeDrop :: Storable a => Int -> MVector s a -> MVector s a
{-# INLINE unsafeDrop #-}
unsafeDrop :: forall a s. Storable a => Int -> MVector s a -> MVector s a
unsafeDrop = forall (v :: * -> * -> *) a s. MVector v a => Int -> v s a -> v s a
G.unsafeDrop

-- | Same as 'init', but doesn't do range checks.
unsafeInit :: Storable a => MVector s a -> MVector s a
{-# INLINE unsafeInit #-}
unsafeInit :: forall a s. Storable a => MVector s a -> MVector s a
unsafeInit = forall (v :: * -> * -> *) a s. MVector v a => v s a -> v s a
G.unsafeInit

-- | Same as 'tail', but doesn't do range checks.
unsafeTail :: Storable a => MVector s a -> MVector s a
{-# INLINE unsafeTail #-}
unsafeTail :: forall a s. Storable a => MVector s a -> MVector s a
unsafeTail = forall (v :: * -> * -> *) a s. MVector v a => v s a -> v s a
G.unsafeTail

-- Overlapping
-- -----------

-- | Check whether two vectors overlap.
overlaps :: Storable a => MVector s a -> MVector s a -> Bool
{-# INLINE overlaps #-}
overlaps :: forall a s. Storable a => MVector s a -> MVector s a -> Bool
overlaps = forall (v :: * -> * -> *) a s.
MVector v a =>
v s a -> v s a -> Bool
G.overlaps

-- Initialisation
-- --------------

-- | Create a mutable vector of the given length.
new :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
{-# INLINE new #-}
new :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> m (MVector (PrimState m) a)
new = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
Int -> m (v (PrimState m) a)
G.new

-- | Create a mutable vector of the given length. The vector content
-- is uninitialized, which means it is filled with whatever the
-- underlying memory buffer happens to contain.
--
-- @since 0.5
unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
{-# INLINE unsafeNew #-}
unsafeNew :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> m (MVector (PrimState m) a)
unsafeNew = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
Int -> m (v (PrimState m) a)
G.unsafeNew

-- | Create a mutable vector of the given length (0 if the length is negative)
-- and fill it with an initial value.
replicate :: (PrimMonad m, Storable a) => Int -> a -> m (MVector (PrimState m) a)
{-# INLINE replicate #-}
replicate :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> a -> m (MVector (PrimState m) a)
replicate = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
Int -> a -> m (v (PrimState m) a)
G.replicate

-- | Create a mutable vector of the given length (0 if the length is negative)
-- and fill it with values produced by repeatedly executing the monadic action.
replicateM :: (PrimMonad m, Storable a) => Int -> m a -> m (MVector (PrimState m) a)
{-# INLINE replicateM #-}
replicateM :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> m a -> m (MVector (PrimState m) a)
replicateM = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
Int -> m a -> m (v (PrimState m) a)
G.replicateM

-- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
-- and fill it with the results of applying the function to each index.
-- Iteration starts at index 0.
--
-- @since 0.12.3.0
generate :: (PrimMonad m, Storable a) => Int -> (Int -> a) -> m (MVector (PrimState m) a)
{-# INLINE generate #-}
generate :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> (Int -> a) -> m (MVector (PrimState m) a)
generate = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
Int -> (Int -> a) -> m (v (PrimState m) a)
G.generate

-- | /O(n)/ Create a mutable vector of the given length (0 if the length is
-- negative) and fill it with the results of applying the monadic function to each
-- index. Iteration starts at index 0.
--
-- @since 0.12.3.0
generateM :: (PrimMonad m, Storable a) => Int -> (Int -> m a) -> m (MVector (PrimState m) a)
{-# INLINE generateM #-}
generateM :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
Int -> (Int -> m a) -> m (MVector (PrimState m) a)
generateM = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
Int -> (Int -> m a) -> m (v (PrimState m) a)
G.generateM

-- | Create a copy of a mutable vector.
clone :: (PrimMonad m, Storable a)
      => MVector (PrimState m) a -> m (MVector (PrimState m) a)
{-# INLINE clone #-}
clone :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> m (MVector (PrimState m) a)
clone = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> m (v (PrimState m) a)
G.clone

-- Growing
-- -------

-- | Grow a storable vector by the given number of elements. The number must be
-- non-negative. This has the same semantics as 'G.grow' for generic vectors.
--
-- ==== __Examples__
--
-- >>> import qualified Data.Vector.Storable as VS
-- >>> import qualified Data.Vector.Storable.Mutable as MVS
-- >>> mv <- VS.thaw $ VS.fromList ([10, 20, 30] :: [Int])
-- >>> mv' <- MVS.grow mv 2
--
-- Extra memory at the end of the newly allocated vector is initialized to 0
-- bytes, which for 'Storable' instances will usually correspond to some default
-- value for a particular type, e.g. @0@ for @Int@, @False@ for @Bool@,
-- etc. However, if 'unsafeGrow' was used instead, this would not have been
-- guaranteed and some garbage would be there instead.
--
-- >>> VS.freeze mv'
-- [10,20,30,0,0]
--
-- Having the extra space we can write new values in there:
--
-- >>> MVS.write mv' 3 999
-- >>> VS.freeze mv'
-- [10,20,30,999,0]
--
-- It is important to note that the source mutable vector is not affected when
-- the newly allocated one is mutated.
--
-- >>> MVS.write mv' 2 888
-- >>> VS.freeze mv'
-- [10,20,888,999,0]
-- >>> VS.freeze mv
-- [10,20,30]
--
-- @since 0.5
grow :: (PrimMonad m, Storable a)
     => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
{-# INLINE grow #-}
grow :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
grow = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> m (v (PrimState m) a)
G.grow

-- | Grow a vector by the given number of elements. The number must be non-negative, but
-- this is not checked. This has the same semantics as 'G.unsafeGrow' for generic vectors.
--
-- @since 0.5
unsafeGrow :: (PrimMonad m, Storable a)
           => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
{-# INLINE unsafeGrow #-}
unsafeGrow :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
unsafeGrow = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> m (v (PrimState m) a)
G.unsafeGrow

-- Restricting memory usage
-- ------------------------

-- | Reset all elements of the vector to some undefined value, clearing all
-- references to external objects. This is a noop.
clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()
{-# INLINE clear #-}
clear :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> m ()
clear = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> m ()
G.clear

-- Accessing individual elements
-- -----------------------------

-- | Yield the element at the given position. Will throw an exception if
-- the index is out of range.
--
-- ==== __Examples__
--
-- >>> import qualified Data.Vector.Storable.Mutable as MVS
-- >>> v <- MVS.generate 10 (\x -> x*x)
-- >>> MVS.read v 3
-- 9
read :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
{-# INLINE read #-}
read :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> m a
read = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> m a
G.read

-- | Yield the element at the given position. Returns 'Nothing' if
-- the index is out of range.
--
-- @since 0.13
--
-- ==== __Examples__
--
-- >>> import qualified Data.Vector.Storable.Mutable as MVS
-- >>> v <- MVS.generate 10 (\x -> x*x)
-- >>> MVS.readMaybe v 3
-- Just 9
-- >>> MVS.readMaybe v 13
-- Nothing
readMaybe :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m (Maybe a)
{-# INLINE readMaybe #-}
readMaybe :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> m (Maybe a)
readMaybe = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> m (Maybe a)
G.readMaybe

-- | Replace the element at the given position.
write
    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m ()
{-# INLINE write #-}
write :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> a -> m ()
write = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> a -> m ()
G.write

-- | Modify the element at the given position.
modify :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> a) -> Int -> m ()
{-# INLINE modify #-}
modify :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (a -> a) -> Int -> m ()
modify = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> (a -> a) -> Int -> m ()
G.modify

-- | Modify the element at the given position using a monadic function.
--
-- @since 0.12.3.0
modifyM :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m a) -> Int -> m ()
{-# INLINE modifyM #-}
modifyM :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (a -> m a) -> Int -> m ()
modifyM = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> (a -> m a) -> Int -> m ()
G.modifyM

-- | Swap the elements at the given positions.
swap
    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
{-# INLINE swap #-}
swap :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> Int -> m ()
swap = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> Int -> m ()
G.swap

-- | Replace the element at the given position and return the old element.
exchange :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m a
{-# INLINE exchange #-}
exchange :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> a -> m a
exchange = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> a -> m a
G.exchange

-- | Yield the element at the given position. No bounds checks are performed.
unsafeRead :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
{-# INLINE unsafeRead #-}
unsafeRead :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> m a
unsafeRead = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> m a
G.unsafeRead

-- | Replace the element at the given position. No bounds checks are performed.
unsafeWrite :: (PrimMonad m, Storable a) =>  MVector (PrimState m) a -> Int -> a -> m ()
{-# INLINE unsafeWrite #-}
unsafeWrite :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> a -> m ()
unsafeWrite = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> a -> m ()
G.unsafeWrite

-- | Modify the element at the given position. No bounds checks are performed.
unsafeModify :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> a) -> Int -> m ()
{-# INLINE unsafeModify #-}
unsafeModify :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (a -> a) -> Int -> m ()
unsafeModify = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> (a -> a) -> Int -> m ()
G.unsafeModify

-- | Modify the element at the given position using a monadic
-- function. No bounds checks are performed.
--
-- @since 0.12.3.0
unsafeModifyM :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m a) -> Int -> m ()
{-# INLINE unsafeModifyM #-}
unsafeModifyM :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (a -> m a) -> Int -> m ()
unsafeModifyM = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> (a -> m a) -> Int -> m ()
G.unsafeModifyM

-- | Swap the elements at the given positions. No bounds checks are performed.
unsafeSwap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
{-# INLINE unsafeSwap #-}
unsafeSwap :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> Int -> m ()
unsafeSwap = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> Int -> m ()
G.unsafeSwap

-- | Replace the element at the given position and return the old element. No
-- bounds checks are performed.
unsafeExchange :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> a -> m a
{-# INLINE unsafeExchange #-}
unsafeExchange :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> Int -> a -> m a
unsafeExchange = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> Int -> a -> m a
G.unsafeExchange

-- Filling and copying
-- -------------------

-- | Set all elements of the vector to the given value.
set :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> a -> m ()
{-# INLINE set #-}
set :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> a -> m ()
set = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> a -> m ()
G.set

-- | Copy a vector. The two vectors must have the same length and may not
-- overlap.
copy :: (PrimMonad m, Storable a)
     => MVector (PrimState m) a   -- ^ target
     -> MVector (PrimState m) a   -- ^ source
     -> m ()
{-# INLINE copy #-}
copy :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
copy = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> v (PrimState m) a -> m ()
G.copy

-- | Copy a vector. The two vectors must have the same length and may not
-- overlap, but this is not checked.
unsafeCopy :: (PrimMonad m, Storable a)
           => MVector (PrimState m) a   -- ^ target
           -> MVector (PrimState m) a   -- ^ source
           -> m ()
{-# INLINE unsafeCopy #-}
unsafeCopy :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
unsafeCopy = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> v (PrimState m) a -> m ()
G.unsafeCopy

-- | Move the contents of a vector. The two vectors must have the same
-- length.
--
-- If the vectors do not overlap, then this is equivalent to 'copy'.
-- Otherwise, the copying is performed as if the source vector were
-- copied to a temporary vector and then the temporary vector was copied
-- to the target vector.
move :: (PrimMonad m, Storable a)
     => MVector (PrimState m) a   -- ^ target
     -> MVector (PrimState m) a   -- ^ source
     -> m ()
{-# INLINE move #-}
move :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
move = forall (m :: * -> *) (v :: * -> * -> *) a.
(HasCallStack, PrimMonad m, MVector v a) =>
v (PrimState m) a -> v (PrimState m) a -> m ()
G.move

-- | Move the contents of a vector. The two vectors must have the same
-- length, but this is not checked.
--
-- If the vectors do not overlap, then this is equivalent to 'unsafeCopy'.
-- Otherwise, the copying is performed as if the source vector were
-- copied to a temporary vector and then the temporary vector was copied
-- to the target vector.
unsafeMove :: (PrimMonad m, Storable a)
           => MVector (PrimState m) a   -- ^ target
           -> MVector (PrimState m) a   -- ^ source
           -> m ()
{-# INLINE unsafeMove #-}
unsafeMove :: forall (m :: * -> *) a.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> MVector (PrimState m) a -> m ()
unsafeMove = forall (m :: * -> *) (v :: * -> * -> *) a.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> v (PrimState m) a -> m ()
G.unsafeMove

-- Modifying vectors
-- -----------------

-- | Compute the (lexicographically) next permutation of the given vector in-place.
-- Returns False when the input is the last permutation.
nextPermutation :: (PrimMonad m, Storable e, Ord e) => MVector (PrimState m) e -> m Bool
{-# INLINE nextPermutation #-}
nextPermutation :: forall (m :: * -> *) e.
(PrimMonad m, Storable e, Ord e) =>
MVector (PrimState m) e -> m Bool
nextPermutation = forall (m :: * -> *) e (v :: * -> * -> *).
(PrimMonad m, Ord e, MVector v e) =>
v (PrimState m) e -> m Bool
G.nextPermutation

-- Folds
-- -----

-- | /O(n)/ Apply the monadic action to every element of the vector, discarding the results.
--
-- @since 0.12.3.0
mapM_ :: (PrimMonad m, Storable a) => (a -> m b) -> MVector (PrimState m) a -> m ()
{-# INLINE mapM_ #-}
mapM_ :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(a -> m b) -> MVector (PrimState m) a -> m ()
mapM_ = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(a -> m b) -> v (PrimState m) a -> m ()
G.mapM_

-- | /O(n)/ Apply the monadic action to every element of the vector and its index, discarding the results.
--
-- @since 0.12.3.0
imapM_ :: (PrimMonad m, Storable a) => (Int -> a -> m b) -> MVector (PrimState m) a -> m ()
{-# INLINE imapM_ #-}
imapM_ :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(Int -> a -> m b) -> MVector (PrimState m) a -> m ()
imapM_ = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(Int -> a -> m b) -> v (PrimState m) a -> m ()
G.imapM_

-- | /O(n)/ Apply the monadic action to every element of the vector,
-- discarding the results. It's the same as @flip mapM_@.
--
-- @since 0.12.3.0
forM_ :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m b) -> m ()
{-# INLINE forM_ #-}
forM_ :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (a -> m b) -> m ()
forM_ = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> (a -> m b) -> m ()
G.forM_

-- | /O(n)/ Apply the monadic action to every element of the vector
-- and its index, discarding the results. It's the same as @flip imapM_@.
--
-- @since 0.12.3.0
iforM_ :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
{-# INLINE iforM_ #-}
iforM_ :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
iforM_ = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
v (PrimState m) a -> (Int -> a -> m b) -> m ()
G.iforM_

-- | /O(n)/ Pure left fold.
--
-- @since 0.12.3.0
foldl :: (PrimMonad m, Storable a) => (b -> a -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldl #-}
foldl :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> a -> b) -> b -> MVector (PrimState m) a -> m b
foldl = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> a -> b) -> b -> v (PrimState m) a -> m b
G.foldl

-- | /O(n)/ Pure left fold with strict accumulator.
--
-- @since 0.12.3.0
foldl' :: (PrimMonad m, Storable a) => (b -> a -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldl' #-}
foldl' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> a -> b) -> b -> MVector (PrimState m) a -> m b
foldl' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> a -> b) -> b -> v (PrimState m) a -> m b
G.foldl'

-- | /O(n)/ Pure left fold using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldl :: (PrimMonad m, Storable a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldl #-}
ifoldl :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
ifoldl = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> Int -> a -> b) -> b -> v (PrimState m) a -> m b
G.ifoldl

-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldl' :: (PrimMonad m, Storable a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldl' #-}
ifoldl' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
ifoldl' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> Int -> a -> b) -> b -> v (PrimState m) a -> m b
G.ifoldl'

-- | /O(n)/ Pure right fold.
--
-- @since 0.12.3.0
foldr :: (PrimMonad m, Storable a) => (a -> b -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldr #-}
foldr :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(a -> b -> b) -> b -> MVector (PrimState m) a -> m b
foldr = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(a -> b -> b) -> b -> v (PrimState m) a -> m b
G.foldr

-- | /O(n)/ Pure right fold with strict accumulator.
--
-- @since 0.12.3.0
foldr' :: (PrimMonad m, Storable a) => (a -> b -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldr' #-}
foldr' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(a -> b -> b) -> b -> MVector (PrimState m) a -> m b
foldr' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(a -> b -> b) -> b -> v (PrimState m) a -> m b
G.foldr'

-- | /O(n)/ Pure right fold using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldr :: (PrimMonad m, Storable a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldr #-}
ifoldr :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
ifoldr = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(Int -> a -> b -> b) -> b -> v (PrimState m) a -> m b
G.ifoldr

-- | /O(n)/ Pure right fold with strict accumulator using a function applied
-- to each element and its index.
--
-- @since 0.12.3.0
ifoldr' :: (PrimMonad m, Storable a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldr' #-}
ifoldr' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
ifoldr' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(Int -> a -> b -> b) -> b -> v (PrimState m) a -> m b
G.ifoldr'

-- | /O(n)/ Monadic fold.
--
-- @since 0.12.3.0
foldM :: (PrimMonad m, Storable a) => (b -> a -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldM #-}
foldM :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> a -> m b) -> b -> MVector (PrimState m) a -> m b
foldM = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> a -> m b) -> b -> v (PrimState m) a -> m b
G.foldM

-- | /O(n)/ Monadic fold with strict accumulator.
--
-- @since 0.12.3.0
foldM' :: (PrimMonad m, Storable a) => (b -> a -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldM' #-}
foldM' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> a -> m b) -> b -> MVector (PrimState m) a -> m b
foldM' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> a -> m b) -> b -> v (PrimState m) a -> m b
G.foldM'

-- | /O(n)/ Monadic fold using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldM :: (PrimMonad m, Storable a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldM #-}
ifoldM :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
ifoldM = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> Int -> a -> m b) -> b -> v (PrimState m) a -> m b
G.ifoldM

-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldM' :: (PrimMonad m, Storable a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldM' #-}
ifoldM' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
ifoldM' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(b -> Int -> a -> m b) -> b -> v (PrimState m) a -> m b
G.ifoldM'

-- | /O(n)/ Monadic right fold.
--
-- @since 0.12.3.0
foldrM :: (PrimMonad m, Storable a) => (a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldrM #-}
foldrM :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
foldrM = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(a -> b -> m b) -> b -> v (PrimState m) a -> m b
G.foldrM

-- | /O(n)/ Monadic right fold with strict accumulator.
--
-- @since 0.12.3.0
foldrM' :: (PrimMonad m, Storable a) => (a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE foldrM' #-}
foldrM' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
foldrM' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(a -> b -> m b) -> b -> v (PrimState m) a -> m b
G.foldrM'

-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
--
-- @since 0.12.3.0
ifoldrM :: (PrimMonad m, Storable a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldrM #-}
ifoldrM :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
ifoldrM = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(Int -> a -> b -> m b) -> b -> v (PrimState m) a -> m b
G.ifoldrM

-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
-- to each element and its index.
--
-- @since 0.12.3.0
ifoldrM' :: (PrimMonad m, Storable a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
{-# INLINE ifoldrM' #-}
ifoldrM' :: forall (m :: * -> *) a b.
(PrimMonad m, Storable a) =>
(Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
ifoldrM' = forall (m :: * -> *) (v :: * -> * -> *) a b.
(PrimMonad m, MVector v a) =>
(Int -> a -> b -> m b) -> b -> v (PrimState m) a -> m b
G.ifoldrM'

-- Unsafe conversions
-- ------------------

-- | /O(1)/ Unsafely cast a mutable vector from one element type to another.
-- The operation just changes the type of the underlying pointer and does not
-- modify the elements.
--
-- The resulting vector contains as many elements as can fit into the
-- underlying memory block.
unsafeCast :: forall a b s.
              (Storable a, Storable b) => MVector s a -> MVector s b
{-# INLINE unsafeCast #-}
unsafeCast :: forall a b s.
(Storable a, Storable b) =>
MVector s a -> MVector s b
unsafeCast (MVector Int
n ForeignPtr a
fp)
  = forall s a. Int -> ForeignPtr a -> MVector s a
MVector ((Int
n forall a. Num a => a -> a -> a
* forall a. Storable a => a -> Int
sizeOf (forall a. HasCallStack => a
undefined :: a)) forall a. Integral a => a -> a -> a
`div` forall a. Storable a => a -> Int
sizeOf (forall a. HasCallStack => a
undefined :: b))
            (forall a b. ForeignPtr a -> ForeignPtr b
castForeignPtr ForeignPtr a
fp)

-- Raw pointers
-- ------------

-- | /O(1)/ Create a mutable vector from a 'ForeignPtr' with an offset and a length.
--
-- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
-- could have been frozen before the modification.
--
-- If your offset is 0, it is more efficient to use 'unsafeFromForeignPtr0'.
unsafeFromForeignPtr :: Storable a
                     => ForeignPtr a    -- ^ pointer
                     -> Int             -- ^ offset
                     -> Int             -- ^ length
                     -> MVector s a
{-# INLINE_FUSED unsafeFromForeignPtr #-}
unsafeFromForeignPtr :: forall a s. Storable a => ForeignPtr a -> Int -> Int -> MVector s a
unsafeFromForeignPtr ForeignPtr a
fp Int
i Int
n = forall a s. ForeignPtr a -> Int -> MVector s a
unsafeFromForeignPtr0 ForeignPtr a
fp' Int
n
    where
      fp' :: ForeignPtr a
fp' = forall a. (Ptr a -> Ptr a) -> ForeignPtr a -> ForeignPtr a
updPtr (forall a. Storable a => Ptr a -> Int -> Ptr a
`advancePtr` Int
i) ForeignPtr a
fp

{-# RULES
"unsafeFromForeignPtr fp 0 n -> unsafeFromForeignPtr0 fp n " forall fp n.
  unsafeFromForeignPtr fp 0 n = unsafeFromForeignPtr0 fp n   #-}


-- | /O(1)/ Create a mutable vector from a 'ForeignPtr' and a length.
--
-- It is assumed that the pointer points directly to the data (no offset).
-- Use 'unsafeFromForeignPtr' if you need to specify an offset.
--
-- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
-- could have been frozen before the modification.
unsafeFromForeignPtr0 :: ForeignPtr a    -- ^ pointer
                      -> Int             -- ^ length
                      -> MVector s a
{-# INLINE unsafeFromForeignPtr0 #-}
unsafeFromForeignPtr0 :: forall a s. ForeignPtr a -> Int -> MVector s a
unsafeFromForeignPtr0 ForeignPtr a
fp Int
n = forall s a. Int -> ForeignPtr a -> MVector s a
MVector Int
n ForeignPtr a
fp

-- | /O(1)/ Yield the underlying 'ForeignPtr' together with the offset to the data
-- and its length. Modifying the data through the 'ForeignPtr' is
-- unsafe if the vector could have been frozen before the modification.
unsafeToForeignPtr :: MVector s a -> (ForeignPtr a, Int, Int)
{-# INLINE unsafeToForeignPtr #-}
unsafeToForeignPtr :: forall s a. MVector s a -> (ForeignPtr a, Int, Int)
unsafeToForeignPtr (MVector Int
n ForeignPtr a
fp) = (ForeignPtr a
fp, Int
0, Int
n)

-- | /O(1)/ Yield the underlying 'ForeignPtr' together with its length.
--
-- You can assume that the pointer points directly to the data (no offset).
--
-- Modifying the data through the 'ForeignPtr' is unsafe if the vector could
-- have been frozen before the modification.
unsafeToForeignPtr0 :: MVector s a -> (ForeignPtr a, Int)
{-# INLINE unsafeToForeignPtr0 #-}
unsafeToForeignPtr0 :: forall s a. MVector s a -> (ForeignPtr a, Int)
unsafeToForeignPtr0 (MVector Int
n ForeignPtr a
fp) = (ForeignPtr a
fp, Int
n)

-- | Pass a pointer to the vector's data to the IO action. Modifying data
-- through the pointer is unsafe if the vector could have been frozen before
-- the modification.
unsafeWith :: Storable a => IOVector a -> (Ptr a -> IO b) -> IO b
{-# INLINE unsafeWith #-}
unsafeWith :: forall a b. Storable a => IOVector a -> (Ptr a -> IO b) -> IO b
unsafeWith (MVector Int
_ ForeignPtr a
fp) = forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr a
fp