OCCT/src/TCollection/TCollection_Stack.cdl

-- Created on: 1993-01-18
-- Created by: Remi LEQUETTE
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and / or modify it
-- under the terms of the GNU Lesser General Public version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

-- Updated:     M. MERCIEN 26, Oct 1994
-- Subject:     StackIterator implementation          	


generic class Stack from TCollection (Item as any)

	---Purpose: A stack is a structure where item can be added and
	-- removed from the top. Like a stack of plates  in a
	-- kitchen. The   last entered item  will be   be the
	-- first  removed. This  is  called  a  LIFO (last In First Out).
    	-- Stack is a generic class which depends on Item, the type
    	-- of element in the structure.
    	-- Use a StackIterator iterator to explore a Stack structure.
    	-- Note: An iterator class is automatically instantiated from
    	-- the TCollection_StackIterator class at the time of
    	-- instantiation of a Stack structure.
raises
    NoSuchObject from Standard

       	class StackNode from TCollection 
	    inherits MapNode from TCollection
	    uses MapNodePtr from TCollection
	    is
	      Create(I : Item; n : MapNodePtr from TCollection) returns StackNode from TCollection;
	      ---C++: inline
      
	      Value(me) returns Item;
	      ---C++: return &
	      ---C++: inline

	 fields  
	      myValue : Item;
	 end;
         
    class StackIterator from TCollection 				      
        ---Purpose: Functions used for iterating the contents of a Stack data structure.
    	-- Note: an iterator class is automatically instantiated from
    	-- this generic class at the time of instantiation of a Stack structure.

    raises NoSuchObject from Standard
    is     
    	Create returns StackIterator from TCollection;
	    ---Purpose: Constructs an empty iterator for a Stack data structure.
    	    -- Use the function Initialize to define the stack to explore.
 
     	Create(S : Stack from TCollection) returns StackIterator from TCollection;
            ---Purpose: Constructs an iterator on the stack stack, and positions it
    	    -- on the first item of the stack stack, if it exists.
    	    -- The current position is undefined if the stack stack is empty.
    	    -- Use in a loop:
    	    -- -   the function More to know if there is a current item,
    	    -- -   then the function Value to read the value of the current item,
    	    -- -   then the function Next to position the iterator on the
    	    --   next item, if it exists.
	    
	Initialize(me : in out; S : Stack from TCollection)
    	    ---Purpose: Sets, or resets this iterator for the stack stack, and
    	    -- positions it on the first item of the stack stack, if it exists.
    	    -- The current position is undefined if the stack stack is empty.
    	    -- Example
    	    -- TColStd_StackOfInteger stack;
    	    -- TColStd_StackIteratorOfStackOfInteger
    	    -- pos;
    	    -- pos.Initialize(stack);
    	    -- Use in a loop:
    	    -- -   the function More to know if there is a current item,
    	    -- -   then the function Value to read the value of the current   item,
    	    -- -   then the function Next to position the iterator on the
    	    --   next item, if it exists.
	is static;

     	More(me) returns Boolean from Standard
    	    ---Purpose:Returns true if there is a current item in the stack explored
    	    -- with this iterator (i.e. when the current position is defined).
    	    -- More is false if:
    	    -- -   the iterator is not initialized, or
    	    -- -   the stack is empty, or
    	    -- -   the exploration is finished.
    	    --   Use:
    	    -- -   the function Value to read the current item,
    	    -- - the function Next to position this iterator on the next  item, if it exists.
	    ---C++: inline
	is static;

     	Next(me: in out)
	    ---Purpose: Sets the iterator to the next item in the explored stack.
    	    -- If the current position of this iterator corresponds to the
    	    -- top of the stack, it becomes undefined. 
	is static;
	    	
     	Value(me) returns any Item 
    	raises NoSuchObject from Standard
	    ---Purpose: Returns the value of the current item of this iterator in the explored stack.
    	    -- Note: Item is the type of element in the explored Stack stack.
    	    -- Example
    	    -- TColStd_StackOfInteger stack;
    	    -- TColStd_StackIteratorOfStackOfInteger
    	    -- pos(stack);
    	    -- stack.Push(1);
    	    -- assert ( pos.Value() == 1 );
    	    -- Exceptions
    	    -- Standard_NoSuchObject if the current position of this
    	    -- iterator is undefined.
	    ---C++: return const &
	is static;

    fields
        current : Address from Standard;
    	
    end StackIterator from TCollection;

