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


-- | A C-compatible array library.
--   
--   A C-compatible array library.
--   
--   Provides both an immutable and mutable (in the IO monad) interface.
--   Includes utilities for multi-dimensional arrays, slicing and norms.
--   Memory is 16-byte aligned by default to enable use of vector
--   instructions.
@package carray
@version 0.1.6.8


-- | This module provides both the immutable <a>CArray</a> and mutable
--   <a>IOCArray</a>. The underlying storage is exactly the same - pinned
--   memory on the GC'd heap. Elements are stored according to the class
--   <a>Storable</a>. You can obtain a pointer to the array contents to
--   manipulate elements from languages like C.
--   
--   <a>CArray</a> is 16-byte aligned by default. If you create a
--   <a>CArray</a> with <a>unsafeForeignPtrToCArray</a> then it may not be
--   aligned. This will be an issue if you intend to use SIMD instructions.
--   
--   <a>CArray</a> is similar to <a>UArray</a> but slower if you stay
--   within Haskell. <a>CArray</a> can handle more types and can be used by
--   external libraries.
--   
--   <a>IOCArray</a> is equivalent to <a>StorableArray</a> and similar to
--   <a>IOUArray</a> but slower. <a>IOCArray</a> has O(1) versions of
--   <a>unsafeFreeze</a> and <a>unsafeThaw</a> when converting to/from
--   <a>CArray</a>.
module Data.Array.CArray.Base

-- | The immutable array type.
data CArray i e
CArray :: !i -> !i -> Int -> !(ForeignPtr e) -> CArray i e

-- | Absolutely equivalent representation, but used for the mutable
--   interface.
data IOCArray i e
IOCArray :: !i -> !i -> Int -> !(ForeignPtr e) -> IOCArray i e

-- | The pointer to the array contents is obtained by <a>withCArray</a>.
--   The idea is similar to <a>ForeignPtr</a> (used internally here). The
--   pointer should be used only during execution of the <a>IO</a> action
--   retured by the function passed as argument to <a>withCArray</a>.
withCArray :: CArray i e -> (Ptr e -> IO a) -> IO a
withIOCArray :: IOCArray i e -> (Ptr e -> IO a) -> IO a

-- | If you want to use it afterwards, ensure that you <tt>touchCArray</tt>
--   after the last use of the pointer, so the array is not freed too
--   early.
touchIOCArray :: IOCArray i e -> IO ()

-- | <i>O(1)</i> Construct a <a>CArray</a> from an arbitrary
--   <a>ForeignPtr</a>. It is the caller's responsibility to ensure that
--   the <a>ForeignPtr</a> points to an area of memory sufficient for the
--   specified bounds.
unsafeForeignPtrToCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (CArray i e)

-- | <i>O(1)</i> Construct a <a>CArray</a> from an arbitrary
--   <a>ForeignPtr</a>. It is the caller's responsibility to ensure that
--   the <a>ForeignPtr</a> points to an area of memory sufficient for the
--   specified bounds.
unsafeForeignPtrToIOCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (IOCArray i e)

-- | <i>O(1)</i> Extract ForeignPtr from a CArray.
toForeignPtr :: CArray i e -> (Int, ForeignPtr e)

-- | <i>O(1)</i> Turn a CArray into a ByteString. Unsafe because it uses
--   <a>castForeignPtr</a> and thus is not platform independent.
unsafeCArrayToByteString :: (Storable e) => CArray i e -> ByteString

-- | <i>O(1)</i> Turn a ByteString into a CArray. Unsafe because it uses
--   <a>castForeignPtr</a> and thus is not platform independent. Returns
--   <a>Nothing</a> if the range specified is larger than the size of the
--   ByteString or the start of the ByteString does not fulfil the
--   alignment requirement of the resulting CArray (as specified by the
--   Storable instance).
unsafeByteStringToCArray :: (Ix i, Storable e) => (i, i) -> ByteString -> Maybe (CArray i e)
copy :: (Ix i, Storable e) => CArray i e -> IO (CArray i e)
freezeIOCArray :: (Ix i, Storable e) => IOCArray i e -> IO (CArray i e)
unsafeFreezeIOCArray :: (Ix i) => IOCArray i e -> IO (CArray i e)
thawIOCArray :: (Ix i, Storable e) => CArray i e -> IO (IOCArray i e)
unsafeThawIOCArray :: (Ix i) => CArray i e -> IO (IOCArray i e)

