array 0.5.5.0 → 0.5.6.0

raw patch · 8 files changed

+159/−39 lines, 8 filesdep ~basenew-uploaderPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: base

API changes (from Hackage documentation)

Files

• Data/Array/Base.hs +102/−35
• Data/Array/IArray.hs +2/−0
• Data/Array/IO/Internals.hs +13/−1
• Data/Array/MArray.hs +3/−0
• Data/Array/MArray/Safe.hs +1/−0
• Data/Array/Storable/Internals.hs +13/−1
• array.cabal +2/−2
• changelog.md +23/−0

@@ -10,7 +10,7 @@   , UnliftedFFITypes   , RoleAnnotations  #-}-{-# OPTIONS_HADDOCK hide #-}+{-# OPTIONS_HADDOCK not-home #-}  ----------------------------------------------------------------------------- -- |@@ -25,13 +25,24 @@ -- Basis for IArray and MArray.  Not intended for external consumption; -- use IArray or MArray instead. --+-- = WARNING+--+-- This module is considered __internal__.+--+-- The Package Versioning Policy __does not apply__.+--+-- The contents of this module may change __in any way whatsoever__+-- and __without any warning__ between minor versions of this package.+--+-- Authors importing this module are expected to track development+-- closely. -----------------------------------------------------------------------------  module Data.Array.Base where  import Control.Monad.ST.Lazy ( strictToLazyST ) import qualified Control.Monad.ST.Lazy as Lazy (ST)-import Data.Ix ( Ix, range, index, rangeSize )+import Data.Ix ( Ix, range, index, inRange, rangeSize ) import Foreign.C.Types import Foreign.StablePtr @@ -39,6 +50,7 @@ import GHC.Arr          ( STArray ) import qualified GHC.Arr as Arr import qualified GHC.Arr as ArrST+import GHC.Ix           ( unsafeIndex ) import GHC.ST           ( ST(..), runST ) import GHC.Base         ( IO(..), divInt# ) import GHC.Exts@@ -183,35 +195,24 @@     let n = safeRangeSize (l,u)     in unsafeArray (l,u) (zip [0 .. n - 1] es) -{-# INLINE listArrayST #-}+{-# INLINE genArray #-}+-- | Constructs an immutable array using a generator function.+genArray :: (IArray a e, Ix i) => (i,i) -> (i -> e) -> a i e+genArray (l,u) f = listArray (l,u) $ map f $ range (l,u)++{-# INLINE listArrayST #-}   -- See Note [Inlining and fusion] listArrayST :: Ix i => (i,i) -> [e] -> ST s (STArray s i e)-listArrayST (l,u) es = do-    marr <- newArray_ (l,u)-    let n = safeRangeSize (l,u)-    let fillFromList i xs | i == n    = return ()-                          | otherwise = case xs of-            []   -> return ()-            y:ys -> unsafeWrite marr i y >> fillFromList (i+1) ys-    fillFromList 0 es-    return marr+listArrayST = newListArray  {-# RULES "listArray/Array" listArray =     \lu es -> runST (listArrayST lu es >>= ArrST.unsafeFreezeSTArray)     #-} -{-# INLINE listUArrayST #-}+{-# INLINE listUArrayST #-}   -- See Note [Inlining and fusion] listUArrayST :: (MArray (STUArray s) e (ST s), Ix i)              => (i,i) -> [e] -> ST s (STUArray s i e)-listUArrayST (l,u) es = do-    marr <- newArray_ (l,u)-    let n = safeRangeSize (l,u)-    let fillFromList i xs | i == n    = return ()-                          | otherwise = case xs of-            []   -> return ()-            y:ys -> unsafeWrite marr i y >> fillFromList (i+1) ys-    fillFromList 0 es-    return marr+listUArrayST = newListArray  -- I don't know how to write a single rule for listUArrayST, because -- the type looks like constrained over 's', which runST doesn't@@ -272,11 +273,21 @@     #-}  {-# INLINE (!) #-}--- | Returns the element of an immutable array at the specified index.+-- | Returns the element of an immutable array at the specified index,+-- or throws an exception if the index is out of bounds. (!) :: (IArray a e, Ix i) => a i e -> i -> e (!) arr i = case bounds arr of               (l,u) -> unsafeAt arr $ safeIndex (l,u) (numElements arr) i +{-# INLINE (!?) #-}+-- | Returns 'Just' the element of an immutable array at the specified index,+-- or 'Nothing' if the index is out of bounds.+(!?) :: (IArray a e, Ix i) => a i e -> i -> Maybe e+(!?) arr i = let b = bounds arr in+             if inRange b i+             then Just $ unsafeAt arr $ unsafeIndex b i+             else Nothing+ {-# INLINE indices #-} -- | Returns a list of all the valid indices in an array. indices :: (IArray a e, Ix i) => a i e -> [i]@@ -824,23 +835,27 @@ -} class (Monad m) => MArray a e m where -    -- | Returns the bounds of the array+    -- | Returns the bounds of the array (lowest,highest)     getBounds      :: Ix i => a i e -> m (i,i)     -- | Returns the number of elements in the array     getNumElements :: Ix i => a i e -> m Int      -- | Builds a new array, with every element initialised to the supplied-    -- value.+    -- value. The first and second element of the tuple specifies the lowest+    -- and highest index, respectively.     newArray    :: Ix i => (i,i) -> e -> m (a i e)      -- | Builds a new array, with every element initialised to an     -- undefined value. In a monadic context in which operations must     -- be deterministic (e.g. the ST monad), the array elements are     -- initialised to a fixed but undefined value, such as zero.+    -- The first and second element of the tuple specifies the lowest+    -- and highest index, respectively.     newArray_ :: Ix i => (i,i) -> m (a i e)      -- | Builds a new array, with every element initialised to an undefined-    -- value.+    -- value. The first and second element of the tuple specifies the lowest+    -- and highest index, respectively.     unsafeNewArray_ :: Ix i => (i,i) -> m (a i e)      unsafeRead  :: Ix i => a i e -> Int -> m e@@ -886,21 +901,31 @@     unsafeRead  = unsafeReadIOArray     unsafeWrite = unsafeWriteIOArray -{-# INLINE newListArray #-}+{-# INLINE newListArray #-}   -- See Note [Inlining and fusion] -- | Constructs a mutable array from a list of initial elements. -- The list gives the elements of the array in ascending order--- beginning with the lowest index.+-- beginning with the lowest index. The first and second element+-- of the tuple specifies the lowest and highest index, respectively. newListArray :: (MArray a e m, Ix i) => (i,i) -> [e] -> m (a i e) newListArray (l,u) es = do     marr <- newArray_ (l,u)     let n = safeRangeSize (l,u)-    let fillFromList i xs | i == n    = return ()-                          | otherwise = case xs of-            []   -> return ()-            y:ys -> unsafeWrite marr i y >> fillFromList (i+1) ys-    fillFromList 0 es+        f x k i+            | i == n    = return ()+            | otherwise = unsafeWrite marr i x >> k (i+1)+    foldr f (const (return ())) es 0     return marr +{-# INLINE newGenArray #-}+-- | Constructs a mutable array using a generator function.+-- It invokes the generator function in ascending order of the indices.+newGenArray :: (MArray a e m, Ix i) => (i,i) -> (i -> m e) -> m (a i e)+newGenArray (l,u) f = do+    marr <- newArray_ (l,u)+    let n = safeRangeSize (l,u)+    sequence_ [ f i >>= unsafeWrite marr (safeIndex (l,u) n i) | i <- range (l,u)]+    return marr+ {-# INLINE readArray #-} -- | Read an element from a mutable array readArray :: (MArray a e m, Ix i) => a i e -> i -> m e@@ -917,6 +942,31 @@   n <- getNumElements marr   unsafeWrite marr (safeIndex (l,u) n i) e +{-# INLINE modifyArray #-}+-- | Modify an element in a mutable array+--+-- @since FIXME+modifyArray :: (MArray a e m, Ix i) => a i e -> i -> (e -> e) -> m ()+modifyArray marr i f = do+  (l,u) <- getBounds marr+  n <- getNumElements marr+  let idx = safeIndex (l,u) n i+  x <- unsafeRead marr idx+  unsafeWrite marr idx (f x)++{-# INLINE modifyArray' #-}+-- | Modify an element in a mutable array. Strict in the written element.+--+-- @since FIXME+modifyArray' :: (MArray a e m, Ix i) => a i e -> i -> (e -> e) -> m ()+modifyArray' marr i f = do+  (l,u) <- getBounds marr+  n <- getNumElements marr+  let idx = safeIndex (l,u) n i+  x <- unsafeRead marr idx+  let !x' = f x+  unsafeWrite marr idx x'+ {-# INLINE getElems #-} -- | Return a list of all the elements of a mutable array getElems :: (MArray a e m, Ix i) => a i e -> m [e]@@ -1349,8 +1399,15 @@  bOOL_SCALE, wORD_SCALE, dOUBLE_SCALE, fLOAT_SCALE :: Int# -> Int# bOOL_SCALE n# =-    -- + 7 to handle case where n is not divisible by 8-    (n# +# 7#) `uncheckedIShiftRA#` 3#+    -- Round the number of bits up to the next whole-word-aligned number+    -- of bytes to avoid ghc#23132; the addition can signed-overflow but+    -- that's OK because it will not unsigned-overflow and the logical+    -- right-shift brings us back in-bounds+#if SIZEOF_HSWORD == 4+    ((n# +# 31#) `uncheckedIShiftRL#` 5#) `uncheckedIShiftL#` 2#+#elif SIZEOF_HSWORD == 8+    ((n# +# 63#) `uncheckedIShiftRL#` 6#) `uncheckedIShiftL#` 3#+#endif wORD_SCALE   n# = safe_scale scale# n# where !(I# scale#) = SIZEOF_HSWORD dOUBLE_SCALE n# = safe_scale scale# n# where !(I# scale#) = SIZEOF_HSDOUBLE fLOAT_SCALE  n# = safe_scale scale# n# where !(I# scale#) = SIZEOF_HSFLOAT@@ -1580,3 +1637,13 @@  castSTUArray :: STUArray s ix a -> ST s (STUArray s ix b) castSTUArray (STUArray l u n marr#) = return (STUArray l u n marr#)++--------------------------------------------------------------------------------++-- Note [Inlining and fusion]+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~+-- Many functions in this module are marked INLINE because they consume their+-- input with `foldr`. By inlining them, it is possible that the `foldr` will+-- meet a `build` from the call site, and beneficial fusion will take place.+-- That is, they become "good consumers". See array issue #8 for data showing+-- the perf improvement that comes with fusion.

