-- Created on: 1993-01-18 -- Created by: Remi LEQUETTE -- Copyright (c) 1993-1999 Matra Datavision -- Copyright (c) 1999-2012 OPEN CASCADE SAS -- -- The content of this file is subject to the Open CASCADE Technology Public -- License Version 6.5 (the "License"). You may not use the content of this file -- except in compliance with the License. Please obtain a copy of the License -- at http://www.opencascade.org and read it completely before using this file. -- -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France. -- -- The Original Code and all software distributed under the License is -- distributed on an "AS IS" basis, without warranty of any kind, and the -- Initial Developer hereby disclaims all such warranties, including without -- limitation, any warranties of merchantability, fitness for a particular -- purpose or non-infringement. Please see the License for the specific terms -- and conditions governing the rights and limitations under the License. -- 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 . --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 is empty ---C++: return const & raises NoSuchObject from Standard is static; Push(me : in out; I : Item) ---Level: Public ---Purpose: Adds 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 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 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;