-- | Hackish way to get the zero element for a Storable type.
zeroElem :: Storable a => a -> a
unsafeArrayCArray :: (Storable e, Ix i) => (i, i) -> [(Int, e)] -> e -> IO (CArray i e)
unsafeReplaceCArray :: (Storable e, Ix i) => CArray i e -> [(Int, e)] -> IO (CArray i e)
unsafeAccumCArray :: (Storable e, Ix i) => (e -> e' -> e) -> CArray i e -> [(Int, e')] -> IO (CArray i e)
unsafeAccumArrayCArray :: (Storable e, Ix i) => (e -> e' -> e) -> e -> (i, i) -> [(Int, e')] -> IO (CArray i e)
eqCArray :: (Storable e, Ix i, Eq e) => CArray i e -> CArray i e -> Bool
cmpCArray :: (Storable e, Ix i, Ord e) => CArray i e -> CArray i e -> Ordering
cmpIntCArray :: (Storable e, Ord e) => CArray Int e -> CArray Int e -> Ordering

-- | O(1) reshape an array. The number of elements in the new shape must
--   not exceed the number in the old shape. The elements are in C-style
--   ordering.
reshape :: (Ix i, Ix j) => (j, j) -> CArray i e -> CArray j e

-- | O(1) make a rank 1 array from an arbitrary shape. It has the property
--   that 'reshape (0, size a - 1) a == flatten a'.
flatten :: Ix i => CArray i e -> CArray Int e

-- | Generic slice and map. This takes the new range, the inverse map on
--   indices, and function to produce the next element. It is the most
--   general operation in its class.
ixmapWithIndP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
ixmapWithInd :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a i' e'

-- | Perform an operation on the elements, independent of their location.
ixmapWithP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
ixmapWith :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a i' e'

-- | More polymorphic version of <tt>ixmap</tt>.
ixmapP :: (Ix i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i' -> i) -> a i e -> a' i' e

-- | More friendly sub-arrays with element mapping.
sliceStrideWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
sliceStrideWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a i' e'

-- | Strided sub-array without element mapping.
sliceStrideP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i, i) -> a i e -> a' i' e

-- | Less polymorphic version.
sliceStride :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i, i) -> a i e -> a i' e

-- | Contiguous sub-array with element mapping.
sliceWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
sliceWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a i' e'

-- | Contiguous sub-array without element mapping.
sliceP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i) -> a i e -> a' i' e

-- | Less polymorphic version.
slice :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i) -> a i e -> a i' e

-- | In-place map on CArray. Note that this is <i>IN PLACE</i> so you
--   should not retain any reference to the original. It flagrantly breaks
--   referential transparency!
mapCArrayInPlace :: (Ix i, Storable e) => (e -> e) -> CArray i e -> CArray i e
indexes :: (Ix i, Shapable i, IArray a e) => a i e -> i -> [Int]
offsetShapeFromThenTo :: [Int] -> [Int] -> [Int] -> [Int] -> [Int]
offsetShapeFromTo :: [Int] -> [Int] -> [Int] -> [Int]
offsetShapeFromTo' :: ([[Int]] -> [[Int]]) -> [Int] -> [Int] -> [Int] -> [Int]
offsets :: (Ix a, Shapable a) => (a, a) -> a -> [Int]

-- | p-norm on the array taken as a vector
normp :: (Ix i, RealFloat e', Abs e e', IArray a e) => e' -> a i e -> e'

-- | 2-norm on the array taken as a vector (Frobenius norm for matrices)
norm2 :: (Ix i, Floating e', Abs e e', IArray a e) => a i e -> e'

-- | Sup norm on the array taken as a vector
normSup :: (Ix i, Num e', Ord e', Abs e e', IArray a e) => a i e -> e'

-- | Polymorphic version of amap.
liftArrayP :: (Ix i, IArray a e, IArray a1 e1) => (e -> e1) -> a i e -> a1 i e1

-- | Equivalent to amap. Here for consistency only.
liftArray :: (Ix i, IArray a e, IArray a e1) => (e -> e1) -> a i e -> a i e1

-- | Polymorphic 2-array lift.
liftArray2P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2) => (e -> e1 -> e2) -> a i e -> a1 i e1 -> a2 i e2

