------------------------------------------------------------------------------
--                                                                          --
--                                                                          --
--                     ASIS UTILITY LIBRARY COMPONENTS                      --
--                                                                          --
--                A S I S _ U L . S I M P L E _ S T A C K S                 --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--                    Copyright (C) 2012-2014, AdaCore                      --
--                                                                          --
-- Asis Utility Library (ASIS UL) is free software; you can redistribute it --
-- and/or  modify  it  under  terms  of  the  GNU General Public License as --
-- published by the Free Software Foundation; either version 3, or (at your --
-- option)  any later version.  ASIS UL  is distributed in the hope that it --
-- will  be  useful,  but  WITHOUT  ANY  WARRANTY; without even the implied --
-- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the --
-- GNU  General Public License for more details. You should have received a --
-- copy of the  GNU General Public License  distributed with GNAT; see file --
-- COPYING3. If not,  go to http://www.gnu.org/licenses for a complete copy --
-- of the license.                                                          --
--                                                                          --
-- ASIS UL is maintained by AdaCore (http://www.adacore.com).               --
--                                                                          --
------------------------------------------------------------------------------

pragma Ada_2012;

--  Defines a simple unlimited stack abstraction.

with Ada.Containers.Vectors;

generic
   type Element_Type is private;
   No_Element : Element_Type;

   with function "=" (Left, Right : Element_Type) return Boolean is <>;

package ASIS_UL.Simple_Stacks is

   --  Element_Type is the type of the stack elements.
   --
   --  No_Element is the special value to be returned in case if the state of
   --  the stack does not allow the given operation to return any meaningful
   --  result. That is, opposite to the classical stac abstraction, this one
   --  returns No_Element instead of raising an exception.
   --
   --  The main usage of this stack is to be used as a state of
   --  Traverse_Element - if we Push an element being visited in Pre_Operation
   --  and Pop it in Post_Operation, then the stack gives us the track to the
   --  top of our traversal (No_Element is set to Nil_Element).

   type Simple_Stack is private;

   procedure Push (S : in out Simple_Stack; Elem : Element_Type);
   --  Places Elem on the top of the stack

   function Pop (S : in out Simple_Stack) return Element_Type;
   --  Returns the top element of the stack and removes this element from
   --  the stack. Returns No_Element if the stack is empty

   procedure Pop (S : in out Simple_Stack);
   --  Removes the top element from the stack. Does nothing if the stack
   --  is empty

   function Top
     (S         : in out Simple_Stack;
      Step_Down :        Natural := 0)
      return             Element_Type;
   --  Returns the top element of the stack without removing this element from
   --  the stack. Returns No_Element if the stack is empty. If Step_Down is
   --  not 0, returns the Element which is Step_Down steps to the bottom of the
   --  stack, except if the stack depth is less than Step_Down, otherwise
   --  No_Element is returned

   function Size (S : in out Simple_Stack) return Natural;
   --  Returns the number of elements in the stack

   function Is_Empty_Stack (S : in out Simple_Stack) return Boolean;
   --  Same as Size = 0

private
   package Simple_Stacks_Package is new Ada.Containers.Vectors
     (Index_Type   => Natural,
      Element_Type => Element_Type,
      "="          => "=");

      type Simple_Stack is new Simple_Stacks_Package.Vector with null record;
end ASIS_UL.Simple_Stacks;