@@ -17,14 +17,14 @@
1717-- Portability : GHC
1818--
1919-- Arrays are the computing duals of streams. Streams are good at sequential
20−-- access, immutable transformations of in-transit data whereas arrays are good
21−-- at random access, in-place transformations of buffered data. Unlike streams
22−-- which are potentially infinite, arrays are necessarily /finite/. Arrays can
23−-- be used as an efficient interface between streams and external storage
24−-- systems like memory, files and network. Streams and arrays complete each
25−-- other to provide a general purpose computing system. The design of streamly
26−-- as a general purpose computing framework is centered around these two
27−-- fundamental aspects of computing and storage.
20+-- access and immutable transformations of in-transit data whereas arrays are
21+-- good at random access and in-place transformations of buffered data. Unlike
22+-- streams which are potentially infinite, arrays are necessarily /finite/.
23+-- Arrays can be used as an efficient interface between streams and external
24+-- storage systems like memory, files and network. Streams and arrays complete
25+-- each other to provide a general purpose computing system. The design of
26+-- streamly as a general purpose computing framework is centered around these
27+-- two fundamental aspects of computing and storage.
2828--
2929-- Even though the implementation allows for in-place mutation, the current
3030-- implementation of arrays is immutable. Arrays are of fixed size. The size of
@@ -90,35 +90,27 @@ module Streamly.Mem.Array
9090 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
9191 -- 'fromList' can be used to construct an array from a string literal.
9292
93+ -- Pure List APIs
94+ , A.fromListN
95+ , A.fromList
96+
97+ -- Monadic APIs
9398 -- , newArray
9499 , writeN
95100 , write
96− , A.fromListN
97− , A.fromList
98101
99− -- Folds
102+ -- Stream Folds
100103 , A.toArrayN
101104 -- , toArrays
102105 , toArray
103106
104− -- Streams of arrays
105− , arraysOf
106−
107107 -- * Elimination
108108 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
109109 -- list.
110110
111+ , A.toList
111112 , A.read
112113 , readRev
113− , A.toList
114−
115− -- Streams of arrays
116− , flattenArrays
117− -- , flattenArraysRev
118− , packArrays
119− , packArraysChunksOf
120− , unlinesArraysBy
121− , splitArraysOn
122114
123115 -- * Random Access
124116 , length
@@ -135,10 +127,22 @@ module Streamly.Mem.Array
135127 , writeSlice
136128 , writeSliceRev
137129 -}
130+
131+ -- * Streams of arrays
132+ , arraysOf
133+
134+ -- Streams of arrays
135+ , flattenArrays
136+ -- , flattenArraysRev
137+ , packArrays
138+ , packArraysChunksOf
139+ , unlinesArraysBy
140+ , splitArraysOn
141+
138142 -- * Immutable Transformations
139143 , transformWith
140144
141− -- * Folds
145+ -- * Folding Arrays
142146 , foldWith
143147 , foldArray
144148 )
@@ -344,6 +348,7 @@ readSliceRev arr i len = undefined
344348-}
345349
346350-- | /O(1)/ Write the given element at the given index in the array.
351+-- Performs in-place mutation of the array.
347352--
348353-- @since 0.7.0
349354{-# INLINE writeIndex #-}
@@ -456,6 +461,10 @@ toArray = toArrayMinChunk (bytesToCount (undefined :: a) (A.mkChunkSize 1024))
456461
457462-- | Convert a stream of arrays into a stream of their elements.
458463--
464+-- Same as the following but more efficient:
465+--
466+-- > flattenArrays = S.concatMap A.read
467+--
459468-- @since 0.7.0
460469{-# INLINE flattenArrays #-}
461470flattenArrays :: (IsStream t, MonadIO m, Storable a) => t m (Array a) -> t m a
@@ -506,10 +515,11 @@ packArraysChunksOf :: (MonadIO m, Storable a)
506515packArraysChunksOf n xs =
507516 D.fromStreamD $ A.packArraysChunksOf n (D.toStreamD xs)
508517
509−-- |
510−-- > arraysOf n = FL.groupsOf n (FL.toArrayN n)
518+-- | Groups the elements in an input stream into arrays of given size.
511519--
512−-- Groups the elements in an input stream into arrays of given size.
520+-- Same as the following but more efficient:
521+--
522+-- > arraysOf n = FL.groupsOf n (FL.toArrayN n)
513523--
514524-- @since 0.7.0
515525{-# INLINE arraysOf #-}