-- | Less polymorphic version.
liftArray2 :: (Ix i, IArray a e, IArray a e1, IArray a e2) => (e -> e1 -> e2) -> a i e -> a i e1 -> a i e2

-- | Polymorphic 3-array lift.
liftArray3P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2, IArray a3 e3) => (e -> e1 -> e2 -> e3) -> a i e -> a1 i e1 -> a2 i e2 -> a3 i e3

-- | Less polymorphic version.
liftArray3 :: (Ix i, IArray a e, IArray a e1, IArray a e2, IArray a e3) => (e -> e1 -> e2 -> e3) -> a i e -> a i e1 -> a i e2 -> a i e3

-- | Hack so that norms have a sensible type.
class Abs a b | a -> b
abs_ :: Abs a b => a -> b

-- | Allocate an array which is 16-byte aligned. Essential for SIMD
--   instructions.
mallocForeignPtrArrayAligned :: Storable a => Int -> IO (ForeignPtr a)

-- | Allocate memory which is 16-byte aligned. This is essential for SIMD
--   instructions. We know that mallocPlainForeignPtrBytes will give
--   word-aligned memory, so we pad enough to be able to return the desired
--   amount of memory after aligning our pointer.
mallocForeignPtrBytesAligned :: Int -> IO (ForeignPtr a)

-- | Make a new CArray with an IO action.
createCArray :: (Ix i, Storable e) => (i, i) -> (Ptr e -> IO ()) -> IO (CArray i e)
unsafeCreateCArray :: (Ix i, Storable e) => (i, i) -> (Ptr e -> IO ()) -> CArray i e
instance (Data.Data.Data e, Data.Data.Data i) => Data.Data.Data (Data.Array.CArray.Base.IOCArray i e)
instance (Data.Data.Data e, Data.Data.Data i) => Data.Data.Data (Data.Array.CArray.Base.CArray i e)
instance Foreign.Storable.Storable e => Data.Array.Base.MArray Data.Array.CArray.Base.IOCArray e GHC.Types.IO
instance Foreign.Storable.Storable e => Data.Array.Base.IArray Data.Array.CArray.Base.CArray e
instance (GHC.Arr.Ix ix, GHC.Classes.Eq e, Foreign.Storable.Storable e) => GHC.Classes.Eq (Data.Array.CArray.Base.CArray ix e)
instance (GHC.Arr.Ix ix, GHC.Classes.Ord e, Foreign.Storable.Storable e) => GHC.Classes.Ord (Data.Array.CArray.Base.CArray ix e)
instance (GHC.Arr.Ix ix, GHC.Show.Show ix, GHC.Show.Show e, Foreign.Storable.Storable e) => GHC.Show.Show (Data.Array.CArray.Base.CArray ix e)
instance Data.Array.CArray.Base.Abs (Data.Complex.Complex GHC.Types.Double) GHC.Types.Double
instance Data.Array.CArray.Base.Abs (Data.Complex.Complex GHC.Types.Float) GHC.Types.Float
instance Data.Array.CArray.Base.Abs GHC.Types.Double GHC.Types.Double
instance Data.Array.CArray.Base.Abs GHC.Types.Float GHC.Types.Float
instance (GHC.Arr.Ix i, Data.Binary.Class.Binary i, Data.Binary.Class.Binary e, Foreign.Storable.Storable e) => Data.Binary.Class.Binary (Data.Array.CArray.Base.CArray i e)
instance (GHC.Arr.Ix i, Test.QuickCheck.Arbitrary.Arbitrary i, Foreign.Storable.Storable e, Test.QuickCheck.Arbitrary.Arbitrary e) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Array.CArray.Base.CArray i e)
instance (GHC.Arr.Ix i, Test.QuickCheck.Arbitrary.CoArbitrary i, Foreign.Storable.Storable e, Test.QuickCheck.Arbitrary.CoArbitrary e) => Test.QuickCheck.Arbitrary.CoArbitrary (Data.Array.CArray.Base.CArray i e)


