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


-- | An Applicative Functor for extracting parts of a stream of values
--   
--   This provides a way to build up a computation that accesses many
--   different indices (possibly out-of-order) of a large stream of values,
--   and run it in a single scan over the stream. In essence, this
--   implements a hash-join.
@package collate
@version 0.1.0.0


-- | An Applicative Functor for extracting parts of a stream of values.
--   
--   Basic usage involves building up a computation from calls to the
--   <a>sample</a> function, then running the computation against a
--   <a>Foldable</a> of inputs. Operationally, this makes one pass over the
--   input in order, extracting each of the values specified by calls to
--   <a>sample</a>, then constructs the result according to the Applicative
--   structure.
--   
--   Because this is written against <a>ST</a>, we can run <a>Collate</a>s
--   purely, or convert them to <a>IO</a> as if by <a>stToIO</a>, and run
--   them with actual I/O interspersed. This means a <a>Collate</a> can be
--   driven by a streaming abstraction such as <a>conduit</a> or
--   <a>pipes</a>.
--   
--   Finally, although <a>Collate</a> itself doesn't admit any reasonable
--   <a>Monad</a> implementation, it can be used with <a>free</a> to
--   describe multi-pass algorithms over (repeatable) streams. To implement
--   <a>join</a>, we'd potentially need to look over the whole stream of
--   inputs to be able to construct the inner <a>Collate</a> and determine
--   which inputs it needs to inspect. So, we'd need to make multiple
--   passes. If we extended the type to support multiple passes and gave it
--   a <a>Monad</a> instance that implemented (<a>&gt;&gt;=</a>) by making
--   two passes, then the <a>Applicative</a> instance would also be
--   required to make two passes for (<a>&lt;*&gt;</a>), because of the law
--   that <tt>(<a>&lt;*&gt;</a>) = <a>ap</a></tt> for any <a>Monad</a>.
module Data.Collate

-- | <tt>Collate c a</tt> is a strategy for extracting an <tt>a</tt> from a
--   sequence of <tt>c</tt>s in a single streaming pass over the input,
--   even when lookups are specified in arbitrary order.
--   
--   Operationally, we build up a collection of mutable references,
--   construct a <a>Collator</a> that describes how to fill all of them,
--   construct an action that will read the mutable references and return
--   the ultimate result, iterate over the input sequence to fill the
--   mutable references, and finally run the action to get the result.
newtype Collate c a
Collate :: (forall s. ST s (ST s a, Collator (ST s) c)) -> Collate c a
[unCollate] :: Collate c a -> forall s. ST s (ST s a, Collator (ST s) c)

-- | An collection of "callbacks" for extracting things from a stream of
--   values.
--   
--   This is generated by <a>Collate</a>, and holds many partially-applied
--   <a>writeSTRef</a>s, so that once they've all been called, some larger
--   value can be extracted.
newtype Collator m c
Collator :: IntMap (c -> ST (PrimState m) ()) -> Collator m c
[getCollator] :: Collator m c -> IntMap (c -> ST (PrimState m) ())

-- | Construct a primitive <a>Collate</a> that strictly extracts the result
--   of a function from the input at the given index.
sample :: Int -> (c -> a) -> Collate c a

-- | Construct a primitive <a>Collate</a> that strictly extracts the result
--   of a function from many different indices.
bulkSample :: Traversable t => t Int -> (c -> a) -> Collate c (t a)

-- | Run a <a>Collate</a> on any <a>Foldable</a>.
collate :: Foldable f => Collate c a -> f c -> a

-- | Run a <a>Collate</a> on any <tt>Fold</tt>.
--   
--   The type signature looks complicated because we expand <tt>Fold</tt>
--   to avoid incurring a dependency on <tt>lens</tt>, but it's effectively
--   just:
--   
--   <pre>
--   collateOf :: Fold s c -&gt; Collate c a -&gt; s -&gt; a
--   </pre>
collateOf :: (forall s0. Traversing' (->) (Const (Sequenced () (StateT Int (ST s0)))) s c) -> Collate c a -> s -> a

-- | Run a <a>Collate</a> by providing an action in any <a>PrimMonad</a> to
--   drive the <a>Collator</a> it generates.
withCollator :: PrimMonad m => Collate c a -> (Collator m c -> m ()) -> m a

-- | Drive a <a>Collator</a> with any <a>Fold</a> over the input type it
--   expects.
--   
--   The <a>Int</a> parameter is the index of the first item in the
--   <a>Fold</a> (so that you can supply the input in multiple chunks).
--   
--   <pre>
--   feedCollatorOf
--     :: PrimMonad m
--     =&gt; Fold s c -&gt; Int -&gt; Collator m c -&gt; s -&gt; m Int
--   </pre>
feedCollatorOf :: forall m s c. PrimMonad m => Traversing' (->) (Const (Sequenced () (StateT Int (ST (PrimState m))))) s c -> Int -> Collator m c -> s -> m Int

-- | Drive a <a>Collator</a> with any <a>Foldable</a> containing its input
--   type.
--   
--   See <a>feedCollatorOf</a>.
feedCollator :: forall m f c. (PrimMonad m, Foldable f) => Int -> Collator m c -> f c -> m Int
instance GHC.Base.Functor (Data.Collate.Collate c)
instance GHC.Base.Applicative (Data.Collate.Collate c)
instance GHC.Base.Semigroup (Data.Collate.Collator m c)
instance GHC.Base.Monoid (Data.Collate.Collator m c)