array-0.5.0.0: Mutable and immutable arrays

Copyright | (c) The University of Glasgow 2011
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | non-portable (uses Data.Array.MArray)
Safe Haskell | None
Language | Haskell2010

Data.Array.Unsafe

Contents

- Unsafe operations

Description

Contains the various unsafe operations that can be performed on arrays.

Since: 0.4.0.0

Synopsis

- castSTUArray :: STUArray s ix a -> ST s (STUArray s ix b)
- castIOUArray :: IOUArray ix a -> IO (IOUArray ix b)
- unsafeFreeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)
- unsafeThaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)
- unsafeForeignPtrToStorableArray :: Ix i => ForeignPtr e -> (i, i) -> IO (StorableArray i e)

# Unsafe operations

castSTUArray :: STUArray s ix a -> ST s (STUArray s ix b)

Casts an `STUArray` with one element type into one with a different element type. All the elements of the resulting array are undefined (unless you know what you're doing...).

castIOUArray :: IOUArray ix a -> IO (IOUArray ix b)

Casts an `IOUArray` with one element type into one with a different element type. All the elements of the resulting array are undefined (unless you know what you're doing...).

unsafeFreeze :: (Ix i, MArray a e m, IArray b e) => a i e -> m (b i e)

Converts an mutable array into an immutable array. The implementation may either simply cast the array from one type to the other without copying the array, or it may take a full copy of the array.

Note that because the array is possibly not copied, any subsequent modifications made to the mutable version of the array may be shared with the immutable version. It is safe to use, therefore, if the mutable version is never modified after the freeze operation.

The non-copying implementation is supported between certain pairs of array types only; one constraint is that the array types must have identical representations. In GHC, The following pairs of array types have a non-copying O(1) implementation of `unsafeFreeze`. Because the optimised versions are enabled by specialisations, you will need to compile with optimisation (-O) to get them.

- `IOUArray` -> `UArray`
  - `STUArray` -> `UArray`
  - `IOArray` -> `Array`
  - `STArray` -> `Array`

unsafeThaw :: (Ix i, IArray a e, MArray b e m) => a i e -> m (b i e)

Converts an immutable array into a mutable array. The implementation may either simply cast the array from one type to the other without copying the array, or it may take a full copy of the array.

Note that because the array is possibly not copied, any subsequent modifications made to the mutable version of the array may be shared with the immutable version. It is only safe to use, therefore, if the immutable array is never referenced again in this thread, and there is no possibility that it can be also referenced in another thread. If you use an unsafeThawwriteunsafeFreeze sequence in a multi-threaded setting, then you must ensure that this sequence is atomic with respect to other threads, or a garbage collector crash may result (because the write may be writing to a frozen array).

The non-copying implementation is supported between certain pairs of array types only; one constraint is that the array types must have identical representations. In GHC, The following pairs of array types have a non-copying O(1) implementation of `unsafeThaw`. Because the optimised versions are enabled by specialisations, you will need to compile with optimisation (-O) to get them.

- `UArray` -> `IOUArray`
  - `UArray` -> `STUArray`
  - `Array` -> `IOArray`
  - `Array` -> `STArray`

unsafeForeignPtrToStorableArray :: Ix i => ForeignPtr e -> (i, i) -> IO (StorableArray i e)

Construct a `StorableArray` from an arbitrary `ForeignPtr`. It is the caller's responsibility to ensure that the `ForeignPtr` points to an area of memory sufficient for the specified bounds.