-- | This module provides both the mutable <a>IOCArray</a> which uses
--   pinned memory on the GC'd heap. Elements are stored according to the
--   class <tt>Storable</tt>. You can obtain a pointer to the array
--   contents to manipulate elements from languages like C.
--   
--   <a>IOCArray</a> is 16-byte aligned by default. If you create a
--   <a>IOCArray</a> with <a>unsafeForeignPtrToIOCArray</a> then it may not
--   be aligned. This will be an issue if you intend to use SIMD
--   instructions.
--   
--   <a>IOCArray</a> is equivalent to <a>StorableArray</a> and similar to
--   <a>IOUArray</a> but slower. <a>IOCArray</a> has O(1) versions of
--   <tt>unsafeFreeze</tt> and <tt>unsafeThaw</tt> when converting to/from
--   <a>CArray</a>.
module Data.Array.IOCArray

-- | Absolutely equivalent representation, but used for the mutable
--   interface.
data IOCArray i e
withIOCArray :: IOCArray i e -> (Ptr e -> IO a) -> IO a

-- | If you want to use it afterwards, ensure that you <tt>touchCArray</tt>
--   after the last use of the pointer, so the array is not freed too
--   early.
touchIOCArray :: IOCArray i e -> IO ()

-- | <i>O(1)</i> Construct a <a>CArray</a> from an arbitrary
--   <a>ForeignPtr</a>. It is the caller's responsibility to ensure that
--   the <a>ForeignPtr</a> points to an area of memory sufficient for the
--   specified bounds.
unsafeForeignPtrToIOCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (IOCArray i e)


-- | This module provides the immutable <a>CArray</a> which uses pinned
--   memory on the GC'd heap. Elements are stored according to the class
--   <tt>Storable</tt>. You can obtain a pointer to the array contents to
--   manipulate elements from languages like C.
--   
--   <a>CArray</a> is 16-byte aligned by default. If you create a
--   <a>CArray</a> with <a>unsafeForeignPtrToCArray</a> then it may not be
--   aligned. This will be an issue if you intend to use SIMD instructions.
--   
--   <a>CArray</a> is similar to <a>UArray</a> but slower if you stay
--   within Haskell. <a>CArray</a> can handle more types and can be used by
--   external libraries.
--   
--   <a>CArray</a> has an instance of <tt>Binary</tt>.
module Data.Array.CArray

-- | The immutable array type.
data CArray i e

-- | O(1) reshape an array. The number of elements in the new shape must
--   not exceed the number in the old shape. The elements are in C-style
--   ordering.
reshape :: (Ix i, Ix j) => (j, j) -> CArray i e -> CArray j e

-- | O(1) make a rank 1 array from an arbitrary shape. It has the property
--   that 'reshape (0, size a - 1) a == flatten a'.
flatten :: Ix i => CArray i e -> CArray Int e

-- | Determine the rank of an array.
rank :: (Shapable i, Ix i, IArray a e) => a i e -> Int

-- | Canonical representation of the shape. The following properties hold:
--   'length . shape = rank' 'product . shape = size'
shape :: (Shapable i, Ix i, IArray a e) => a i e -> [Int]

-- | Number of elements in the Array.
size :: (Ix i, IArray a e) => a i e -> Int

-- | Generic slice and map. This takes the new range, the inverse map on
--   indices, and function to produce the next element. It is the most
--   general operation in its class.
ixmapWithIndP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
ixmapWithInd :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (i -> e -> i' -> e') -> a i e -> a i' e'

-- | Perform an operation on the elements, independent of their location.
ixmapWithP :: (Ix i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
ixmapWith :: (Ix i, Ix i', IArray a e, IArray a e') => (i', i') -> (i' -> i) -> (e -> e') -> a i e -> a i' e'

-- | More polymorphic version of <tt>ixmap</tt>.
ixmapP :: (Ix i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i' -> i) -> a i e -> a' i' e

-- | More friendly sub-arrays with element mapping.
sliceStrideWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
sliceStrideWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i, i) -> (e -> e') -> a i e -> a i' e'

-- | Strided sub-array without element mapping.
sliceStrideP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i, i) -> a i e -> a' i' e

-- | Less polymorphic version.
sliceStride :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i, i) -> a i e -> a i' e

