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