-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Mutable and immutable arrays
gr
grIn addition to providing the <a>Data.Array</a> module <a>as specified
grin the Haskell 2010 Language Report</a>, this package also defines the
grclasses <a>IArray</a> of immutable arrays and <a>MArray</a> of arrays
grmutable within appropriate monads, as well as some instances of these
grclasses.
@package array
@version 0.5.2.0


-- | Basic non-strict arrays.
gr
gr<i>Note:</i> The <a>Data.Array.IArray</a> module provides a more
grgeneral interface to immutable arrays: it defines operations with the
grsame names as those defined below, but with more general types, and
gralso defines <a>Array</a> instances of the relevant classes. To use
grthat more general interface, import <a>Data.Array.IArray</a> but not
gr<a>Data.Array</a>.
module Data.Array

-- | The type of immutable non-strict (boxed) arrays with indices in
gr<tt>i</tt> and elements in <tt>e</tt>.
data Array i e

-- | Construct an array with the specified bounds and containing values for
grgiven indices within these bounds.
gr
grThe array is undefined (i.e. bottom) if any index in the list is out
grof bounds. The Haskell 2010 Report further specifies that if any two
grassociations in the list have the same index, the value at that index
gris undefined (i.e. bottom). However in GHC's implementation, the value
grat such an index is the value part of the last association with that
grindex in the list.
gr
grBecause the indices must be checked for these errors, <a>array</a> is
grstrict in the bounds argument and in the indices of the association
grlist, but non-strict in the values. Thus, recurrences such as the
grfollowing are possible:
gr
gr<pre>
gra = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i &lt;- [2..100]])
gr</pre>
gr
grNot every index within the bounds of the array need appear in the
grassociation list, but the values associated with indices that do not
grappear will be undefined (i.e. bottom).
gr
grIf, in any dimension, the lower bound is greater than the upper bound,
grthen the array is legal, but empty. Indexing an empty array always
grgives an array-bounds error, but <a>bounds</a> still yields the bounds
grwith which the array was constructed.
array :: Ix i => (i, i) -> [(i, e)] -> Array i e

-- | Construct an array from a pair of bounds and a list of values in index
grorder.
listArray :: Ix i => (i, i) -> [e] -> Array i e

-- | The <a>accumArray</a> function deals with repeated indices in the
grassociation list using an <i>accumulating function</i> which combines
grthe values of associations with the same index. For example, given a
grlist of values of some index type, <tt>hist</tt> produces a histogram
grof the number of occurrences of each index within a specified range:
gr
gr<pre>
grhist :: (Ix a, Num b) =&gt; (a,a) -&gt; [a] -&gt; Array a b
grhist bnds is = accumArray (+) 0 bnds [(i, 1) | i&lt;-is, inRange bnds i]
gr</pre>
gr
grIf the accumulating function is strict, then <a>accumArray</a> is
grstrict in the values, as well as the indices, in the association list.
grThus, unlike ordinary arrays built with <a>array</a>, accumulated
grarrays should not in general be recursive.
accumArray :: Ix i => e -> a -> e -> e -> (i, i) -> [(i, a)] -> Array i e

-- | The value at the given index in an array.
(!) :: Ix i => Array i e -> i -> e
infixl 9 !

-- | The bounds with which an array was constructed.
bounds :: () => Array i e -> (i, i)

-- | The list of indices of an array in ascending order.
indices :: Ix i => Array i e -> [i]

-- | The list of elements of an array in index order.
elems :: () => Array i e -> [e]

-- | The list of associations of an array in index order.
assocs :: Ix i => Array i e -> [(i, e)]

