From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/qvaluestack.doc | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 doc/qvaluestack.doc (limited to 'doc/qvaluestack.doc') diff --git a/doc/qvaluestack.doc b/doc/qvaluestack.doc new file mode 100644 index 0000000..8fa7b77 --- /dev/null +++ b/doc/qvaluestack.doc @@ -0,0 +1,169 @@ +/**************************************************************************** +** +** QValueStack class documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt 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 Qt 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. +** +**********************************************************************/ + + +/***************************************************************************** + QValueStack documentation + *****************************************************************************/ + +/*! + \class QValueStack qvaluestack.h + \brief The QValueStack class is a value-based template class that provides a stack. + + \ingroup qtl + \ingroup tools + \ingroup shared + \mainclass + \reentrant + + Define a template instance QValueStack\ to create a stack of + values that all have the class X. QValueStack is part of the \link + qtl.html Qt Template Library\endlink. + + Note that QValueStack 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 + QValueStack 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 + + QValueStack is a specialized QValueList provided for convenience. + All of QValueList's functionality also applies to QPtrStack, for + example the facility to iterate over all elements using + QValueStack::Iterator. See QValueListIterator for further + details. + + Some classes cannot be used within a QValueStack, for example + everything derived from QObject and thus all classes that + implement widgets. Only values can be used in a QValueStack. 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 QValueStack::QValueStack() + + Constructs an empty stack. +*/ + +/*! + \fn QValueStack::~QValueStack() + + Destroys the stack. References to the values in the stack and all + iterators of this stack become invalidated. Because QValueStack 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 QValueStack::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& QValueStack::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(), QValueList::fromLast() +*/ + + +/*! + \fn const T& QValueStack::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(), QValueList::fromLast() +*/ + +/*! + \fn T QValueStack::pop() + + Removes the top item from the stack and returns it. + + \sa top() push() +*/ + + + + + -- cgit v1.2.1