mirror of
https://gitlab.com/fbb-git/cppannotations
synced 2024-11-16 07:48:44 +01:00
92 lines
4.8 KiB
Text
92 lines
4.8 KiB
Text
The ti(stack) class implements a i(stack data structure). Before using
|
|
tt(stack) containers the header file tthi(stack) must be included.
|
|
|
|
A stack is also called a i(first in, last out) (i(FILO) or i(LIFO)) data
|
|
structure as the first item to enter the stack is the last item to leave. A
|
|
stack is an extremely useful data structure in situations where data must
|
|
temporarily remain available. For example, programs maintain a stack to store
|
|
local variables of functions: the lifetime of these variables is determined by
|
|
the time these functions are active, contrary to global (or static local)
|
|
variables, which live for as long as the program itself lives. Another example
|
|
is found in calculators using the
|
|
emi(Reverse Polish Notation) (i(RPN)), in which the operands of operators are
|
|
kept in a stack, whereas operators pop their operands off the stack and
|
|
push the results of their work back onto the stack.
|
|
|
|
As an example of the use of a stack, consider figure ref(StackFig), in which
|
|
the contents of the stack is shown while the expression tt((3 + 4) * 2) is
|
|
evaluated. In the RPN this expression becomes tt(3 4 + 2 *), and figure
|
|
ref(StackFig) shows the stack contents after each emi(token) (i.e., the
|
|
operands and the operators) is read from the input. Notice that each operand
|
|
is indeed pushed on the stack, while each operator changes the contents of the
|
|
stack.
|
|
figure(containers/stack/stack)
|
|
(The contents of a stack while evaluating tt(3 4 + 2 *))
|
|
(StackFig)
|
|
The expression is evaluated in five steps. The caret between the tokens
|
|
in the expressions shown on the first line of figure ref(StackFig) shows what
|
|
token has just been read. The next line shows the actual stack-contents, and
|
|
the final line shows the steps for referential purposes. Note that at step 2,
|
|
two numbers have been pushed on the stack. The first number (tt(3)) is now at
|
|
the bottom of the stack. Next, in step 3, the tt(+) operator is read. The
|
|
operator pops two operands (so that the stack is empty at that moment),
|
|
calculates their sum, and pushes the resulting value (tt(7)) on the
|
|
stack. Then, in step 4, the number tt(2) is read, which is dutifully pushed on
|
|
the stack again. Finally, in step 5 the final operator tt(*) is read, which
|
|
pops the values tt(2) and tt(7) from the stack, computes their product, and
|
|
pushes the result back on the stack. This result (tt(14)) could then be popped
|
|
to be displayed on some medium.
|
|
|
|
From figure ref(StackFig) we see that a stack has one location (the emi(top))
|
|
where items can be pushed onto and popped off the stack. This top element is
|
|
the stack's only immediately visible element. It may be accessed and modified
|
|
directly.
|
|
|
|
Bearing this model of the stack in mind, let's see what we formally can do
|
|
with the tt(stack) container. For the tt(stack), the following constructors,
|
|
operators, and member functions are available:
|
|
itemization(
|
|
it() hi(stack constructors) Constructors:
|
|
itemization(
|
|
it() The copy and move constructors are available;
|
|
it() A tt(stack) may be constructed empty:
|
|
verb(
|
|
stack<string> object;
|
|
)
|
|
)
|
|
it() Only the basic set of container operators are supported by the
|
|
tt(stack)
|
|
it() The following member functions are available for stacks:
|
|
itemization(
|
|
ithtq(empty)(bool empty())(this
|
|
member returns tt(true) if the stack contains no elements.)
|
|
ithtq(pop)(void pop())(removes the element at the top of
|
|
the stack. Note that the popped element is em(not) returned by this member,
|
|
and refer to section ref(QUEUE) for a discussion about the reason why tt(pop)
|
|
has return type tt(void).) Furthermore, it is the responsibility of the
|
|
stack's user to assure that tt(pop) is not called when the stack is empty. If
|
|
tt(pop) em(is) called for an empty stack, its internal administration breaks,
|
|
resulting, e.g., in a negative size (showing itself as a very large stacksize
|
|
due to its tt(size) member returning a tt(size_t), and other operations (like
|
|
tt(push)) fail and may crash your program. Of course, with a well designed
|
|
algorithm requests to pop from empty stacks do not occur (which is probably
|
|
why this implementation was used for the stack container).
|
|
ithtq(push)(void push(value))(places
|
|
tt(value) at the top of the stack, hiding the other elements from view.)
|
|
ithtq(size)(size_t size())(this
|
|
member returns the number of elements in the stack.)
|
|
ithtq(top)(Type &top())(this member
|
|
returns a reference to the stack's top (and only visible) element. It is the
|
|
i(responsibility of the programmer) to use this member only if the stack
|
|
is not empty.)
|
|
)
|
|
)
|
|
The stack does not support iterators or a subscript
|
|
operator. The only elements that can be accessed is its top element.
|
|
To empty a stack:
|
|
itemization(
|
|
it() repeatedly remove its front element;
|
|
it() assign an empty stack to it;
|
|
it() have its destructor called (e.g., by ending its lifetime).
|
|
)
|
|
)
|