{-# LANGUAGE BangPatterns #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE RankNTypes #-}
{-# LANGUAGE ScopedTypeVariables #-}
-- |
-- Module      : Data.Massiv.Array.Mutable
-- Copyright   : (c) Alexey Kuleshevich 2018-2021
-- License     : BSD3
-- Maintainer  : Alexey Kuleshevich <lehins@yandex.ru>
-- Stability   : experimental
-- Portability : non-portable
--
module Data.Massiv.Array.Mutable
  ( -- ** Size
    msize
    -- ** Element-wise mutation
  , read
  , readM
  , read'
  , write
  , write_
  , writeM
  , write'
  , modify
  , modify_
  , modifyM
  , modifyM_
  , modify'
  , swap
  , swap_
  , swapM
  , swapM_
  , swap'
  -- ** Operations on @MArray@
  -- *** Immutable conversion
  , thaw
  , thawS
  , freeze
  , freezeS
  -- *** Create mutable
  , new
  , newMArray
  , newMArray'
  , makeMArray
  , makeMArrayLinear
  , makeMArrayS
  , makeMArrayLinearS
  -- *** Create pure
  , createArray_
  , createArray
  , createArrayS_
  , createArrayS
  , createArrayST_
  , createArrayST
  -- *** Generate
  , generateArray
  , generateArrayLinear
  , generateArrayS
  , generateArrayLinearS
  -- *** Stateful worker threads
  , generateArrayWS
  , generateArrayLinearWS
  -- *** Unfold
  , unfoldrPrimM_
  , iunfoldrPrimM_
  , unfoldrPrimM
  , iunfoldrPrimM
  , unfoldlPrimM_
  , iunfoldlPrimM_
  , unfoldlPrimM
  , iunfoldlPrimM
  -- *** Mapping
  , forPrimM
  , forPrimM_
  , iforPrimM
  , iforPrimM_
  , iforLinearPrimM
  , iforLinearPrimM_
  -- *** Modify
  , withMArray
  , withMArray_
  , withMArrayS
  , withMArrayS_
  , withMArrayST
  , withMArrayST_
  -- *** Initialize
  , initialize
  , initializeNew
  -- ** Computation
  , Mutable
  , MArray
  , RealWorld
  , computeInto
  , loadArray
  , loadArrayS
  ) where

-- TODO: add fromListM, et al.

import Data.Maybe (fromMaybe)
import Control.Monad (void, when, unless, (>=>))
import Control.Monad.ST
import Control.Scheduler
import Data.Massiv.Core.Common
import Data.Massiv.Array.Mutable.Internal
import Prelude hiding (mapM, read)

-- | /O(n)/ - Initialize a new mutable array. All elements will be set to some default value. For
-- boxed arrays in will be a thunk with `Uninitialized` exception, while for others it will be
-- simply zeros.
--
-- @since 0.1.0
new ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix
  -> m (MArray (PrimState m) r ix e)
new :: Sz ix -> m (MArray (PrimState m) r ix e)
new = Maybe e -> Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Maybe e -> Sz ix -> m (MArray (PrimState m) r ix e)
initializeNew Maybe e
forall a. Maybe a
Nothing
{-# INLINE new #-}
{-# DEPRECATED new "In favor of a more robust and safer `newMArray` or a more consistently named `newMArray'`" #-}


-- | /O(n)/ - Initialize a new mutable array. All elements will be set to some default value. For
-- boxed arrays in will be a thunk with `Uninitialized` exception, while for others it will be
-- simply zeros. This is a partial function.
--
-- ==== __Examples__
--
-- >>> import Data.Massiv.Array
-- >>> marr <- newMArray' (Sz2 2 6) :: IO (MArray RealWorld P Ix2 Int)
-- >>> freeze Seq marr
-- Array P Seq (Sz (2 :. 6))
--   [ [ 0, 0, 0, 0, 0, 0 ]
--   , [ 0, 0, 0, 0, 0, 0 ]
--   ]
--
-- Or using @TypeApplications@:
--
-- >>> :set -XTypeApplications
-- >>> newMArray' @P @Ix2 @Int (Sz2 2 6) >>= freezeS
-- Array P Seq (Sz (2 :. 6))
--   [ [ 0, 0, 0, 0, 0, 0 ]
--   , [ 0, 0, 0, 0, 0, 0 ]
--   ]
-- >>> newMArray' @B @_ @Int (Sz2 2 6) >>= (`readM` 1)
-- *** Exception: Uninitialized
--
-- @since 0.6.0
newMArray' ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix
  -> m (MArray (PrimState m) r ix e)
newMArray' :: Sz ix -> m (MArray (PrimState m) r ix e)
newMArray' Sz ix
sz = Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz m (MArray (PrimState m) r ix e)
-> (MArray (PrimState m) r ix e -> m (MArray (PrimState m) r ix e))
-> m (MArray (PrimState m) r ix e)
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \MArray (PrimState m) r ix e
ma -> MArray (PrimState m) r ix e
ma MArray (PrimState m) r ix e
-> m () -> m (MArray (PrimState m) r ix e)
forall (f :: * -> *) a b. Functor f => a -> f b -> f a
<$ MArray (PrimState m) r ix e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> m ()
initialize MArray (PrimState m) r ix e
ma
{-# INLINE newMArray' #-}


-- | /O(n)/ - Make a mutable copy of a pure array. Keep in mind that both `freeze` and `thaw` trigger a
-- copy of the full array.
--
-- ==== __Example__
--
-- >>> import Data.Massiv.Array
-- >>> :set -XTypeApplications
-- >>> arr <- fromListsM @U @Ix2 @Double Par [[12,21],[13,31]]
-- >>> marr <- thaw arr
-- >>> modify marr (pure . (+ 10)) (1 :. 0)
-- Just 13.0
-- >>> freeze Par marr
-- Array U Par (Sz (2 :. 2))
--   [ [ 12.0, 21.0 ]
--   , [ 23.0, 31.0 ]
--   ]
--
-- @since 0.1.0
thaw :: forall r ix e m. (Mutable r ix e, MonadIO m) => Array r ix e -> m (MArray RealWorld r ix e)
thaw :: Array r ix e -> m (MArray RealWorld r ix e)
thaw Array r ix e
arr =
  IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e)
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e))
-> IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e)
forall a b. (a -> b) -> a -> b
$ do
    let sz :: Sz ix
sz = Array r ix e -> Sz ix
forall r ix e. Load r ix e => Array r ix e -> Sz ix
size Array r ix e
arr
        totalLength :: Int
totalLength = Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz
    MArray RealWorld r ix e
marr <- Sz ix -> IO (MArray (PrimState IO) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
    Comp -> (Scheduler IO () -> IO ()) -> IO ()
withMassivScheduler_ (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) ((Scheduler IO () -> IO ()) -> IO ())
-> (Scheduler IO () -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Scheduler IO ()
scheduler ->
      Int -> Int -> (Int -> Int -> IO ()) -> IO ()
forall a. Int -> Int -> (Int -> Int -> a) -> a
splitLinearly (Scheduler IO () -> Int
forall (m :: * -> *) a. Scheduler m a -> Int
numWorkers Scheduler IO ()
scheduler) Int
totalLength ((Int -> Int -> IO ()) -> IO ()) -> (Int -> Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Int
chunkLength Int
slackStart -> do
        Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> IO ()) -> IO ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Int
slackStart) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
chunkLength) ((Int -> IO ()) -> IO ()) -> (Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \ !Int
start ->
          Scheduler IO () -> IO () -> IO ()
forall (m :: * -> *). Scheduler m () -> m () -> m ()
scheduleWork_ Scheduler IO ()
scheduler (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$ Array r ix e
-> Int -> MArray (PrimState IO) r ix e -> Int -> Sz1 -> IO ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
Array r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeArrayLinearCopy Array r ix e
arr Int
start MArray RealWorld r ix e
MArray (PrimState IO) r ix e
marr Int
start (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz Int
chunkLength)
        let slackLength :: Int
slackLength = Int
totalLength Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
slackStart
        Bool -> IO () -> IO ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Int
slackLength Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
> Int
0) (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$
          Scheduler IO () -> IO () -> IO ()
forall (m :: * -> *). Scheduler m () -> m () -> m ()
scheduleWork_ Scheduler IO ()
scheduler (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$
          Array r ix e
-> Int -> MArray (PrimState IO) r ix e -> Int -> Sz1 -> IO ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
Array r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeArrayLinearCopy Array r ix e
arr Int
slackStart MArray RealWorld r ix e
MArray (PrimState IO) r ix e
marr Int
slackStart (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz Int
slackLength)
    MArray RealWorld r ix e -> IO (MArray RealWorld r ix e)
forall (f :: * -> *) a. Applicative f => a -> f a
pure MArray RealWorld r ix e
marr
{-# INLINE thaw #-}

-- | Same as `thaw`, but restrict computation to sequential only.
--
-- ==== __Example__
--
-- >>> import Data.Massiv.Array
-- >>> :set -XOverloadedLists
-- >>> thawS @P @Ix1 @Double [1..10]
-- >>> marr <- thawS @P @Ix1 @Double [1..10]
-- >>> writeM marr 5 100
-- >>> freezeS marr
-- Array P Seq (Sz1 10)
--   [ 1.0, 2.0, 3.0, 4.0, 5.0, 100.0, 7.0, 8.0, 9.0, 10.0 ]
--
-- @since 0.3.0
thawS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Array r ix e
  -> m (MArray (PrimState m) r ix e)
thawS :: Array r ix e -> m (MArray (PrimState m) r ix e)
thawS Array r ix e
arr = do
  MArray (PrimState m) r ix e
tmarr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew (Array r ix e -> Sz ix
forall r ix e. Load r ix e => Array r ix e -> Sz ix
size Array r ix e
arr)
  Array r ix e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
Array r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeArrayLinearCopy Array r ix e
arr Int
0 MArray (PrimState m) r ix e
tmarr Int
0 (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (Array r ix e -> Sz ix
forall r ix e. Load r ix e => Array r ix e -> Sz ix
size Array r ix e
arr)))
  MArray (PrimState m) r ix e -> m (MArray (PrimState m) r ix e)
forall (f :: * -> *) a. Applicative f => a -> f a
pure MArray (PrimState m) r ix e
tmarr
{-# INLINE thawS #-}


-- | /O(n)/ - Yield an immutable copy of the mutable array. Note that mutable representations
-- have to be the same.
--
-- ==== __Example__
--
-- >>> import Data.Massiv.Array
-- >>> marr <- newMArray @P @_ @Int (Sz2 2 6) 0
-- >>> forM_ (range Seq 0 (Ix2 1 4)) $ \ix -> write marr ix 9
-- >>> freeze Seq marr
-- Array P Seq (Sz (2 :. 6))
--   [ [ 9, 9, 9, 9, 0, 0 ]
--   , [ 0, 0, 0, 0, 0, 0 ]
--   ]
--
-- @since 0.1.0
freeze ::
     forall r ix e m. (Mutable r ix e, MonadIO m)
  => Comp
  -> MArray RealWorld r ix e
  -> m (Array r ix e)
freeze :: Comp -> MArray RealWorld r ix e -> m (Array r ix e)
freeze Comp
comp MArray RealWorld r ix e
smarr =
  IO (Array r ix e) -> m (Array r ix e)
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO (Array r ix e) -> m (Array r ix e))
-> IO (Array r ix e) -> m (Array r ix e)
forall a b. (a -> b) -> a -> b
$ do
    let sz :: Sz ix
sz = MArray RealWorld r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray RealWorld r ix e
smarr
        totalLength :: Int
totalLength = Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz
    MArray RealWorld r ix e
tmarr <- Sz ix -> IO (MArray (PrimState IO) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
    Comp -> (Scheduler IO () -> IO ()) -> IO ()
withMassivScheduler_ Comp
comp ((Scheduler IO () -> IO ()) -> IO ())
-> (Scheduler IO () -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Scheduler IO ()
scheduler ->
      Int -> Int -> (Int -> Int -> IO ()) -> IO ()
forall a. Int -> Int -> (Int -> Int -> a) -> a
splitLinearly (Scheduler IO () -> Int
forall (m :: * -> *) a. Scheduler m a -> Int
numWorkers Scheduler IO ()
scheduler) Int
totalLength ((Int -> Int -> IO ()) -> IO ()) -> (Int -> Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Int
chunkLength Int
slackStart -> do
        Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> IO ()) -> IO ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Int
slackStart) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
chunkLength) ((Int -> IO ()) -> IO ()) -> (Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \ !Int
start ->
          Scheduler IO () -> IO () -> IO ()
forall (m :: * -> *). Scheduler m () -> m () -> m ()
scheduleWork_ Scheduler IO ()
scheduler (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$ MArray (PrimState IO) r ix e
-> Int -> MArray (PrimState IO) r ix e -> Int -> Sz1 -> IO ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
MArray (PrimState m) r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeLinearCopy MArray RealWorld r ix e
MArray (PrimState IO) r ix e
smarr Int
start MArray RealWorld r ix e
MArray (PrimState IO) r ix e
tmarr Int
start (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz Int
chunkLength)
        let slackLength :: Int
slackLength = Int
totalLength Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
slackStart
        Bool -> IO () -> IO ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Int
slackLength Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
> Int
0) (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$
          Scheduler IO () -> IO () -> IO ()
forall (m :: * -> *). Scheduler m () -> m () -> m ()
scheduleWork_ Scheduler IO ()
scheduler (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$
          MArray (PrimState IO) r ix e
-> Int -> MArray (PrimState IO) r ix e -> Int -> Sz1 -> IO ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
MArray (PrimState m) r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeLinearCopy MArray RealWorld r ix e
MArray (PrimState IO) r ix e
smarr Int
slackStart MArray RealWorld r ix e
MArray (PrimState IO) r ix e
tmarr Int
slackStart (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz Int
slackLength)
    Comp -> MArray (PrimState IO) r ix e -> IO (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
comp MArray RealWorld r ix e
MArray (PrimState IO) r ix e
tmarr
{-# INLINE freeze #-}


-- | Same as `freeze`, but do the copy of supplied muable array sequentially. Also, unlike `freeze`
-- that has to be done in `IO`, `freezeS` can be used with `ST`.
--
-- @since 0.3.0
freezeS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => MArray (PrimState m) r ix e
  -> m (Array r ix e)
freezeS :: MArray (PrimState m) r ix e -> m (Array r ix e)
freezeS MArray (PrimState m) r ix e
smarr = do
  let sz :: Sz ix
sz = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
smarr
  MArray (PrimState m) r ix e
tmarr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
  MArray (PrimState m) r ix e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
forall r ix e ix' (m :: * -> *).
(Mutable r ix e, Mutable r ix' e, PrimMonad m) =>
MArray (PrimState m) r ix' e
-> Int -> MArray (PrimState m) r ix e -> Int -> Sz1 -> m ()
unsafeLinearCopy MArray (PrimState m) r ix e
smarr Int
0 MArray (PrimState m) r ix e
tmarr Int
0 (Int -> Sz1
forall ix. ix -> Sz ix
SafeSz (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz))
  Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
Seq MArray (PrimState m) r ix e
tmarr
{-# INLINE freezeS #-}


unsafeNewUninitialized ::
     (Load r' ix e, Mutable r ix e, PrimMonad m) => Array r' ix e -> m (MArray (PrimState m) r ix e)
unsafeNewUninitialized :: Array r' ix e -> m (MArray (PrimState m) r ix e)
unsafeNewUninitialized !Array r' ix e
arr = Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew (Sz ix -> Maybe (Sz ix) -> Sz ix
forall a. a -> Maybe a -> a
fromMaybe Sz ix
forall ix. Index ix => Sz ix
zeroSz (Array r' ix e -> Maybe (Sz ix)
forall r ix e. Load r ix e => Array r ix e -> Maybe (Sz ix)
maxSize Array r' ix e
arr))
{-# INLINE unsafeNewUninitialized #-}


-- | Load sequentially a pure array into the newly created mutable array.
--
-- @since 0.3.0
loadArrayS ::
     forall r ix e r' m. (Load r' ix e, Mutable r ix e, PrimMonad m)
  => Array r' ix e
  -> m (MArray (PrimState m) r ix e)
loadArrayS :: Array r' ix e -> m (MArray (PrimState m) r ix e)
loadArrayS Array r' ix e
arr = do
  MArray (PrimState m) r ix e
marr <- Array r' ix e -> m (MArray (PrimState m) r ix e)
forall r' ix e r (m :: * -> *).
(Load r' ix e, Mutable r ix e, PrimMonad m) =>
Array r' ix e -> m (MArray (PrimState m) r ix e)
unsafeNewUninitialized Array r' ix e
arr
  MArray (PrimState m) r ix e
-> Array r' ix e -> m (MArray (PrimState m) r ix e)
forall r ix e r' (m :: * -> *).
(Load r ix e, Mutable r' ix e, PrimMonad m) =>
MArray (PrimState m) r' ix e
-> Array r ix e -> m (MArray (PrimState m) r' ix e)
unsafeLoadIntoS MArray (PrimState m) r ix e
marr Array r' ix e
arr
{-# INLINE loadArrayS #-}


-- | Load a pure array into the newly created mutable array, while respecting computation startegy.
--
-- @since 0.3.0
loadArray ::
     forall r ix e r' m. (Load r' ix e, Mutable r ix e, MonadIO m)
  => Array r' ix e
  -> m (MArray RealWorld r ix e)
loadArray :: Array r' ix e -> m (MArray RealWorld r ix e)
loadArray Array r' ix e
arr =
  IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e)
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e))
-> IO (MArray RealWorld r ix e) -> m (MArray RealWorld r ix e)
forall a b. (a -> b) -> a -> b
$ do
    MArray RealWorld r ix e
marr <- Array r' ix e -> IO (MArray (PrimState IO) r ix e)
forall r' ix e r (m :: * -> *).
(Load r' ix e, Mutable r ix e, PrimMonad m) =>
Array r' ix e -> m (MArray (PrimState m) r ix e)
unsafeNewUninitialized Array r' ix e
arr
    MArray RealWorld r ix e
-> Array r' ix e -> IO (MArray RealWorld r ix e)
forall r ix e r' (m :: * -> *).
(Load r ix e, Mutable r' ix e, MonadIO m) =>
MArray RealWorld r' ix e
-> Array r ix e -> m (MArray RealWorld r' ix e)
unsafeLoadIntoM MArray RealWorld r ix e
marr Array r' ix e
arr
{-# INLINE loadArray #-}



-- | Compute an Array while loading the results into the supplied mutable target array. Number of
-- elements for arrays must agree, otherwise `SizeElementsMismatchException` exception is thrown.
--
-- @since 0.1.3
computeInto ::
     (Load r' ix' e, Mutable r ix e, MonadIO m)
  => MArray RealWorld r ix e -- ^ Target Array
  -> Array r' ix' e -- ^ Array to load
  -> m ()
computeInto :: MArray RealWorld r ix e -> Array r' ix' e -> m ()
computeInto !MArray RealWorld r ix e
mArr !Array r' ix' e
arr =
  IO () -> m ()
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
    Bool -> IO () -> IO ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
unless (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray RealWorld r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray RealWorld r ix e
mArr) Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Sz ix' -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (Array r' ix' e -> Sz ix'
forall r ix e. Load r ix e => Array r ix e -> Sz ix
size Array r' ix' e
arr)) (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$
      SizeException -> IO ()
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (SizeException -> IO ()) -> SizeException -> IO ()
forall a b. (a -> b) -> a -> b
$ Sz ix -> Sz ix' -> SizeException
forall ix ix'.
(Index ix, Index ix') =>
Sz ix -> Sz ix' -> SizeException
SizeElementsMismatchException (MArray RealWorld r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray RealWorld r ix e
mArr) (Array r' ix' e -> Sz ix'
forall r ix e. Load r ix e => Array r ix e -> Sz ix
size Array r' ix' e
arr)
    Comp -> (Scheduler IO () -> IO ()) -> IO ()
withMassivScheduler_ (Array r' ix' e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r' ix' e
arr) ((Scheduler IO () -> IO ()) -> IO ())
-> (Scheduler IO () -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Scheduler IO ()
scheduler ->
      Scheduler IO () -> Array r' ix' e -> (Int -> e -> IO ()) -> IO ()
forall r ix e (m :: * -> *).
(Load r ix e, Monad m) =>
Scheduler m () -> Array r ix e -> (Int -> e -> m ()) -> m ()
loadArrayM Scheduler IO ()
scheduler Array r' ix' e
arr (MArray (PrimState IO) r ix e -> Int -> e -> IO ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray RealWorld r ix e
MArray (PrimState IO) r ix e
mArr)
{-# INLINE computeInto #-}


-- | Create a mutable array using an index aware generating action.
--
-- @since 0.3.0
makeMArrayS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the create array
  -> (ix -> m e) -- ^ Element generating action
  -> m (MArray (PrimState m) r ix e)
makeMArrayS :: Sz ix -> (ix -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayS Sz ix
sz ix -> m e
f = Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayLinearS Sz ix
sz (ix -> m e
f (ix -> m e) -> (Int -> ix) -> Int -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex Sz ix
sz)
{-# INLINE makeMArrayS #-}


-- | Same as `makeMArrayS`, but index supplied to the action is row-major linear index.
--
-- @since 0.3.0
makeMArrayLinearS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix
  -> (Int -> m e)
  -> m (MArray (PrimState m) r ix e)
makeMArrayLinearS :: Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayLinearS Sz ix
sz Int -> m e
f = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m ()) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) (\ !Int
i -> Int -> m e
f Int
i m e -> (e -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i)
  MArray (PrimState m) r ix e -> m (MArray (PrimState m) r ix e)
forall (m :: * -> *) a. Monad m => a -> m a
return MArray (PrimState m) r ix e
marr
{-# INLINE makeMArrayLinearS #-}

-- | Just like `makeMArrayS`, but also accepts computation strategy and runs in `IO`.
--
-- @since 0.3.0
makeMArray ::
     forall r ix e m. (PrimMonad m, MonadUnliftIO m, Mutable r ix e)
  => Comp
  -> Sz ix
  -> (ix -> m e)
  -> m (MArray (PrimState m) r ix e)
makeMArray :: Comp -> Sz ix -> (ix -> m e) -> m (MArray (PrimState m) r ix e)
makeMArray Comp
comp Sz ix
sz ix -> m e
f = Comp -> Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(PrimMonad m, MonadUnliftIO m, Mutable r ix e) =>
Comp -> Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayLinear Comp
comp Sz ix
sz (ix -> m e
f (ix -> m e) -> (Int -> ix) -> Int -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex Sz ix
sz)
{-# INLINE makeMArray #-}


-- | Just like `makeMArrayLinearS`, but also accepts computation strategy and runs in `IO`.
--
-- @since 0.3.0
makeMArrayLinear ::
     forall r ix e m. (PrimMonad m, MonadUnliftIO m, Mutable r ix e)
  => Comp
  -> Sz ix
  -> (Int -> m e)
  -> m (MArray (PrimState m) r ix e)
makeMArrayLinear :: Comp -> Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayLinear Comp
comp Sz ix
sz Int -> m e
f = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
  Comp -> (Scheduler m () -> m ()) -> m ()
forall (m :: * -> *) a b.
MonadUnliftIO m =>
Comp -> (Scheduler m a -> m b) -> m ()
withScheduler_ Comp
comp ((Scheduler m () -> m ()) -> m ())
-> (Scheduler m () -> m ()) -> m ()
forall a b. (a -> b) -> a -> b
$ \Scheduler m ()
scheduler ->
    Scheduler m () -> Int -> (Int -> m e) -> (Int -> e -> m ()) -> m ()
forall (m :: * -> *) b c.
Monad m =>
Scheduler m () -> Int -> (Int -> m b) -> (Int -> b -> m c) -> m ()
splitLinearlyWithM_ Scheduler m ()
scheduler (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz) Int -> m e
f (MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr)
  MArray (PrimState m) r ix e -> m (MArray (PrimState m) r ix e)
forall (m :: * -> *) a. Monad m => a -> m a
return MArray (PrimState m) r ix e
marr
{-# INLINE makeMArrayLinear #-}




-- | Create a new array by supplying an action that will fill the new blank mutable array. Use
-- `createArray` if you'd like to keep the result of the filling function.
--
-- ====__Examples__
--
-- >>> :set -XTypeApplications
-- >>> import Data.Massiv.Array
-- >>> createArray_ @P @_ @Int Seq (Sz1 2) (\ s marr -> scheduleWork s (writeM marr 0 10) >> scheduleWork s (writeM marr 1 11))
-- Array P Seq (Sz1 2)
--   [ 10, 11 ]
--
-- @since 0.3.0
--
createArray_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m, MonadUnliftIO m)
  => Comp -- ^ Computation strategy to use after `MArray` gets frozen and onward.
  -> Sz ix -- ^ Size of the newly created array
  -> (Scheduler m () -> MArray (PrimState m) r ix e -> m a)
  -- ^ An action that should fill all elements of the brand new mutable array
  -> m (Array r ix e)
createArray_ :: Comp
-> Sz ix
-> (Scheduler m () -> MArray (PrimState m) r ix e -> m a)
-> m (Array r ix e)
createArray_ Comp
comp Sz ix
sz Scheduler m () -> MArray (PrimState m) r ix e -> m a
action = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
new Sz ix
sz
  Comp -> (Scheduler m () -> m a) -> m ()
forall (m :: * -> *) a b.
MonadUnliftIO m =>
Comp -> (Scheduler m a -> m b) -> m ()
withScheduler_ Comp
comp (Scheduler m () -> MArray (PrimState m) r ix e -> m a
`action` MArray (PrimState m) r ix e
marr)
  Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
comp MArray (PrimState m) r ix e
marr
{-# INLINE createArray_ #-}

-- | Just like `createArray_`, but together with `Array` it returns results of scheduled filling
-- actions.
--
-- @since 0.3.0
--
createArray ::
     forall r ix e a m b. (Mutable r ix e, PrimMonad m, MonadUnliftIO m)
  => Comp -- ^ Computation strategy to use after `MArray` gets frozen and onward.
  -> Sz ix -- ^ Size of the newly created array
  -> (Scheduler m a -> MArray (PrimState m) r ix e -> m b)
  -- ^ An action that should fill all elements of the brand new mutable array
  -> m ([a], Array r ix e)
createArray :: Comp
-> Sz ix
-> (Scheduler m a -> MArray (PrimState m) r ix e -> m b)
-> m ([a], Array r ix e)
createArray Comp
comp Sz ix
sz Scheduler m a -> MArray (PrimState m) r ix e -> m b
action = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
new Sz ix
sz
  [a]
a <- Comp -> (Scheduler m a -> m b) -> m [a]
forall (m :: * -> *) a b.
MonadUnliftIO m =>
Comp -> (Scheduler m a -> m b) -> m [a]
withScheduler Comp
comp (Scheduler m a -> MArray (PrimState m) r ix e -> m b
`action` MArray (PrimState m) r ix e
marr)
  Array r ix e
arr <- Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
comp MArray (PrimState m) r ix e
marr
  ([a], Array r ix e) -> m ([a], Array r ix e)
forall (m :: * -> *) a. Monad m => a -> m a
return ([a]
a, Array r ix e
arr)
{-# INLINE createArray #-}


-- | Create a new array by supplying an action that will fill the new blank mutable array. Use
-- `createArrayS` if you'd like to keep the result of the filling function.
--
-- ====__Examples__
--
-- >>> :set -XTypeApplications
-- >>> import Data.Massiv.Array
-- >>> createArrayS_ @P @_ @Int (Sz1 2) (\ marr -> write marr 0 10 >> write marr 1 12)
-- Array P Seq (Sz1 2)
--   [ 10, 12 ]
--
-- @since 0.3.0
createArrayS_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the newly created array
  -> (MArray (PrimState m) r ix e -> m a)
  -- ^ An action that should fill all elements of the brand new mutable array
  -> m (Array r ix e)
createArrayS_ :: Sz ix -> (MArray (PrimState m) r ix e -> m a) -> m (Array r ix e)
createArrayS_ Sz ix
sz MArray (PrimState m) r ix e -> m a
action = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
createArrayS Sz ix
sz MArray (PrimState m) r ix e -> m a
action
{-# INLINE createArrayS_ #-}

-- | Just like `createArray_`, but together with `Array` it returns the result of the filling action.
--
-- @since 0.3.0
createArrayS ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the newly created array
  -> (MArray (PrimState m) r ix e -> m a)
  -- ^ An action that should fill all elements of the brand new mutable array
  -> m (a, Array r ix e)
createArrayS :: Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
createArrayS Sz ix
sz MArray (PrimState m) r ix e -> m a
action = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
new Sz ix
sz
  a
a <- MArray (PrimState m) r ix e -> m a
action MArray (PrimState m) r ix e
marr
  Array r ix e
arr <- Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
Seq MArray (PrimState m) r ix e
marr
  (a, Array r ix e) -> m (a, Array r ix e)
forall (m :: * -> *) a. Monad m => a -> m a
return (a
a, Array r ix e
arr)
{-# INLINE createArrayS #-}

-- | Just like `createArrayS_`, but restricted to `ST`.
--
-- @since 0.3.0
createArrayST_ ::
     forall r ix e a. Mutable r ix e
  => Sz ix
  -> (forall s. MArray s r ix e -> ST s a)
  -> Array r ix e
createArrayST_ :: Sz ix -> (forall s. MArray s r ix e -> ST s a) -> Array r ix e
createArrayST_ Sz ix
sz forall s. MArray s r ix e -> ST s a
action = (forall s. ST s (Array r ix e)) -> Array r ix e
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s (Array r ix e)) -> Array r ix e)
-> (forall s. ST s (Array r ix e)) -> Array r ix e
forall a b. (a -> b) -> a -> b
$ Sz ix
-> (MArray (PrimState (ST s)) r ix e -> ST s a)
-> ST s (Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (MArray (PrimState m) r ix e -> m a) -> m (Array r ix e)
createArrayS_ Sz ix
sz MArray (PrimState (ST s)) r ix e -> ST s a
forall s. MArray s r ix e -> ST s a
action
{-# INLINE createArrayST_ #-}


-- | Just like `createArrayS`, but restricted to `ST`.
--
-- @since 0.2.6
createArrayST ::
     forall r ix e a. Mutable r ix e
  => Sz ix
  -> (forall s. MArray s r ix e -> ST s a)
  -> (a, Array r ix e)
createArrayST :: Sz ix -> (forall s. MArray s r ix e -> ST s a) -> (a, Array r ix e)
createArrayST Sz ix
sz forall s. MArray s r ix e -> ST s a
action = (forall s. ST s (a, Array r ix e)) -> (a, Array r ix e)
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s (a, Array r ix e)) -> (a, Array r ix e))
-> (forall s. ST s (a, Array r ix e)) -> (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ Sz ix
-> (MArray (PrimState (ST s)) r ix e -> ST s a)
-> ST s (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
createArrayS Sz ix
sz MArray (PrimState (ST s)) r ix e -> ST s a
forall s. MArray s r ix e -> ST s a
action
{-# INLINE createArrayST #-}


-- | Sequentially generate a pure array. Much like `makeArray` creates a pure array this
-- function will use `Mutable` interface to generate a pure `Array` in the end, except that
-- computation strategy is set to `Seq`. Element producing function no longer has to be pure
-- but is a stateful action, becuase it is restricted to `PrimMonad` thus allows for sharing
-- the state between computation of each element.
--
-- ====__Examples__
--
-- >>> import Data.Massiv.Array
-- >>> import Data.IORef
-- >>> ref <- newIORef (0 :: Int)
-- >>> generateArrayS (Sz1 6) (\ i -> modifyIORef' ref (+i) >> print i >> pure i) :: IO (Array U Ix1 Int)
-- 0
-- 1
-- 2
-- 3
-- 4
-- 5
-- Array U Seq (Sz1 6)
--   [ 0, 1, 2, 3, 4, 5 ]
-- >>> readIORef ref
-- 15
--
-- @since 0.2.6
generateArrayS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Resulting size of the array
  -> (ix -> m e) -- ^ Element producing generator
  -> m (Array r ix e)
generateArrayS :: Sz ix -> (ix -> m e) -> m (Array r ix e)
generateArrayS Sz ix
sz ix -> m e
gen = Sz ix -> (Int -> m e) -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (Int -> m e) -> m (Array r ix e)
generateArrayLinearS Sz ix
sz (ix -> m e
gen (ix -> m e) -> (Int -> ix) -> Int -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex Sz ix
sz)
{-# INLINE generateArrayS #-}

-- | Same as `generateArray` but with action that accepts row-major linear index.
--
-- @since 0.3.0
generateArrayLinearS ::
     forall r ix e m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Resulting size of the array
  -> (Int -> m e) -- ^ Element producing generator
  -> m (Array r ix e)
generateArrayLinearS :: Sz ix -> (Int -> m e) -> m (Array r ix e)
generateArrayLinearS Sz ix
sz Int -> m e
gen = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m ()) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) ((Int -> m ()) -> m ()) -> (Int -> m ()) -> m ()
forall a b. (a -> b) -> a -> b
$ \Int
i -> Int -> m e
gen Int
i m e -> (e -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i
  Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
Seq MArray (PrimState m) r ix e
marr
{-# INLINE generateArrayLinearS #-}


-- | Just like `generateArrayS`, except this generator __will__ respect the supplied computation
-- strategy, and for that reason it is restricted to `IO`.
--
-- @since 0.2.6
generateArray ::
     forall r ix e m. (MonadUnliftIO m, PrimMonad m, Mutable r ix e)
  => Comp
  -> Sz ix
  -> (ix -> m e)
  -> m (Array r ix e)
generateArray :: Comp -> Sz ix -> (ix -> m e) -> m (Array r ix e)
generateArray Comp
comp Sz ix
sz ix -> m e
f = Comp -> Sz ix -> (Int -> m e) -> m (Array r ix e)
forall r ix e (m :: * -> *).
(MonadUnliftIO m, PrimMonad m, Mutable r ix e) =>
Comp -> Sz ix -> (Int -> m e) -> m (Array r ix e)
generateArrayLinear Comp
comp Sz ix
sz (ix -> m e
f (ix -> m e) -> (Int -> ix) -> Int -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex Sz ix
sz)
{-# INLINE generateArray #-}

-- | Just like `generateArray`, except generating action will receive a row-major linear
-- index.
--
-- @since 0.3.0
generateArrayLinear ::
     forall r ix e m. (MonadUnliftIO m, PrimMonad m, Mutable r ix e)
  => Comp
  -> Sz ix
  -> (Int -> m e)
  -> m (Array r ix e)
generateArrayLinear :: Comp -> Sz ix -> (Int -> m e) -> m (Array r ix e)
generateArrayLinear Comp
comp Sz ix
sz Int -> m e
f = Comp -> Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(PrimMonad m, MonadUnliftIO m, Mutable r ix e) =>
Comp -> Sz ix -> (Int -> m e) -> m (MArray (PrimState m) r ix e)
makeMArrayLinear Comp
comp Sz ix
sz Int -> m e
f m (MArray (PrimState m) r ix e)
-> (MArray (PrimState m) r ix e -> m (Array r ix e))
-> m (Array r ix e)
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze Comp
comp
{-# INLINE generateArrayLinear #-}


-- | Same as `generateArrayWS`, but use linear indexing instead.
--
-- @since 0.3.4
generateArrayLinearWS ::
     forall r ix e s m. (Mutable r ix e, MonadUnliftIO m, PrimMonad m)
  => WorkerStates s
  -> Sz ix
  -> (Int -> s -> m e)
  -> m (Array r ix e)
generateArrayLinearWS :: WorkerStates s -> Sz ix -> (Int -> s -> m e) -> m (Array r ix e)
generateArrayLinearWS WorkerStates s
states Sz ix
sz Int -> s -> m e
make = do
  MArray (PrimState m) r ix e
marr <- Sz ix -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> m (MArray (PrimState m) r ix e)
unsafeNew Sz ix
sz
  WorkerStates s -> (SchedulerWS s m () -> m ()) -> m ()
forall (m :: * -> *) s b.
MonadUnliftIO m =>
WorkerStates s -> (SchedulerWS s m () -> m b) -> m ()
withSchedulerWS_ WorkerStates s
states ((SchedulerWS s m () -> m ()) -> m ())
-> (SchedulerWS s m () -> m ()) -> m ()
forall a b. (a -> b) -> a -> b
$ \SchedulerWS s m ()
schedulerWS ->
    SchedulerWS s m ()
-> Int -> (Int -> s -> m e) -> (Int -> e -> m ()) -> m ()
forall (m :: * -> *) s b c.
Monad m =>
SchedulerWS s m ()
-> Int -> (Int -> s -> m b) -> (Int -> b -> m c) -> m ()
splitLinearlyWithStatefulM_
      SchedulerWS s m ()
schedulerWS
      (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz)
      Int -> s -> m e
make
      (MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr)
  Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze (WorkerStates s -> Comp
forall s. WorkerStates s -> Comp
workerStatesComp WorkerStates s
states) MArray (PrimState m) r ix e
marr
{-# INLINE generateArrayLinearWS #-}

-- | Use per worker thread state while generating elements of the array. Very useful for
-- things that are not thread safe.
--
-- @since 0.3.4
generateArrayWS ::
     forall r ix e s m. (Mutable r ix e, MonadUnliftIO m, PrimMonad m)
  => WorkerStates s
  -> Sz ix
  -> (ix -> s -> m e)
  -> m (Array r ix e)
generateArrayWS :: WorkerStates s -> Sz ix -> (ix -> s -> m e) -> m (Array r ix e)
generateArrayWS WorkerStates s
states Sz ix
sz ix -> s -> m e
make = WorkerStates s -> Sz ix -> (Int -> s -> m e) -> m (Array r ix e)
forall r ix e s (m :: * -> *).
(Mutable r ix e, MonadUnliftIO m, PrimMonad m) =>
WorkerStates s -> Sz ix -> (Int -> s -> m e) -> m (Array r ix e)
generateArrayLinearWS WorkerStates s
states Sz ix
sz (ix -> s -> m e
make (ix -> s -> m e) -> (Int -> ix) -> Int -> s -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex Sz ix
sz)
{-# INLINE generateArrayWS #-}


-- | Sequentially unfold an array from the left.
--
-- ====__Examples__
--
-- Create an array with Fibonacci numbers while performing and `IO` action on the accumulator for
-- each element of the array.
--
-- >>> import Data.Massiv.Array
-- >>> unfoldrPrimM_ (Sz1 10) (\a@(f0, f1) -> let fn = f0 + f1 in print a >> return (f0, (f1, fn))) (0, 1) :: IO (Array P Ix1 Int)
-- (0,1)
-- (1,1)
-- (1,2)
-- (2,3)
-- (3,5)
-- (5,8)
-- (8,13)
-- (13,21)
-- (21,34)
-- (34,55)
-- Array P Seq (Sz1 10)
--   [ 0, 1, 1, 2, 3, 5, 8, 13, 21, 34 ]
--
-- @since 0.3.0
unfoldrPrimM_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> m (e, a)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (Array r ix e)
unfoldrPrimM_ :: Sz ix -> (a -> m (e, a)) -> a -> m (Array r ix e)
unfoldrPrimM_ Sz ix
sz a -> m (e, a)
gen a
acc0 = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Sz ix -> (a -> m (e, a)) -> a -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (a -> m (e, a)) -> a -> m (a, Array r ix e)
unfoldrPrimM Sz ix
sz a -> m (e, a)
gen a
acc0
{-# INLINE unfoldrPrimM_ #-}

-- | Same as `unfoldrPrimM_` but do the unfolding with index aware function.
--
-- @since 0.3.0
iunfoldrPrimM_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> ix -> m (e, a)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (Array r ix e)
iunfoldrPrimM_ :: Sz ix -> (a -> ix -> m (e, a)) -> a -> m (Array r ix e)
iunfoldrPrimM_ Sz ix
sz a -> ix -> m (e, a)
gen a
acc0 = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Sz ix -> (a -> ix -> m (e, a)) -> a -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (a -> ix -> m (e, a)) -> a -> m (a, Array r ix e)
iunfoldrPrimM Sz ix
sz a -> ix -> m (e, a)
gen a
acc0
{-# INLINE iunfoldrPrimM_ #-}


-- | Just like `iunfoldrPrimM_`, but also returns the final value of the accumulator.
--
-- @since 0.3.0
iunfoldrPrimM ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> ix -> m (e, a)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (a, Array r ix e)
iunfoldrPrimM :: Sz ix -> (a -> ix -> m (e, a)) -> a -> m (a, Array r ix e)
iunfoldrPrimM Sz ix
sz a -> ix -> m (e, a)
gen a
acc0 =
  Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
unsafeCreateArrayS Sz ix
sz ((MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e))
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ \MArray (PrimState m) r ix e
marr ->
    let sz' :: Sz ix
sz' = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
     in Sz ix
-> Int
-> Int
-> Int
-> (Int -> Int -> Bool)
-> a
-> (Int -> ix -> a -> m a)
-> m a
forall ix (m :: * -> *) a.
(Index ix, Monad m) =>
Sz ix
-> Int
-> Int
-> Int
-> (Int -> Int -> Bool)
-> a
-> (Int -> ix -> a -> m a)
-> m a
iterLinearM Sz ix
sz' Int
0 (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz') Int
1 Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
(<) a
acc0 ((Int -> ix -> a -> m a) -> m a) -> (Int -> ix -> a -> m a) -> m a
forall a b. (a -> b) -> a -> b
$ \ !Int
i ix
ix !a
acc -> do
          (e
e, a
acc') <- a -> ix -> m (e, a)
gen a
acc ix
ix
          MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i e
e
          a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure a
acc'
{-# INLINE iunfoldrPrimM #-}

-- | Just like `iunfoldrPrimM`, but do the unfolding with index aware function.
--
-- @since 0.3.0
unfoldrPrimM ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> m (e, a)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (a, Array r ix e)
unfoldrPrimM :: Sz ix -> (a -> m (e, a)) -> a -> m (a, Array r ix e)
unfoldrPrimM Sz ix
sz a -> m (e, a)
gen a
acc0 =
  Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
unsafeCreateArrayS Sz ix
sz ((MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e))
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ \MArray (PrimState m) r ix e
marr ->
    let sz' :: Sz ix
sz' = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
     in Int
-> (Int -> Bool) -> (Int -> Int) -> a -> (Int -> a -> m a) -> m a
forall (m :: * -> *) a.
Monad m =>
Int
-> (Int -> Bool) -> (Int -> Int) -> a -> (Int -> a -> m a) -> m a
loopM Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz') (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) a
acc0 ((Int -> a -> m a) -> m a) -> (Int -> a -> m a) -> m a
forall a b. (a -> b) -> a -> b
$ \ !Int
i !a
acc -> do
          (e
e, a
acc') <- a -> m (e, a)
gen a
acc
          MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i e
e
          a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure a
acc'
{-# INLINE unfoldrPrimM #-}

-- | Sequentially unfold an array from the left.
--
-- ====__Examples__
--
-- Create an array with Fibonacci numbers starting at the end while performing and `IO` action on
-- the accumulator for each element of the array.
--
-- >>> import Data.Massiv.Array
-- >>> unfoldlPrimM_ (Sz1 10) (\a@(f0, f1) -> let fn = f0 + f1 in print a >> return ((f1, fn), f0)) (0, 1) :: IO (Array P Ix1 Int)
-- (0,1)
-- (1,1)
-- (1,2)
-- (2,3)
-- (3,5)
-- (5,8)
-- (8,13)
-- (13,21)
-- (21,34)
-- (34,55)
-- Array P Seq (Sz1 10)
--   [ 34, 21, 13, 8, 5, 3, 2, 1, 1, 0 ]
--
-- @since 0.3.0
unfoldlPrimM_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> m (a, e)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (Array r ix e)
unfoldlPrimM_ :: Sz ix -> (a -> m (a, e)) -> a -> m (Array r ix e)
unfoldlPrimM_ Sz ix
sz a -> m (a, e)
gen a
acc0 = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Sz ix -> (a -> m (a, e)) -> a -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (a -> m (a, e)) -> a -> m (a, Array r ix e)
unfoldlPrimM Sz ix
sz a -> m (a, e)
gen a
acc0
{-# INLINE unfoldlPrimM_ #-}

-- | Same as `unfoldlPrimM_` but do the unfolding with index aware function.
--
-- @since 0.3.0
iunfoldlPrimM_ ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> ix -> m (a, e)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (Array r ix e)
iunfoldlPrimM_ :: Sz ix -> (a -> ix -> m (a, e)) -> a -> m (Array r ix e)
iunfoldlPrimM_ Sz ix
sz a -> ix -> m (a, e)
gen a
acc0 = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Sz ix -> (a -> ix -> m (a, e)) -> a -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix -> (a -> ix -> m (a, e)) -> a -> m (a, Array r ix e)
iunfoldlPrimM Sz ix
sz a -> ix -> m (a, e)
gen a
acc0
{-# INLINE iunfoldlPrimM_ #-}


-- | Just like `iunfoldlPrimM_`, but also returns the final value of the accumulator.
--
-- @since 0.3.0
iunfoldlPrimM ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> ix -> m (a, e)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (a, Array r ix e)
iunfoldlPrimM :: Sz ix -> (a -> ix -> m (a, e)) -> a -> m (a, Array r ix e)
iunfoldlPrimM Sz ix
sz a -> ix -> m (a, e)
gen a
acc0 =
  Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
unsafeCreateArrayS Sz ix
sz ((MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e))
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ \MArray (PrimState m) r ix e
marr ->
    let sz' :: Sz ix
sz' = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
     in Sz ix
-> Int
-> Int
-> Int
-> (Int -> Int -> Bool)
-> a
-> (Int -> ix -> a -> m a)
-> m a
forall ix (m :: * -> *) a.
(Index ix, Monad m) =>
Sz ix
-> Int
-> Int
-> Int
-> (Int -> Int -> Bool)
-> a
-> (Int -> ix -> a -> m a)
-> m a
iterLinearM Sz ix
sz' (Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz' Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
1) Int
0 (Int -> Int
forall a. Num a => a -> a
negate Int
1) Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
(>=) a
acc0 ((Int -> ix -> a -> m a) -> m a) -> (Int -> ix -> a -> m a) -> m a
forall a b. (a -> b) -> a -> b
$ \ !Int
i ix
ix !a
acc -> do
          (a
acc', e
e) <- a -> ix -> m (a, e)
gen a
acc ix
ix
          MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i e
e
          a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure a
acc'
{-# INLINE iunfoldlPrimM #-}

-- | Just like `iunfoldlPrimM`, but do the unfolding with index aware function.
--
-- @since 0.3.0
unfoldlPrimM ::
     forall r ix e a m. (Mutable r ix e, PrimMonad m)
  => Sz ix -- ^ Size of the desired array
  -> (a -> m (a, e)) -- ^ Unfolding action
  -> a -- ^ Initial accumulator
  -> m (a, Array r ix e)
unfoldlPrimM :: Sz ix -> (a -> m (a, e)) -> a -> m (a, Array r ix e)
unfoldlPrimM Sz ix
sz a -> m (a, e)
gen a
acc0 =
  Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e a (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Sz ix
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
unsafeCreateArrayS Sz ix
sz ((MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e))
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ \MArray (PrimState m) r ix e
marr ->
    let sz' :: Sz ix
sz' = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
     in Int
-> (Int -> Bool) -> (Int -> Int) -> a -> (Int -> a -> m a) -> m a
forall (m :: * -> *) a.
Monad m =>
Int
-> (Int -> Bool) -> (Int -> Int) -> a -> (Int -> a -> m a) -> m a
loopDeepM Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem Sz ix
sz') (Int -> Int -> Int
forall a. Num a => a -> a -> a
+Int
1) a
acc0 ((Int -> a -> m a) -> m a) -> (Int -> a -> m a) -> m a
forall a b. (a -> b) -> a -> b
$ \ !Int
i !a
acc -> do
          (a
acc', e
e) <- a -> m (a, e)
gen a
acc
          MArray (PrimState m) r ix e -> Int -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> e -> m ()
unsafeLinearWrite MArray (PrimState m) r ix e
marr Int
i e
e
          a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure a
acc'
{-# INLINE unfoldlPrimM #-}

-- | Sequentially loop over a mutable array while reading each element and applying an
-- action to it. There is no mutation to the array, unless the action itself modifies it.
--
-- @since 0.4.0
forPrimM_ :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (e -> m ()) -> m ()
forPrimM_ :: MArray (PrimState m) r ix e -> (e -> m ()) -> m ()
forPrimM_ MArray (PrimState m) r ix e
marr e -> m ()
f =
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m ()) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+Int
1) (MArray (PrimState m) r ix e -> Int -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> m e
unsafeLinearRead MArray (PrimState m) r ix e
marr (Int -> m e) -> (e -> m ()) -> Int -> m ()
forall (m :: * -> *) a b c.
Monad m =>
(a -> m b) -> (b -> m c) -> a -> m c
>=> e -> m ()
f)
{-# INLINE forPrimM_ #-}

-- | Sequentially loop over a mutable array while modifying each element with an action.
--
-- @since 0.4.0
forPrimM :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (e -> m e) -> m ()
forPrimM :: MArray (PrimState m) r ix e -> (e -> m e) -> m ()
forPrimM MArray (PrimState m) r ix e
marr e -> m e
f =
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m e) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+Int
1) (MArray (PrimState m) r ix e -> (e -> m e) -> Int -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> Int -> m e
unsafeLinearModify MArray (PrimState m) r ix e
marr e -> m e
f)
{-# INLINE forPrimM #-}


-- | Sequentially loop over a mutable array while reading each element and applying an
-- index aware action to it. There is no mutation to the array, unless the
-- action itself modifies it.
--
-- @since 0.4.0
iforPrimM_ ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (ix -> e -> m ()) -> m ()
iforPrimM_ :: MArray (PrimState m) r ix e -> (ix -> e -> m ()) -> m ()
iforPrimM_ MArray (PrimState m) r ix e
marr ix -> e -> m ()
f = MArray (PrimState m) r ix e -> (Int -> e -> m ()) -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (Int -> e -> m ()) -> m ()
iforLinearPrimM_ MArray (PrimState m) r ix e
marr (ix -> e -> m ()
f (ix -> e -> m ()) -> (Int -> ix) -> Int -> e -> m ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr))
{-# INLINE iforPrimM_ #-}

-- | Sequentially loop over a mutable array while modifying each element with an index aware action.
--
-- @since 0.4.0
iforPrimM ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (ix -> e -> m e) -> m ()
iforPrimM :: MArray (PrimState m) r ix e -> (ix -> e -> m e) -> m ()
iforPrimM MArray (PrimState m) r ix e
marr ix -> e -> m e
f = MArray (PrimState m) r ix e -> (Int -> e -> m e) -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (Int -> e -> m e) -> m ()
iforLinearPrimM MArray (PrimState m) r ix e
marr (ix -> e -> m e
f (ix -> e -> m e) -> (Int -> ix) -> Int -> e -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Sz ix -> Int -> ix
forall ix. Index ix => Sz ix -> Int -> ix
fromLinearIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr))
{-# INLINE iforPrimM #-}


-- | Sequentially loop over a mutable array while reading each element and applying a
-- linear index aware action to it. There is no mutation to the array, unless the action
-- itself modifies it.
--
-- @since 0.4.0
iforLinearPrimM_ ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (Int -> e -> m ()) -> m ()
iforLinearPrimM_ :: MArray (PrimState m) r ix e -> (Int -> e -> m ()) -> m ()
iforLinearPrimM_ MArray (PrimState m) r ix e
marr Int -> e -> m ()
f =
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m ()) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) (\Int
i -> MArray (PrimState m) r ix e -> Int -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> Int -> m e
unsafeLinearRead MArray (PrimState m) r ix e
marr Int
i m e -> (e -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Int -> e -> m ()
f Int
i)
{-# INLINE iforLinearPrimM_ #-}

-- | Sequentially loop over a mutable array while modifying each element with an index aware action.
--
-- @since 0.4.0
iforLinearPrimM ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> (Int -> e -> m e) -> m ()
iforLinearPrimM :: MArray (PrimState m) r ix e -> (Int -> e -> m e) -> m ()
iforLinearPrimM MArray (PrimState m) r ix e
marr Int -> e -> m e
f =
  Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m e) -> m ()
forall (m :: * -> *) a.
Monad m =>
Int -> (Int -> Bool) -> (Int -> Int) -> (Int -> m a) -> m ()
loopM_ Int
0 (Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Sz ix -> Int
forall ix. Index ix => Sz ix -> Int
totalElem (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr)) (Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) (\Int
i -> MArray (PrimState m) r ix e -> (e -> m e) -> Int -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> Int -> m e
unsafeLinearModify MArray (PrimState m) r ix e
marr (Int -> e -> m e
f Int
i) Int
i)
{-# INLINE iforLinearPrimM #-}

-- | Same as `withMArray_`, but allows to keep artifacts of scheduled tasks.
--
-- @since 0.5.0
withMArray ::
     (Mutable r ix e, MonadUnliftIO m)
  => Array r ix e
  -> (Scheduler m a -> MArray RealWorld r ix e -> m b)
  -> m ([a], Array r ix e)
withMArray :: Array r ix e
-> (Scheduler m a -> MArray RealWorld r ix e -> m b)
-> m ([a], Array r ix e)
withMArray Array r ix e
arr Scheduler m a -> MArray RealWorld r ix e -> m b
action = do
  MArray RealWorld r ix e
marr <- Array r ix e -> m (MArray RealWorld r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, MonadIO m) =>
Array r ix e -> m (MArray RealWorld r ix e)
thaw Array r ix e
arr
  [a]
xs <- Comp -> (Scheduler m a -> m b) -> m [a]
forall (m :: * -> *) a b.
MonadUnliftIO m =>
Comp -> (Scheduler m a -> m b) -> m [a]
withScheduler (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) (Scheduler m a -> MArray RealWorld r ix e -> m b
`action` MArray RealWorld r ix e
marr)
  IO ([a], Array r ix e) -> m ([a], Array r ix e)
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO ((,) [a]
xs (Array r ix e -> ([a], Array r ix e))
-> IO (Array r ix e) -> IO ([a], Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Comp -> MArray (PrimState IO) r ix e -> IO (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) MArray RealWorld r ix e
MArray (PrimState IO) r ix e
marr)
{-# INLINE withMArray #-}

-- | Create a copy of a pure array, mutate it in place and return its frozen version. The big
-- difference between `withMArrayS` is that it's not only gonna respect the computation strategy
-- supplied to it while making a copy, but it will also pass extra argumens to the action that
-- suppose to modify the mutable copy of the source array. These two extra arguments are:
--
-- * Number of capabilities derived from the `Comp`utation strategy of the array.
--
-- * An action that can be used to schedule arbitrary number of jobs that will be executed in
--   parallel.
--
-- * And, of course, the mutable array itself.
--
-- @since 0.5.0
withMArray_ ::
     (Mutable r ix e, MonadUnliftIO m)
  => Array r ix e
  -> (Scheduler m () -> MArray RealWorld r ix e -> m a)
  -> m (Array r ix e)
withMArray_ :: Array r ix e
-> (Scheduler m () -> MArray RealWorld r ix e -> m a)
-> m (Array r ix e)
withMArray_ Array r ix e
arr Scheduler m () -> MArray RealWorld r ix e -> m a
action = do
  MArray RealWorld r ix e
marr <- Array r ix e -> m (MArray RealWorld r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, MonadIO m) =>
Array r ix e -> m (MArray RealWorld r ix e)
thaw Array r ix e
arr
  Comp -> (Scheduler m () -> m a) -> m ()
forall (m :: * -> *) a b.
MonadUnliftIO m =>
Comp -> (Scheduler m a -> m b) -> m ()
withScheduler_ (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) (Scheduler m () -> MArray RealWorld r ix e -> m a
`action` MArray RealWorld r ix e
marr)
  IO (Array r ix e) -> m (Array r ix e)
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO (Array r ix e) -> m (Array r ix e))
-> IO (Array r ix e) -> m (Array r ix e)
forall a b. (a -> b) -> a -> b
$ Comp -> MArray (PrimState IO) r ix e -> IO (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) MArray RealWorld r ix e
MArray (PrimState IO) r ix e
marr
{-# INLINE withMArray_ #-}


-- | Create a copy of a pure array, mutate it in place and return its frozen version. The important
-- benefit over doing a manual `thawS` followed by a `freezeS` is that an array will only be copied
-- once.
--
-- @since 0.5.0
withMArrayS ::
     (Mutable r ix e, PrimMonad m)
  => Array r ix e
  -> (MArray (PrimState m) r ix e -> m a)
  -> m (a, Array r ix e)
withMArrayS :: Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
withMArrayS Array r ix e
arr MArray (PrimState m) r ix e -> m a
action = do
  MArray (PrimState m) r ix e
marr <- Array r ix e -> m (MArray (PrimState m) r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Array r ix e -> m (MArray (PrimState m) r ix e)
thawS Array r ix e
arr
  a
a <- MArray (PrimState m) r ix e -> m a
action MArray (PrimState m) r ix e
marr
  (,) a
a (Array r ix e -> (a, Array r ix e))
-> m (Array r ix e) -> m (a, Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
Comp -> MArray (PrimState m) r ix e -> m (Array r ix e)
unsafeFreeze (Array r ix e -> Comp
forall r ix e. Load r ix e => Array r ix e -> Comp
getComp Array r ix e
arr) MArray (PrimState m) r ix e
marr
{-# INLINE withMArrayS #-}


-- | Same as `withMArrayS`, but discards rhe element produced by the supplied action
--
-- @since 0.5.0
withMArrayS_ ::
     (Mutable r ix e, PrimMonad m)
  => Array r ix e
  -> (MArray (PrimState m) r ix e -> m a)
  -> m (Array r ix e)
withMArrayS_ :: Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (Array r ix e)
withMArrayS_ Array r ix e
arr MArray (PrimState m) r ix e -> m a
action = (a, Array r ix e) -> Array r ix e
forall a b. (a, b) -> b
snd ((a, Array r ix e) -> Array r ix e)
-> m (a, Array r ix e) -> m (Array r ix e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
forall r ix e (m :: * -> *) a.
(Mutable r ix e, PrimMonad m) =>
Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
withMArrayS Array r ix e
arr MArray (PrimState m) r ix e -> m a
action
{-# INLINE withMArrayS_ #-}


-- | Same as `withMArrayS` but in `ST`. This is not only pure, but also the safest way to do
-- mutation to the array.
--
-- @since 0.5.0
withMArrayST ::
     Mutable r ix e
  => Array r ix e
  -> (forall s . MArray s r ix e -> ST s a)
  -> (a, Array r ix e)
withMArrayST :: Array r ix e
-> (forall s. MArray s r ix e -> ST s a) -> (a, Array r ix e)
withMArrayST Array r ix e
arr forall s. MArray s r ix e -> ST s a
f = (forall s. ST s (a, Array r ix e)) -> (a, Array r ix e)
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s (a, Array r ix e)) -> (a, Array r ix e))
-> (forall s. ST s (a, Array r ix e)) -> (a, Array r ix e)
forall a b. (a -> b) -> a -> b
$ Array r ix e
-> (MArray (PrimState (ST s)) r ix e -> ST s a)
-> ST s (a, Array r ix e)
forall r ix e (m :: * -> *) a.
(Mutable r ix e, PrimMonad m) =>
Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (a, Array r ix e)
withMArrayS Array r ix e
arr MArray (PrimState (ST s)) r ix e -> ST s a
forall s. MArray s r ix e -> ST s a
f
{-# INLINE withMArrayST #-}

-- | Same as `withMArrayS` but in `ST`. This is not only pure, but also the safest way to do
-- mutation to the array.
--
-- @since 0.5.0
withMArrayST_ ::
     Mutable r ix e => Array r ix e -> (forall s. MArray s r ix e -> ST s a) -> Array r ix e
withMArrayST_ :: Array r ix e
-> (forall s. MArray s r ix e -> ST s a) -> Array r ix e
withMArrayST_ Array r ix e
arr forall s. MArray s r ix e -> ST s a
f = (forall s. ST s (Array r ix e)) -> Array r ix e
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s (Array r ix e)) -> Array r ix e)
-> (forall s. ST s (Array r ix e)) -> Array r ix e
forall a b. (a -> b) -> a -> b
$ Array r ix e
-> (MArray (PrimState (ST s)) r ix e -> ST s a)
-> ST s (Array r ix e)
forall r ix e (m :: * -> *) a.
(Mutable r ix e, PrimMonad m) =>
Array r ix e
-> (MArray (PrimState m) r ix e -> m a) -> m (Array r ix e)
withMArrayS_ Array r ix e
arr MArray (PrimState (ST s)) r ix e -> ST s a
forall s. MArray s r ix e -> ST s a
f
{-# INLINE withMArrayST_ #-}


-- | /O(1)/ - Lookup an element in the mutable array. Returns `Nothing` when index is out of bounds.
--
-- @since 0.1.0
read :: (Mutable r ix e, PrimMonad m) =>
        MArray (PrimState m) r ix e -> ix -> m (Maybe e)
read :: MArray (PrimState m) r ix e -> ix -> m (Maybe e)
read MArray (PrimState m) r ix e
marr ix
ix =
  if Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix
    then e -> Maybe e
forall a. a -> Maybe a
Just (e -> Maybe e) -> m e -> m (Maybe e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> MArray (PrimState m) r ix e -> ix -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> m e
unsafeRead MArray (PrimState m) r ix e
marr ix
ix
    else Maybe e -> m (Maybe e)
forall (m :: * -> *) a. Monad m => a -> m a
return Maybe e
forall a. Maybe a
Nothing
{-# INLINE read #-}


-- | /O(1)/ - Same as `read`, but throws `IndexOutOfBoundsException` on an invalid index.
--
-- @since 0.4.0
readM :: (Mutable r ix e, PrimMonad m, MonadThrow m) =>
        MArray (PrimState m) r ix e -> ix -> m e
readM :: MArray (PrimState m) r ix e -> ix -> m e
readM MArray (PrimState m) r ix e
marr ix
ix =
  MArray (PrimState m) r ix e -> ix -> m (Maybe e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> m (Maybe e)
read MArray (PrimState m) r ix e
marr ix
ix m (Maybe e) -> (Maybe e -> m e) -> m e
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    Just e
e -> e -> m e
forall (f :: * -> *) a. Applicative f => a -> f a
pure e
e
    Maybe e
Nothing -> IndexException -> m e
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (IndexException -> m e) -> IndexException -> m e
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix
{-# INLINE readM #-}


-- | /O(1)/ - Same as `read`, but throws `IndexOutOfBoundsException` on an invalid index.
--
-- @since 0.1.0
read' :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> m e
read' :: MArray (PrimState m) r ix e -> ix -> m e
read' MArray (PrimState m) r ix e
marr ix
ix =
  MArray (PrimState m) r ix e -> ix -> m (Maybe e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> m (Maybe e)
read MArray (PrimState m) r ix e
marr ix
ix m (Maybe e) -> (Maybe e -> m e) -> m e
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    Just e
e -> e -> m e
forall (f :: * -> *) a. Applicative f => a -> f a
pure e
e
    Maybe e
Nothing -> IndexException -> m e
forall a e. Exception e => e -> a
throw (IndexException -> m e) -> IndexException -> m e
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix
{-# INLINE read' #-}
{-# DEPRECATED read' "In favor of more general `readM`" #-}


-- | /O(1)/ - Write an element into the cell of a mutable array. Returns `False` when index is out
-- of bounds.
--
-- @since 0.1.0
write :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> e -> m Bool
write :: MArray (PrimState m) r ix e -> ix -> e -> m Bool
write MArray (PrimState m) r ix e
marr ix
ix e
e =
  if Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix
  then MArray (PrimState m) r ix e -> ix -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> e -> m ()
unsafeWrite MArray (PrimState m) r ix e
marr ix
ix e
e m () -> m Bool -> m Bool
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> Bool -> m Bool
forall (f :: * -> *) a. Applicative f => a -> f a
pure Bool
True
  else Bool -> m Bool
forall (f :: * -> *) a. Applicative f => a -> f a
pure Bool
False
{-# INLINE write #-}

-- | /O(1)/ - Write an element into the cell of a mutable array. Same as `write` function
-- in case of an out of bounds index it is noop, but unlike `write`, there is no
-- information is returned about was the writing of element successful or not.  In other
-- words, just like `writeM`, but doesn't throw an exception.
--
-- @since 0.4.4
write_ :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> e -> m ()
write_ :: MArray (PrimState m) r ix e -> ix -> e -> m ()
write_ MArray (PrimState m) r ix e
marr ix
ix = Bool -> m () -> m ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix) (m () -> m ()) -> (e -> m ()) -> e -> m ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. MArray (PrimState m) r ix e -> ix -> e -> m ()
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> e -> m ()
unsafeWrite MArray (PrimState m) r ix e
marr ix
ix
{-# INLINE write_ #-}

-- | /O(1)/ - Same as `write`, but throws `IndexOutOfBoundsException` on an invalid index.
--
-- @since 0.4.0
writeM ::
     (Mutable r ix e, PrimMonad m, MonadThrow m) => MArray (PrimState m) r ix e -> ix -> e -> m ()
writeM :: MArray (PrimState m) r ix e -> ix -> e -> m ()
writeM MArray (PrimState m) r ix e
marr ix
ix e
e =
  MArray (PrimState m) r ix e -> ix -> e -> m Bool
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> e -> m Bool
write MArray (PrimState m) r ix e
marr ix
ix e
e m Bool -> (Bool -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (Bool -> m () -> m ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
`unless` IndexException -> m ()
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix))
{-# INLINE writeM #-}


-- | /O(1)/ - Same as `write`, but lives in IO and throws `IndexOutOfBoundsException` on invalid
-- index.
--
-- @since 0.1.0
write' ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> e -> m ()
write' :: MArray (PrimState m) r ix e -> ix -> e -> m ()
write' MArray (PrimState m) r ix e
marr ix
ix e
e = MArray (PrimState m) r ix e -> ix -> e -> m Bool
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> e -> m Bool
write MArray (PrimState m) r ix e
marr ix
ix e
e m Bool -> (Bool -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (Bool -> m () -> m ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
`unless` IndexException -> m ()
forall a e. Exception e => e -> a
throw (Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix))
{-# INLINE write' #-}
{-# DEPRECATED write' "In favor of more general `writeM`" #-}

-- | /O(1)/ - Modify an element in the cell of a mutable array with a supplied
-- action. Returns the previous value, if index was not out of bounds.
--
-- @since 0.1.0
modify ::
     (Mutable r ix e, PrimMonad m)
  => MArray (PrimState m) r ix e -- ^ Array to mutate.
  -> (e -> m e) -- ^ Monadic action that modifies the element
  -> ix -- ^ Index at which to perform modification.
  -> m (Maybe e)
modify :: MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m (Maybe e)
modify MArray (PrimState m) r ix e
marr e -> m e
f ix
ix =
  if Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix
    then e -> Maybe e
forall a. a -> Maybe a
Just (e -> Maybe e) -> m e -> m (Maybe e)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
unsafeModify MArray (PrimState m) r ix e
marr e -> m e
f ix
ix
    else Maybe e -> m (Maybe e)
forall (m :: * -> *) a. Monad m => a -> m a
return Maybe e
forall a. Maybe a
Nothing
{-# INLINE modify #-}

-- | /O(1)/ - Same as `modify`, except that neither the previous value, nor any
-- information on whether the modification was successful are returned. In other words,
-- just like `modifyM_`, but doesn't throw an exception.
--
-- @since 0.4.4
modify_ ::
     (Mutable r ix e, PrimMonad m)
  => MArray (PrimState m) r ix e -- ^ Array to mutate.
  -> (e -> m e) -- ^ Monadic action that modifies the element
  -> ix -- ^ Index at which to perform modification.
  -> m ()
modify_ :: MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m ()
modify_ MArray (PrimState m) r ix e
marr e -> m e
f ix
ix = Bool -> m () -> m ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix) (m () -> m ()) -> m () -> m ()
forall a b. (a -> b) -> a -> b
$ m e -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (m e -> m ()) -> m e -> m ()
forall a b. (a -> b) -> a -> b
$ MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
unsafeModify MArray (PrimState m) r ix e
marr e -> m e
f ix
ix
{-# INLINE modify_ #-}

-- | /O(1)/ - Modify an element in the cell of a mutable array with a supplied
-- action. Throws an `IndexOutOfBoundsException` exception for invalid index and returns
-- the previous value otherwise.
--
-- @since 0.4.0
modifyM ::
     (Mutable r ix e, PrimMonad m, MonadThrow m)
  => MArray (PrimState m) r ix e -- ^ Array to mutate.
  -> (e -> m e) -- ^ Monadic action that modifies the element
  -> ix -- ^ Index at which to perform modification.
  -> m e
modifyM :: MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
modifyM MArray (PrimState m) r ix e
marr e -> m e
f ix
ix
  | Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix = MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
unsafeModify MArray (PrimState m) r ix e
marr e -> m e
f ix
ix
  | Bool
otherwise = IndexException -> m e
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix)
{-# INLINE modifyM #-}

-- | /O(1)/ - Same as `modifyM`, but discard the returned element
--
-- ====__Examples__
--
-- >>> :set -XTypeApplications
-- >>> import Control.Monad.ST
-- >>> import Data.Massiv.Array
-- >>> runST $ newMArray' @P @Ix1 @Int (Sz1 3) >>= (\ma -> modifyM_ ma (pure . (+10)) 1 >> freezeS ma)
-- Array P Seq (Sz1 3)
--   [ 0, 10, 0 ]
--
-- @since 0.4.0
modifyM_ ::
     (Mutable r ix e, PrimMonad m, MonadThrow m)
  => MArray (PrimState m) r ix e -- ^ Array to mutate.
  -> (e -> m e) -- ^ Monadic action that modifies the element
  -> ix -- ^ Index at which to perform modification.
  -> m ()
modifyM_ :: MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m ()
modifyM_ MArray (PrimState m) r ix e
marr e -> m e
f ix
ix = m e -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (m e -> m ()) -> m e -> m ()
forall a b. (a -> b) -> a -> b
$ MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m, MonadThrow m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m e
modifyM MArray (PrimState m) r ix e
marr e -> m e
f ix
ix
{-# INLINE modifyM_ #-}


-- | /O(1)/ - Same as `modify`, but throws an error if index is out of bounds.
--
-- @since 0.1.0
modify' :: (Mutable r ix e, PrimMonad m) =>
        MArray (PrimState m) r ix e -> (e -> e) -> ix -> m ()
modify' :: MArray (PrimState m) r ix e -> (e -> e) -> ix -> m ()
modify' MArray (PrimState m) r ix e
marr e -> e
f ix
ix =
  MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m (Maybe e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> (e -> m e) -> ix -> m (Maybe e)
modify MArray (PrimState m) r ix e
marr (e -> m e
forall (f :: * -> *) a. Applicative f => a -> f a
pure (e -> m e) -> (e -> e) -> e -> m e
forall b c a. (b -> c) -> (a -> b) -> a -> c
. e -> e
f) ix
ix m (Maybe e) -> (Maybe e -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    Just e
_ -> () -> m ()
forall (f :: * -> *) a. Applicative f => a -> f a
pure ()
    Maybe e
Nothing -> IndexException -> m ()
forall a e. Exception e => e -> a
throw (Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix)
{-# INLINE modify' #-}
{-# DEPRECATED modify' "In favor of more general `modifyM`" #-}


-- | /O(1)/ - Same as `swapM`, but instead of throwing an exception returns `Nothing` when
-- either one of the indices is out of bounds and `Just` elements under those indices
-- otherwise.
--
-- @since 0.1.0
swap :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> ix -> m (Maybe (e, e))
swap :: MArray (PrimState m) r ix e -> ix -> ix -> m (Maybe (e, e))
swap MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2 =
  let !sz :: Sz ix
sz = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
   in if Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix1 Bool -> Bool -> Bool
&& Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix2
        then (e, e) -> Maybe (e, e)
forall a. a -> Maybe a
Just ((e, e) -> Maybe (e, e)) -> m (e, e) -> m (Maybe (e, e))
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
unsafeSwap MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2
        else Maybe (e, e) -> m (Maybe (e, e))
forall (f :: * -> *) a. Applicative f => a -> f a
pure Maybe (e, e)
forall a. Maybe a
Nothing
{-# INLINE swap #-}


-- | /O(1)/ - Same as `swap`, but instead of returning `Nothing` it does nothing. In other
-- words, it is similar to `swapM_`, but does not throw any exceptions.
--
-- @since 0.4.4
swap_ :: (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> ix -> m ()
swap_ :: MArray (PrimState m) r ix e -> ix -> ix -> m ()
swap_ MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2 =
  let !sz :: Sz ix
sz = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
   in Bool -> m () -> m ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix1 Bool -> Bool -> Bool
&& Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix2) (m () -> m ()) -> m () -> m ()
forall a b. (a -> b) -> a -> b
$ m (e, e) -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (m (e, e) -> m ()) -> m (e, e) -> m ()
forall a b. (a -> b) -> a -> b
$ MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
unsafeSwap MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2
{-# INLINE swap_ #-}

-- | /O(1)/ - Swap two elements in a mutable array under the supplied indices. Throws an
-- `IndexOutOfBoundsException` when either one of the indices is out of bounds and
-- elements under those indices otherwise.
--
-- @since 0.4.0
swapM ::
     (Mutable r ix e, PrimMonad m, MonadThrow m)
  => MArray (PrimState m) r ix e
  -> ix -- ^ Index for the first element, which will be returned as the first element in the
        -- tuple.
  -> ix -- ^ Index for the second element, which will be returned as the second element in
        -- the tuple.
  -> m (e, e)
swapM :: MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
swapM MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2
  | Bool -> Bool
not (Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix1) = IndexException -> m (e, e)
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (IndexException -> m (e, e)) -> IndexException -> m (e, e)
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix1
  | Bool -> Bool
not (Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex Sz ix
sz ix
ix2) = IndexException -> m (e, e)
forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
throwM (IndexException -> m (e, e)) -> IndexException -> m (e, e)
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix2
  | Bool
otherwise = MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
unsafeSwap MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2
  where
    !sz :: Sz ix
sz = MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr
{-# INLINE swapM #-}


-- | /O(1)/ - Same as `swapM`, but discard the returned elements
--
-- @since 0.4.0
swapM_ ::
     (Mutable r ix e, PrimMonad m, MonadThrow m) => MArray (PrimState m) r ix e -> ix -> ix -> m ()
swapM_ :: MArray (PrimState m) r ix e -> ix -> ix -> m ()
swapM_ MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2 = m (e, e) -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (m (e, e) -> m ()) -> m (e, e) -> m ()
forall a b. (a -> b) -> a -> b
$ MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m, MonadThrow m) =>
MArray (PrimState m) r ix e -> ix -> ix -> m (e, e)
swapM MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2
{-# INLINE swapM_ #-}


-- | /O(1)/ - Same as `swap`, but throws an `IndexOutOfBoundsException` on invalid indices.
--
-- @since 0.1.0
swap' ::
     (Mutable r ix e, PrimMonad m) => MArray (PrimState m) r ix e -> ix -> ix -> m ()
swap' :: MArray (PrimState m) r ix e -> ix -> ix -> m ()
swap' MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2 =
  MArray (PrimState m) r ix e -> ix -> ix -> m (Maybe (e, e))
forall r ix e (m :: * -> *).
(Mutable r ix e, PrimMonad m) =>
MArray (PrimState m) r ix e -> ix -> ix -> m (Maybe (e, e))
swap MArray (PrimState m) r ix e
marr ix
ix1 ix
ix2 m (Maybe (e, e)) -> (Maybe (e, e) -> m ()) -> m ()
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    Just (e, e)
_ -> () -> m ()
forall (f :: * -> *) a. Applicative f => a -> f a
pure ()
    Maybe (e, e)
Nothing ->
      if Sz ix -> ix -> Bool
forall ix. Index ix => Sz ix -> ix -> Bool
isSafeIndex (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix1
        then IndexException -> m ()
forall a e. Exception e => e -> a
throw (IndexException -> m ()) -> IndexException -> m ()
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix2
        else IndexException -> m ()
forall a e. Exception e => e -> a
throw (IndexException -> m ()) -> IndexException -> m ()
forall a b. (a -> b) -> a -> b
$ Sz ix -> ix -> IndexException
forall ix. Index ix => Sz ix -> ix -> IndexException
IndexOutOfBoundsException (MArray (PrimState m) r ix e -> Sz ix
forall r ix e s. Mutable r ix e => MArray s r ix e -> Sz ix
msize MArray (PrimState m) r ix e
marr) ix
ix1
{-# INLINE swap' #-}
{-# DEPRECATED swap' "In favor of more general `swapM`" #-}