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


-- | Mutable and immutable arrays
°5u
°5uIn addition to providing the <a>Data.Array</a> module <a>as specified
°5uin the Haskell 2010 Language Report</a>, this package also defines the
°5uclasses <a>IArray</a> of immutable arrays and <a>MArray</a> of arrays
°5umutable within appropriate monads, as well as some instances of these
°5uclasses.
@package array
@version 0.5.2.0


-- | Basic non-strict arrays.
°5u
°5u<i>Note:</i> The <a>Data.Array.IArray</a> module provides a more
°5ugeneral interface to immutable arrays: it defines operations with the
°5usame names as those defined below, but with more general types, and
°5ualso defines <a>Array</a> instances of the relevant classes. To use
°5uthat more general interface, import <a>Data.Array.IArray</a> but not
°5u<a>Data.Array</a>.
module Data.Array

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

-- | Construct an array with the specified bounds and containing values for
°5ugiven indices within these bounds.
°5u
°5uThe array is undefined (i.e. bottom) if any index in the list is out
°5uof bounds. The Haskell 2010 Report further specifies that if any two
°5uassociations in the list have the same index, the value at that index
°5uis undefined (i.e. bottom). However in GHC's implementation, the value
°5uat such an index is the value part of the last association with that
°5uindex in the list.
°5u
°5uBecause the indices must be checked for these errors, <a>array</a> is
°5ustrict in the bounds argument and in the indices of the association
°5ulist, but non-strict in the values. Thus, recurrences such as the
°5ufollowing are possible:
°5u
°5u<pre>
°5ua = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i &lt;- [2..100]])
°5u</pre>
°5u
°5uNot every index within the bounds of the array need appear in the
°5uassociation list, but the values associated with indices that do not
°5uappear will be undefined (i.e. bottom).
°5u
°5uIf, in any dimension, the lower bound is greater than the upper bound,
°5uthen the array is legal, but empty. Indexing an empty array always
°5ugives an array-bounds error, but <a>bounds</a> still yields the bounds
°5uwith 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
°5uorder.
listArray :: Ix i => (i, i) -> [e] -> Array i e

-- | The <a>accumArray</a> function deals with repeated indices in the
°5uassociation list using an <i>accumulating function</i> which combines
°5uthe values of associations with the same index. For example, given a
°5ulist of values of some index type, <tt>hist</tt> produces a histogram
°5uof the number of occurrences of each index within a specified range:
°5u
°5u<pre>
°5uhist :: (Ix a, Num b) =&gt; (a,a) -&gt; [a] -&gt; Array a b
°5uhist bnds is = accumArray (+) 0 bnds [(i, 1) | i&lt;-is, inRange bnds i]
°5u</pre>
°5u
°5uIf the accumulating function is strict, then <a>accumArray</a> is
°5ustrict in the values, as well as the indices, in the association list.
°5uThus, unlike ordinary arrays built with <a>array</a>, accumulated
°5uarrays 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
°5ubeen updated by the associations in the right argument. For example,
°5uif <tt>m</tt> is a 1-origin, <tt>n</tt> by <tt>n</tt> matrix, then
°5u
°5u<pre>
°5um//[((i,i), 0) | i &lt;- [1..n]]
°5u</pre>
°5u
°5uis the same matrix, except with the diagonal zeroed.
°5u
°5uRepeated indices in the association list are handled as for
°5u<a>array</a>: Haskell 2010 specifies that the resulting array is
°5uundefined (i.e. bottom), but GHC's implementation uses the last
°5uassociation 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
°5uaccumulates pairs from the list into the array with the accumulating
°5ufunction <tt>f</tt>. Thus <a>accumArray</a> can be defined using
°5u<a>accum</a>:
°5u
°5u<pre>
°5uaccumArray f z b = accum f (array b [(i, z) | i &lt;- range b])
°5u</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
°5uthought of as providing function composition on the right with the
°5umapping that the original array embodies.
°5u
°5uA similar transformation of array values may be achieved using
°5u<a>fmap</a> from the <a>Array</a> instance of the <a>Functor</a>
°5uclass.
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
°5ucan be used with this interface, see the <a>Array</a> type exported by
°5uthis module and the <a>Data.Array.Unboxed</a> module. Other packages,
°5usuch as diffarray, also provide arrays using this interface.
module Data.Array.IArray

