1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43   \class Q3PtrVector

    44   \brief The Q3PtrVector class is a template collection class that

    45   provides a vector (array).

    46   \compat

    47 

    48   Q3ValueVector is an STL-compatible alternative to this class.

    49 

    50   Q3PtrVector is implemented as a template class. Defines a template

    51   instance Q3PtrVector\<X\> to create a vector that contains pointers

    52   to X (X*).

    53 

    54   A vector is the same as an array. The main difference between

    55   Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the

    56   elements, whereas Q3MemArray stores the elements themselves (i.e.

    57   Q3MemArray is value-based and Q3PtrVector is pointer-based).

    58 

    59   Items are added to the vector using insert() or fill(). Items are

    60   removed with remove(). You can get a pointer to an item at a

    61   particular index position using at().

    62 

    63   Unless otherwise stated, all functions that remove items from the

    64   vector will also delete the element pointed to if \link

    65   setAutoDelete() auto-deletion\endlink is enabled. By default,

    66   auto-deletion is disabled; see setAutoDelete(). This behavior can

    67   be changed in a subclass by reimplementing the virtual function

    68   deleteItem().

    69 

    70   Functions that compare items (find() and sort() for example) will

    71   do so using the virtual function compareItems(). The default

    72   implementation of this function only compares the pointer values.

    73   Reimplement compareItems() in a subclass to get searching and

    74   sorting based on the item contents. You can perform a linear

    75   search for a pointer in the vector using findRef(), or a binary

    76   search (of a sorted vector) using bsearch(). You can count the

    77   number of times an item appears in the vector with contains() or

    78   containsRef().

    79 

    80   \sa Q3MemArray

    81 */

    82 

    83 /*!

    84   \fn Q3PtrVector::Q3PtrVector()

    85 

    86   Constructs a null vector.

    87 

    88   \sa isNull()

    89 */

    90 

    91 /*!

    92   \fn Q3PtrVector::Q3PtrVector(uint size)

    93 

    94   Constructs an vector with room for \a size items. Makes a null

    95   vector if \a size == 0.

    96 

    97   All \a size positions in the vector are initialized to 0.

    98 

    99   \sa size(), resize(), isNull()

   100 */

   101 

   102 /*!

   103   \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector<type> &v)

   104 

   105   Constructs a copy of \a v. Only the pointers are copied (i.e.

   106   shallow copy).

   107 */

   108 

   109 /*!

   110   \fn Q3PtrVector::~Q3PtrVector()

   111 

   112   Removes all items from the vector, and destroys the vector itself.

   113 

   114   \sa clear()

   115 */

   116 

   117 /*!

   118   \fn Q3PtrVector<type> &Q3PtrVector::operator=(const Q3PtrVector<type> &v)

   119 

   120   Assigns \a v to this vector and returns a reference to this

   121   vector.

   122 

   123   This vector is first cleared and then all the items from \a v are

   124   copied into the vector. Only the pointers are copied (i.e. shallow

   125   copy).

   126 

   127   \sa clear()

   128 */

   129 

   130 /*!

   131   \fn type **Q3PtrVector::data() const

   132 

   133   Returns a pointer to the actual vector data, which is an array of

   134   type*.

   135 

   136   The vector is a null vector if data() == 0 (null pointer).

   137 

   138   \sa isNull()

   139 */

   140 

   141 /*!

   142   \fn uint Q3PtrVector::size() const

   143 

   144   Returns the size of the vector, i.e. the number of vector

   145   positions. This is also the maximum number of items the vector can

   146   hold.

   147 

   148   The vector is a null vector if size() == 0.

   149 

   150   \sa isNull(), resize(), count()

   151 */

   152 

   153 /*!

   154   \fn uint Q3PtrVector::count() const 

   155 

   156   Returns the number of items in the vector. The vector is empty if

   157   count() == 0.

   158 

   159   \sa isEmpty(), size(), isNull()

   160 */

   161 

   162 /*!

   163   \fn bool Q3PtrVector::isEmpty() const

   164 

   165   Returns true if the vector is empty; otherwise returns false.

   166 

   167   \sa count()

   168 */

   169 

   170 /*!

   171   \fn bool Q3PtrVector::isNull() const

   172 

   173   Returns true if the vector is null; otherwise returns false.

   174 

   175   A null vector has size() == 0 and data() == 0.

   176 

   177   \sa size()

   178 */

   179 

   180 /*!

   181   \fn bool Q3PtrVector::resize(uint size)

   182 

   183   Resizes (expands or shrinks) the vector to \a size elements. The

   184   vector becomes a null vector if \a size == 0.

   185 

   186   Any items at position \a size or beyond in the vector are removed.

   187   New positions are initialized to 0.

   188 

   189   Returns true if successful, i.e. if the memory was successfully

   190   allocated; otherwise returns false.

   191 

   192   \sa size(), isNull()

   193 */

   194 

   195 /*!

   196   \fn bool Q3PtrVector::insert(uint i, const type *d)

   197 

   198   Sets position \a i in the vector to contain the item \a d. \a i

   199   must be less than size(). Any previous element in position \a i is

   200   removed.

   201 

   202   Returns true if \a i is within range; otherwise returns false.

   203 

   204   \sa at()

   205 */

   206 

   207 /*!

   208   \fn bool Q3PtrVector::remove(uint i)

   209 

   210   Removes the item at position \a i in the vector, if there is one.

   211   \a i must be less than size().

   212 

   213   Returns true if \a i is within range; otherwise returns false.

   214 

   215   \sa take(), at()

   216 */

   217 

   218 /*!

   219   \fn type* Q3PtrVector::take(uint i)

   220 

   221   Returns the item at position \a i in the vector, and removes that

   222   item from the vector. \a i must be less than size(). If there is

   223   no item at position \a i, 0 is returned.

   224 

   225   Unlike remove(), this function does \e not call deleteItem() for

   226   the removed item.

   227 

   228   \sa remove(), at()

   229 */

   230 

   231 /*!

   232   \fn void Q3PtrVector::clear()

   233 

   234   Removes all items from the vector, and destroys the vector itself.

   235 

   236   The vector becomes a null vector.

   237 

   238   \sa isNull()

   239 */

   240 

   241 /*!

   242   \fn bool Q3PtrVector::fill(const type *d, int size)

   243 

   244   Inserts item \a d in all positions in the vector. Any existing

   245   items are removed. If \a d is 0, the vector becomes empty.

   246 

   247   If \a size >= 0, the vector is first resized to \a size. By

   248   default, \a size is -1.

   249 

   250   Returns true if successful, i.e. \a size is the same as the

   251   current size, or \a size is larger and the memory has successfully

   252   been allocated; otherwise returns false.

   253 

   254   \sa resize(), insert(), isEmpty()

   255 */

   256 

   257 /*!

   258   \fn void Q3PtrVector::sort()

   259 

   260   Sorts the items in ascending order. Any empty positions will be

   261   put last.

   262 

   263   Compares items using the virtual function compareItems().

   264 

   265   \sa bsearch()

   266 */

   267 

   268 /*!

   269   \fn int Q3PtrVector::bsearch(const type* d) const

   270 

   271   In a sorted array, finds the first occurrence of \a d using a

   272   binary search. For a sorted array, this is generally much faster

   273   than find(), which performs a linear search.

   274 

   275   Returns the position of \a d, or -1 if \a d could not be found. \a

   276   d must not be 0.

   277 

   278   Compares items using the virtual function compareItems().

   279 

   280   \sa sort(), find()

   281 */

   282 

   283 

   284 /*!

   285   \fn int Q3PtrVector::findRef(const type *d, uint i) const

   286 

   287   Finds the first occurrence of the item pointer \a d in the vector

   288   using a linear search. The search starts at position \a i, which

   289   must be less than size(). \a i is by default 0; i.e. the search

   290   starts at the start of the vector.

   291 

   292   Returns the position of \a d, or -1 if \a d could not be found.

   293 

   294   This function does \e not use compareItems() to compare items.

   295 

   296   Use the much faster bsearch() to search a sorted vector.

   297 

   298   \sa find(), bsearch()

   299 */

   300 

   301 /*!

   302   \fn int Q3PtrVector::find(const type *d, uint i) const

   303 

   304   Finds the first occurrence of item \a d in the vector using a

   305   linear search. The search starts at position \a i, which must be

   306   less than size(). \a i is by default 0; i.e. the search starts at

   307   the start of the vector.

   308 

   309   Returns the position of \a d, or -1 if \a d could not be found.

   310 

   311   Compares items using the virtual function compareItems().

   312 

   313   Use the much faster bsearch() to search a sorted vector.

   314 

   315   \sa findRef(), bsearch()

   316 */

   317 

   318 

   319 /*!

   320   \fn uint Q3PtrVector::containsRef(const type *d) const

   321 

   322   Returns the number of occurrences of the item pointer \a d in the

   323   vector.

   324 

   325   This function does \e not use compareItems() to compare items.

   326 

   327   \sa findRef()

   328 */

   329 

   330 /*!

   331   \fn uint Q3PtrVector::contains(const type *d) const

   332 

   333   Returns the number of occurrences of item \a d in the vector.

   334 

   335   Compares items using the virtual function compareItems().

   336 

   337   \sa containsRef()

   338 */

   339 

   340 /*!

   341   \fn type *Q3PtrVector::operator[](int i) const

   342 

   343   Returns the item at position \a i, or 0 if there is no item at

   344   that position. \a i must be less than size().

   345 

   346   Equivalent to at(\a i).

   347 

   348   \sa at()

   349 */

   350 

   351 /*!

   352   \fn type *Q3PtrVector::at(uint i) const

   353 

   354   Returns the item at position \a i, or 0 if there is no item at

   355   that position. \a i must be less than size().

   356 */

   357 

   358 

   359 /*!

   360   \fn void Q3PtrVector::toList(Q3GList *list) const

   361 

   362   \internal

   363 

   364   Copies all items in this vector to the list \a list. \a list is

   365   first cleared and then all items are appended to \a list.

   366 

   367   \sa Q3PtrList, Q3PtrStack, Q3PtrQueue

   368 */

   369 

   370 /*!

   371   \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1,

   372 				    Q3PtrCollection::Item d2)

   373 

   374   This virtual function compares two list items.

   375 

   376   Returns:

   377   \list

   378   \i zero if \a d1 == \a d2

   379   \i nonzero if \a d1 != \a d2

   380   \endlist

   381 

   382   This function returns \e int rather than \e bool so that

   383   reimplementations can return one of three values and use it to

   384   sort by:

   385   \list

   386   \i 0 if \a d1 == \a d2

   387   \i \> 0 (positive integer) if \a d1 \> \a d2

   388   \i \< 0 (negative integer) if \a d1 \< \a d2

   389   \endlist

   390 

   391   The sort() and bsearch() functions require compareItems() to be

   392   implemented as described here.

   393 

   394   This function should not modify the vector because some const

   395   functions call compareItems().

   396 */

   397 

   398 /*!

   399   \fn QDataStream& Q3PtrVector::read(QDataStream &s,

   400 				     Q3PtrCollection::Item &item)

   401 

   402   Reads a vector item, \a item, from the stream \a s and returns a

   403   reference to the stream.

   404 

   405   The default implementation sets \a item to 0.

   406 

   407   \sa write()

   408 */

   409 

   410 /*!

   411   \fn QDataStream& Q3PtrVector::write(QDataStream &s,

   412 			 	      Q3PtrCollection::Item item) const

   413 

   414   Writes a vector item, \a item, to the stream \a s and returns a

   415   reference to the stream.

   416 

   417   The default implementation does nothing.

   418 

   419   \sa read()

   420 */

   421   

   422 /*!

   423   \fn bool Q3PtrVector::operator==(const Q3PtrVector<type> &v) const

   424 

   425   Returns true if this vector and \a v are equal; otherwise returns

   426   false.

   427 */