source: trunk/src/qt3support/tools/q3ptrstack.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
  • Property svn:eol-style set to native
File size: 5.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \class Q3PtrStack
30 \brief The Q3PtrStack class is a template class that provides a stack.
31 \compat
32
33 Q3ValueStack is an STL-compatible alternative to this class.
34
35 Define a template instance Q3PtrStack\<X\> to create a stack that
36 operates on pointers to X, (X*).
37
38 A stack is a last in, first out (LIFO) structure. Items are added
39 to the top of the stack with push() and retrieved from the top
40 with pop(). Use top() to get a reference to the top element
41 without changing the stack.
42
43 You can control the stack's deletion policy with setAutoDelete().
44
45 For compatibility with the Q3PtrCollection classes current() and
46 remove() are provided; they both operate on the top().
47
48 \sa Q3PtrList Q3PtrQueue
49*/
50
51/*!
52 \fn Q3PtrStack::Q3PtrStack ()
53
54 Creates an empty stack.
55*/
56
57/*!
58 \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack<type>& s)
59
60 Creates a stack by making a shallow copy of another stack \a s.
61*/
62
63/*!
64 \fn Q3PtrStack::~Q3PtrStack ()
65
66 Destroys the stack. All items will be deleted if autoDelete() is
67 true.
68*/
69
70/*!
71 \fn Q3PtrStack<type>& Q3PtrStack::operator= (const Q3PtrStack<type>& s)
72
73 Sets the contents of this stack by making a shallow copy of
74 another stack \a s. Elements currently in this stack will be
75 deleted if autoDelete() is true.
76*/
77
78/*!
79 \fn bool Q3PtrStack::isEmpty () const
80
81 Returns true if the stack contains no elements; otherwise returns
82 false.
83*/
84
85/*!
86 \fn void Q3PtrStack::push (const type* d)
87
88 Adds an element \a d to the top of the stack. Last in, first out.
89*/
90
91/*!
92 \fn type* Q3PtrStack::pop ()
93
94 Removes the top item from the stack and returns it. The stack must
95 not be empty.
96*/
97
98/*!
99 \fn bool Q3PtrStack::remove ()
100
101 Removes the top item from the stack and deletes it if autoDelete()
102 is true. Returns true if there was an item to pop; otherwise
103 returns false.
104
105 \sa clear()
106*/
107
108/*!
109 \fn void Q3PtrStack::clear()
110
111 Removes all items from the stack, deleting them if autoDelete() is
112 true.
113
114 \sa remove()
115*/
116
117/*!
118 \fn uint Q3PtrStack::count() const
119
120 Returns the number of items in the stack.
121
122 \sa isEmpty()
123*/
124
125/*!
126 \fn type* Q3PtrStack::top () const
127
128 Returns a pointer to the top item on the stack (most recently
129 pushed). The stack is not changed. Returns 0 if the stack is
130 empty.
131*/
132
133/*!
134 \fn Q3PtrStack::operator type* ()const
135
136 Returns a pointer to the top item on the stack (most recently
137 pushed). The stack is not changed. Returns 0 if the stack is
138 empty.
139*/
140
141/*!
142 \fn type* Q3PtrStack::current () const
143
144 Returns a pointer to the top item on the stack (most recently
145 pushed). The stack is not changed. Returns 0 if the stack is
146 empty.
147*/
148
149/*!
150 \fn bool Q3PtrStack::autoDelete() const
151
152 The same as Q3PtrCollection::autoDelete(). Returns true if
153 the auto-delete option is set. If the option is set, the
154 stack auto-deletes its contents.
155
156 \sa setAutoDelete()
157*/
158
159/*!
160 \fn void Q3PtrStack::setAutoDelete(bool enable)
161
162 Defines whether this stack auto-deletes its contents. The same as
163 Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete
164 is turned on.
165
166 If auto-deleting is turned on, all the items in the stack are
167 deleted when the stack itself is deleted. This is convenient if
168 the stack has the only pointers to the items.
169
170 The default setting is false, for safety. If you turn it on, be
171 careful about copying the stack, or you might find yourself with
172 two stacks deleting the same items.
173
174 Note that the auto-delete setting may also affect other functions in
175 subclasses. For example, a subclass that has a remove() function
176 will remove the item from its data structure, and if auto-delete is
177 enabled, will also delete the item.
178
179 \sa autoDelete()
180*/
181
182/*!
183 \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item)
184
185 Reads a stack item, \a item, from the stream \a s and returns a
186 reference to the stream.
187
188 The default implementation sets \a item to 0.
189
190 \sa write()
191*/
192
193/*!
194 \fn QDataStream& Q3PtrStack::write(QDataStream& s,
195 Q3PtrCollection::Item item) const
196
197 Writes a stack item, \a item, to the stream \a s and returns a
198 reference to the stream.
199
200 The default implementation does nothing.
201
202 \sa read()
203*/
Note: See TracBrowser for help on using the repository browser.