-- | Class of immutable array types.
°5u
°5uAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
°5uarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
°5uis the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
°5uthe element type. The <tt>IArray</tt> class is parameterised over both
°5u<tt>a</tt> and <tt>e</tt>, so that instances specialised to certain
°5uelement types can be defined.
class IArray a e

-- | The type of immutable non-strict (boxed) arrays with indices in
°5u<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
°5uinitial associations.
°5u
°5uThe bounds are specified as a pair of the lowest and highest bounds in
°5uthe array respectively. For example, a one-origin vector of length 10
°5uhas bounds (1,10), and a one-origin 10 by 10 matrix has bounds
°5u((1,1),(10,10)).
°5u
°5uAn association is a pair of the form <tt>(i,x)</tt>, which defines the
°5uvalue of the array at index <tt>i</tt> to be <tt>x</tt>. The array is
°5uundefined if any index in the list is out of bounds. If any two
°5uassociations in the list have the same index, the value at that index
°5uis implementation-dependent. (In GHC, the last value specified for
°5uthat index is used. Other implementations will also do this for
°5uunboxed arrays, but Haskell 98 requires that for <tt>Array</tt> the
°5uvalue at such indices is bottom.)
°5u
°5uBecause the indices must be checked for these errors, <a>array</a> is
°5ustrict in the bounds argument and in the indices of the association
°5ulist. Whether <tt>array</tt> is strict or non-strict in the elements
°5udepends on the array type: <a>Array</a> is a non-strict array type,
°5ubut all of the <a>UArray</a> arrays are strict. Thus in a non-strict
°5uarray, recurrences such as the following are possible:
°5u
°5u<pre>
°5ua = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i \&lt;- [2..100]])
°5u</pre>
°5u
°5uNot every index within the bounds of the array need appear in the
°5uassociation list, but the values associated with indices that do not
°5uappear will be undefined.
°5u
°5uIf, in any dimension, the lower bound is greater than the upper bound,
°5uthen the array is legal, but empty. Indexing an empty array always
°5ugives an array-bounds error, but <a>bounds</a> still yields the bounds
°5uwith 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
°5ulist gives the elements of the array in ascending order beginning with
°5uthe lowest index.
listArray :: (IArray a e, Ix i) => (i, i) -> [e] -> a i e

-- | Constructs an immutable array from a list of associations. Unlike
°5u<a>array</a>, the same index is allowed to occur multiple times in the
°5ulist of associations; an <i>accumulating function</i> is used to
°5ucombine the values of elements with the same index.
°5u
°5uFor example, given a list of values of some index type, hist produces
°5ua histogram of the number of occurrences of each index within a
°5uspecified range:
°5u
°5u<pre>
°5uhist :: (Ix a, Num b) =&gt; (a,a) -&gt; [a] -&gt; Array a b
°5uhist bnds is = accumArray (+) 0 bnds [(i, 1) | i\&lt;-is, inRange bnds i]
°5u</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
°5utheir 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
°5uthe left argument except that it has been updated by the associations
°5uin the right argument. For example, if m is a 1-origin, n by n matrix,
°5uthen <tt>m//[((i,i), 0) | i &lt;- [1..n]]</tt> is the same matrix,
°5uexcept with the diagonal zeroed.
°5u
°5uAs with the <a>array</a> function, if any two associations in the list
°5uhave the same index, the value at that index is
°5uimplementation-dependent. (In GHC, the last value specified for that
°5uindex is used. Other implementations will also do this for unboxed
°5uarrays, but Haskell 98 requires that for <tt>Array</tt> the value at
°5usuch indices is bottom.)
°5u
°5uFor most array types, this operation is O(<i>n</i>) where <i>n</i> is
°5uthe size of the array. However, the diffarray package provides an
°5uarray type for which this operation has complexity linear in the
°5unumber 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
°5uaccumulates pairs from the list into the array with the accumulating
°5ufunction <tt>f</tt>. Thus <a>accumArray</a> can be defined using
°5u<a>accum</a>:
°5u
°5u<pre>
°5uaccumArray f z b = accum f (array b [(i, z) | i \&lt;- range b])
°5u</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
°5ufunction 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
°5ufunction 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
°5ube used with this interface, see <a>Data.Array.IO</a>,
°5u<a>Data.Array.ST</a>, and <a>Data.Array.Storable</a>.
module Data.Array.MArray