-- | Contiguous sub-array with element mapping.
sliceWithP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a' i' e'

-- | Less polymorphic version.
sliceWith :: (Ix i, Shapable i, Ix i', IArray a e, IArray a e') => (i', i') -> (i, i) -> (e -> e') -> a i e -> a i' e'

-- | Contiguous sub-array without element mapping.
sliceP :: (Ix i, Shapable i, Ix i', IArray a e, IArray a' e) => (i', i') -> (i, i) -> a i e -> a' i' e

-- | Less polymorphic version.
slice :: (Ix i, Shapable i, Ix i', IArray a e) => (i', i') -> (i, i) -> a i e -> a i' e

-- | Polymorphic version of amap.
liftArrayP :: (Ix i, IArray a e, IArray a1 e1) => (e -> e1) -> a i e -> a1 i e1

-- | Equivalent to amap. Here for consistency only.
liftArray :: (Ix i, IArray a e, IArray a e1) => (e -> e1) -> a i e -> a i e1

-- | Polymorphic 2-array lift.
liftArray2P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2) => (e -> e1 -> e2) -> a i e -> a1 i e1 -> a2 i e2

-- | Less polymorphic version.
liftArray2 :: (Ix i, IArray a e, IArray a e1, IArray a e2) => (e -> e1 -> e2) -> a i e -> a i e1 -> a i e2

-- | Polymorphic 3-array lift.
liftArray3P :: (Ix i, IArray a e, IArray a1 e1, IArray a2 e2, IArray a3 e3) => (e -> e1 -> e2 -> e3) -> a i e -> a1 i e1 -> a2 i e2 -> a3 i e3

-- | Less polymorphic version.
liftArray3 :: (Ix i, IArray a e, IArray a e1, IArray a e2, IArray a e3) => (e -> e1 -> e2 -> e3) -> a i e -> a i e1 -> a i e2 -> a i e3

-- | p-norm on the array taken as a vector
normp :: (Ix i, RealFloat e', Abs e e', IArray a e) => e' -> a i e -> e'

-- | 2-norm on the array taken as a vector (Frobenius norm for matrices)
norm2 :: (Ix i, Floating e', Abs e e', IArray a e) => a i e -> e'

-- | Sup norm on the array taken as a vector
normSup :: (Ix i, Num e', Ord e', Abs e e', IArray a e) => a i e -> e'

-- | We need this type class to distinguish between different tuples of Ix.
--   There are Shapable instances for homogenous Int tuples, but may
--   Haddock doesn't see them.
class Shapable i

-- | Hack so that norms have a sensible type.
class Abs a b | a -> b

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

-- | <i>O(1)</i> Construct a <a>CArray</a> from an arbitrary
--   <a>ForeignPtr</a>. It is the caller's responsibility to ensure that
--   the <a>ForeignPtr</a> points to an area of memory sufficient for the
--   specified bounds.
unsafeForeignPtrToCArray :: Ix i => ForeignPtr e -> (i, i) -> IO (CArray i e)

-- | <i>O(1)</i> Extract ForeignPtr from a CArray.
toForeignPtr :: CArray i e -> (Int, ForeignPtr e)

-- | <i>O(1)</i> Turn a CArray into a ByteString. Unsafe because it uses
--   <a>castForeignPtr</a> and thus is not platform independent.
unsafeCArrayToByteString :: (Storable e) => CArray i e -> ByteString

-- | <i>O(1)</i> Turn a ByteString into a CArray. Unsafe because it uses
--   <a>castForeignPtr</a> and thus is not platform independent. Returns
--   <a>Nothing</a> if the range specified is larger than the size of the
--   ByteString or the start of the ByteString does not fulfil the
--   alignment requirement of the resulting CArray (as specified by the
--   Storable instance).
unsafeByteStringToCArray :: (Ix i, Storable e) => (i, i) -> ByteString -> Maybe (CArray i e)

-- | Make a new CArray with an IO action.
createCArray :: (Ix i, Storable e) => (i, i) -> (Ptr e -> IO ()) -> IO (CArray i e)
