Mercurial > ~dholland > hg > ag > index.cgi

comparison doc/misc/html/oldclasslib/stack.html @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>Stack Class Definition</TITLE>
5 </HEAD>
6
7
8 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
9 TEXT="#000000" LINK="#0033CC"
10 VLINK="#CC0033" ALINK="#CC0099">
11
12 <P>
13 <IMG ALIGN="right" SRC="../images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30 >
15 <BR CLEAR="all">
16 Back to :
17 <A HREF="../index.html">Index</A> |
18 <A HREF="index.html">Class libraries for examples</A>
19 <P>
20 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
21 WIDTH=1010 HEIGHT=2 >
22 <P>
23
24 <H1>Stack Class Definition</H1>
25
26 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
27 WIDTH=1010 HEIGHT=2 >
28 <P>
29 <BR>
30 <H2>Introduction</H2>
31
32 stack&lt;class T&gt; is a template class that facilitates the use
33 of push down stacks. Each stack is actually a stack of
34 stacks: by incrementing a level counter, a fresh stack can be
35 started on top of an existing one. When the level counter is
36 decremented the previous stack is restored. Multiple levels
37 allow stacks to be nested, a convenience in recursive
38 programs such as parsers.
39 <P>
40 <BR>
41
42 <H2>Constructors</H2>
43
44 The constructor for stack&lt;class T&gt; takes two unsigned integer
45 arguments: The maximum number of elements that can be stored
46 on the stack and the maximum number of levels. If the level
47 count is not specified it will default to 1. For example:
48 <PRE>
49 stack&lt;int&gt; arguments(100,10);
50 class widget {
51 .
52 .
53 .
54 };
55 stack&lt;widget&gt; widget_stack(200,20);
56 stack&lt;class T&gt; paths(25);
57 </PRE>
58 These definitions provide for a stack of ints with room for
59 up to one hundred numbers in up to 10 levels, 200 widgets in
60 up to twenty levels. and 25 character string pointers in a
61 single level.
62 <P>
63 <BR>
64
65 <H2>Error Checking</H2>
66
67 All stack operations are protected by "assert" statements, so
68 that improper use as well as overflow conditions will be
69 detected and diagnosed.
70 <P>
71 <BR>
72
73 <H2>Changing Levels</H2>
74
75 If you have a multilevel stack, you may use the "++" operator
76 to increment the level and protect the previous contents.
77 When you are done, you use the "--" operator to decrement the
78 level and restore the previous contents of the stack. This
79 effectively allows you to build a nested stack in such a way
80 that when you are done the previous stack is restored. This
81 technique is very useful in recursive functions and in
82 recursive grammars. For example,
83 <PRE>
84 ++widget_stack; //protect previous content
85 --widget_stack; //restore previous content
86 </PRE>
87 The pre-increment and pre-decrement operators return a
88 reference to the stack so that operations can be combined.
89 <P>
90 Post-increment and post-decrement operators are also defined
91 for convenience in use, however they the result of these
92 operations can only be used for reading data, not for
93 changing the state of the stack.
94 <P>
95 Note that the first level of a stack need not be initialized,
96 since the increment and decrement operators cannot be used on
97 a single level stack.
98 <P>
99 <BR>
100
101 <H2>Pushing Data on a Stack</H2>
102
103 To push data onto the stack, use the overloaded "&lt;&lt;"
104 operator. For example, using the stack definitions above, you
105 may write:
106 <PRE>
107 widget w, v;
108 widget_stack &lt;&lt; w &lt;&lt; v;
109 int k,n;
110 arguments &lt;&lt; n;
111 arguments &lt;&lt; k &lt;&lt; 2;
112 </PRE>
113 The "&lt;&lt;" operator returns a reference to the stack to make
114 chaining possible.
115 <P>
116 <BR>
117
118 <H2>Popping Data from a Stack</H2>
119
120 To pop data from the stack, use the overloaded "&gt;&gt;" operator:
121 <PRE>
122 widget w, v;
123 widget_stack &gt;&gt; v &gt;&gt; w;
124 int k,n;
125 arguments &gt;&gt; k &gt;&gt; n;
126 </PRE>
127 Remember that the stack is last in, first out.
128
129 The "&gt;&gt;" operator also returns a reference to the stack to
130 make chaining possible.
131 <P>
132 <BR>
133
134 <H2>Accessing Stack Elements</H2>
135
136 To inspect or change a particular element on the stack, use
137 the overloaded "[ ]" operator:
138 <PRE>
139 widget w = widget_stack[k];
140 widget_stack[k] = w;
141 </PRE>
142 An index of zero yields the top element on the stack, one
143 yields the next lower element and so forth. The index must be
144 less than the number of elements at the current level, so
145 that you cannot trespass on a lower level.
146 <P>
147 You may also use the cast operator to refer to the top
148 element of the stack:
149 <PRE>
150 widget w = (widget *) widget_stack;
151 </PRE>
152 <P>
153 <BR>
154
155 <H2>Number of Elements on a Stack</H2>
156
157 To determine the number of elements at the current level of
158 the stack, use "size":
159 <PRE>
160 int n = size(widget_stack);
161 </PRE>
162 <P>
163 <BR>
164
165 <H2>Resetting a Stack</H2>
166
167 The overloaded function reset() can be used to reset a stack
168 to its initial state. reset() returns a reference to the
169 stack so that operations can be combined:
170 <PRE>
171 widget w;
172 reset(widget_stack) &lt;&lt; w;
173 </PRE>
174 <P>
175 <BR>
176
177 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
178 WIDTH=1010 HEIGHT=2 >
179 <P>
180 <IMG ALIGN="right" SRC="../images/pslrb6d.gif" ALT="Parsifal Software"
181 WIDTH=181 HEIGHT=25>
182 <BR CLEAR="right">
183 <P>
184 Back to :
185 <A HREF="../index.html">Index</A> |
186 <A HREF="index.html">Class libraries for examples</A>
187
188 <P>
189 <ADDRESS>
190 <FONT SIZE=-1>AnaGram parser generator - examples</FONT>
191 <BR><FONT SIZE=-1>Class libraries - Stack class definition</FONT>
192 <BR><FONT SIZE=-1>Copyright &copy; 1993-1999, Parsifal Software.</FONT>
193 <BR><FONT SIZE=-1>All Rights Reserved.</FONT>
194 <BR>
195 </ADDRESS>
196 </BODY>
197 </HTML>
198