diff options
Diffstat (limited to 'doc/tqptrvector.doc')
| -rw-r--r-- | doc/tqptrvector.doc | 431 |
1 files changed, 431 insertions, 0 deletions
diff --git a/doc/tqptrvector.doc b/doc/tqptrvector.doc new file mode 100644 index 00000000..abc4be39 --- /dev/null +++ b/doc/tqptrvector.doc @@ -0,0 +1,431 @@ +/**************************************************************************** +** +** TQPtrVector 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. +** +**********************************************************************/ + + +/***************************************************************************** + TQPtrVector documentation + *****************************************************************************/ + +/*! + \class TQPtrVector tqptrvector.h + \brief The TQPtrVector class is a template collection class that + provides a vector (array). + + \ingroup tools + + \important autoDelete setAutoDelete + + TQValueVector is an STL-compatible alternative to this class. + + TQPtrVector is implemented as a template class. Defines a template + instance TQPtrVector\<X\> to create a vector that contains pointers + to X (X*). + + A vector is the same as an array. The main difference between + TQPtrVector and QMemArray is that TQPtrVector stores pointers to the + elements, whereas QMemArray stores the elements themselves (i.e. + QMemArray is value-based and TQPtrVector is pointer-based). + + Items are added to the vector using insert() or fill(). Items are + removed with remove(). You can get a pointer to an item at a + particular index position using at(). + + Unless otherwise stated, all functions that remove items from the + vector will also delete the element pointed to if \link + setAutoDelete() auto-deletion\endlink is enabled. By default, + auto-deletion is disabled; see setAutoDelete(). This behaviour can + be changed in a subclass by reimplementing the virtual function + deleteItem(). + + Functions that compare items (find() and sort() for example) will + do so using the virtual function compareItems(). The default + implementation of this function only compares the pointer values. + Reimplement compareItems() in a subclass to get searching and + sorting based on the item contents. You can perform a linear + search for a pointer in the vector using findRef(), or a binary + search (of a sorted vector) using bsearch(). You can count the + number of times an item appears in the vector with contains() or + containsRef(). + + \sa QMemArray +*/ + +/*! + \fn TQPtrVector::TQPtrVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn TQPtrVector::TQPtrVector( uint size ) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn TQPtrVector::TQPtrVector( const TQPtrVector<type> &v ) + + Constructs a copy of \a v. Only the pointers are copied (i.e. + shallow copy). +*/ + +/*! + \fn TQPtrVector::~TQPtrVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn TQPtrVector<type> &TQPtrVector::operator=( const TQPtrVector<type> &v ) + + Assigns \a v to this vector and returns a reference to this + vector. + + This vector is first cleared and then all the items from \a v are + copied into the vector. Only the pointers are copied (i.e. shallow + copy). + + \sa clear() +*/ + +/*! + \fn type **TQPtrVector::data() const + + Returns a pointer to the actual vector data, which is an array of + type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint TQPtrVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint TQPtrVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size(), isNull() +*/ + +/*! + \fn bool TQPtrVector::isEmpty() const + + Returns TRUE if the vector is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool TQPtrVector::isNull() const + + Returns TRUE if the vector is null; otherwise returns FALSE. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool TQPtrVector::resize( uint size ) + + Resizes (expands or shrinks) the vector to \a size elements. The + vector becomes a null vector if \a size == 0. + + Any items at position \a size or beyond in the vector are removed. + New positions are initialized to 0. + + Returns TRUE if successful, i.e. if the memory was successfully + allocated; otherwise returns FALSE. + + \sa size(), isNull() +*/ + +/*! + \fn bool TQPtrVector::insert( uint i, const type *d ) + + Sets position \a i in the vector to contain the item \a d. \a i + must be less than size(). Any previous element in position \a i is + removed. + + \sa at() +*/ + +/*! + \fn bool TQPtrVector::remove( uint i ) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns TRUE if \a i is within range; otherwise returns FALSE. + + \sa take(), at() +*/ + +/*! + \fn type* TQPtrVector::take( uint i ) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is + no item at position \a i, 0 is returned. + + Unlike remove(), this function does \e not call deleteItem() for + the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void TQPtrVector::clear() + + Removes all items from the vector, and destroys the vector itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool TQPtrVector::fill( const type *d, int size ) + + Inserts item \a d in all positions in the vector. Any existing + items are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By + default, \a size is -1. + + Returns TRUE if successful, i.e. \a size is the same as the + current size, or \a size is larger and the memory has successfully + been allocated; otherwise returns FALSE. + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void TQPtrVector::sort() + + Sorts the items in ascending order. Any empty positions will be + put last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int TQPtrVector::bsearch( const type* d ) const + + In a sorted array, finds the first occurrence of \a d using a + binary search. For a sorted array, this is generally much faster + than find(), which performs a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a + d must not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int TQPtrVector::findRef( const type *d, uint i ) const + + Finds the first occurrence of the item pointer \a d in the vector + using a linear search. The search starts at position \a i, which + must be less than size(). \a i is by default 0; i.e. the search + starts at the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + Use the much faster bsearch() to search a sorted vector. + + \sa find(), bsearch() +*/ + +/*! + \fn int TQPtrVector::find( const type *d, uint i ) const + + Finds the first occurrence of item \a d in the vector using a + linear search. The search starts at position \a i, which must be + less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + Compares items using the virtual function compareItems(). + + Use the much faster bsearch() to search a sorted vector. + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint TQPtrVector::containsRef( const type *d ) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint TQPtrVector::contains( const type *d ) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *TQPtrVector::operator[]( int i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at( \a i ). + + \sa at() +*/ + +/*! + \fn type *TQPtrVector::at( uint i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void TQPtrVector::toList( QGList *list ) const + + \internal + + Copies all items in this vector to the list \a list. \a list is + first cleared and then all items are appended to \a list. + + \sa TQPtrList, TQPtrStack, TQPtrQueue +*/ + +/*! + \fn int TQPtrVector::compareItems( TQPtrCollection::Item d1, + TQPtrCollection::Item d2 ) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a d1 == \a d2 + \i nonzero if \a d1 != \a d2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return one of three values and use it to + sort by: + \list + \i 0 if \a d1 == \a d2 + \i \> 0 (positive integer) if \a d1 \> \a d2 + \i \< 0 (negative integer) if \a d1 \< \a d2 + \endlist + + The sort() and bsearch() functions require compareItems() to be + implemented as described here. + + This function should not modify the vector because some const + functions call compareItems(). +*/ + +/*! + \fn QDataStream& TQPtrVector::read( QDataStream &s, + TQPtrCollection::Item &item ) + + Reads a vector item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& TQPtrVector::write( QDataStream &s, + TQPtrCollection::Item item ) const + + Writes a vector item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! + \fn bool TQPtrVector::operator==( const TQPtrVector<type> &v ) const + + Returns TRUE if this vector and \a v are equal; otherwise returns + FALSE. +*/ + |