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


-- | Unified interface for primitive arrays
--   
--   This package provides a typeclass <a>Contiguous</a> that offers a
--   unified interface to working with <a>Array</a>, <a>SmallArray</a>,
--   <a>PrimArray</a>, and <a>UnliftedArray</a>.
@package contiguous
@version 0.4


-- | The contiguous typeclass parameterises over a contiguous array type.
--   This allows us to have a common API to a number of contiguous array
--   types and their mutable counterparts.
module Data.Primitive.Contiguous

-- | The size of the array
size :: (Contiguous arr, Element arr b) => arr b -> Int

-- | The size of the mutable array
sizeMutable :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> m Int

-- | Test whether the array is empty.
null :: Contiguous arr => arr b -> Bool

-- | Index into an array at the given index.
index :: (Contiguous arr, Element arr b) => arr b -> Int -> b

-- | Index into an array at the given index, yielding an unboxed one-tuple
--   of the element.
index# :: (Contiguous arr, Element arr b) => arr b -> Int -> (# b #)

-- | Read a mutable array at the given index.
read :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> m b

-- | Indexing in a monad.
--   
--   The monad allows operations to be strict in the array when necessary.
--   Suppose array copying is implemented like this:
--   
--   <pre>
--   copy mv v = ... write mv i (v ! i) ...
--   </pre>
--   
--   For lazy arrays, <tt>v ! i</tt> would not be not be evaluated, which
--   means that <tt>mv</tt> would unnecessarily retain a reference to
--   <tt>v</tt> in each element written.
--   
--   With <a>indexM</a>, copying can be implemented like this instead:
--   
--   <pre>
--   copy mv v = ... do
--     x &lt;- indexM v i
--     write mv i x
--   </pre>
--   
--   Here, no references to <tt>v</tt> are retained because indexing (but
--   <i>not</i> the elements) is evaluated eagerly.
indexM :: (Contiguous arr, Element arr b, Monad m) => arr b -> Int -> m b

-- | The empty array.
empty :: Contiguous arr => arr a

-- | Allocate a new mutable array of the given size.
new :: (Contiguous arr, PrimMonad m, Element arr b) => Int -> m (Mutable arr (PrimState m) b)

-- | Create a singleton array.
singleton :: (Contiguous arr, Element arr a) => a -> arr a

-- | Create a doubleton array.
doubleton :: (Contiguous arr, Element arr a) => a -> a -> arr a

-- | Create a tripleton array.
tripleton :: (Contiguous arr, Element arr a) => a -> a -> a -> arr a

-- | <tt><a>replicate</a> n x</tt> is an array of length <tt>n</tt> with
--   <tt>x</tt> the value of every element.
replicate :: (Contiguous arr, Element arr a) => Int -> a -> arr a

-- | <tt><a>replicateMutable</a> n x</tt> is a mutable array of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
replicateMutable :: (Contiguous arr, PrimMonad m, Element arr b) => Int -> b -> m (Mutable arr (PrimState m) b)

-- | Construct an array of the given length by applying the function to
--   each index.
generate :: (Contiguous arr, Element arr a) => Int -> (Int -> a) -> arr a

-- | Construct a mutable array of the given length by applying the function
--   to each index.
generateMutable :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> (Int -> a) -> m (Mutable arr (PrimState m) a)

-- | Apply a function <tt>n</tt> times to a value and construct an array
--   where each consecutive element is the result of an additional
--   application of this function. The zeroth element is the original
--   value.
--   
--   <pre>
--   <a>iterateN</a> 5 (<a>+</a> 1) 0 = <a>fromListN</a> 5 [0,1,2,3,4]
--   </pre>
iterateN :: (Contiguous arr, Element arr a) => Int -> (a -> a) -> a -> arr a

-- | Apply a function <tt>n</tt> times to a value and construct a mutable
--   array where each consecutive element is the result of an additional
--   application of this function. The zeroth element is the original
--   value.
iterateMutableN :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> (a -> a) -> a -> m (Mutable arr (PrimState m) a)

