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


-- | Circular fixed-sized mutable vectors
--   
--   Please see the README at
--   <a>https://github.com/dschrempf/circular#readme</a>
@package circular
@version 0.4.0.2


-- | Creation date: Thu Jun 18 10:00:28 2020.
--   
--   Construction of mutable circular stacks is done with <a>replicate</a>
--   and subsequent <a>push</a>es, or with <a>fromVector</a>.
--   
--   When denoting the asymptotic runtime of functions, <tt>n</tt> refers
--   to the circular stack size.
module Data.Stack.Circular

-- | Mutable circular stacks with fixed size are just mutable vectors with
--   a pointer to the last element.
data MStack v s a

-- | A circular stack of given size with the same element replicated.
--   
--   Call <a>error</a> if the maximum size is zero or negative.
--   
--   O(n).
replicate :: (Vector v a, PrimMonad m) => Int -> a -> m (MStack v (PrimState m) a)

-- | Convert a vector to a circular stack with size being equal to the
--   length of the vector. The first element of the vector is the oldest
--   element of the stack, the last element of the vector is the youngest
--   element of the stack.
--   
--   The vector must be non-empty.
--   
--   O(n).
fromVector :: (Vector v a, PrimMonad m) => v a -> m (MStack v (PrimState m) a)

-- | Convert a vector to a circular stack with size being equal to the
--   length of the vector. The element of the vector at the given index is
--   the youngest element of the stack, the next element of the vector is
--   the oldest element of the stack.
--   
--   The vector must be non-empty.
--   
--   O(n).
fromVectorWithIndex :: (Vector v a, PrimMonad m) => Int -> v a -> m (MStack v (PrimState m) a)

-- | Convert a circular stack to a vector. The first element of the
--   returned vector is the oldest element of the stack, the last element
--   of the returned vector is the youngest element of the stack.
--   
--   O(n).
toVector :: (Vector v a, PrimMonad m) => MStack v (PrimState m) a -> m (v a)

-- | Convert the last k elements of a circular stack to a vector. The first
--   element of the returned vector is the oldest element of the stack, the
--   last element of the returned vector is the youngest element of the
--   stack.
--   
--   The size of the stack must be larger than k.
--   
--   O(k).
take :: (Vector v a, PrimMonad m) => Int -> MStack v (PrimState m) a -> m (v a)

-- | Size of the stack.
size :: Vector v a => MStack v s a -> Int

-- | Get the last element without changing the stack.
--   
--   O(1).
get :: (Vector v a, PrimMonad m) => MStack v (PrimState m) a -> m a

-- | Pop the youngest element from the stack and put the focus on the
--   previous element.
--   
--   Be careful:
--   
--   The stack is always full! Popping returns the last element and moves
--   the index to the second-last element, but the element is not truly
--   removed from the stack. It is only put to the end of the queue.
--   
--   Hence, <a>pop</a> always succeeds, even if there are actually no more
--   elements on the stack (similar to walking backwards in a circle).
--   
--   O(1).
pop :: (Vector v a, PrimMonad m) => MStack v (PrimState m) a -> m (a, MStack v (PrimState m) a)

-- | Push an element on the stack.
--   
--   O(1).
push :: (Vector v a, PrimMonad m) => a -> MStack v (PrimState m) a -> m (MStack v (PrimState m) a)

-- | Monadic fold from young to old over all elements of the stack.
--   
--   Please also see the documentation of <a>pop</a>.
--   
--   O(n).
foldM :: (Vector v b, PrimMonad m) => (a -> b -> a) -> a -> MStack v (PrimState m) b -> m a

-- | See <a>foldM</a> but only over the <tt>k</tt> youngest elements on the
--   stack.
--   
--   O(k).
foldKM :: (Vector v b, PrimMonad m) => Int -> (a -> b -> a) -> a -> MStack v (PrimState m) b -> m a

-- | Immutable circular stack; useful, for example, to save, or restore a
--   mutable circular stack.
data Stack v a

-- | Conversion from immutable to mutable circular stack.
--   
--   O(n).
thaw :: (Vector v a, PrimMonad m) => Stack v a -> m (MStack v (PrimState m) a)

-- | Conversion from mutable to immutable circular stack.
--   
--   O(n).
freeze :: (Vector v a, PrimMonad m) => MStack v (PrimState m) a -> m (Stack v a)
instance Data.Aeson.Types.FromJSON.FromJSON (v a) => Data.Aeson.Types.FromJSON.FromJSON (Data.Stack.Circular.Stack v a)
instance Data.Aeson.Types.ToJSON.ToJSON (v a) => Data.Aeson.Types.ToJSON.ToJSON (Data.Stack.Circular.Stack v a)
instance GHC.Show.Show (v a) => GHC.Show.Show (Data.Stack.Circular.Stack v a)
instance GHC.Read.Read (v a) => GHC.Read.Read (Data.Stack.Circular.Stack v a)
instance GHC.Classes.Eq (v a) => GHC.Classes.Eq (Data.Stack.Circular.Stack v a)