-- | Constructs an array identical to the first argument except that it has
grbeen updated by the associations in the right argument. For example,
grif <tt>m</tt> is a 1-origin, <tt>n</tt> by <tt>n</tt> matrix, then
gr
gr<pre>
grm//[((i,i), 0) | i &lt;- [1..n]]
gr</pre>
gr
gris the same matrix, except with the diagonal zeroed.
gr
grRepeated indices in the association list are handled as for
gr<a>array</a>: Haskell 2010 specifies that the resulting array is
grundefined (i.e. bottom), but GHC's implementation uses the last
grassociation for each index.
(//) :: Ix i => Array i e -> [(i, e)] -> Array i e
infixl 9 //

-- | <tt><a>accum</a> f</tt> takes an array and an association list and
graccumulates pairs from the list into the array with the accumulating
grfunction <tt>f</tt>. Thus <a>accumArray</a> can be defined using
gr<a>accum</a>:
gr
gr<pre>
graccumArray f z b = accum f (array b [(i, z) | i &lt;- range b])
gr</pre>
accum :: Ix i => e -> a -> e -> Array i e -> [(i, a)] -> Array i e

-- | <a>ixmap</a> allows for transformations on array indices. It may be
grthought of as providing function composition on the right with the
grmapping that the original array embodies.
gr
grA similar transformation of array values may be achieved using
gr<a>fmap</a> from the <a>Array</a> instance of the <a>Functor</a>
grclass.
ixmap :: (Ix i, Ix j) => (i, i) -> i -> j -> Array j e -> Array i e


-- | Immutable arrays, with an overloaded interface. For array types which
grcan be used with this interface, see the <a>Array</a> type exported by
grthis module and the <a>Data.Array.Unboxed</a> module. Other packages,
grsuch as diffarray, also provide arrays using this interface.
module Data.Array.IArray

-- | Class of immutable array types.
gr
grAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
grarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
gris the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
grthe element type. The <tt>IArray</tt> class is parameterised over both
gr<tt>a</tt> and <tt>e</tt>, so that instances specialised to certain
grelement types can be defined.
class IArray a e

-- | The type of immutable non-strict (boxed) arrays with indices in
gr<tt>i</tt> and elements in <tt>e</tt>.
data Array i e

-- | Constructs an immutable array from a pair of bounds and a list of
grinitial associations.
gr
grThe bounds are specified as a pair of the lowest and highest bounds in
grthe array respectively. For example, a one-origin vector of length 10
grhas bounds (1,10), and a one-origin 10 by 10 matrix has bounds
gr((1,1),(10,10)).
gr
grAn association is a pair of the form <tt>(i,x)</tt>, which defines the
grvalue of the array at index <tt>i</tt> to be <tt>x</tt>. The array is
grundefined if any index in the list is out of bounds. If any two
grassociations in the list have the same index, the value at that index
gris implementation-dependent. (In GHC, the last value specified for
grthat index is used. Other implementations will also do this for
grunboxed arrays, but Haskell 98 requires that for <tt>Array</tt> the
grvalue at such indices is bottom.)
gr
grBecause the indices must be checked for these errors, <a>array</a> is
grstrict in the bounds argument and in the indices of the association
grlist. Whether <tt>array</tt> is strict or non-strict in the elements
grdepends on the array type: <a>Array</a> is a non-strict array type,
grbut all of the <a>UArray</a> arrays are strict. Thus in a non-strict
grarray, recurrences such as the following are possible:
gr
gr<pre>
gra = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i \&lt;- [2..100]])
gr</pre>
gr
grNot every index within the bounds of the array need appear in the
grassociation list, but the values associated with indices that do not
grappear will be undefined.
gr
grIf, in any dimension, the lower bound is greater than the upper bound,
grthen the array is legal, but empty. Indexing an empty array always
grgives an array-bounds error, but <a>bounds</a> still yields the bounds
grwith which the array was constructed.
array :: (IArray a e, Ix i) => (i, i) -> [(i, e)] -> a i e

-- | Constructs an immutable array from a list of initial elements. The
grlist gives the elements of the array in ascending order beginning with
grthe lowest index.
listArray :: (IArray a e, Ix i) => (i, i) -> [e] -> a i e

-- | Constructs an immutable array from a list of associations. Unlike
gr<a>array</a>, the same index is allowed to occur multiple times in the
grlist of associations; an <i>accumulating function</i> is used to
grcombine the values of elements with the same index.
gr
grFor example, given a list of values of some index type, hist produces
gra histogram of the number of occurrences of each index within a
grspecified range:
gr
gr<pre>
grhist :: (Ix a, Num b) =&gt; (a,a) -&gt; [a] -&gt; Array a b
grhist bnds is = accumArray (+) 0 bnds [(i, 1) | i\&lt;-is, inRange bnds i]
gr</pre>
accumArray :: (IArray a e, Ix i) => (e -> e' -> e) -> e -> (i, i) -> [(i, e')] -> a i e

