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