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


-- | Stack data structure
--   
--   A stack is a basic data structure that can be logically thought as
--   linear structure represented by a real physical stack or pile, a
--   structure where insertion and deletion of items takes place at one end
--   called top of the stack.
--   
@package Stack
@version 0.3.2


-- | Stack data structure and associated operations
--   
--   A stack is a basic data structure that can be logically thought as
--   linear structure represented by a real physical stack or pile, a
--   structure where insertion and deletion of items takes place at one end
--   called top of the stack.
--   
--   In other words, a <a>Stack</a> is an abstract data type that serves as
--   a collection of elements, with two principal operations:
--   <a>stackPush</a>, which adds an element to the collection, and
--   <a>stackPop</a>, which removes the most recently added element that
--   was not yet removed.
--   
--   
--   See also
--   <a>https://en.wikipedia.org/wiki/Stack_(abstract_data_type)</a>
module Data.Stack

-- | Abstract Stack data type
data Stack a

-- | <i>O(1)</i>. Create new empty Stack
stackNew :: Stack a

-- | <i>O(1)</i>. Push item onto Stack
--   
--   <pre>
--   (∀x)(∀s)(stackPop (stackPush s x) == Just (s,x))
--   </pre>
stackPush :: Stack a -> a -> Stack a

-- | <i>O(1)</i>. Pop most recently added item without removing from the
--   Stack
--   
--   <pre>
--   stackPeek stackNew == Nothing
--   (∀x)(∀s)(stackPeek (stackPush s x) == Just x)
--   (∀s)(stackPeek s == fmap snd (stackPop s))
--   </pre>
stackPeek :: Stack a -> Maybe a

-- | <i>O(1)</i>. Pop most recently added item from Stack
--   
--   <pre>
--   stackPop stackNew == Nothing
--   (∀x)(∀s)(stackPop (stackPush s x) == Just (s,x))
--   </pre>
stackPop :: Stack a -> Maybe (Stack a, a)

-- | <i>O(1)</i>. Test if stack is empty
--   
--   <pre>
--   stackIsEmpty stackNew == True
--   (∀x)(∀s)(stackIsEmpty (stackPush s x) == True)
--   (∀s)((stackSize s == 0) ⇔ (stackIsEmpty s == True))
--   </pre>
stackIsEmpty :: Stack a -> Bool

-- | <i>O(1)</i>. Compute number of elements contained in the Stack
--   
--   <pre>
--   stackSize stackNew == 0
--   (∀x)(∀s)((stackSize s == n) ⇒ (stackSize (stackPush s x) == n+1))
--   </pre>
stackSize :: Stack a -> Natural
instance GHC.Show.Show a => GHC.Show.Show (Data.Stack.Stack a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Stack.Stack a)


-- | Provides a stack container for use in the <a>ST</a> monad
module Data.Stack.ST

-- | A mutable stack in state thread s, containing values of type a
data Stack s a

-- | Create new empty Stack
stackNew :: ST s (Stack s a)

-- | Push item onto Stack
stackPush :: Stack s a -> a -> ST s ()

-- | Pop most recently added item without removing from the Stack
stackPeek :: Stack s a -> ST s (Maybe a)

-- | Pop most recently added item from Stack
stackPop :: Stack s a -> ST s (Maybe a)

-- | Test if stack is empty
stackIsEmpty :: Stack s a -> ST s Bool

-- | Compute number of elements contained in the Stack
stackSize :: Stack s a -> ST s Natural


-- | Provides a synchronized stack container for use in the <a>STM</a>
--   monad
--   
--   See also <a>Control.Concurrent.Stack</a>
module Control.Concurrent.STM.Stack

-- | Synchronized stack data type
data Stack a

-- | Create new empty Stack
stackNew :: STM (Stack a)

-- | Push item onto Stack
stackPush :: Stack a -> a -> STM ()

-- | Pop most recently added item without removing from the Stack
--   
--   Automatically retries if stack is empty
stackPeek :: Stack a -> STM a

-- | Pop most recently added item without removing from the Stack
stackTryPeek :: Stack a -> STM (Maybe a)

-- | Pop most recently added item from Stack
--   
--   Automatically retries if stack is empty
stackPop :: Stack a -> STM a

-- | Pop most recently added item from Stack
stackTryPop :: Stack a -> STM (Maybe a)

-- | Test if stack is empty
stackIsEmpty :: Stack a -> STM Bool

-- | Compute number of elements contained in the Stack
stackSize :: Stack a -> STM Natural


-- | Provides a synchronized stack for use in the IO monad
--   
--   See also <a>Control.Concurrent.STM.Stack</a>
module Control.Concurrent.Stack

-- | Synchronized stack data type
data Stack a

-- | Create new empty Stack
stackNew :: IO (Stack a)

-- | Push item onto Stack
stackPush :: Stack a -> a -> IO ()

-- | Pop most recently added item without removing from the Stack
--   
--   Blocks if stack is empty
stackPeek :: Stack a -> IO a

-- | Pop most recently added item without removing from the Stack
stackTryPeek :: Stack a -> IO (Maybe a)

-- | Pop most recently added item from Stack
--   
--   Blocks if stack is empty
stackPop :: Stack a -> IO a

-- | Pop most recently added item from Stack
stackTryPop :: Stack a -> IO (Maybe a)

-- | Test if stack is empty
stackIsEmpty :: Stack a -> IO Bool

-- | Compute number of elements contained in the Stack
stackSize :: Stack a -> IO Natural