-- | Returns the element of an immutable array at the specified index.
(!) :: (IArray a e, Ix i) => a i e -> i -> e

-- | Extracts the bounds of an immutable array
bounds :: (IArray a e, Ix i) => a i e -> (i, i)

-- | Returns a list of all the valid indices in an array.
indices :: (IArray a e, Ix i) => a i e -> [i]

-- | Returns a list of all the elements of an array, in the same order as
grtheir indices.
elems :: (IArray a e, Ix i) => a i e -> [e]

-- | Returns the contents of an array as a list of associations.
assocs :: (IArray a e, Ix i) => a i e -> [(i, e)]

-- | Takes an array and a list of pairs and returns an array identical to
grthe left argument except that it has been updated by the associations
grin the right argument. For example, if m is a 1-origin, n by n matrix,
grthen <tt>m//[((i,i), 0) | i &lt;- [1..n]]</tt> is the same matrix,
grexcept with the diagonal zeroed.
gr
grAs with the <a>array</a> function, if any two associations in the list
grhave the same index, the value at that index is
grimplementation-dependent. (In GHC, the last value specified for that
grindex is used. Other implementations will also do this for unboxed
grarrays, but Haskell 98 requires that for <tt>Array</tt> the value at
grsuch indices is bottom.)
gr
grFor most array types, this operation is O(<i>n</i>) where <i>n</i> is
grthe size of the array. However, the diffarray package provides an
grarray type for which this operation has complexity linear in the
grnumber of updates.
(//) :: (IArray a e, Ix i) => a i e -> [(i, e)] -> a i e

-- | <tt>accum f</tt> takes an array and an association list and
graccumulates pairs from the list into the array with the accumulating
grfunction <tt>f</tt>. Thus <a>accumArray</a> can be defined using
gr<a>accum</a>:
gr
gr<pre>
graccumArray f z b = accum f (array b [(i, z) | i \&lt;- range b])
gr</pre>
accum :: (IArray a e, Ix i) => (e -> e' -> e) -> a i e -> [(i, e')] -> a i e

-- | Returns a new array derived from the original array by applying a
grfunction to each of the elements.
amap :: (IArray a e', IArray a e, Ix i) => (e' -> e) -> a i e' -> a i e

-- | Returns a new array derived from the original array by applying a
grfunction to each of the indices.
ixmap :: (IArray a e, Ix i, Ix j) => (i, i) -> (i -> j) -> a j e -> a i e


-- | An overloaded interface to mutable arrays. For array types which can
grbe used with this interface, see <a>Data.Array.IO</a>,
gr<a>Data.Array.ST</a>, and <a>Data.Array.Storable</a>.
module Data.Array.MArray

-- | Class of mutable array types.
gr
grAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
grarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
gris the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
grthe element type.
gr
grThe <tt>MArray</tt> class is parameterised over both <tt>a</tt> and
gr<tt>e</tt> (so that instances specialised to certain element types can
grbe defined, in the same way as for <a>IArray</a>), and also over the
grtype of the monad, <tt>m</tt>, in which the mutable array will be
grmanipulated.
class (Monad m) => MArray a e m

-- | Builds a new array, with every element initialised to the supplied
grvalue.
newArray :: (MArray a e m, Ix i) => (i, i) -> e -> m (a i e)

-- | Builds a new array, with every element initialised to an undefined
grvalue. In a monadic context in which operations must be deterministic
gr(e.g. the ST monad), the array elements are initialised to a fixed but
grundefined value, such as zero.
newArray_ :: (MArray a e m, Ix i) => (i, i) -> m (a i e)

-- | Constructs a mutable array from a list of initial elements. The list
grgives the elements of the array in ascending order beginning with the
grlowest index.
newListArray :: (MArray a e m, Ix i) => (i, i) -> [e] -> m (a i e)

-- | Read an element from a mutable array
readArray :: (MArray a e m, Ix i) => a i e -> i -> m e

-- | Write an element in a mutable array
writeArray :: (MArray a e m, Ix i) => a i e -> i -> e -> m ()