-- | Class of mutable array types.
°5u
°5uAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
°5uarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
°5uis the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
°5uthe element type.
°5u
°5uThe <tt>MArray</tt> class is parameterised over both <tt>a</tt> and
°5u<tt>e</tt> (so that instances specialised to certain element types can
°5ube defined, in the same way as for <a>IArray</a>), and also over the
°5utype of the monad, <tt>m</tt>, in which the mutable array will be
°5umanipulated.
class (Monad m) => MArray a e m

-- | Builds a new array, with every element initialised to the supplied
°5uvalue.
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
°5uvalue. In a monadic context in which operations must be deterministic
°5u(e.g. the ST monad), the array elements are initialised to a fixed but
°5uundefined 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
°5ugives the elements of the array in ascending order beginning with the
°5ulowest 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
°5ufunction 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
°5ufunction 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
°5uorder.
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
°5uimmutable array (any instance of <a>IArray</a>) by taking a complete
°5ucopy 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
°5umutable array (any instance of <a>MArray</a>) by taking a complete
°5ucopy 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
°5u<a>IO</a> monad. The type arguments are as follows:
°5u
°5u<ul>
°5u<li><tt>i</tt>: the index type of the array (should be an instance of
°5u<a>Ix</a>)</li>
°5u<li><tt>e</tt>: the element type of the array.</li>
°5u</ul>
data IOArray i e

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

-- | Reads a number of <a>Word8</a>s from the specified <a>Handle</a>
°5udirectly 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
°5ube used with this interface, see <a>Data.Array.IO</a>,
°5u<a>Data.Array.ST</a>, and <a>Data.Array.Storable</a>. . Safe API only
°5uof <a>Data.Array.MArray</a>.
module Data.Array.MArray.Safe

-- | Class of mutable array types.
°5u
°5uAn array type has the form <tt>(a i e)</tt> where <tt>a</tt> is the
°5uarray type constructor (kind <tt>* -&gt; * -&gt; *</tt>), <tt>i</tt>
°5uis the index type (a member of the class <a>Ix</a>), and <tt>e</tt> is
°5uthe element type.
°5u
°5uThe <tt>MArray</tt> class is parameterised over both <tt>a</tt> and
°5u<tt>e</tt> (so that instances specialised to certain element types can
°5ube defined, in the same way as for <a>IArray</a>), and also over the
°5utype of the monad, <tt>m</tt>, in which the mutable array will be
°5umanipulated.
class (Monad m) => MArray a e m

-- | Builds a new array, with every element initialised to the supplied
°5uvalue.
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
°5uvalue. In a monadic context in which operations must be deterministic
°5u(e.g. the ST monad), the array elements are initialised to a fixed but
°5uundefined 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
°5ugives the elements of the array in ascending order beginning with the
°5ulowest 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
°5ufunction 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
°5ufunction 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
°5uorder.
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
°5uimmutable array (any instance of <a>IArray</a>) by taking a complete
°5ucopy 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
°5umutable array (any instance of <a>MArray</a>) by taking a complete
°5ucopy 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
°5u<a>Data.Array.IO</a>.
module Data.Array.IO.Safe

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

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

-- | Reads a number of <a>Word8</a>s from the specified <a>Handle</a>
°5udirectly 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
°5uarguments are as follows:
°5u
°5u<ul>
°5u<li><tt>s</tt>: the state variable argument for the <a>ST</a>
°5utype</li>
°5u<li><tt>i</tt>: the index type of the array (should be an instance of
°5u<a>Ix</a>)</li>
°5u<li><tt>e</tt>: the element type of the array.</li>
°5u</ul>
data STArray s i e

