diff options
Diffstat (limited to 'doc/tqvaluestack.doc')
| -rw-r--r-- | doc/tqvaluestack.doc | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/doc/tqvaluestack.doc b/doc/tqvaluestack.doc new file mode 100644 index 000000000..39f9f07ac --- /dev/null +++ b/doc/tqvaluestack.doc @@ -0,0 +1,169 @@ +/**************************************************************************** +** +** TQValueStack class documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the TQt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free TQt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing requirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + + +/***************************************************************************** + TQValueStack documentation + *****************************************************************************/ + +/*! + \class TQValueStack tqvaluestack.h + \brief The TQValueStack class is a value-based template class that provides a stack. + + \ingroup qtl + \ingroup tools + \ingroup shared + \mainclass + \reentrant + + Define a template instance TQValueStack\<X\> to create a stack of + values that all have the class X. TQValueStack is part of the \link + ntqtl.html TQt Template Library\endlink. + + Note that TQValueStack does not store pointers to the members of + the stack; it holds a copy of every member. That is why these + kinds of classes are called "value based"; QPtrStack, QPtrList, + QDict, etc., are "pointer based". + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). The top() function provides access to the topmost item + without removing it. + + Example: + \code + TQValueStack<int> stack; + stack.push( 1 ); + stack.push( 2 ); + stack.push( 3 ); + while ( ! stack.isEmpty() ) + cout << "Item: " << stack.pop() << endl; + + // Output: + // Item: 3 + // Item: 2 + // Item: 1 + \endcode + + TQValueStack is a specialized TQValueList provided for convenience. + All of TQValueList's functionality also applies to QPtrStack, for + example the facility to iterate over all elements using + TQValueStack<T>::Iterator. See TQValueListIterator for further + details. + + Some classes cannot be used within a TQValueStack, for example + everything derived from TQObject and thus all classes that + implement widgets. Only values can be used in a TQValueStack. To + qualify as a value, the class must provide + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. +*/ + + +/*! + \fn TQValueStack::TQValueStack() + + Constructs an empty stack. +*/ + +/*! + \fn TQValueStack::~TQValueStack() + + Destroys the stack. References to the values in the stack and all + iterators of this stack become invalidated. Because TQValueStack is + highly tuned for performance, you won't see warnings if you use + invalid iterators because it is impossible for an iterator to + check whether or not it is valid. +*/ + + +/*! + \fn void TQValueStack::push( const T& d ) + + Adds element, \a d, to the top of the stack. Last in, first out. + + This function is equivalent to append(). + + \sa pop(), top() +*/ + +/*! + \fn T& TQValueStack::top() + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. Note that you must not + change the value the end() iterator points to. + + This function is equivalent to last(). + + \sa pop(), push(), TQValueList::fromLast() +*/ + + +/*! + \fn const T& TQValueStack::top() const + + \overload + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. + + This function is equivalent to last(). + + \sa pop(), push(), TQValueList::fromLast() +*/ + +/*! + \fn T TQValueStack::pop() + + Removes the top item from the stack and returns it. + + \sa top() push() +*/ + + + + + |