-- | Constructs a new array derived from the original array by applying a
grfunction to each of the elements.
mapArray :: (MArray a e' m, MArray a e m, Ix i) => (e' -> e) -> a i e' -> m (a i e)

-- | Constructs a new array derived from the original array by applying a
grfunction to each of the indices.
mapIndices :: (MArray a e m, Ix i, Ix j) => (i, i) -> (i -> j) -> a j e -> m (a i e)

-- | Returns the bounds of the array
getBounds :: (MArray a e m, Ix i) => a i e -> m (i, i)

-- | Return a list of all the elements of a mutable array
getElems :: (MArray a e m, Ix i) => a i e -> m [e]

-- | Return a list of all the associations of a mutable array, in index
grorder.
getAssocs :: (MArray a e m, Ix i) => a i e -> m [(i, e)]

-- | Converts a mutable array (any instance of <a>MArray</a>) to an
grimmutable array (any instance of <a>IArray</a>) by taking a complete
grcopy of it.
freeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)

-- | Converts an immutable array (any instance of <a>IArray</a>) into a
grmutable array (any instance of <a>MArray</a>) by taking a complete
grcopy of it.
thaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)


-- | Mutable boxed and unboxed arrays in the IO monad.
module Data.Array.IO

-- | An <a>IOArray</a> is a mutable, boxed, non-strict array in the
gr<a>IO</a> monad. The type arguments are as follows:
gr
gr<ul>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<a>Ix</a>)</li>
gr<li><tt>e</tt>: the element type of the array.</li>
gr</ul>
data IOArray i e

-- | Mutable, unboxed, strict arrays in the <a>IO</a> monad. The type
grarguments are as follows:
gr
gr<ul>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<tt>Ix</tt>)</li>
gr<li><tt>e</tt>: the element type of the array. Only certain element
grtypes are supported: see <a>Data.Array.MArray</a> for a list of
grinstances.</li>
gr</ul>
data IOUArray i e

-- | Reads a number of <a>Word8</a>s from the specified <a>Handle</a>
grdirectly into an array.
hGetArray :: Handle -> IOUArray Int Word8 -> Int -> IO Int

-- | Writes an array of <a>Word8</a> to the specified <a>Handle</a>.
hPutArray :: Handle -> IOUArray Int Word8 -> Int -> IO ()


-- | An overloaded interface to mutable arrays. For array types which can
grbe used with this interface, see <a>Data.Array.IO</a>,
gr<a>Data.Array.ST</a>, and <a>Data.Array.Storable</a>. . Safe API only
grof <a>Data.Array.MArray</a>.
module Data.Array.MArray.Safe

-- | Class of mutable array types.
gr
grAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
grarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
gris the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
grthe element type.
gr
grThe <tt>MArray</tt> class is parameterised over both <tt>a</tt> and
gr<tt>e</tt> (so that instances specialised to certain element types can
grbe defined, in the same way as for <a>IArray</a>), and also over the
grtype of the monad, <tt>m</tt>, in which the mutable array will be
grmanipulated.
class (Monad m) => MArray a e m

-- | Builds a new array, with every element initialised to the supplied
grvalue.
newArray :: (MArray a e m, Ix i) => (i, i) -> e -> m (a i e)

-- | Builds a new array, with every element initialised to an undefined
grvalue. In a monadic context in which operations must be deterministic
gr(e.g. the ST monad), the array elements are initialised to a fixed but
grundefined value, such as zero.
newArray_ :: (MArray a e m, Ix i) => (i, i) -> m (a i e)

-- | Constructs a mutable array from a list of initial elements. The list
grgives the elements of the array in ascending order beginning with the
grlowest index.
newListArray :: (MArray a e m, Ix i) => (i, i) -> [e] -> m (a i e)

-- | Read an element from a mutable array
readArray :: (MArray a e m, Ix i) => a i e -> i -> m e

-- | Write an element in a mutable array
writeArray :: (MArray a e m, Ix i) => a i e -> i -> e -> m ()

-- | Constructs a new array derived from the original array by applying a
grfunction to each of the elements.
mapArray :: (MArray a e' m, MArray a e m, Ix i) => (e' -> e) -> a i e' -> m (a i e)

