Mercurial > ~dholland > hg > ag > index.cgi
diff doc/misc/html/oldclasslib/stack.html @ 0:13d2b8934445
Import AnaGram (near-)release tree into Mercurial.
| author | David A. Holland |
|---|---|
| date | Sat, 22 Dec 2007 17:52:45 -0500 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/html/oldclasslib/stack.html Sat Dec 22 17:52:45 2007 -0500 @@ -0,0 +1,198 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>Stack Class Definition</TITLE> +</HEAD> + + +<BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif" + TEXT="#000000" LINK="#0033CC" + VLINK="#CC0033" ALINK="#CC0099"> + +<P> +<IMG ALIGN="right" SRC="../images/agrsl6c.gif" ALT="AnaGram" + WIDTH=124 HEIGHT=30 > +<BR CLEAR="all"> +Back to : +<A HREF="../index.html">Index</A> | +<A HREF="index.html">Class libraries for examples</A> +<P> +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> + +<H1>Stack Class Definition</H1> + +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<BR> +<H2>Introduction</H2> + + stack<class T> is a template class that facilitates the use + of push down stacks. Each stack is actually a stack of + stacks: by incrementing a level counter, a fresh stack can be + started on top of an existing one. When the level counter is + decremented the previous stack is restored. Multiple levels + allow stacks to be nested, a convenience in recursive + programs such as parsers. +<P> +<BR> + +<H2>Constructors</H2> + + The constructor for stack<class T> takes two unsigned integer + arguments: The maximum number of elements that can be stored + on the stack and the maximum number of levels. If the level + count is not specified it will default to 1. For example: +<PRE> + stack<int> arguments(100,10); + class widget { + . + . + . + }; + stack<widget> widget_stack(200,20); + stack<class T> paths(25); +</PRE> + These definitions provide for a stack of ints with room for + up to one hundred numbers in up to 10 levels, 200 widgets in + up to twenty levels. and 25 character string pointers in a + single level. +<P> +<BR> + +<H2>Error Checking</H2> + + All stack operations are protected by "assert" statements, so + that improper use as well as overflow conditions will be + detected and diagnosed. +<P> +<BR> + +<H2>Changing Levels</H2> + + If you have a multilevel stack, you may use the "++" operator + to increment the level and protect the previous contents. + When you are done, you use the "--" operator to decrement the + level and restore the previous contents of the stack. This + effectively allows you to build a nested stack in such a way + that when you are done the previous stack is restored. This + technique is very useful in recursive functions and in + recursive grammars. For example, +<PRE> + ++widget_stack; //protect previous content + --widget_stack; //restore previous content +</PRE> + The pre-increment and pre-decrement operators return a + reference to the stack so that operations can be combined. +<P> + Post-increment and post-decrement operators are also defined + for convenience in use, however they the result of these + operations can only be used for reading data, not for + changing the state of the stack. +<P> + Note that the first level of a stack need not be initialized, + since the increment and decrement operators cannot be used on + a single level stack. +<P> +<BR> + +<H2>Pushing Data on a Stack</H2> + + To push data onto the stack, use the overloaded "<<" + operator. For example, using the stack definitions above, you + may write: +<PRE> + widget w, v; + widget_stack << w << v; + int k,n; + arguments << n; + arguments << k << 2; +</PRE> + The "<<" operator returns a reference to the stack to make + chaining possible. +<P> +<BR> + +<H2>Popping Data from a Stack</H2> + + To pop data from the stack, use the overloaded ">>" operator: +<PRE> + widget w, v; + widget_stack >> v >> w; + int k,n; + arguments >> k >> n; +</PRE> + Remember that the stack is last in, first out. + + The ">>" operator also returns a reference to the stack to + make chaining possible. +<P> +<BR> + +<H2>Accessing Stack Elements</H2> + + To inspect or change a particular element on the stack, use + the overloaded "[ ]" operator: +<PRE> + widget w = widget_stack[k]; + widget_stack[k] = w; +</PRE> + An index of zero yields the top element on the stack, one + yields the next lower element and so forth. The index must be + less than the number of elements at the current level, so + that you cannot trespass on a lower level. +<P> + You may also use the cast operator to refer to the top + element of the stack: +<PRE> + widget w = (widget *) widget_stack; +</PRE> +<P> +<BR> + +<H2>Number of Elements on a Stack</H2> + + To determine the number of elements at the current level of + the stack, use "size": +<PRE> + int n = size(widget_stack); +</PRE> +<P> +<BR> + +<H2>Resetting a Stack</H2> + + The overloaded function reset() can be used to reset a stack + to its initial state. reset() returns a reference to the + stack so that operations can be combined: +<PRE> + widget w; + reset(widget_stack) << w; +</PRE> +<P> +<BR> + +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<IMG ALIGN="right" SRC="../images/pslrb6d.gif" ALT="Parsifal Software" + WIDTH=181 HEIGHT=25> +<BR CLEAR="right"> +<P> +Back to : +<A HREF="../index.html">Index</A> | +<A HREF="index.html">Class libraries for examples</A> + +<P> +<ADDRESS> +<FONT SIZE=-1>AnaGram parser generator - examples</FONT> +<BR><FONT SIZE=-1>Class libraries - Stack class definition</FONT> +<BR><FONT SIZE=-1>Copyright © 1993-1999, Parsifal Software.</FONT> +<BR><FONT SIZE=-1>All Rights Reserved.</FONT> +<BR> +</ADDRESS> +</BODY> +</HTML> +