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


-- | Utilities for the "vector" library
--   
--   This library is in an experimental state. Users should be prepared for
--   frequent updates.
@package vector-extras
@version 0.2.7

module VectorExtras.Immutable.FoldM.PrimMonad.Index

-- | Fold on indices in PrimMonad.
type IndexPrimMonadFoldM result = forall m. PrimMonad m => FoldM m Int result

-- | Given the size of the vector, construct a fold, which produces a
--   vector of frequencies of each index. I.e., the counts of how often it
--   appeared.
--   
--   It is your responsibility to ensure that the indices are within the
--   size of the vector produced.
frequency :: (Vector vector count, Enum count) => Int -> IndexPrimMonadFoldM (vector count)

module VectorExtras.Immutable

-- | Distribute the elements of a vector across the specified amount of
--   chunks.
--   
--   Depending on the size of the vector the first chunks may be larger in
--   size then the others by one.
chunk :: (Vector v1 a, Vector v2 (v1 a)) => Int -> v1 a -> v2 (v1 a)

-- | Construct from an unfoldr of the specified size.
--   
--   It is your responsibility to ensure that the unfoldr is of the same
--   size as the one specified.
unfoldrWithSize :: (MVector (Mutable vector) a, Vector vector a) => Int -> Unfoldr a -> vector a

-- | Construct from an unfoldr of associations of the specified size.
--   
--   It is your responsibility to ensure that the indices in the unfoldr
--   are within the specified size.
assocUnfoldrWithSize :: (MVector (Mutable vector) a, Vector vector a) => Int -> Unfoldr (Int, a) -> vector a

-- | Construct from a hash-map of the specified size.
--   
--   It is your responsibility to ensure that the indices in the unfoldr
--   are within the specified size.
indexHashMapWithSize :: (MVector (Mutable vector) a, Vector vector a) => Int -> HashMap a Int -> vector a

-- | Construct from a hash-map.
indexHashMap :: (MVector (Mutable vector) a, Vector vector a) => HashMap a Int -> vector a

module VectorExtras.Generic.Mutable
writeListInReverseOrderStartingFrom :: MVector v a => v s a -> Int -> [a] -> ST s ()
writeAssocList :: MVector v a => v s a -> [(Int, a)] -> ST s ()


-- | Utility for construction of vectors when the size is not known ahead.
module VectorExtras.Accumulator

-- | Constructor of vectors optimised for appending elements one by one,
--   providing for <math> complexity of the whole construction
--   process.
--   
--   Very useful as accumulator in folds.
--   
--   Under the hood it is the size counter and a reverse list of elements.
--   When executed, a vector of the according size gets allocated and gets
--   populated with the elements in reverse order (starting from the last
--   element).
data Accumulator a

-- | Create an empty accumulator.
init :: Accumulator a

-- | Add an element to the accumulator.
add :: a -> Accumulator a -> Accumulator a

-- | Add a list of elements to the accumulator.
addList :: [a] -> Accumulator a -> Accumulator a

-- | Add a foldable of elements to the accumulator.
addFoldable :: Foldable f => f a -> Accumulator a -> Accumulator a

-- | Finalise the accumulator as vector.
toVector :: Vector v a => Accumulator a -> v a

-- | Finalise the accumulator as vector in reverse order.
toReverseVector :: Vector v a => Accumulator a -> v a

module VectorExtras.Generic

-- | Notice: It is your responsibility to ensure that the indices in the
--   assoc list are within bounds.
fromAssocListWithGen :: Vector v a => Int -> (Int -> a) -> [(Int, a)] -> v a

-- | Notice: It is your responsibility to ensure that the indices in the
--   assoc list are within bounds.
fromAssocListWithDef :: Vector v a => Int -> a -> [(Int, a)] -> v a

-- | <pre>
--   &gt;&gt;&gt; fromReverseListN 3 [1,2,3] :: Data.Vector.Vector Int
--   [3,2,1]
--   </pre>
fromReverseListN :: Vector v a => Int -> [a] -> v a
initialized :: Vector v a => Int -> (forall s. Mutable v s a -> ST s ()) -> v a
fromFoldable :: (Foldable f, Vector v a) => f a -> v a


-- | Vector-specialised combinators often used for parsing.
module VectorExtras.Combinators
many :: (MonadPlus m, Vector v a) => m a -> m (v a)
sepBy :: (MonadPlus m, Vector v a) => m a -> m sep -> m (v a)
sepBy1 :: (MonadPlus m, Vector v a) => m a -> m sep -> m (v a)

-- | Same as <a>sepBy</a> but with arguments flipped. Because the order of
--   arguments in <a>sepBy</a> does not feel right.
sep :: (MonadPlus m, Vector v a) => m sep -> m a -> m (v a)

-- | Same as <a>sepBy1</a> but with arguments flipped. Because the order of
--   arguments in <a>sepBy1</a> does not feel right.
sep1 :: (MonadPlus m, Vector v a) => m sep -> m a -> m (v a)
sepEnd :: (MonadPlus m, Vector v a) => m sep -> m end -> m a -> m (v a)
sepEnd1 :: (MonadPlus m, Vector v a) => m sep -> m end -> m a -> m (v a)