qtools/qvector.doc

   1 /****************************************************************************
   2 **
   3 **
   4 ** QVector class documentation
   5 **
   6 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
   7 **
   8 ** This file is part of the Qt GUI Toolkit.
   9 **
  10 ** This file may be distributed under the terms of the Q Public License
  11 ** as defined by Trolltech AS of Norway and appearing in the file
  12 ** LICENSE.QPL included in the packaging of this file.
  13 **
  14 ** This file may be distributed and/or modified under the terms of the
  15 ** GNU General Public License version 2 as published by the Free Software
  16 ** Foundation and appearing in the file LICENSE.GPL included in the
  17 ** packaging of this file.
  18 **
  19 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
  20 ** licenses may use this file in accordance with the Qt Commercial License
  21 ** Agreement provided with the Software.
  22 **
  23 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  24 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  25 **
  26 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
  27 **   information about Qt Commercial License Agreements.
  28 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
  29 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
  30 **
  31 ** Contact info@trolltech.com if any conditions of this licensing are
  32 ** not clear to you.
  33 **
  34 **********************************************************************/
  35
  36
  37 /*****************************************************************************
  38   QVector documentation
  39  *****************************************************************************/
  40
  41 // BEING REVISED: ettrich
  42 /*!
  43   \class QVector qvector.h
  44
  45   \brief The QVector class is a template collection class that
  46   provides a vector (array).
  47
  48   \ingroup tools
  49
  50   QVector is implemented as a template class. Define a template
  51   instance QVector\<X\> to create a vector that contains pointers to
  52   X, or X*.
  53
  54   A vector is the same as an array. The main difference between
  55   QVector and QArray is that QVector stores pointers to the elements,
  56   while QArray stores the elements themselves (i.e. QArray is
  57   value-based).
  58
  59   Unless where otherwise stated, all functions that remove items from
  60   the vector will also delete the element pointed to if auto-deletion
  61   is enabled - see setAutoDelete(). By default, auto-deletion is
  62   disabled. This behaviour can be changed in a subclass by
  63   reimplementing the virtual method deleteItem().
  64
  65   Functions that compares items, e.g. find() and sort(), will do so
  66   using the virtual function compareItems(). The default
  67   implementation of this function will only compare the absolute
  68   pointer values. Reimplement compareItems() in a subclass to get
  69   searching and sorting based on the item contents.
  70
  71   \sa \link collection.html Collection Classes\endlink, QArray
  72 */
  73
  74 /*!
  75   \fn QVector::QVector()
  76
  77   Constructs a null vector.
  78
  79   \sa isNull()
  80 */
  81
  82 /*!
  83   \fn QVector::QVector( uint size )
  84
  85   Constructs an vector with room for \a size items.  Makes a null
  86   vector if \a size == 0.
  87
  88   All \a size positions in the vector are initialized to 0.
  89
  90   \sa size(), resize(), isNull()
  91 */
  92
  93 /*!
  94   \fn QVector::QVector( const QVector<type> &v )
  95
  96   Constructs a copy of \a v. Only the pointers are copied (i.e. shallow copy).
  97 */
  98
  99 /*!
 100   \fn QVector::~QVector()
 101
 102   Removes all items from the vector, and destroys the vector itself.
 103
 104   \sa clear()
 105 */
 106
 107 /*!
 108   \fn QVector<type> &QVector::operator=( const QVector<type> &v )
 109
 110   Assigns \a v to this vector and returns a reference to this vector.
 111
 112   This vector is first cleared, then all the items from \a v is copied
 113   into this vector. Only the pointers are copied (i.e. shallow copy).
 114
 115   \sa clear()
 116 */
 117
 118 /*!
 119   \fn type **QVector::data() const
 120   Returns a pointer to the actual vector data, which is an array of type*.
 121
 122   The vector is a null vector if data() == 0 (null pointer).
 123
 124   \sa isNull()
 125 */
 126
 127 /*!
 128   \fn uint QVector::size() const
 129
 130   Returns the size of the vector, i.e. the number of vector
 131   positions. This is also the maximum number of items the vector can
 132   hold.
 133
 134   The vector is a null vector if size() == 0.
 135
 136   \sa isNull(), resize(), count()
 137 */
 138
 139 /*!
 140   \fn uint QVector::count() const
 141
 142   Returns the number of items in the vector. The vector is empty if
 143   count() == 0.
 144
 145   \sa isEmpty(), size()
 146 */
 147
 148 /*!
 149   \fn bool QVector::isEmpty() const
 150
 151   Returns TRUE if the vector is empty, i.e. count() == 0, otherwise FALSE.
 152
 153   \sa count()
 154 */
 155
 156 /*!
 157   \fn bool QVector::isNull() const
 158
 159   Returns TRUE if the vector is null, otherwise FALSE.
 160
 161   A null vector has size() == 0 and data() == 0.
 162
 163   \sa size()
 164 */
 165
 166 /*!
 167   \fn bool QVector::resize( uint size )
 168   Resizes (expands or shrinks) the vector to \a size elements. The array
 169   becomes a null array if \a size == 0.
 170
 171   Any items in position \a size or beyond in the vector are removed.
 172   New positions are initialized 0.
 173
 174   Returns TRUE if successful, or FALSE if the memory cannot be allocated.
 175
 176   \sa size(), isNull()
 177 */
 178
 179 /*!
 180   \fn bool QVector::insert( uint i, const type *d )
 181
 182   Sets position \a i in the vector to contain the item \a d. \a i must
 183   be less than size(). Any previous element in position \a i is removed.
 184
 185   \sa at()
 186 */
 187
 188 /*!
 189   \fn bool QVector::remove( uint i )
 190
 191   Removes the item at position \a i in the vector, if there is one.
 192   \a i must be less than size().
 193
 194   Returns TRUE unless \a i is out of range.
 195
 196   \sa take(), at()
 197 */
 198
 199 /*!
 200   \fn type* QVector::take( uint i )
 201
 202   Returns the item at position \a i in the vector, and removes that
 203   item from the vector. \a i must be less than size(). If there is no
 204   item at position \a i, 0 is returned.
 205
 206   In contrast to remove(), this function does \e not call deleteItem()
 207   for the removed item.
 208
 209   \sa remove(), at()
 210 */
 211
 212 /*!
 213   \fn void QVector::clear()
 214
 215   Removes all items from the vector, and destroys the vector
 216   itself.
 217
 218   The vector becomes a null vector.
 219
 220   \sa isNull()
 221 */
 222
 223 /*!
 224   \fn bool QVector::fill( const type *d, int size )
 225
 226   Inserts item \a d in all positions in the vector. Any existing items
 227   are removed. If \a d is 0, the vector becomes empty.
 228
 229   If \a size >= 0, the vector is first resized to \a size. By default,
 230   \a size is -1.
 231
 232   Returns TRUE if successful, or FALSE if the memory cannot be allocated
 233   (only if a resize has been requested).
 234
 235   \sa resize(), insert(), isEmpty()
 236 */
 237
 238 /*!
 239   \fn void QVector::sort()
 240
 241   Sorts the items in ascending order. Any empty positions will be put
 242   last.
 243
 244   Compares items using the virtual function compareItems().
 245
 246   \sa bsearch()
 247 */
 248
 249 /*!
 250   \fn int QVector::bsearch( const type* d ) const
 251
 252   In a sorted array, finds the first occurrence of \a d using binary
 253   search. For a sorted array, this is generally much faster than
 254   find(), which does a linear search.
 255
 256   Returns the position of \a d, or -1 if \a d could not be found. \a d
 257   may not be 0.
 258
 259   Compares items using the virtual function compareItems().
 260
 261   \sa sort(), find()
 262 */
 263
 264
 265 /*!
 266   \fn int QVector::findRef( const type *d, uint i ) const
 267
 268   Finds the first occurrence of the item pointer \a d in the vector,
 269   using linear search. The search starts at position \a i, which must
 270   be less than size(). \a i is by default 0; i.e. the search starts at
 271   the start of the vector.
 272
 273   Returns the position of \a d, or -1 if \a d could not be found.
 274
 275   This function does \e not use compareItems() to compare items.
 276
 277   \sa find(), bsearch()
 278 */
 279
 280 /*!
 281   \fn int QVector::find( const type *d, uint i ) const
 282
 283   Finds the first occurrence of item \a d in the vector, using linear
 284   search. The search starts at position \a i, which must be less than
 285   size(). \a i is by default 0; i.e. the search starts at the start of
 286   the vector.
 287
 288   Returns the position of \e v, or -1 if \e v could not be found.
 289
 290   Compares items using the virtual function compareItems().
 291
 292   \sa findRef(), bsearch()
 293 */
 294
 295
 296 /*!
 297   \fn uint QVector::containsRef( const type *d ) const
 298
 299   Returns the number of occurrences of the item pointer \a d in the
 300   vector.
 301
 302   This function does \e not use compareItems() to compare items.
 303
 304   \sa findRef()
 305 */
 306
 307 /*!
 308   \fn uint QVector::contains( const type *d ) const
 309
 310   Returns the number of occurrences of item \a d in the vector.
 311
 312   Compares items using the virtual function compareItems().
 313
 314   \sa containsRef()
 315 */
 316
 317 /*!
 318   \fn type *QVector::operator[]( int i ) const
 319
 320   Returns the item at position \a i, or 0 if there is no item at
 321   that position. \a i must be less than size().
 322
 323   Equivalent to at( \a i ).
 324
 325   \sa at()
 326 */
 327
 328 /*!
 329   \fn type *QVector::at( uint i ) const
 330
 331   Returns the item at position \a i, or 0 if there is no item at
 332   that position. \a i must be less than size().
 333 */
 334
 335
 336 /*!
 337   \fn void QVector::toList( QGList *list ) const
 338
 339   Copies all items in this vector to the list \a list. First, \a list
 340   is cleared, then all items are appended to \a list.
 341
 342   \sa QList, QStack, QQueue
 343 */
 344