-- | Constructs a new array derived from the original array by applying a
grfunction to each of the indices.
mapIndices :: (MArray a e m, Ix i, Ix j) => (i, i) -> (i -> j) -> a j e -> m (a i e)

-- | Returns the bounds of the array
getBounds :: (MArray a e m, Ix i) => a i e -> m (i, i)

-- | Return a list of all the elements of a mutable array
getElems :: (MArray a e m, Ix i) => a i e -> m [e]

-- | Return a list of all the associations of a mutable array, in index
grorder.
getAssocs :: (MArray a e m, Ix i) => a i e -> m [(i, e)]

-- | Converts a mutable array (any instance of <a>MArray</a>) to an
grimmutable array (any instance of <a>IArray</a>) by taking a complete
grcopy of it.
freeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)

-- | Converts an immutable array (any instance of <a>IArray</a>) into a
grmutable array (any instance of <a>MArray</a>) by taking a complete
grcopy of it.
thaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)


-- | Mutable boxed and unboxed arrays in the IO monad. . Safe API only of
gr<a>Data.Array.IO</a>.
module Data.Array.IO.Safe

-- | An <a>IOArray</a> is a mutable, boxed, non-strict array in the
gr<a>IO</a> monad. The type arguments are as follows:
gr
gr<ul>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<a>Ix</a>)</li>
gr<li><tt>e</tt>: the element type of the array.</li>
gr</ul>
data IOArray i e

-- | Mutable, unboxed, strict arrays in the <a>IO</a> monad. The type
grarguments are as follows:
gr
gr<ul>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<tt>Ix</tt>)</li>
gr<li><tt>e</tt>: the element type of the array. Only certain element
grtypes are supported: see <a>Data.Array.MArray</a> for a list of
grinstances.</li>
gr</ul>
data IOUArray i e

-- | Reads a number of <a>Word8</a>s from the specified <a>Handle</a>
grdirectly into an array.
hGetArray :: Handle -> IOUArray Int Word8 -> Int -> IO Int

-- | Writes an array of <a>Word8</a> to the specified <a>Handle</a>.
hPutArray :: Handle -> IOUArray Int Word8 -> Int -> IO ()


-- | Mutable boxed and unboxed arrays in the <a>ST</a> monad.
module Data.Array.ST

-- | Mutable, boxed, non-strict arrays in the <a>ST</a> monad. The type
grarguments are as follows:
gr
gr<ul>
gr<li><tt>s</tt>: the state variable argument for the <a>ST</a>
grtype</li>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<a>Ix</a>)</li>
gr<li><tt>e</tt>: the element type of the array.</li>
gr</ul>
data STArray s i e

-- | A safe way to create and work with a mutable array before returning an
grimmutable array for later perusal. This function avoids copying the
grarray before returning it - it uses <tt>unsafeFreeze</tt> internally,
grbut this wrapper is a safe interface to that function.
runSTArray :: (forall s. ST s (STArray s i e)) -> Array i e

-- | A mutable array with unboxed elements, that can be manipulated in the
gr<a>ST</a> monad. The type arguments are as follows:
gr
gr<ul>
gr<li><tt>s</tt>: the state variable argument for the <a>ST</a>
grtype</li>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<tt>Ix</tt>)</li>
gr<li><tt>e</tt>: the element type of the array. Only certain element
grtypes are supported.</li>
gr</ul>
gr
grAn <a>STUArray</a> will generally be more efficient (in terms of both
grtime and space) than the equivalent boxed version (<a>STArray</a>)
grwith the same element type. However, <a>STUArray</a> is strict in its
grelements - so don't use <a>STUArray</a> if you require the
grnon-strictness that <a>STArray</a> provides.
data STUArray s i e

-- | A safe way to create and work with an unboxed mutable array before
grreturning an immutable array for later perusal. This function avoids
grcopying the array before returning it - it uses <tt>unsafeFreeze</tt>
grinternally, but this wrapper is a safe interface to that function.
runSTUArray :: (forall s. ST s (STUArray s i e)) -> UArray i e


-- | Mutable boxed and unboxed arrays in the <a>ST</a> monad.
gr
grSafe API only of <a>Data.Array.ST</a>.
module Data.Array.ST.Safe