-- | Write to a mutable array at the given index.
write :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> b -> m ()

-- | <tt><a>replicateMutableM</a> n act</tt> performs the action n times,
--   gathering the results.
replicateMutableM :: (PrimMonad m, Contiguous arr, Element arr a) => Int -> m a -> m (Mutable arr (PrimState m) a)

-- | Construct a mutable array of the given length by applying the monadic
--   action to each index.
generateMutableM :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> (Int -> m a) -> m (Mutable arr (PrimState m) a)

-- | Apply a monadic function <tt>n</tt> times to a value and construct a
--   mutable array where each consecutive element is the result of an
--   additional application of this function. The zeroth element is the
--   original value.
iterateMutableNM :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> (a -> m a) -> a -> m (Mutable arr (PrimState m) a)

-- | Execute the monad action and freeze the resulting array.
create :: (Contiguous arr, Element arr a) => (forall s. ST s (Mutable arr s a)) -> arr a

-- | Execute the monadic action and freeze the resulting array.
createT :: (Contiguous arr, Element arr a, Traversable f) => (forall s. ST s (f (Mutable arr s a))) -> f (arr a)

-- | Construct an array by repeatedly applying a generator function to a
--   seed. The generator function yields <a>Just</a> the next element and
--   the new seed or <a>Nothing</a> if there are no more elements.
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr (\n -&gt; if n == 0 then Nothing else Just (n,n-1) 10
--       &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldr :: (Contiguous arr, Element arr a) => (b -> Maybe (a, b)) -> b -> arr a

-- | Construct an array with at most n elements by repeatedly applying the
--   generator function to a seed. The generator function yields
--   <a>Just</a> the next element and the new seed or <a>Nothing</a> if
--   there are no more elements.
unfoldrN :: (Contiguous arr, Element arr a) => Int -> (b -> Maybe (a, b)) -> b -> arr a

-- | Construct a mutable array by repeatedly applying a generator function
--   to a seed. The generator function yields <a>Just</a> the next element
--   and the new seed or <a>Nothing</a> if there are no more elements.
--   
--   <pre>
--   &gt;&gt;&gt; unfoldrMutable (\n -&gt; if n == 0 then Nothing else Just (n,n-1) 10
--       &lt;10,9,8,7,6,5,4,3,2,1&gt;
--   </pre>
unfoldrMutable :: (Contiguous arr, Element arr a, PrimMonad m) => (b -> Maybe (a, b)) -> b -> m (Mutable arr (PrimState m) a)

-- | Yield an array of the given length containing the values <tt>x,
--   <a>succ</a> x, <a>succ</a> (<a>succ</a> x)</tt> etc.
enumFromN :: (Contiguous arr, Element arr a, Enum a) => a -> Int -> arr a

-- | Yield a mutable array of the given length containing the values <tt>x,
--   <a>succ</a> x, <a>succ</a> (<a>succ</a> x)</tt> etc.
enumFromMutableN :: (Contiguous arr, Element arr a, PrimMonad m, Enum a) => a -> Int -> m (Mutable arr (PrimState m) a)

-- | Append two arrays.
append :: (Contiguous arr, Element arr a) => arr a -> arr a -> arr a

-- | Reverse the elements of an array.
reverse :: (Contiguous arr, Element arr a) => arr a -> arr a

-- | Reverse the elements of a mutable array, in-place.
reverseMutable :: (Contiguous arr, Element arr a, PrimMonad m) => Mutable arr (PrimState m) a -> m ()

-- | Resize an array into one with the given size.
resize :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> m (Mutable arr (PrimState m) b)

-- | Map over the elements of an array.
--   
--   Note that because a new array must be created, the resulting array
--   type can be <i>different</i> than the original.
map :: (Contiguous arr1, Element arr1 b, Contiguous arr2, Element arr2 c) => (b -> c) -> arr1 b -> arr2 c

-- | Map strictly over the elements of an array.
--   
--   Note that because a new array must be created, the resulting array
--   type can be <i>different</i> than the original.
map' :: (Contiguous arr1, Element arr1 b, Contiguous arr2, Element arr2 c) => (b -> c) -> arr1 b -> arr2 c

-- | Map over a mutable array, modifying the elements in place.
mapMutable :: (Contiguous arr, Element arr a, PrimMonad m) => (a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | Strictly map over a mutable array, modifying the elements in place.
mapMutable' :: (PrimMonad m, Contiguous arr, Element arr a) => (a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | Map over the elements of an array with the index.
imap :: (Contiguous arr1, Element arr1 b, Contiguous arr2, Element arr2 c) => (Int -> b -> c) -> arr1 b -> arr2 c

-- | Map strictly over the elements of an array with the index.
--   
--   Note that because a new array must be created, the resulting array
--   type can be <i>different</i> than the original.
imap' :: (Contiguous arr1, Element arr1 b, Contiguous arr2, Element arr2 c) => (Int -> b -> c) -> arr1 b -> arr2 c

-- | Map over a mutable array with indices, modifying the elements in
--   place.
imapMutable :: (Contiguous arr, Element arr a, PrimMonad m) => (Int -> a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | Strictly map over a mutable array with indices, modifying the elements
--   in place.
imapMutable' :: (PrimMonad m, Contiguous arr, Element arr a) => (Int -> a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | Modify the elements of a mutable array in-place.
modify :: (Contiguous arr, Element arr a, PrimMonad m) => (a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | Strictly modify the elements of a mutable array in-place.
modify' :: (Contiguous arr, Element arr a, PrimMonad m) => (a -> a) -> Mutable arr (PrimState m) a -> m ()

-- | The <a>mapMaybe</a> function is a version of <a>map</a> which can
--   throw out elements. In particular, the functional arguments returns
--   something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>,
--   no element is added on to the result array. If it is <tt><a>Just</a>
--   b</tt>, then <tt>b</tt> is included in the result array.
mapMaybe :: forall arr1 arr2 a b. (Contiguous arr1, Element arr1 a, Contiguous arr2, Element arr2 b) => (a -> Maybe b) -> arr1 a -> arr2 b

-- | Drop elements that do not satisfy the predicate.
filter :: (Contiguous arr, Element arr a) => (a -> Bool) -> arr a -> arr a

-- | Drop elements that do not satisfy the predicate which is applied to
--   values and their indices.
ifilter :: (Contiguous arr, Element arr a) => (Int -> a -> Bool) -> arr a -> arr a

-- | Test the two arrays for equality.
equals :: (Contiguous arr, Element arr b, Eq b) => arr b -> arr b -> Bool

-- | Test the two mutable arrays for pointer equality. Does not check
--   equality of elements.
equalsMutable :: Contiguous arr => Mutable arr s a -> Mutable arr s a -> Bool

-- | This function does not behave deterministically. Optimization level
--   and inlining can affect its results. However, the one thing that can
--   be counted on is that if it returns <a>True</a>, the two immutable
--   arrays are definitely the same. This is useful as shortcut for
--   equality tests. However, keep in mind that a result of <a>False</a>
--   tells us nothing about the arguments.
same :: Contiguous arr => arr a -> arr a -> Bool

-- | Left fold over the elements of an array.
foldl :: (Contiguous arr, Element arr a) => (b -> a -> b) -> b -> arr a -> b

-- | Strict left fold over the elements of an array.
foldl' :: (Contiguous arr, Element arr a) => (b -> a -> b) -> b -> arr a -> b

-- | Right fold over the element of an array.
foldr :: (Contiguous arr, Element arr a) => (a -> b -> b) -> b -> arr a -> b

-- | Strict right fold over the elements of an array.
foldr' :: (Contiguous arr, Element arr a) => (a -> b -> b) -> b -> arr a -> b

-- | Monoidal fold over the element of an array.
foldMap :: (Contiguous arr, Element arr a, Monoid m) => (a -> m) -> arr a -> m

-- | Strict monoidal fold over the elements of an array.
foldMap' :: (Contiguous arr, Element arr a, Monoid m) => (a -> m) -> arr a -> m

-- | Strict left monoidal fold over the elements of an array.
foldlMap' :: (Contiguous arr, Element arr a, Monoid m) => (a -> m) -> arr a -> m

-- | Strict left fold over the elements of an array, where the accumulating
--   function cares about the index of the element.
ifoldl' :: (Contiguous arr, Element arr a) => (b -> Int -> a -> b) -> b -> arr a -> b

-- | Strict right fold over the elements of an array, where the
--   accumulating function cares about the index of the element.
ifoldr' :: (Contiguous arr, Element arr a) => (Int -> a -> b -> b) -> b -> arr a -> b

-- | Strict monoidal fold over the elements of an array.
ifoldlMap' :: (Contiguous arr, Element arr a, Monoid m) => (Int -> a -> m) -> arr a -> m

-- | Strict monoidal fold over the elements of an array.
ifoldlMap1' :: (Contiguous arr, Element arr a, Semigroup m) => (Int -> a -> m) -> arr a -> m

-- | Strict left monadic fold over the elements of an array.
foldlM' :: (Contiguous arr, Element arr a, Monad m) => (b -> a -> m b) -> b -> arr a -> m b

-- | Map each element of the array to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results, see <a>traverse_</a>.
traverse :: (Contiguous arr, Element arr a, Element arr b, Applicative f) => (a -> f b) -> arr a -> f (arr b)

-- | Map each element of the array to an action, evaluate these actions
--   from left to right, and ignore the results. For a version that doesn't
--   ignore the results, see <a>traverse</a>.
traverse_ :: (Contiguous arr, Element arr a, Applicative f) => (a -> f b) -> arr a -> f ()

-- | Map each element of the array and its index to an action, evaluating
--   these actions from left to right.
itraverse :: (Contiguous arr, Element arr a, Element arr b, Applicative f) => (Int -> a -> f b) -> arr a -> f (arr b)

-- | Map each element of the array and its index to an action, evaluate
--   these actions from left to right, and ignore the results. For a
--   version that doesn't ignore the results, see <a>itraverse</a>.
itraverse_ :: (Contiguous arr, Element arr a, Applicative f) => (Int -> a -> f b) -> arr a -> f ()

-- | Map each element of the array to an action, evaluate these actions
--   from left to right, and collect the results in a new array.
traverseP :: (PrimMonad m, Contiguous arr1, Contiguous arr2, Element arr1 a, Element arr2 b) => (a -> m b) -> arr1 a -> m (arr2 b)

-- | Convert a list into an array.
fromList :: (Contiguous arr, Element arr a) => [a] -> arr a

-- | Given an <a>Int</a> that is representative of the length of the list,
--   convert the list into a mutable array of the given length.
--   
--   <i>Note</i>: calls <a>error</a> if the given length is incorrect.
fromListN :: (Contiguous arr, Element arr a) => Int -> [a] -> arr a

-- | Convert a list into a mutable array of the given length.
fromListMutable :: (Contiguous arr, Element arr a, PrimMonad m) => [a] -> m (Mutable arr (PrimState m) a)

-- | Given an <a>Int</a> that is representative of the length of the list,
--   convert the list into a mutable array of the given length.
--   
--   <i>Note</i>: calls <a>error</a> if the given length is incorrect.
fromListMutableN :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> [a] -> m (Mutable arr (PrimState m) a)

-- | Create an array from a list. If the given length does not match the
--   actual length, this function has undefined behavior.
unsafeFromListN :: (Contiguous arr, Element arr a) => Int -> [a] -> arr a

-- | Create an array from a list, reversing the order of the elements. If
--   the given length does not match the actual length, this function has
--   undefined behavior.
unsafeFromListReverseN :: (Contiguous arr, Element arr a) => Int -> [a] -> arr a

-- | Create a mutable array from a list, reversing the order of the
--   elements. If the given length does not match the actual length, this
--   function has undefined behavior.
unsafeFromListReverseMutableN :: (Contiguous arr, Element arr a, PrimMonad m) => Int -> [a] -> m (Mutable arr (PrimState m) a)

-- | Convert an array to a list.
toList :: (Contiguous arr, Element arr a) => arr a -> [a]

-- | Convert a mutable array to a list.
toListMutable :: (Contiguous arr, Element arr a, PrimMonad m) => Mutable arr (PrimState m) a -> m [a]

-- | Convert one type of array into another.
convert :: (Contiguous arr1, Element arr1 b, Contiguous arr2, Element arr2 b) => arr1 b -> arr2 b

-- | Lift an <a>ArrayArray#</a> into an array.
lift :: Contiguous arr => ArrayArray# -> arr b

-- | Unlift an array into an <a>ArrayArray#</a>.
unlift :: Contiguous arr => arr b -> ArrayArray#

-- | Clone a slice of an array.
clone :: (Contiguous arr, Element arr b) => arr b -> Int -> Int -> arr b

-- | Clone a slice of a mutable array.
cloneMutable :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> Int -> m (Mutable arr (PrimState m) b)

-- | Copy a slice of an array into a mutable array.
copy :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> arr b -> Int -> Int -> m ()

-- | Copy a slice of a mutable array into another mutable array. In the
--   case that the destination and source arrays are the same, the regions
--   may overlap.
copyMutable :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> Mutable arr (PrimState m) b -> Int -> Int -> m ()

-- | Turn a mutable array into an immutable one with copying, using a slice
--   of the mutable array.
freeze :: (Contiguous arr, PrimMonad m, Element arr b) => Mutable arr (PrimState m) b -> Int -> Int -> m (arr b)

-- | Copy a slice of an immutable array into a new mutable array.
thaw :: (Contiguous arr, PrimMonad m, Element arr b) => arr b -> Int -> Int -> m (Mutable arr (PrimState m) b)

-- | Turn a mutable array into an immutable one without copying. The
--   mutable array should not be used after this conversion.
unsafeFreeze :: (Contiguous arr, PrimMonad m) => Mutable arr (PrimState m) b -> m (arr b)

-- | Lift an accumulating hash function over the elements of the array,
--   returning the final accumulated hash.
liftHashWithSalt :: (Contiguous arr, Element arr a) => (Int -> a -> Int) -> Int -> arr a -> Int

-- | Reduce the array and all of its elements to WHNF.
rnf :: (Contiguous arr, NFData a, Element arr a) => arr a -> ()

-- | The <a>Contiguous</a> typeclass as an interface to a multitude of
--   contiguous structures.
class Contiguous (arr :: Type -> Type) where {
    
    -- | The Mutable counterpart to the array.
    type family Mutable arr = (r :: Type -> Type -> Type) | r -> arr;
    
    -- | The constraint needed to store elements in the array.
    type family Element arr :: Type -> Constraint;
}

-- | A typeclass that is satisfied by all types. This is used used to
--   provide a fake constraint for <a>Array</a> and <a>SmallArray</a>.
class Always a
instance Data.Primitive.Contiguous.Contiguous Data.Primitive.SmallArray.SmallArray
instance Data.Primitive.Contiguous.Contiguous Data.Primitive.PrimArray.PrimArray
instance Data.Primitive.Contiguous.Contiguous Data.Primitive.Array.Array
instance Data.Primitive.Contiguous.Contiguous Data.Primitive.UnliftedArray.UnliftedArray
instance Data.Primitive.Contiguous.Always a