-- | A safe way to create and work with a mutable array before returning an
°5uimmutable array for later perusal. This function avoids copying the
°5uarray before returning it - it uses <tt>unsafeFreeze</tt> internally,
°5ubut 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
°5u<a>ST</a> monad. The type arguments are as follows:
°5u
°5u<ul>
°5u<li><tt>s</tt>: the state variable argument for the <a>ST</a>
°5utype</li>
°5u<li><tt>i</tt>: the index type of the array (should be an instance of
°5u<tt>Ix</tt>)</li>
°5u<li><tt>e</tt>: the element type of the array. Only certain element
°5utypes are supported.</li>
°5u</ul>
°5u
°5uAn <a>STUArray</a> will generally be more efficient (in terms of both
°5utime and space) than the equivalent boxed version (<a>STArray</a>)
°5uwith the same element type. However, <a>STUArray</a> is strict in its
°5uelements - so don't use <a>STUArray</a> if you require the
°5unon-strictness that <a>STArray</a> provides.
data STUArray s i e

-- | A safe way to create and work with an unboxed mutable array before
°5ureturning an immutable array for later perusal. This function avoids
°5ucopying the array before returning it - it uses <tt>unsafeFreeze</tt>
°5uinternally, 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.
°5u
°5uSafe 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
°5uarguments are as follows:
°5u
°5u<ul>
°5u<li><tt>s</tt>: the state variable argument for the <a>ST</a>
°5utype</li>
°5u<li><tt>i</tt>: the index type of the array (should be an instance of
°5u<a>Ix</a>)</li>
°5u<li><tt>e</tt>: the element type of the array.</li>
°5u</ul>
data STArray s i e

-- | A safe way to create and work with a mutable array before returning an
°5uimmutable array for later perusal. This function avoids copying the
°5uarray before returning it - it uses <tt>unsafeFreeze</tt> internally,
°5ubut 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
°5u<a>ST</a> monad. The type arguments are as follows:
°5u
°5u<ul>
°5u<li><tt>s</tt>: the state variable argument for the <a>ST</a>
°5utype</li>
°5u<li><tt>i</tt>: the index type of the array (should be an instance of
°5u<tt>Ix</tt>)</li>
°5u<li><tt>e</tt>: the element type of the array. Only certain element
°5utypes are supported.</li>
°5u</ul>
°5u
°5uAn <a>STUArray</a> will generally be more efficient (in terms of both
°5utime and space) than the equivalent boxed version (<a>STArray</a>)
°5uwith the same element type. However, <a>STUArray</a> is strict in its
°5uelements - so don't use <a>STUArray</a> if you require the
°5unon-strictness that <a>STArray</a> provides.
data STUArray s i e

-- | A safe way to create and work with an unboxed mutable array before
°5ureturning an immutable array for later perusal. This function avoids
°5ucopying the array before returning it - it uses <tt>unsafeFreeze</tt>
°5uinternally, 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
°5ucontiguous memory block living in the C heap. Elements are stored
°5uaccording to the class <tt>Storable</tt>. You can obtain the pointer
°5uto the array contents to manipulate elements from languages like C.
°5u
°5uIt is similar to <a>IOUArray</a> but slower. Its advantage is that
°5uit's compatible with C.
module Data.Array.Storable

-- | The array type
data StorableArray i e

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

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


-- | A storable array is an IO-mutable array which stores its contents in a
°5ucontiguous memory block living in the C heap. Elements are stored
°5uaccording to the class <tt>Storable</tt>. You can obtain the pointer
°5uto the array contents to manipulate elements from languages like C.
°5u
°5uIt is similar to <a>IOUArray</a> but slower. Its advantage is that
°5uit's compatible with C.
°5u
°5uSafe 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
°5u<a>withStorableArray</a>. The idea is similar to <a>ForeignPtr</a>
°5u(used internally here). The pointer should be used only during
°5uexecution of the <a>IO</a> action retured by the function passed as
°5uargument to <a>withStorableArray</a>.
withStorableArray :: StorableArray i e -> (Ptr e -> IO a) -> IO a

