git.iko.soy/streamly
on 4300a9f help sign in
streamly/core/src/Streamly/Data/Array.hs
168 lines 5.2 kB history raw
1{-# LANGUAGE CPP #-}
2-- |
3-- Module : Streamly.Data.Array
4-- Copyright : (c) 2019 Composewell Technologies
5--
6-- License : BSD3
7-- Maintainer : streamly@composewell.com
8-- Stability : released
9-- Portability : GHC
10--
11-- Unboxed immutable arrays with streaming interfaces.
12--
13-- Please refer to "Streamly.Internal.Data.Array" for functions that have not
14-- yet been released.
15--
16-- For arrays that work on boxed types, not requiring the 'Unbox' constraint,
17-- please refer to "Streamly.Data.Array.Generic". For arrays that can be
18-- mutated in-place, please see "Streamly.Data.MutArray".
20module Streamly.Data.Array
21 (
22 -- * Setup
23 -- | To execute the code examples provided in this module in ghci, please
24 -- run the following commands first.
25 --
26 -- $setup
28 -- * Overview
29 -- $overview
31 -- * The Array Type
32 A.Array
34 -- * Construction
35 -- | When performance matters, the fastest way to generate an array is
36 -- 'writeN'. 'IsList' and 'IsString' instances can be
37 -- used to conveniently construct arrays from literal values.
38 -- 'OverloadedLists' extension or 'fromList' can be used to construct an
39 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
40 -- 'fromList' can be used to construct an array from a string literal.
42 -- Pure List APIs
43 , A.fromListN
44 , A.fromList
46 -- Monadic APIs
47 , A.writeN -- drop new
48 , A.write -- full buffer
49 , writeLastN -- drop old (ring buffer)
51 -- * Conversion
52 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
53 -- list.
54 , A.toList
56 -- * Unfolds
57 , A.reader
58 , A.readerRev
60 -- * Casting
61 , cast
62 , asBytes
64 -- * Random Access
65 , A.length
66 -- , (!!)
67 , A.getIndex
69 -- * Unbox Type Class
70 , Unbox (..)
72 -- * Deprecated
73 , read
74 , readRev
75 )
76where
78#include "inline.hs"
80import Streamly.Internal.Data.Unfold (Unfold)
81import Streamly.Internal.Data.Array as A hiding (read, readRev)
83import Streamly.Internal.Data.Unboxed (Unbox (..))
84import Prelude hiding (read)
86#include "DocTestDataArray.hs"
88-- $overview
89--
90-- This module provides APIs to create and use unboxed immutable arrays. Once
91-- created, their contents cannot be modified. Only types that are unboxable
92-- via the 'Unbox' type class can be stored in these arrays. Note that the
93-- array memory grows automatically when creating a new array, therefore, an
94-- array can be created from a variable length stream.
95--
96-- == Folding Arrays
97--
98-- Convert array to stream, and fold the stream:
99--
100-- >>> fold f arr = Stream.unfold Array.reader arr & Stream.fold f
101-- >>> fold Fold.sum (Array.fromList [1,2,3::Int])
102-- 6
103--
104-- == Transforming Arrays
105--
106-- Convert array to stream, transform, and fold back to array:
107--
108-- >>> amap f arr = Stream.unfold Array.reader arr & fmap f & Stream.fold Array.write
109-- >>> amap (+1) (Array.fromList [1,2,3::Int])
110-- fromList [2,3,4]
111--
112-- == Pinned and Unpinned Arrays
113--
114-- The array type can use both pinned and unpinned memory under the hood.
115-- Currently the array creation APIs create arrays in pinned memory but it will
116-- change to unpinned in future releases. The change should not affect users
117-- functionally unless they are directly accessing the internal memory of the
118-- array via internal APIs. As of now unpinned arrays can be created using
119-- unreleased APIs.
120--
121-- Unpinned arrays have the advantage of allowing automatic defragmentation of
122-- the memory by GC. Whereas pinned arrays have the advantage of not requiring
123-- a copy by GC. Normally you would want to use unpinned arrays. However, in
124-- some cases, for example, for long lived large data storage, and for
125-- interfacing with the operating system or foreign (non-Haskell) consumers you
126-- may want to use pinned arrays.
127--
128-- == Creating Arrays from Non-IO Streams
129--
130-- Array creation folds require 'MonadIO' because they need to sequence effects
131-- in IO streams. To operate on streams in pure Monads like 'Identity' you can
132-- morph it to IO monad as follows:
133--
134-- The 'MonadIO' based folds can be morphed to 'Identity' stream folds:
135--
136-- >>> purely = Fold.morphInner (Identity . unsafePerformIO)
137-- >>> Stream.fold (purely Array.write) $ Stream.fromList [1,2,3::Int]
138-- Identity fromList [1,2,3]
139--
140-- Since it is a pure stream we can use 'unsafePerformIO' to extract the result
141-- of fold from IO.
142--
143-- Alternatively, 'Identity' streams can be generalized to IO streams:
144--
145-- >>> pure = Stream.fromList [1,2,3] :: Stream Identity Int
146-- >>> generally = Stream.morphInner (return . runIdentity)
147-- >>> Stream.fold Array.write (generally pure :: Stream IO Int)
148-- fromList [1,2,3]
149--
150-- == Programming Tips
151--
152-- This module is designed to be imported qualified:
153--
154-- >>> import qualified Streamly.Data.Array as Array
156-- | Same as 'reader'
157--
158{-# DEPRECATED read "Please use 'reader' instead" #-}
159{-# INLINE_NORMAL read #-}
160read :: (Monad m, Unbox a) => Unfold m (Array a) a
161read = reader
163-- | Same as 'readerRev'
164--
165{-# DEPRECATED readRev "Please use 'readerRev' instead" #-}
166{-# INLINE_NORMAL readRev #-}
167readRev :: (Monad m, Unbox a) => Unfold m (Array a) a
168readRev = readerRev