@@ -17,14 +17,14 @@
17-- Portability : GHC
17-- Portability : GHC
19-- Arrays are the computing duals of streams. Streams are good at sequential
19-- Arrays are the computing duals of streams. Streams are good at sequential
20−-- access, immutable transformations of in-transit data whereas arrays are good
20+-- access and immutable transformations of in-transit data whereas arrays are
21−-- at random access, in-place transformations of buffered data. Unlike streams
21+-- good at random access and in-place transformations of buffered data. Unlike
22−-- which are potentially infinite, arrays are necessarily /finite/. Arrays can
22+-- streams which are potentially infinite, arrays are necessarily /finite/.
23−-- be used as an efficient interface between streams and external storage
23+-- Arrays can be used as an efficient interface between streams and external
24−-- systems like memory, files and network. Streams and arrays complete each
24+-- storage systems like memory, files and network. Streams and arrays complete
25−-- other to provide a general purpose computing system. The design of streamly
25+-- each other to provide a general purpose computing system. The design of
26−-- as a general purpose computing framework is centered around these two
26+-- streamly as a general purpose computing framework is centered around these
27−-- fundamental aspects of computing and storage.
27+-- two fundamental aspects of computing and storage.
29-- Even though the implementation allows for in-place mutation, the current
29-- Even though the implementation allows for in-place mutation, the current
30-- implementation of arrays is immutable. Arrays are of fixed size. The size of
30-- implementation of arrays is immutable. Arrays are of fixed size. The size of
@@ -90,35 +90,27 @@ module Streamly.Mem.Array
90 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
90 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
91 -- 'fromList' can be used to construct an array from a string literal.
91 -- 'fromList' can be used to construct an array from a string literal.
93 -- , newArray
98 -- , newArray
99− -- Folds
102+ -- Stream Folds
100 , A.toArrayN
103 , A.toArrayN
101 -- , toArrays
104 -- , toArrays
102 , toArray
105 , toArray
104− -- Streams of arrays
107 -- * Elimination
107 -- * Elimination
108 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
108 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
112 , readRev
113 , readRev
115− -- Streams of arrays
117− -- , flattenArraysRev
119− , packArraysChunksOf
123 -- * Random Access
115 -- * Random Access
@@ -135,10 +127,22 @@ module Streamly.Mem.Array
135 , writeSlice
127 , writeSlice
136 , writeSliceRev
128 , writeSliceRev
131+ -- * Streams of arrays
134+ -- Streams of arrays
136+ -- , flattenArraysRev
138+ , packArraysChunksOf
138 -- * Immutable Transformations
142 -- * Immutable Transformations
139 , transformWith
143 , transformWith
141− -- * Folds
145+ -- * Folding Arrays
142 , foldWith
146 , foldWith
143 , foldArray
147 , foldArray
@@ -344,6 +348,7 @@ readSliceRev arr i len = undefined
346-- | /O(1)/ Write the given element at the given index in the array.
350-- | /O(1)/ Write the given element at the given index in the array.
351+-- Performs in-place mutation of the array.
348-- @since 0.7.0
353-- @since 0.7.0
349{-# INLINE writeIndex #-}
354{-# INLINE writeIndex #-}
@@ -456,6 +461,10 @@ toArray = toArrayMinChunk (bytesToCount (undefined :: a) (A.mkChunkSize 1024))
457-- | Convert a stream of arrays into a stream of their elements.
462-- | Convert a stream of arrays into a stream of their elements.
464+-- Same as the following but more efficient:
466+-- > flattenArrays = S.concatMap A.read
459-- @since 0.7.0
468-- @since 0.7.0
460{-# INLINE flattenArrays #-}
469{-# INLINE flattenArrays #-}
461flattenArrays :: (IsStream t, MonadIO m, Storable a) => t m (Array a) -> t m a
470flattenArrays :: (IsStream t, MonadIO m, Storable a) => t m (Array a) -> t m a
@@ -506,10 +515,11 @@ packArraysChunksOf :: (MonadIO m, Storable a)
506packArraysChunksOf n xs =
515packArraysChunksOf n xs =
507 D.fromStreamD $ A.packArraysChunksOf n (D.toStreamD xs)
516 D.fromStreamD $ A.packArraysChunksOf n (D.toStreamD xs)
509−-- |
518+-- | Groups the elements in an input stream into arrays of given size.
510−-- > arraysOf n = FL.groupsOf n (FL.toArrayN n)
512−-- Groups the elements in an input stream into arrays of given size.
520+-- Same as the following but more efficient:
522+-- > arraysOf n = FL.groupsOf n (FL.toArrayN n)
514-- @since 0.7.0
524-- @since 0.7.0
515{-# INLINE arraysOf #-}
525{-# INLINE arraysOf #-}