-- 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 i, Data.Data.Data e) => Data.Data.Data (Data.Array.CArray.Base.IOCArray i e)
instance (Data.Data.Data i, Data.Data.Data e) => Data.Data.Data (Data.Array.CArray.Base.CArray i 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 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 (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 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)


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