is
    Create returns Stack from TCollection;
	---Purpose: Constructs an empty stack.
    	-- Use:
    	-- -   the function Push to add an item at the top of the stack,
    	-- -   the function Top to read the item at the top of the stack,
    	-- -   the function ChangeTop to assign a new value to the
    	--   item at the top of the stack,
    	-- -   the function Pop to remove the item at the top of the stack,
    	-- -   and a stack iterator to explore the stack and read all its items.
    	--   Warning
    	-- To copy a stack, you must explicitly call the assignment
    	--  operator (operator=)..
	
    Create(Other : Stack from TCollection) 
    returns Stack from TCollection 
    is private;
	---Purpose: Creates by copying an existing Stack.
	--  Warning: Prints a message when  other is not  empty.  It is
	-- recommanded to use Assign (operator =).
    
    Assign(me : in out; Other : Stack from TCollection) 
    returns Stack from TCollection
	---Purpose: Copies in this stack the content of <Other>.
    	--If this stack is not empty, it is automatically cleared before copying.
    	-- Note that this method is an alias of the assignment
    	-- operator operator =.
	---C++: alias operator =
	---C++: return const &
    is static;
	
    IsEmpty(me) returns Boolean
	---Purpose: Returns True when the stack is empty.
	-- i.e. Depth() == 0
	---C++: inline
    is static;
    
    Depth(me) returns Integer
        ---Level: Public
	---Purpose: Returns the number of Items in the stack.
	-- The depth of this stack is:
    	-- -   incremented by Push, and
    	-- -   decremented by Pop.
        --  Example:          
	-- me = (A B C)
	-- returns 3
	---C++: inline
    is static;
    
    Top(me) returns any Item
        ---Level: Public
	---Purpose: Returns the Item at the top of the stack.
	--  Example:
        -- before
        --   me = (A B C) 
        -- after
        --   me = (A B C)
        -- returns 
        --   A
        --  Trigger: Raises an exception when <me> is empty 
	---C++: return const &
    raises NoSuchObject from Standard
    is static;
    
    Push(me : in out; I : Item)
        ---Level: Public
	---Purpose: Adds  <I> at  the  top  of  the stack.   Depth  is
	-- incremented.
	--  Example:          
        -- before
        --   me = (A B C) I = D
        -- after
        --   me = (D A B C)
    is static;
    
    Pop(me : in out)
        ---Level: Public
	---Purpose: Removes the Item at the top of the stack. Depth is
	-- decremented.
	--  Example:         
        -- before
        --   me = (A B C)
        -- after
        --   me = (B C)
        --  Trigger: Raises an exception when <me> is empty 
    raises NoSuchObject from Standard
    is static;
    
    Clear(me : in out)
        ---Level: Public
	---Purpose: Removes all the items from the stack.
	---C++: alias ~
    is static;

    ChangeTop(me : in out) returns any Item
        ---Level: Public
	---Purpose: Returns a modifiable reference of the top of the stack.
	--  Example:          
        -- before
        --   me = (A B C) 
        --   me.ChangeTop() = D
        -- after
        --   me = (D B C)
        --  Trigger: Raises an exception when <me> is empty
    raises NoSuchObject from Standard
	---C++: return &    
    is static;
    
fields
    
    myTop   : Address from Standard;
    myDepth : Integer from Standard;

friends
    class StackIterator from TCollection

end Stack;