-- | Mutable, boxed, non-strict arrays in the <a>ST</a> monad. The type
grarguments are as follows:
gr
gr<ul>
gr<li><tt>s</tt>: the state variable argument for the <a>ST</a>
grtype</li>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<a>Ix</a>)</li>
gr<li><tt>e</tt>: the element type of the array.</li>
gr</ul>
data STArray s i e

-- | A safe way to create and work with a mutable array before returning an
grimmutable array for later perusal. This function avoids copying the
grarray before returning it - it uses <tt>unsafeFreeze</tt> internally,
grbut this wrapper is a safe interface to that function.
runSTArray :: (forall s. ST s (STArray s i e)) -> Array i e

-- | A mutable array with unboxed elements, that can be manipulated in the
gr<a>ST</a> monad. The type arguments are as follows:
gr
gr<ul>
gr<li><tt>s</tt>: the state variable argument for the <a>ST</a>
grtype</li>
gr<li><tt>i</tt>: the index type of the array (should be an instance of
gr<tt>Ix</tt>)</li>
gr<li><tt>e</tt>: the element type of the array. Only certain element
grtypes are supported.</li>
gr</ul>
gr
grAn <a>STUArray</a> will generally be more efficient (in terms of both
grtime and space) than the equivalent boxed version (<a>STArray</a>)
grwith the same element type. However, <a>STUArray</a> is strict in its
grelements - so don't use <a>STUArray</a> if you require the
grnon-strictness that <a>STArray</a> provides.
data STUArray s i e

-- | A safe way to create and work with an unboxed mutable array before
grreturning an immutable array for later perusal. This function avoids
grcopying the array before returning it - it uses <tt>unsafeFreeze</tt>
grinternally, but this wrapper is a safe interface to that function.
runSTUArray :: (forall s. ST s (STUArray s i e)) -> UArray i e


-- | A storable array is an IO-mutable array which stores its contents in a
grcontiguous memory block living in the C heap. Elements are stored
graccording to the class <tt>Storable</tt>. You can obtain the pointer
grto the array contents to manipulate elements from languages like C.
gr
grIt is similar to <a>IOUArray</a> but slower. Its advantage is that
grit's compatible with C.
module Data.Array.Storable

-- | The array type
data StorableArray i e

-- | The pointer to the array contents is obtained by
gr<a>withStorableArray</a>. The idea is similar to <a>ForeignPtr</a>
gr(used internally here). The pointer should be used only during
grexecution of the <a>IO</a> action retured by the function passed as
grargument to <a>withStorableArray</a>.
withStorableArray :: StorableArray i e -> (Ptr e -> IO a) -> IO a

-- | If you want to use it afterwards, ensure that you
gr<a>touchStorableArray</a> after the last use of the pointer, so the
grarray is not freed too early.
touchStorableArray :: StorableArray i e -> IO ()


-- | A storable array is an IO-mutable array which stores its contents in a
grcontiguous memory block living in the C heap. Elements are stored
graccording to the class <tt>Storable</tt>. You can obtain the pointer
grto the array contents to manipulate elements from languages like C.
gr
grIt is similar to <a>IOUArray</a> but slower. Its advantage is that
grit's compatible with C.
gr
grSafe API only of <a>Data.Array.Storable</a>.
module Data.Array.Storable.Safe

-- | The array type
data StorableArray i e

-- | The pointer to the array contents is obtained by
gr<a>withStorableArray</a>. The idea is similar to <a>ForeignPtr</a>
gr(used internally here). The pointer should be used only during
grexecution of the <a>IO</a> action retured by the function passed as
grargument to <a>withStorableArray</a>.
withStorableArray :: StorableArray i e -> (Ptr e -> IO a) -> IO a

-- | If you want to use it afterwards, ensure that you
gr<a>touchStorableArray</a> after the last use of the pointer, so the
grarray is not freed too early.
touchStorableArray :: StorableArray i e -> IO ()


-- | Unboxed immutable arrays.
module Data.Array.Unboxed

