source: trunk/doc/src/q3ptrvector.qdoc@ 321

Last change on this file since 321 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 11.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
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/*!