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


-- | Grouped lists. Equal consecutive elements are grouped.
--   
--   Grouped lists work like regular lists, except for two conditions:
--   
--   <ul>
--   <li>Grouped lists are always finite. Attempting to construct an
--   infinite grouped list will result in an infinite loop.</li>
--   <li>Grouped lists internally represent consecutive equal elements as
--   only one, hence the name of <i>grouped lists</i>.</li>
--   </ul>
--   
--   This mean that grouped lists are ideal for cases where the list has
--   many repetitions (like <tt>[1,1,1,1,7,7,7,7,7,7,7,7,2,2,2,2,2]</tt>,
--   although they might present some deficiencies in the absent of
--   repetitions.
@package grouped-list
@version 0.2.2.0


-- | Grouped lists are like lists, but internally they are represented as
--   groups of consecutive elements.
--   
--   For example, the list <tt>[1,2,2,3,4,5,5,5]</tt> would be internally
--   represented as <tt>[[1],[2,2],[3],[4],[5,5,5]]</tt>. Use
--   <a>groupedGroups</a> to see this.
module Data.GroupedList

-- | Type of grouped lists. Grouped lists are finite lists that perform
--   better than regular lists in the abundance of sublists that have all
--   their elements equal.
data Grouped a

-- | Grouped list with no elements.
empty :: Grouped a
point :: Pointed p => forall a. () => a -> p a

-- | Map a function that produces a grouped list for each element in a
--   grouped list, then concat the results.
concatMap :: Eq b => Grouped a -> (a -> Grouped b) -> Grouped b

-- | Replicate a single element the given number of times. If the given
--   number is less or equal to zero, it produces an empty list.
replicate :: Int -> a -> Grouped a

-- | Build a grouped list from a group (see <a>Group</a>).
fromGroup :: Group a -> Grouped a

-- | Returns the size/length of a finite structure as an <a>Int</a>. The
--   default implementation is optimized for structures that are similar to
--   cons-lists, because there is no general way to do better.
length :: Foldable t => forall a. () => t a -> Int

-- | Retrieve the element at the given index. If the index is out of the
--   list index range, it returns <a>Nothing</a>.
index :: Grouped a -> Int -> Maybe a

-- | Update the element at the given index. If the index is out of range,
--   the original list is returned.
adjust :: Eq a => (a -> a) -> Int -> Grouped a -> Grouped a

-- | Just like <a>adjust</a>, but the function returns in a <a>Monad</a>.
adjustM :: (Monad m, Eq a) => (a -> m a) -> Int -> Grouped a -> m (Grouped a)

-- | Take the given number of elements from the left end of the list.
take :: Int -> Grouped a -> Grouped a

-- | Discard the given number of elements from the left end of the list.
drop :: Int -> Grouped a -> Grouped a

-- | Apply a function to every element in a grouped list.
map :: Eq b => (a -> b) -> Grouped a -> Grouped b

-- | Apply a function with results residing in an applicative functor to
--   every element in a grouped list.
traverseGrouped :: (Applicative f, Eq b) => (a -> f b) -> Grouped a -> f (Grouped b)

-- | Similar to <a>traverseGrouped</a>, but instead of applying a function
--   to every element of the list, it is applied to groups of consecutive
--   elements. You might return more than one element, so the result is of
--   type <a>Grouped</a>. The results are then concatenated into a single
--   value, embedded in the applicative functor.
traverseGroupedByGroup :: (Applicative f, Eq b) => (Group a -> f (Grouped b)) -> Grouped a -> f (Grouped b)

-- | Like <a>traverseGroupedByGroup</a>, but carrying an accumulator. Note
--   the <a>Monad</a> constraint instead of <a>Applicative</a>.
traverseGroupedByGroupAccum :: (Monad m, Eq b) => (acc -> Group a -> m (acc, Grouped b)) -> acc -> Grouped a -> m (acc, Grouped b)

-- | Break a grouped list in the elements that match a given condition and
--   those that don't.
partition :: Eq a => (a -> Bool) -> Grouped a -> (Grouped a, Grouped a)

-- | Filter a grouped list by keeping only those elements that match a
--   given condition.
filter :: Eq a => (a -> Bool) -> Grouped a -> Grouped a

-- | Sort a grouped list.
sort :: Ord a => Grouped a -> Grouped a

-- | Combine two lists using a combining function. If one list is longer,
--   remaining elements are discarded.
zipWith :: Eq c => (a -> b -> c) -> Grouped a -> Grouped b -> Grouped c

-- | Combine two lists in a single list of pairs. If one list is longer,
--   remaining elements are discarded.
zip :: (Eq a, Eq b) => Grouped a -> Grouped b -> Grouped (a, b)

-- | Build a grouped list from a regular list. It doesn't work if the input
--   list is infinite.
fromList :: Eq a => [a] -> Grouped a

-- | A <a>Group</a> is a non-empty finite list that contains the same
--   element repeated a number of times.
data Group a

-- | Build a group by repeating the given element a number of times. If the
--   given number is less or equal to 0, <a>Nothing</a> is returned.
buildGroup :: Int -> a -> Maybe (Group a)

-- | Get the element of a group.
groupElement :: Group a -> a

-- | Size of a group.
groupSize :: Group a -> Int

-- | Groups of consecutive elements in a grouped list.
groupedGroups :: Grouped a -> [Group a]

-- | Get the first group (if the list is not empty) and the rest of the
--   list.
firstGroup :: Grouped a -> Maybe (Group a, Grouped a)

-- | Get the last group (if the list is not empty) and the rest of the
--   list.
lastGroup :: Grouped a -> Maybe (Grouped a, Group a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.GroupedList.Grouped a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.GroupedList.Group a)
instance GHC.Classes.Eq a => GHC.Exts.IsList (Data.GroupedList.Grouped a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Data.GroupedList.Grouped a)
instance Data.Pointed.Pointed Data.GroupedList.Grouped
instance GHC.Classes.Eq a => GHC.Base.Monoid (Data.GroupedList.Grouped a)
instance Data.Foldable.Foldable Data.GroupedList.Grouped
instance GHC.Show.Show a => GHC.Show.Show (Data.GroupedList.Grouped a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.GroupedList.Grouped a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Data.GroupedList.Group a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.GroupedList.Group a)
instance Data.Pointed.Pointed Data.GroupedList.Group
instance GHC.Base.Functor Data.GroupedList.Group
instance Data.Foldable.Foldable Data.GroupedList.Group
instance GHC.Show.Show a => GHC.Show.Show (Data.GroupedList.Group a)
instance GHC.Base.Applicative Data.GroupedList.Group
instance GHC.Base.Monad Data.GroupedList.Group
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.GroupedList.Group a)
