|
Packit |
1c1d7e |
/****************************************************************************
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** QVector class documentation
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** This file is part of the Qt GUI Toolkit.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** This file may be distributed under the terms of the Q Public License
|
|
Packit |
1c1d7e |
** as defined by Trolltech AS of Norway and appearing in the file
|
|
Packit |
1c1d7e |
** LICENSE.QPL included in the packaging of this file.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** This file may be distributed and/or modified under the terms of the
|
|
Packit |
1c1d7e |
** GNU General Public License version 2 as published by the Free Software
|
|
Packit |
1c1d7e |
** Foundation and appearing in the file LICENSE.GPL included in the
|
|
Packit |
1c1d7e |
** packaging of this file.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
|
|
Packit |
1c1d7e |
** licenses may use this file in accordance with the Qt Commercial License
|
|
Packit |
1c1d7e |
** Agreement provided with the Software.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
|
|
Packit |
1c1d7e |
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
|
|
Packit |
1c1d7e |
** information about Qt Commercial License Agreements.
|
|
Packit |
1c1d7e |
** See http://www.trolltech.com/qpl/ for QPL licensing information.
|
|
Packit |
1c1d7e |
** See http://www.trolltech.com/gpl/ for GPL licensing information.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
** Contact info@trolltech.com if any conditions of this licensing are
|
|
Packit |
1c1d7e |
** not clear to you.
|
|
Packit |
1c1d7e |
**
|
|
Packit |
1c1d7e |
**********************************************************************/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*****************************************************************************
|
|
Packit |
1c1d7e |
QVector documentation
|
|
Packit |
1c1d7e |
*****************************************************************************/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
// BEING REVISED: ettrich
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\class QVector qvector.h
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\brief The QVector class is a template collection class that
|
|
Packit |
1c1d7e |
provides a vector (array).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\ingroup tools
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
QVector is implemented as a template class. Define a template
|
|
Packit |
1c1d7e |
instance QVector\<X\> to create a vector that contains pointers to
|
|
Packit |
1c1d7e |
X, or X*.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A vector is the same as an array. The main difference between
|
|
Packit |
1c1d7e |
QVector and QArray is that QVector stores pointers to the elements,
|
|
Packit |
1c1d7e |
while QArray stores the elements themselves (i.e. QArray is
|
|
Packit |
1c1d7e |
value-based).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Unless where otherwise stated, all functions that remove items from
|
|
Packit |
1c1d7e |
the vector will also delete the element pointed to if auto-deletion
|
|
Packit |
1c1d7e |
is enabled - see setAutoDelete(). By default, auto-deletion is
|
|
Packit |
1c1d7e |
disabled. This behaviour can be changed in a subclass by
|
|
Packit |
1c1d7e |
reimplementing the virtual method deleteItem().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Functions that compares items, e.g. find() and sort(), will do so
|
|
Packit |
1c1d7e |
using the virtual function compareItems(). The default
|
|
Packit |
1c1d7e |
implementation of this function will only compare the absolute
|
|
Packit |
1c1d7e |
pointer values. Reimplement compareItems() in a subclass to get
|
|
Packit |
1c1d7e |
searching and sorting based on the item contents.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa \link collection.html Collection Classes\endlink, QArray
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn QVector::QVector()
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Constructs a null vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa isNull()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn QVector::QVector( uint size )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Constructs an vector with room for \a size items. Makes a null
|
|
Packit |
1c1d7e |
vector if \a size == 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
All \a size positions in the vector are initialized to 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa size(), resize(), isNull()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn QVector::QVector( const QVector<type> &v )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Constructs a copy of \a v. Only the pointers are copied (i.e. shallow copy).
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn QVector::~QVector()
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Removes all items from the vector, and destroys the vector itself.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa clear()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn QVector<type> &QVector::operator=( const QVector<type> &v )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Assigns \a v to this vector and returns a reference to this vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
This vector is first cleared, then all the items from \a v is copied
|
|
Packit |
1c1d7e |
into this vector. Only the pointers are copied (i.e. shallow copy).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa clear()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn type **QVector::data() const
|
|
Packit |
1c1d7e |
Returns a pointer to the actual vector data, which is an array of type*.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The vector is a null vector if data() == 0 (null pointer).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa isNull()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn uint QVector::size() const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the size of the vector, i.e. the number of vector
|
|
Packit |
1c1d7e |
positions. This is also the maximum number of items the vector can
|
|
Packit |
1c1d7e |
hold.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The vector is a null vector if size() == 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa isNull(), resize(), count()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn uint QVector::count() const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the number of items in the vector. The vector is empty if
|
|
Packit |
1c1d7e |
count() == 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa isEmpty(), size()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::isEmpty() const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns TRUE if the vector is empty, i.e. count() == 0, otherwise FALSE.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa count()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::isNull() const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns TRUE if the vector is null, otherwise FALSE.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A null vector has size() == 0 and data() == 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa size()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::resize( uint size )
|
|
Packit |
1c1d7e |
Resizes (expands or shrinks) the vector to \a size elements. The array
|
|
Packit |
1c1d7e |
becomes a null array if \a size == 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Any items in position \a size or beyond in the vector are removed.
|
|
Packit |
1c1d7e |
New positions are initialized 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns TRUE if successful, or FALSE if the memory cannot be allocated.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa size(), isNull()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::insert( uint i, const type *d )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Sets position \a i in the vector to contain the item \a d. \a i must
|
|
Packit |
1c1d7e |
be less than size(). Any previous element in position \a i is removed.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa at()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::remove( uint i )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Removes the item at position \a i in the vector, if there is one.
|
|
Packit |
1c1d7e |
\a i must be less than size().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns TRUE unless \a i is out of range.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa take(), at()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn type* QVector::take( uint i )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the item at position \a i in the vector, and removes that
|
|
Packit |
1c1d7e |
item from the vector. \a i must be less than size(). If there is no
|
|
Packit |
1c1d7e |
item at position \a i, 0 is returned.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
In contrast to remove(), this function does \e not call deleteItem()
|
|
Packit |
1c1d7e |
for the removed item.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa remove(), at()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn void QVector::clear()
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Removes all items from the vector, and destroys the vector
|
|
Packit |
1c1d7e |
itself.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The vector becomes a null vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa isNull()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn bool QVector::fill( const type *d, int size )
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Inserts item \a d in all positions in the vector. Any existing items
|
|
Packit |
1c1d7e |
are removed. If \a d is 0, the vector becomes empty.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If \a size >= 0, the vector is first resized to \a size. By default,
|
|
Packit |
1c1d7e |
\a size is -1.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns TRUE if successful, or FALSE if the memory cannot be allocated
|
|
Packit |
1c1d7e |
(only if a resize has been requested).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa resize(), insert(), isEmpty()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn void QVector::sort()
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Sorts the items in ascending order. Any empty positions will be put
|
|
Packit |
1c1d7e |
last.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Compares items using the virtual function compareItems().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa bsearch()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn int QVector::bsearch( const type* d ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
In a sorted array, finds the first occurrence of \a d using binary
|
|
Packit |
1c1d7e |
search. For a sorted array, this is generally much faster than
|
|
Packit |
1c1d7e |
find(), which does a linear search.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the position of \a d, or -1 if \a d could not be found. \a d
|
|
Packit |
1c1d7e |
may not be 0.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Compares items using the virtual function compareItems().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa sort(), find()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn int QVector::findRef( const type *d, uint i ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Finds the first occurrence of the item pointer \a d in the vector,
|
|
Packit |
1c1d7e |
using linear search. The search starts at position \a i, which must
|
|
Packit |
1c1d7e |
be less than size(). \a i is by default 0; i.e. the search starts at
|
|
Packit |
1c1d7e |
the start of the vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the position of \a d, or -1 if \a d could not be found.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
This function does \e not use compareItems() to compare items.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa find(), bsearch()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn int QVector::find( const type *d, uint i ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Finds the first occurrence of item \a d in the vector, using linear
|
|
Packit |
1c1d7e |
search. The search starts at position \a i, which must be less than
|
|
Packit |
1c1d7e |
size(). \a i is by default 0; i.e. the search starts at the start of
|
|
Packit |
1c1d7e |
the vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the position of \e v, or -1 if \e v could not be found.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Compares items using the virtual function compareItems().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa findRef(), bsearch()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn uint QVector::containsRef( const type *d ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the number of occurrences of the item pointer \a d in the
|
|
Packit |
1c1d7e |
vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
This function does \e not use compareItems() to compare items.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa findRef()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn uint QVector::contains( const type *d ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the number of occurrences of item \a d in the vector.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Compares items using the virtual function compareItems().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa containsRef()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn type *QVector::operator[]( int i ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the item at position \a i, or 0 if there is no item at
|
|
Packit |
1c1d7e |
that position. \a i must be less than size().
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Equivalent to at( \a i ).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa at()
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn type *QVector::at( uint i ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Returns the item at position \a i, or 0 if there is no item at
|
|
Packit |
1c1d7e |
that position. \a i must be less than size().
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
\fn void QVector::toList( QGList *list ) const
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Copies all items in this vector to the list \a list. First, \a list
|
|
Packit |
1c1d7e |
is cleared, then all items are appended to \a list.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\sa QList, QStack, QQueue
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|