array-utils 0.2 → 0.3

raw patch · 2 files changed

+66/−49 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• Data/Array/Util.hs +62/−48
• array-utils.cabal +4/−1

@@ -4,11 +4,11 @@     -- $intro      -- * Updating all elements-      updateElems-    , updateElemsIx+      updateAll+    , updateAllIx     -- ** Monadic versions-    , updateElemsM-    , updateElemsIxM+    , updateAllM+    , updateAllIxM     -- * Updating certain elements     , updateOn     , updateOnIx@@ -49,50 +49,58 @@ -- as possible, and should be quite fast. --  -- Some functions throw 'IndexOutOfBounds' exceptions. If an exception--- is thrown, the array will be left untouched.+-- is thrown, the array will be left untouched, meaning it may be ok to+-- catch the exception, and continue using the array. -- +-- Each function has four varieties: a simple version which uses a pure+-- function ('e -> e') to update each element, a version which also passes+-- the element's index to the pure function ('i -> e -> e'), and two monadic+-- versions of the previous two ('e -> m e', 'i -> e -> m e'),+-- which are useful for reading other elements of the array, or filling the+-- array with values from an external source.+--  -- This library relies on some of the primitives in "GHC.Arr", so is -- probably not portable.   -- ================--- = updateElems* =+-- = updateAll* = -- ================  {-|-updateElems mutates every element in an array while avoiding all bounds checks. /O(size of arr)/+updateAll mutates every element in an array while avoiding all bounds checks. Think of it as a mutable version of map. /O(size of arr)/  >>> arr <- newArray (1,10) 0 :: IO (IOArray Int Int)     -- Produces a 1 based array with 10 elements all set to 0.->>> updateElems arr (+ 10)+>>> updateAll arr (+ 10)     -- Updates all elements to 10  -}-INLINE(updateElems)-updateElems :: (MArray a e m, Ix i)+INLINE(updateAll)+updateAll :: (MArray a e m, Ix i)     => (e -> e) -- ^ Update function     -> a i e    -- ^ The array     -> m ()-updateElems f arr = do+updateAll f arr = do     bnds@(_ , end') <- getBounds arr     let !end = unsafeIndex bnds end'     forM_ [0..end] (update arr f)  --- | The same as updateElems but taking a monadic function. /O(size of arr)/-INLINE(updateElemsM)-updateElemsM :: (MArray a e m, Ix i) => (e -> m e) -> a i e -> m ()-updateElemsM f arr = do+-- | The same as updateAll but taking a monadic function. /O(size of arr)/+INLINE(updateAllM)+updateAllM :: (MArray a e m, Ix i) => (e -> m e) -> a i e -> m ()+updateAllM f arr = do     bnds@(_ , end') <- getBounds arr     let !end = unsafeIndex bnds end'     forM_ [0..end] (updateM arr f)  --- | The same as updateElems, but also providing the index to the+-- | The same as updateAll, but also providing the index to the -- mapping function. /O(size of arr)/-INLINE(updateElemsIx)-updateElemsIx :: (MArray a e m, Ix i) => (i -> e -> e) -> a i e -> m ()-updateElemsIx f arr = do+INLINE(updateAllIx)+updateAllIx :: (MArray a e m, Ix i) => (i -> e -> e) -> a i e -> m ()+updateAllIx f arr = do     bnds@(_ , end') <- getBounds arr     let !end                    = unsafeIndex bnds end' @@ -102,10 +110,10 @@     go 0 (range bnds)  --- | The same updateElemsIx but taking a monadic function. /O(size of arr)/-INLINE(updateElemsIxM)-updateElemsIxM :: (MArray a e m, Ix i) => (i -> e -> m e) -> a i e -> m ()-updateElemsIxM f arr = do+-- | The same updateAllIx but taking a monadic function. /O(size of arr)/+INLINE(updateAllIxM)+updateAllIxM :: (MArray a e m, Ix i) => (i -> e -> m e) -> a i e -> m ()+updateAllIxM f arr = do     bnds@(_ , end') <- getBounds arr     let !end                     = unsafeIndex bnds end' @@ -114,9 +122,9 @@         go _ _                  = return ()     go 0 (range bnds) --- ======================+-- ================= -- = updateWithin* =--- ======================+-- =================  {-| Takes an update function 'f' and a tuple of indicies '(start, finish)',@@ -142,7 +150,7 @@     forM_ indicies (update arr f)  --- | The same as 'updateWithin' but taking a monadic function.+--  The same as 'updateWithin' but taking a monadic function. --  -- Throws an 'IndexOutOfBounds' exception if either of the indicies are out of bounds. INLINE(updateWithinM)@@ -152,11 +160,11 @@     let !ok      = inRange bnds start && inRange bnds finish         indicies = map (unsafeIndex bnds) $ range (start, finish) -    when (not ok) $ throw $ IndexOutOfBounds $ "Data.Array.Util updateWithin"+    when (not ok) $ throw $ IndexOutOfBounds $ "Data.Array.Util updateWithinM"     forM_ indicies (updateM arr f)  --- | Takes an update function 'f' and a tuple of indicies '(start, finish)'+--  Takes an update function 'f' and a tuple of indicies '(start, finish)' -- , and applies the function to all elements returned by range (start, finish). --  -- Throws an 'IndexOutOfBounds' exception if either of the indicies are out of bounds.@@ -175,7 +183,7 @@     go indicies rnge  --- | The same as 'updateWithinIx' but taking a monadic function.+--  The same as 'updateWithinIx' but taking a monadic function. --  -- Throws an 'IndexOutOfBounds' exception if either of the indicies are out of bounds. INLINE(updateWithinIxM)@@ -189,7 +197,7 @@         go (!i:is) (x:xs) = updateIxM arr f i x >> go is xs         go _ _            = return () -    when (not ok) $ throw $ IndexOutOfBounds $ "Data.Array.Util updateWithinIx"+    when (not ok) $ throw $ IndexOutOfBounds $ "Data.Array.Util updateWithinIxM"     go indicies rnge  -- ==================@@ -201,6 +209,7 @@  Throws an 'IndexOutOfBounds' exception if any of the indicies are out of bounds. In this case the array will be left unmutated.+ /O(length xs)/ -} INLINE(updateOn)@@ -214,14 +223,16 @@     let !ok      = all (inRange bnds) xs         toOffset = unsafeIndex bnds -    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateElems'")+    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateOn")     forM_ (map toOffset xs) (update arr f)  --- | Takes a mapping function, and a list of indicies to mutate.--- Throws an 'IndexOutOfBounds' exception if any of the indicies are--- out of bounds. In this case the array will be left unmutated.--- /O(length xs)/+{- Takes a mapping function, and a list of indicies to mutate.++Throws an 'IndexOutOfBounds' exception if any of the indicies are+out of bounds. In this case the array will be left unmutated.+/O(length xs)/+-} INLINE(updateOnM) updateOnM :: (MArray a e m, Ix i) => (e -> m e) -> [i] -> a i e -> m () updateOnM f xs arr = do@@ -229,12 +240,12 @@     let !ok      = all (inRange bnds) xs         toOffset = unsafeIndex bnds -    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateElems'")+    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateAll'")     forM_ (map toOffset xs) (updateM arr f)  --- | Takes a mapping function which takes an index, and a list of indicies--- to mutate. Throws 'IndexOutOfBounds' exception as 'updateElems'' does.+-- Takes a mapping function which takes an index, and a list of indicies+-- to mutate. Throws 'IndexOutOfBounds' exception as 'updateAll'' does. -- /O(length xs)/ INLINE(updateOnIx) updateOnIx :: (MArray a e m, Ix i) => (i -> e -> e) -> [i] -> a i e -> m ()@@ -248,14 +259,14 @@         go (!i:is) (x:xs)  = updateIx arr f i x >> go is xs         go _ _             = return () -    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateElemsIx'")+    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateAllIx'")     go ixs indexes  --- | Takes a mapping function which takes an index, and a list of indicies+-- Takes a mapping function which takes an index, and a list of indicies -- to mutate. /O(length xs)/ -- --- Throws 'IndexOutOfBounds' exception as 'updateElems'' does.+-- Throws 'IndexOutOfBounds' exception as 'updateAll'' does. INLINE(updateOnIxM) updateOnIxM :: (MArray a e m, Ix i) => (i -> e -> m e) -> [i] -> a i e -> m () updateOnIxM f indexes arr = do@@ -268,7 +279,7 @@         go (!i:is) (x:xs)  = updateIxM arr f i x >> go is xs         go _ _             = return () -    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateElemsIx'")+    when (not ok) $ throw (IndexOutOfBounds $ "Data.Array.Util updateAllIx'")     go ixs indexes  @@ -286,9 +297,12 @@ For example:  >>> arr <- newArray ((1,1),(5,5)) 0 :: IO (IOArray Int Int)-    -- Produces aa 2D array with 25 elements all set to 0.->>> updateSlice arr ((2,4),(3,5)) (+ 10)-    -- Updates elements at indexes [(2,4),(2,5),(3,1),(3,2),(3,3),(3,4),(3,5)] to 10+    -- Produces a 2D array with 25 elements all set to 0.+>>> updateSlice ((2,4),(3,5)) (+ 10) arr+    -- Updates elements at indexes:+    --                     [(2,4),(2,5),+    --    (3,1),(3,2),(3,3),(3,4),(3,5)]+    --  to 10  \*Ix versions are not included, because there's no easy way to map from an Int to an element in a particular bounds.@@ -325,7 +339,7 @@     forM_ [start..finish] (update arr f)  --- | The same as updateElems but taking a monadic function. /O(size of arr)/+-- The same as updateAll but taking a monadic function. /O(size of arr)/ INLINE(updateSliceM) updateSliceM :: (MArray a e m, Ix i) => (e -> m e) -> (i,i) -> a i e -> m () updateSliceM f (start', finish') arr = do@@ -348,10 +362,10 @@ {-# INLINE updateM #-} {-# INLINE updateIxM #-} update :: (MArray a e m, Ix i) => a i e -> (e -> e) -> Int -> m ()-update arr f i = unsafeRead arr i >>= unsafeWrite arr i . f+update arr f i = updateM arr (return . f) i  updateIx :: (MArray a e m, Ix i) => a i e -> (i -> e -> e) -> Int -> i -> m ()-updateIx arr f i x = unsafeRead arr i >>= unsafeWrite arr i . f x+updateIx arr f i x = updateIxM arr (\x -> return . f x) i x  updateM :: (MArray a e m, Ix i) => a i e -> (e -> m e) -> Int -> m () updateM arr f i = unsafeRead arr i >>= f >>= unsafeWrite arr i

@@ -1,10 +1,13 @@ Name:                array-utils-Version:             0.2+Version:             0.3 category:            Data, Data Structures Synopsis:            Primitive functions for updating many elements in mutable arrays at once Description:         An collection of functions for working with multiple elements in                      mutable arrays. It is hoped some or all of these functions will be                      included in the array package for GHC 7.2.+                     +                     New in this version: Basically all names have been changed. A lot+                     of redundant information has been removed as well. License:             BSD3 License-file:        LICENSE Author:              Alex Mason