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

<!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&lt;class T&gt; 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&lt;class T&gt; 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&lt;int&gt; arguments(100,10);
            class widget {
            .
            .
            .
            };
            stack&lt;widget&gt; widget_stack(200,20);
            stack&lt;class T&gt; 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 "&lt;&lt;"
          operator. For example, using the stack definitions above, you
          may write:
<PRE>
            widget w, v;
            widget_stack &lt;&lt; w &lt;&lt; v;
            int k,n;
            arguments &lt;&lt; n;
            arguments &lt;&lt; k &lt;&lt; 2;
</PRE>
          The "&lt;&lt;" 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 "&gt;&gt;" operator:
<PRE>
            widget w, v;
            widget_stack &gt;&gt; v &gt;&gt; w;
            int k,n;
            arguments &gt;&gt; k &gt;&gt; n;
</PRE>
          Remember that the stack is last in, first out.

          The "&gt;&gt;" 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) &lt;&lt; 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 &copy; 1993-1999, Parsifal Software.</FONT>
<BR><FONT SIZE=-1>All Rights Reserved.</FONT>
<BR>
</ADDRESS>
</BODY>
</HTML>
author	David A. Holland
date	Sat, 22 Dec 2007 17:52:45 -0500
parents
children