@@ -29,9 +29,11 @@     array,      -- :: (IArray a e, Ix i) => (i,i) -> [(i, e)] -> a i e     listArray,  -- :: (IArray a e, Ix i) => (i,i) -> [e] -> a i e     accumArray, -- :: (IArray a e, Ix i) => (e -> e' -> e) -> e -> (i,i) -> [(i, e')] -> a i e+    genArray,   -- :: (IArray a e, Ix i) => (i,i) -> (i -> e) -> a i e      -- * Accessing arrays     (!),        -- :: (IArray a e, Ix i) => a i e -> i -> e+    (!?),       -- :: (IArray a e, Ix i) => a i e -> i -> Maybe e     bounds,     -- :: (HasBounds a, Ix i) => a i e -> (i,i)     indices,    -- :: (HasBounds a, Ix i) => a i e -> [i]     elems,      -- :: (IArray a e, Ix i) => a i e -> [e]

@@ -4,7 +4,7 @@   , RoleAnnotations  #-} -{-# OPTIONS_HADDOCK hide #-}+{-# OPTIONS_HADDOCK not-home #-} ----------------------------------------------------------------------------- -- | -- Module      :  Data.Array.IO.Internal@@ -16,6 +16,18 @@ -- Portability :  non-portable (uses Data.Array.Base) -- -- Mutable boxed and unboxed arrays in the IO monad.+--+-- = WARNING+--+-- This module is considered __internal__.+--+-- The Package Versioning Policy __does not apply__.+--+-- The contents of this module may change __in any way whatsoever__+-- and __without any warning__ between minor versions of this package.+--+-- Authors importing this module are expected to track development+-- closely. -- ----------------------------------------------------------------------------- 

