68cb972 · streamly · git.iko.soy

git.iko.soy/streamly

on master help sign in

Update docs and expose doctest setup for MutArray

68cb972Harendra Kumar4 years ago

core/src/DocTestDataMutArray.hsnew file+10

compare with master

unifiedsplit

@@ -0,0 +1,10 @@

1+{- $setup

2+>>> :m

3+>>> import qualified Streamly.Data.Fold as Fold

4+>>> import qualified Streamly.Data.MutArray as MutArray

5+>>> import qualified Streamly.Data.Stream as Stream

7+For APIs that have not been released yet.

9+>>> import Streamly.Internal.Data.Array.Mut as MutArray

10+-}

core/src/DocTestDataMutArrayGeneric.hsnew file+10

@@ -0,0 +1,10 @@

1+{- $setup

2+>>> :m

3+>>> import qualified Streamly.Data.Fold as Fold

4+>>> import qualified Streamly.Data.MutArray.Generic as MutArray

5+>>> import qualified Streamly.Data.Stream as Stream

7+For APIs that have not been released yet.

9+>>> import Streamly.Internal.Data.Array.Generic.Mut.Type as MutArray

10+-}

core/src/Streamly/Data/MutArray.hs+18−6

@@ -1,3 +1,4 @@

1+{-# LANGUAGE CPP #-}

1-- |

2-- |

2-- Module : Streamly.Data.MutArray

3-- Module : Streamly.Data.MutArray

@@ -7,16 +8,25 @@

7-- Stability : released

8-- Stability : released

8-- Portability : GHC

9-- Portability : GHC

9--

10--

10−-- Mutable version of "Streamly.Data.Array". Please refer to that module for

11+-- This module provides a mutable version of "Streamly.Data.Array". The

11−-- general documentation. The contents of mutable ararys can be modified

12+-- contents of a mutable array can be modified in-place. For general

12−-- in-place.

13+-- documentation, please refer to the original module.

13--

14--

14−-- See "Streamly.Data.MutArray.Generic" for mutable arrays that work for boxed

15+-- Please refer to "Streamly.Internal.Data.Array.Mut" for functions that have

16+-- not yet been released.

17+--

15−-- types i.e. not requiring the 'Unbox' constraint.

18+-- For mutable arrays that work on boxed types, not requiring the 'Unbox'

19+-- constraint, please refer to "Streamly.Data.MutArray.Generic".

17module Streamly.Data.MutArray

21module Streamly.Data.MutArray

18 (

22 (

19− -- * Types

23+ -- * Setup

24+ -- | To execute the code examples provided in this module in ghci, please

25+ -- run the following commands first.

26+ --

27+ -- $setup

28+

29+ -- * Mutable Array Type

20 MutArray

30 MutArray

22 -- * Construction

32 -- * Construction

@@ -67,3 +77,5 @@ where

67import Prelude hiding (length, read)

77import Prelude hiding (length, read)

68import Streamly.Internal.Data.Array.Mut

78import Streamly.Internal.Data.Array.Mut

69import Streamly.Internal.Data.Unboxed (Unbox (..))

79import Streamly.Internal.Data.Unboxed (Unbox (..))

80+

81+#include "DocTestDataMutArray.hs"

core/src/Streamly/Data/MutArray/Generic.hs+9

@@ -1,3 +1,4 @@

1+{-# LANGUAGE CPP #-}

1-- |

2-- |

2-- Module : Streamly.Data.MutArray.Generic

3-- Module : Streamly.Data.MutArray.Generic

@@ -12,6 +13,12 @@

12--

13--

13module Streamly.Data.MutArray.Generic

14module Streamly.Data.MutArray.Generic

14(

15(

16+ -- * Setup

17+ -- | To execute the code examples provided in this module in ghci, please

18+ -- run the following commands first.

19+ --

20+ -- $setup

21+

15 -- * Type

22 -- * Type

16 MutArray

23 MutArray

@@ -38,3 +45,5 @@ module Streamly.Data.MutArray.Generic

38where

45where

40import Streamly.Internal.Data.Array.Generic.Mut.Type

47import Streamly.Internal.Data.Array.Generic.Mut.Type

48+

49+#include "DocTestDataMutArrayGeneric.hs"

core/src/Streamly/Internal/Data/Array/Generic/Mut/Type.hs+6−12

@@ -1,5 +1,5 @@

1+{-# LANGUAGE CPP #-}

1{-# LANGUAGE UnboxedTuples #-}

2{-# LANGUAGE UnboxedTuples #-}

2−

3-- |

4-- Module : Streamly.Internal.Data.Array.Generic.Mut.Type

@@ -188,13 +188,7 @@ import qualified Streamly.Internal.Data.Stream.StreamK.Type as K

188

189import Prelude hiding (read, length)

190

191−-- $setup

191+#include "DocTestDataMutArrayGeneric.hs"

192−-- >>> :m

193−-- >>> import qualified Streamly.Internal.Data.Array.Generic.Mut.Type as Array

194−-- >>> import qualified Streamly.Internal.Data.Stream as Stream

195−-- >>> import qualified Streamly.Internal.Data.Stream.StreamD as StreamD

196−-- >>> import qualified Streamly.Internal.Data.Fold as Fold

197−-- >>> import qualified Streamly.Internal.Data.Fold.Type as Fold

198

192

199-------------------------------------------------------------------------------

193-------------------------------------------------------------------------------

200-- MutArray Data Type

194-- MutArray Data Type

@@ -256,7 +250,7 @@ new n@(I# n#) =

256-- |

250-- |

257-- Definition:

251-- Definition:

258--

252--

259−-- >>> nil = Array.new 0

253+-- >>> nil = MutArray.new 0

260{-# INLINE nil #-}

254{-# INLINE nil #-}

261nil :: MonadIO m => m (MutArray a)

255nil :: MonadIO m => m (MutArray a)

262nil = new 0

256nil = new 0

@@ -288,7 +282,7 @@ invalidIndex label i =

288-- | /O(1)/ Write the given element at the given index in the array.

282-- | /O(1)/ Write the given element at the given index in the array.

289-- Performs in-place mutation of the array.

283-- Performs in-place mutation of the array.

290--

284--

291−-- >>> putIndex ix arr val = Array.modifyIndex ix arr (const (val, ()))

285+-- >>> putIndex ix arr val = MutArray.modifyIndex ix arr (const (val, ()))

292--

286--

293-- /Pre-release/

287-- /Pre-release/

294{-# INLINE putIndex #-}

288{-# INLINE putIndex #-}

@@ -434,7 +428,7 @@ snocWith sizer arr@MutArray {..} x = do

434--

428--

435-- Note that the returned array may be a mutated version of the original array.

429-- Note that the returned array may be a mutated version of the original array.

436--

430--

437−-- >>> snoc = Array.snocWith (* 2)

431+-- >>> snoc = MutArray.snocWith (* 2)

438--

432--

439-- Performs O(n * log n) copies to grow, but is liberal with memory allocation.

433-- Performs O(n * log n) copies to grow, but is liberal with memory allocation.

440--

434--

@@ -593,7 +587,7 @@ writeNUnsafe n = Fold step initial return

593-- | @writeN n@ folds a maximum of @n@ elements from the input stream to an

587-- | @writeN n@ folds a maximum of @n@ elements from the input stream to an

594-- 'Array'.

588-- 'Array'.

595--

589--

596−-- >>> writeN n = Fold.take n (Array.writeNUnsafe n)

590+-- >>> writeN n = Fold.take n (MutArray.writeNUnsafe n)

597--

591--

598-- /Pre-release/

592-- /Pre-release/

599{-# INLINE_NORMAL writeN #-}

593{-# INLINE_NORMAL writeN #-}

core/src/Streamly/Internal/Data/Array/Mut.hs+2−16

@@ -1,5 +1,3 @@

1−#include "inline.hs"

2−

3-- |

1-- |

4-- Module : Streamly.Internal.Data.Array.Mut

2-- Module : Streamly.Internal.Data.Array.Mut

@@ -8,20 +6,6 @@

8-- Stability : experimental

6-- Stability : experimental

9-- Portability : GHC

7-- Portability : GHC

10--

8--

11−-- Unboxed pinned mutable array type for 'Unboxed' types with an option to use

12−-- foreign (non-GHC) memory allocators. Fulfils the following goals:

13−--

14−-- * Random access (array)

15−-- * Efficient storage (unboxed)

16−-- * Performance (unboxed access)

17−-- * Performance - in-place operations (mutable)

18−-- * Performance - GC (pinned, mutable)

19−-- * interfacing with OS (pinned)

20−-- * Fragmentation control (foreign allocators)

21−--

22−-- Stream and Fold APIs allow easy, efficient and convenient operations on

23−-- arrays.

24−

25module Streamly.Internal.Data.Array.Mut

9module Streamly.Internal.Data.Array.Mut

26 (

10 (

27 module Streamly.Internal.Data.Array.Mut.Type

11 module Streamly.Internal.Data.Array.Mut.Type

@@ -32,6 +16,8 @@ module Streamly.Internal.Data.Array.Mut

32 )

16 )

33where

17where

19+#include "inline.hs"

20+

35import Control.Monad.IO.Class (MonadIO(..))

21import Control.Monad.IO.Class (MonadIO(..))

36import Streamly.Internal.Data.Unboxed (Unbox)

22import Streamly.Internal.Data.Unboxed (Unbox)

37import Streamly.Internal.Data.Stream.StreamD (Stream)

23import Streamly.Internal.Data.Stream.StreamD (Stream)

core/src/Streamly/Internal/Data/Array/Mut/Type.hs+26−23

@@ -1,12 +1,26 @@

1+{-# LANGUAGE CPP #-}

1{-# LANGUAGE UnboxedTuples #-}

2{-# LANGUAGE UnboxedTuples #-}

2-- |

3-- |

3−-- Module : Streamly.Internal.Data.MutArray.Mut.Type

4+-- Module : Streamly.Internal.Data.Array.Mut.Type

5-- License : BSD3-3-Clause

6-- License : BSD3-3-Clause

6-- Maintainer : streamly@composewell.com

7-- Maintainer : streamly@composewell.com

7-- Stability : experimental

8-- Stability : experimental

8-- Portability : GHC

9-- Portability : GHC

9--

10--

11+-- Pinned and unpinned mutable array for 'Unboxed' types. Fulfils the following

12+-- goals:

13+--

14+-- * Random access (array)

15+-- * Efficient storage (unboxed)

16+-- * Performance (unboxed access)

17+-- * Performance - in-place operations (mutable)

18+-- * Performance - GC (pinned, mutable)

19+-- * interfacing with OS (pinned)

20+--

21+-- Stream and Fold APIs allow easy, efficient and convenient operations on

22+-- arrays.

23+--

10-- Mutable arrays and file system files are quite similar, they can grow and

24-- Mutable arrays and file system files are quite similar, they can grow and

11-- their content is mutable. Therefore, both have similar APIs as well. We

25-- their content is mutable. Therefore, both have similar APIs as well. We

12-- strive to keep the API consistent for both. Ideally, you should be able to

26-- strive to keep the API consistent for both. Ideally, you should be able to

@@ -205,10 +219,6 @@ module Streamly.Internal.Data.Array.Mut.Type

205 )

219 )

206where

220where

207

221

208−-- Notes:

209−-- When we use a purely lazy Monad like Identity, we need to force ordering of

210−-- some actions for correctness.

211−

212#include "assert.hs"

222#include "assert.hs"

213#include "inline.hs"

223#include "inline.hs"

214#include "ArrayMacros.h"

224#include "ArrayMacros.h"

@@ -259,13 +269,7 @@ import qualified Prelude

259import Prelude hiding

269import Prelude hiding

260 (length, foldr, read, unlines, splitAt, reverse, truncate)

270 (length, foldr, read, unlines, splitAt, reverse, truncate)

261

271

262−-- $setup

272+#include "DocTestDataMutArray.hs"

263−-- >>> :m

264−-- >>> import qualified Streamly.Internal.Data.Array.Mut.Type as MutArray

265−-- >>> import qualified Streamly.Internal.Data.Stream as Stream

266−-- >>> import qualified Streamly.Internal.Data.Stream.StreamD as StreamD

267−-- >>> import qualified Streamly.Internal.Data.Fold as Fold

268−-- >>> import qualified Streamly.Internal.Data.Fold.Type as Fold

269

273

270-------------------------------------------------------------------------------

274-------------------------------------------------------------------------------

271-- Foreign helpers

275-- Foreign helpers

@@ -305,14 +309,12 @@ memcmp p1 p2 len = do

305

309

306-- $arrayNotes

310-- $arrayNotes

307--

311--

308−-- We can use an 'Unboxed' constraint in the MutArray type and the constraint can

312+-- We can use an 'Unboxed' constraint in the MutArray type and the constraint

309−-- be automatically provided to a function that pattern matches on the MutArray

313+-- can be automatically provided to a function that pattern matches on the

310−-- type. However, it has huge performance cost, so we do not use it.

314+-- MutArray type. However, it has huge performance cost, so we do not use it.

311-- Investigate a GHC improvement possiblity.

315-- Investigate a GHC improvement possiblity.

312

316

313−-- XXX Rename the fields to better names.

314−

315−-- | An unboxed, pinned mutable array. An array is created with a given length

317+-- | An unboxed mutable array. An array is created with a given length

316-- and capacity. Length is the number of valid elements in the array. Capacity

318-- and capacity. Length is the number of valid elements in the array. Capacity

317-- is the maximum number of elements that the array can be expanded to without

319-- is the maximum number of elements that the array can be expanded to without

318-- having to reallocate the memory.

320-- having to reallocate the memory.

@@ -1520,7 +1522,8 @@ toListFB c n MutArray{..} = go arrStart

1520

1522

1521-- XXX Monadic foldr/build fusion?

1523-- XXX Monadic foldr/build fusion?

1522-- Reference: https://www.researchgate.net/publication/220676509_Monadic_augment_and_generalised_short_cut_fusion

1524-- Reference: https://www.researchgate.net/publication/220676509_Monadic_augment_and_generalised_short_cut_fusion

1525+

1523−-- | Convert an 'MutArray' into a list.

1526+-- | Convert a 'MutArray' into a list.

1524--

1527--

1525{-# INLINE toList #-}

1528{-# INLINE toList #-}

1526toList :: forall m a. (MonadIO m, Unbox a) => MutArray a -> m [a]

1529toList :: forall m a. (MonadIO m, Unbox a) => MutArray a -> m [a]

@@ -1813,7 +1816,7 @@ writeRevN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)

1813writeRevN = writeRevNWith newPinned

1816writeRevN = writeRevNWith newPinned

1814

1817

1815-- | @writeNAligned align n@ folds a maximum of @n@ elements from the input

1818-- | @writeNAligned align n@ folds a maximum of @n@ elements from the input

1816−-- stream to an 'MutArray' aligned to the given size.

1819+-- stream to a 'MutArray' aligned to the given size.

1817--

1820--

1818-- >>> writeNAligned align = MutArray.writeNWith (MutArray.newAlignedPinned align)

1821-- >>> writeNAligned align = MutArray.writeNWith (MutArray.newAlignedPinned align)

1819-- >>> writeNAligned align n = MutArray.writeAppendN n (MutArray.newAlignedPinned align n)

1822-- >>> writeNAligned align n = MutArray.writeAppendN n (MutArray.newAlignedPinned align n)

@@ -1911,7 +1914,7 @@ write = writeWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)

1911

1914

1912-- | Use the 'writeN' fold instead.

1915-- | Use the 'writeN' fold instead.

1913--

1916--

1914−-- >>> fromStreamDN n = StreamD.fold (MutArray.writeN n)

1917+-- >>> fromStreamDN n = Stream.fold (MutArray.writeN n)

1915--

1918--

1916{-# INLINE_NORMAL fromStreamDN #-}

1919{-# INLINE_NORMAL fromStreamDN #-}

1917fromStreamDN :: forall m a. (MonadIO m, Unbox a)

1920fromStreamDN :: forall m a. (MonadIO m, Unbox a)

@@ -1928,7 +1931,7 @@ fromStreamDN limit str = do

1928 liftIO $ pokeWith arrContents ptr x

1931 liftIO $ pokeWith arrContents ptr x

1929 return $ INDEX_NEXT(ptr,a)

1932 return $ INDEX_NEXT(ptr,a)

1930

1933

1931−-- | Create an 'MutArray' from the first N elements of a list. The array is

1934+-- | Create a 'MutArray' from the first N elements of a list. The array is

1932-- allocated to size N, if the list terminates before N elements then the

1935-- allocated to size N, if the list terminates before N elements then the

1933-- array may hold less than N elements.

1936-- array may hold less than N elements.

1934--

1937--

@@ -1978,7 +1981,7 @@ fromArrayStreamK as = do

1978fromStreamD :: (MonadIO m, Unbox a) => D.Stream m a -> m (MutArray a)

1981fromStreamD :: (MonadIO m, Unbox a) => D.Stream m a -> m (MutArray a)

1979fromStreamD m = arrayStreamKFromStreamD m >>= fromArrayStreamK

1982fromStreamD m = arrayStreamKFromStreamD m >>= fromArrayStreamK

1980

1983

1981−-- | Create an 'MutArray' from a list. The list must be of finite size.

1984+-- | Create a 'MutArray' from a list. The list must be of finite size.

1982--

1985--

1983{-# INLINE fromList #-}

1986{-# INLINE fromList #-}

1984fromList :: (MonadIO m, Unbox a) => [a] -> m (MutArray a)

1987fromList :: (MonadIO m, Unbox a) => [a] -> m (MutArray a)

core/streamly-core.cabal+2

@@ -40,6 +40,8 @@ extra-source-files:

40 -- doctest include files

41 src/DocTestDataArray.hs

42 src/DocTestDataFold.hs

43+ src/DocTestDataMutArray.hs

44+ src/DocTestDataMutArrayGeneric.hs

44 -- This is duplicated

46 -- This is duplicated

45 src/Streamly/Internal/Data/Array/ArrayMacros.h

47 src/Streamly/Internal/Data/Array/ArrayMacros.h