-- | Arrays with unboxed elements. Instances of <a>IArray</a> are provided
grfor <a>UArray</a> with certain element types (<a>Int</a>,
gr<a>Float</a>, <a>Char</a>, etc.; see the <a>UArray</a> class for a
grfull list).
gr
grA <a>UArray</a> will generally be more efficient (in terms of both
grtime and space) than the equivalent <a>Array</a> with the same element
grtype. However, <a>UArray</a> is strict in its elements - so don't use
gr<a>UArray</a> if you require the non-strictness that <a>Array</a>
grprovides.
gr
grBecause the <tt>IArray</tt> interface provides operations overloaded
gron the type of the array, it should be possible to just change the
grarray type being used by a program from say <tt>Array</tt> to
gr<tt>UArray</tt> to get the benefits of unboxed arrays (don't forget to
grimport <a>Data.Array.Unboxed</a> instead of <a>Data.Array</a>).
data UArray i e


-- | Contains the various unsafe operations that can be performed on
grarrays.
module Data.Array.Unsafe

-- | Casts an <a>STUArray</a> with one element type into one with a
grdifferent element type. All the elements of the resulting array are
grundefined (unless you know what you're doing...).
castSTUArray :: STUArray s ix a -> ST s (STUArray s ix b)

-- | Casts an <a>IOUArray</a> with one element type into one with a
grdifferent element type. All the elements of the resulting array are
grundefined (unless you know what you're doing...).
castIOUArray :: IOUArray ix a -> IO (IOUArray ix b)

-- | Converts an mutable array into an immutable array. The implementation
grmay either simply cast the array from one type to the other without
grcopying the array, or it may take a full copy of the array.
gr
grNote that because the array is possibly not copied, any subsequent
grmodifications made to the mutable version of the array may be shared
grwith the immutable version. It is safe to use, therefore, if the
grmutable version is never modified after the freeze operation.
gr
grThe non-copying implementation is supported between certain pairs of
grarray types only; one constraint is that the array types must have
gridentical representations. In GHC, The following pairs of array types
grhave a non-copying O(1) implementation of <a>unsafeFreeze</a>. Because
grthe optimised versions are enabled by specialisations, you will need
grto compile with optimisation (-O) to get them.
gr
gr<ul>
gr<li><a>IOUArray</a> -&gt; <a>UArray</a></li>
gr<li><a>STUArray</a> -&gt; <a>UArray</a></li>
gr<li><a>IOArray</a> -&gt; <a>Array</a></li>
gr<li><a>STArray</a> -&gt; <a>Array</a></li>
gr</ul>
unsafeFreeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)

-- | Converts an immutable array into a mutable array. The implementation
grmay either simply cast the array from one type to the other without
grcopying the array, or it may take a full copy of the array.
gr
grNote that because the array is possibly not copied, any subsequent
grmodifications made to the mutable version of the array may be shared
grwith the immutable version. It is only safe to use, therefore, if the
grimmutable array is never referenced again in this thread, and there is
grno possibility that it can be also referenced in another thread. If
gryou use an unsafeThaw<i>write</i>unsafeFreeze sequence in a
grmulti-threaded setting, then you must ensure that this sequence is
gratomic with respect to other threads, or a garbage collector crash may
grresult (because the write may be writing to a frozen array).
gr
grThe non-copying implementation is supported between certain pairs of
grarray types only; one constraint is that the array types must have
gridentical representations. In GHC, The following pairs of array types
grhave a non-copying O(1) implementation of <a>unsafeThaw</a>. Because
grthe optimised versions are enabled by specialisations, you will need
grto compile with optimisation (-O) to get them.
gr
gr<ul>
gr<li><a>UArray</a> -&gt; <a>IOUArray</a></li>
gr<li><a>UArray</a> -&gt; <a>STUArray</a></li>
gr<li><a>Array</a> -&gt; <a>IOArray</a></li>
gr<li><a>Array</a> -&gt; <a>STArray</a></li>
gr</ul>
unsafeThaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)

-- | Construct a <a>StorableArray</a> from an arbitrary <a>ForeignPtr</a>.
grIt is the caller's responsibility to ensure that the <a>ForeignPtr</a>
grpoints to an area of memory sufficient for the specified bounds.
unsafeForeignPtrToStorableArray :: Ix i => ForeignPtr e -> (i, i) -> IO (StorableArray i e)