@@ -27,10 +27,13 @@     newArray,     -- :: (MArray a e m, Ix i) => (i,i) -> e -> m (a i e)     newArray_,    -- :: (MArray a e m, Ix i) => (i,i) -> m (a i e)     newListArray, -- :: (MArray a e m, Ix i) => (i,i) -> [e] -> m (a i e)+    newGenArray,  -- :: (MArray a e m, Ix i) => (i,i) -> (i -> m e) -> m (a i e)      -- * Reading and writing mutable arrays     readArray,    -- :: (MArray a e m, Ix i) => a i e -> i -> m e     writeArray,   -- :: (MArray a e m, Ix i) => a i e -> i -> e -> m ()+    modifyArray,+    modifyArray',      -- * Derived arrays     mapArray,     -- :: (MArray a e' m, MArray a e m, Ix i) => (e' -> e) -> a i e' -> m (a i e)

@@ -29,6 +29,7 @@     newArray,     -- :: (MArray a e m, Ix i) => (i,i) -> e -> m (a i e)     newArray_,    -- :: (MArray a e m, Ix i) => (i,i) -> m (a i e)     newListArray, -- :: (MArray a e m, Ix i) => (i,i) -> [e] -> m (a i e)+    newGenArray,  -- :: (MArray a e m, Ix i) => (i,i) -> (i -> m e) -> m (a i e)      -- * Reading and writing mutable arrays     readArray,    -- :: (MArray a e m, Ix i) => a i e -> i -> m e

@@ -1,5 +1,5 @@ {-# LANGUAGE FlexibleInstances, MultiParamTypeClasses, RoleAnnotations #-}-{-# OPTIONS_HADDOCK hide #-}+{-# OPTIONS_HADDOCK not-home #-} ----------------------------------------------------------------------------- -- | -- Module      :  Data.Array.Storable.Internals@@ -13,6 +13,18 @@ -- Actual implementation of "Data.Array.Storable". -- -- @since 0.4.0.0+--+-- = WARNING+--+-- This module is considered __internal__.+--+-- The Package Versioning Policy __does not apply__.+--+-- The contents of this module may change __in any way whatsoever__+-- and __without any warning__ between minor versions of this package.+--+-- Authors importing this module are expected to track development+-- closely. -----------------------------------------------------------------------------  module Data.Array.Storable.Internals (

@@ -1,6 +1,6 @@ cabal-version: >= 1.10 name:          array-version:       0.5.5.0+version:       0.5.6.0  -- NOTE: Don't forget to update ./changelog.md license:       BSD3@@ -36,7 +36,7 @@       Trustworthy,       UnboxedTuples,       UnliftedFFITypes-  build-depends: base >= 4.9 && < 4.19+  build-depends: base >= 4.9 && < 4.20   ghc-options: -Wall   exposed-modules:       Data.Array

@@ -1,5 +1,28 @@ # Changelog for [`array` package](http://hackage.haskell.org/package/array) +## 0.5.6.0  *July 2023*++### Changed++  * `listArray` and `newListArray` are now good consumers of the input list+  * Bump base bound to `<4.20`++### Added++  * Add the `genArray` and `newGenArray` function+  * Add `Data.Array.MArray.modifyArray` and `Data.Array.MArray.modifyArray'`+    These are also exposed from `Data.Array.IO`, `Data.Array.ST`, and+    `Data.Array.Storable`.+  * Add `Data.Array.IArray.(!?)`++### Fixed++  * Array docs regarding constructing arrays+  * Update note [Inlining and fusion]+  * Unboxed Bool arrays no longer cause spurious alarms+    when used with `-fcheck-prim-bounds`+  * Replace Haddock hide pragma with not-home to make the Haddocks more readable+ ## 0.5.5.0  *February 2022*    * Compatibility with GHC's new JavaScript backend.