-- 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)