-- | If you want to use it afterwards, ensure that you
°5u<a>touchStorableArray</a> after the last use of the pointer, so the
°5uarray 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
°5ufor <a>UArray</a> with certain element types (<a>Int</a>,
°5u<a>Float</a>, <a>Char</a>, etc.; see the <a>UArray</a> class for a
°5ufull list).
°5u
°5uA <a>UArray</a> will generally be more efficient (in terms of both
°5utime and space) than the equivalent <a>Array</a> with the same element
°5utype. However, <a>UArray</a> is strict in its elements - so don't use
°5u<a>UArray</a> if you require the non-strictness that <a>Array</a>
°5uprovides.
°5u
°5uBecause the <tt>IArray</tt> interface provides operations overloaded
°5uon the type of the array, it should be possible to just change the
°5uarray type being used by a program from say <tt>Array</tt> to
°5u<tt>UArray</tt> to get the benefits of unboxed arrays (don't forget to
°5uimport <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
°5uarrays.
module Data.Array.Unsafe

-- | Casts an <a>STUArray</a> with one element type into one with a
°5udifferent element type. All the elements of the resulting array are
°5uundefined (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
°5udifferent element type. All the elements of the resulting array are
°5uundefined (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
°5umay either simply cast the array from one type to the other without
°5ucopying the array, or it may take a full copy of the array.
°5u
°5uNote that because the array is possibly not copied, any subsequent
°5umodifications made to the mutable version of the array may be shared
°5uwith the immutable version. It is safe to use, therefore, if the
°5umutable version is never modified after the freeze operation.
°5u
°5uThe non-copying implementation is supported between certain pairs of
°5uarray types only; one constraint is that the array types must have
°5uidentical representations. In GHC, The following pairs of array types
°5uhave a non-copying O(1) implementation of <a>unsafeFreeze</a>. Because
°5uthe optimised versions are enabled by specialisations, you will need
°5uto compile with optimisation (-O) to get them.
°5u
°5u<ul>
°5u<li><a>IOUArray</a> -&gt; <a>UArray</a></li>
°5u<li><a>STUArray</a> -&gt; <a>UArray</a></li>
°5u<li><a>IOArray</a> -&gt; <a>Array</a></li>
°5u<li><a>STArray</a> -&gt; <a>Array</a></li>
°5u</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
°5umay either simply cast the array from one type to the other without
°5ucopying the array, or it may take a full copy of the array.
°5u
°5uNote that because the array is possibly not copied, any subsequent
°5umodifications made to the mutable version of the array may be shared
°5uwith the immutable version. It is only safe to use, therefore, if the
°5uimmutable array is never referenced again in this thread, and there is
°5uno possibility that it can be also referenced in another thread. If
°5uyou use an unsafeThaw<i>write</i>unsafeFreeze sequence in a
°5umulti-threaded setting, then you must ensure that this sequence is
°5uatomic with respect to other threads, or a garbage collector crash may
°5uresult (because the write may be writing to a frozen array).
°5u
°5uThe non-copying implementation is supported between certain pairs of
°5uarray types only; one constraint is that the array types must have
°5uidentical representations. In GHC, The following pairs of array types
°5uhave a non-copying O(1) implementation of <a>unsafeThaw</a>. Because
°5uthe optimised versions are enabled by specialisations, you will need
°5uto compile with optimisation (-O) to get them.
°5u
°5u<ul>
°5u<li><a>UArray</a> -&gt; <a>IOUArray</a></li>
°5u<li><a>UArray</a> -&gt; <a>STUArray</a></li>
°5u<li><a>Array</a> -&gt; <a>IOArray</a></li>
°5u<li><a>Array</a> -&gt; <a>STArray</a></li>
°5u</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>.
°5uIt is the caller's responsibility to ensure that the <a>ForeignPtr</a>
°5upoints to an area of memory sufficient for the specified bounds.
unsafeForeignPtrToStorableArray :: Ix i => ForeignPtr e -> (i, i) -> IO (StorableArray i e)
