]>
Commit | Line | Data |
---|---|---|
42526146 PE |
1 | // Queue implementation -*- C++ -*- |
2 | ||
9dd90ac6 | 3 | // Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc. |
42526146 PE |
4 | // |
5 | // This file is part of the GNU ISO C++ Library. This library is free | |
6 | // software; you can redistribute it and/or modify it under the | |
7 | // terms of the GNU General Public License as published by the | |
8 | // Free Software Foundation; either version 2, or (at your option) | |
9 | // any later version. | |
10 | ||
11 | // This library is distributed in the hope that it will be useful, | |
12 | // but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
14 | // GNU General Public License for more details. | |
15 | ||
16 | // You should have received a copy of the GNU General Public License along | |
17 | // with this library; see the file COPYING. If not, write to the Free | |
18 | // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
19 | // USA. | |
20 | ||
21 | // As a special exception, you may use this file as part of a free software | |
22 | // library without restriction. Specifically, if other files instantiate | |
23 | // templates or use macros or inline functions from this file, or you compile | |
24 | // this file and link it with other files to produce an executable, this | |
25 | // file does not by itself cause the resulting executable to be covered by | |
26 | // the GNU General Public License. This exception does not however | |
27 | // invalidate any other reasons why the executable file might be covered by | |
28 | // the GNU General Public License. | |
29 | ||
725dc051 BK |
30 | /* |
31 | * | |
32 | * Copyright (c) 1994 | |
33 | * Hewlett-Packard Company | |
34 | * | |
35 | * Permission to use, copy, modify, distribute and sell this software | |
36 | * and its documentation for any purpose is hereby granted without fee, | |
37 | * provided that the above copyright notice appear in all copies and | |
38 | * that both that copyright notice and this permission notice appear | |
39 | * in supporting documentation. Hewlett-Packard Company makes no | |
40 | * representations about the suitability of this software for any | |
41 | * purpose. It is provided "as is" without express or implied warranty. | |
42 | * | |
43 | * | |
44 | * Copyright (c) 1996,1997 | |
45 | * Silicon Graphics Computer Systems, Inc. | |
46 | * | |
47 | * Permission to use, copy, modify, distribute and sell this software | |
48 | * and its documentation for any purpose is hereby granted without fee, | |
49 | * provided that the above copyright notice appear in all copies and | |
50 | * that both that copyright notice and this permission notice appear | |
51 | * in supporting documentation. Silicon Graphics makes no | |
52 | * representations about the suitability of this software for any | |
53 | * purpose. It is provided "as is" without express or implied warranty. | |
54 | */ | |
55 | ||
729e3d3f PE |
56 | /** @file stl_queue.h |
57 | * This is an internal header file, included by other library headers. | |
58 | * You should not attempt to use it directly. | |
725dc051 BK |
59 | */ |
60 | ||
3d7c150e BK |
61 | #ifndef _QUEUE_H |
62 | #define _QUEUE_H 1 | |
725dc051 | 63 | |
30a20a1e | 64 | #include <bits/concept_check.h> |
285b36d6 | 65 | #include <debug/debug.h> |
725dc051 | 66 | |
d53d7f6e PE |
67 | namespace std |
68 | { | |
3971a4d2 | 69 | // Forward declarations of operators < and ==, needed for friend declaration. |
285b36d6 BK |
70 | template<typename _Tp, typename _Sequence = deque<_Tp> > |
71 | class queue; | |
3971a4d2 | 72 | |
285b36d6 BK |
73 | template<typename _Tp, typename _Seq> |
74 | inline bool | |
75 | operator==(const queue<_Tp,_Seq>&, const queue<_Tp,_Seq>&); | |
3971a4d2 | 76 | |
285b36d6 BK |
77 | template<typename _Tp, typename _Seq> |
78 | inline bool | |
79 | operator<(const queue<_Tp,_Seq>&, const queue<_Tp,_Seq>&); | |
3971a4d2 | 80 | |
4df6abc6 | 81 | /** |
3971a4d2 | 82 | * @brief A standard container giving FIFO behavior. |
4df6abc6 | 83 | * |
3971a4d2 PE |
84 | * @ingroup Containers |
85 | * @ingroup Sequences | |
4df6abc6 | 86 | * |
3971a4d2 PE |
87 | * Meets many of the requirements of a |
88 | * <a href="tables.html#65">container</a>, | |
89 | * but does not define anything to do with iterators. Very few of the | |
90 | * other standard container interfaces are defined. | |
4df6abc6 | 91 | * |
3971a4d2 PE |
92 | * This is not a true container, but an @e adaptor. It holds another |
93 | * container, and provides a wrapper interface to that container. The | |
94 | * wrapper is what enforces strict first-in-first-out %queue behavior. | |
4df6abc6 | 95 | * |
3971a4d2 PE |
96 | * The second template parameter defines the type of the underlying |
97 | * sequence/container. It defaults to std::deque, but it can be any type | |
98 | * that supports @c front, @c back, @c push_back, and @c pop_front, | |
99 | * such as std::list or an appropriate user-defined type. | |
100 | * | |
101 | * Members not found in "normal" containers are @c container_type, | |
102 | * which is a typedef for the second Sequence parameter, and @c push and | |
103 | * @c pop, which are standard %queue/FIFO operations. | |
4df6abc6 | 104 | */ |
285b36d6 | 105 | template<typename _Tp, typename _Sequence> |
3971a4d2 | 106 | class queue |
285b36d6 BK |
107 | { |
108 | // concept requirements | |
109 | typedef typename _Sequence::value_type _Sequence_value_type; | |
110 | __glibcxx_class_requires(_Tp, _SGIAssignableConcept) | |
111 | __glibcxx_class_requires(_Sequence, _FrontInsertionSequenceConcept) | |
112 | __glibcxx_class_requires(_Sequence, _BackInsertionSequenceConcept) | |
113 | __glibcxx_class_requires2(_Tp, _Sequence_value_type, _SameTypeConcept) | |
114 | ||
115 | template<typename _Tp1, typename _Seq1> | |
116 | friend bool | |
117 | operator==(const queue<_Tp1, _Seq1>&, const queue<_Tp1, _Seq1>&); | |
118 | ||
119 | template<typename _Tp1, typename _Seq1> | |
120 | friend bool | |
121 | operator<(const queue<_Tp1, _Seq1>&, const queue<_Tp1, _Seq1>&); | |
122 | ||
123 | public: | |
124 | typedef typename _Sequence::value_type value_type; | |
125 | typedef typename _Sequence::reference reference; | |
126 | typedef typename _Sequence::const_reference const_reference; | |
127 | typedef typename _Sequence::size_type size_type; | |
128 | typedef _Sequence container_type; | |
129 | ||
130 | protected: | |
131 | /** | |
132 | * 'c' is the underlying container. Maintainers wondering why | |
133 | * this isn't uglified as per style guidelines should note that | |
134 | * this name is specified in the standard, [23.2.3.1]. (Why? | |
135 | * Presumably for the same reason that it's protected instead | |
136 | * of private: to allow derivation. But none of the other | |
137 | * containers allow for derivation. Odd.) | |
138 | */ | |
139 | _Sequence c; | |
140 | ||
141 | public: | |
142 | /** | |
143 | * @brief Default constructor creates no elements. | |
144 | */ | |
145 | explicit | |
146 | queue(const _Sequence& __c = _Sequence()) : c(__c) {} | |
147 | ||
148 | /** | |
149 | * Returns true if the %queue is empty. | |
150 | */ | |
151 | bool | |
152 | empty() const { return c.empty(); } | |
153 | ||
154 | /** Returns the number of elements in the %queue. */ | |
155 | size_type | |
156 | size() const { return c.size(); } | |
157 | ||
158 | /** | |
159 | * Returns a read/write reference to the data at the first | |
160 | * element of the %queue. | |
161 | */ | |
162 | reference | |
163 | front() | |
164 | { | |
165 | __glibcxx_requires_nonempty(); | |
166 | return c.front(); | |
167 | } | |
168 | ||
169 | /** | |
170 | * Returns a read-only (constant) reference to the data at the first | |
171 | * element of the %queue. | |
172 | */ | |
173 | const_reference | |
174 | front() const | |
175 | { | |
176 | __glibcxx_requires_nonempty(); | |
177 | return c.front(); | |
178 | } | |
179 | ||
180 | /** | |
181 | * Returns a read/write reference to the data at the last | |
182 | * element of the %queue. | |
183 | */ | |
184 | reference | |
185 | back() | |
186 | { | |
187 | __glibcxx_requires_nonempty(); | |
188 | return c.back(); | |
189 | } | |
190 | ||
191 | /** | |
192 | * Returns a read-only (constant) reference to the data at the last | |
193 | * element of the %queue. | |
194 | */ | |
195 | const_reference | |
196 | back() const | |
197 | { | |
198 | __glibcxx_requires_nonempty(); | |
199 | return c.back(); | |
200 | } | |
201 | ||
202 | /** | |
203 | * @brief Add data to the end of the %queue. | |
204 | * @param x Data to be added. | |
205 | * | |
206 | * This is a typical %queue operation. The function creates an | |
207 | * element at the end of the %queue and assigns the given data | |
208 | * to it. The time complexity of the operation depends on the | |
209 | * underlying sequence. | |
210 | */ | |
211 | void | |
212 | push(const value_type& __x) { c.push_back(__x); } | |
213 | ||
214 | /** | |
215 | * @brief Removes first element. | |
216 | * | |
217 | * This is a typical %queue operation. It shrinks the %queue by one. | |
218 | * The time complexity of the operation depends on the underlying | |
219 | * sequence. | |
220 | * | |
221 | * Note that no data is returned, and if the first element's | |
222 | * data is needed, it should be retrieved before pop() is | |
223 | * called. | |
224 | */ | |
225 | void | |
226 | pop() | |
227 | { | |
228 | __glibcxx_requires_nonempty(); | |
229 | c.pop_front(); | |
230 | } | |
231 | }; | |
3971a4d2 PE |
232 | |
233 | ||
4df6abc6 | 234 | /** |
3971a4d2 PE |
235 | * @brief Queue equality comparison. |
236 | * @param x A %queue. | |
237 | * @param y A %queue of the same type as @a x. | |
238 | * @return True iff the size and elements of the queues are equal. | |
239 | * | |
240 | * This is an equivalence relation. Complexity and semantics depend on the | |
241 | * underlying sequence type, but the expected rules are: this relation is | |
242 | * linear in the size of the sequences, and queues are considered equivalent | |
243 | * if their sequences compare equal. | |
4df6abc6 | 244 | */ |
285b36d6 | 245 | template<typename _Tp, typename _Sequence> |
3971a4d2 | 246 | inline bool |
285b36d6 BK |
247 | operator==(const queue<_Tp,_Sequence>& __x, |
248 | const queue<_Tp,_Sequence>& __y) | |
3971a4d2 PE |
249 | { return __x.c == __y.c; } |
250 | ||
4df6abc6 | 251 | /** |
3971a4d2 PE |
252 | * @brief Queue ordering relation. |
253 | * @param x A %queue. | |
254 | * @param y A %queue of the same type as @a x. | |
9536ca34 | 255 | * @return True iff @a x is lexicographically less than @a y. |
4df6abc6 | 256 | * |
285b36d6 BK |
257 | * This is an total ordering relation. Complexity and semantics |
258 | * depend on the underlying sequence type, but the expected rules | |
259 | * are: this relation is linear in the size of the sequences, the | |
260 | * elements must be comparable with @c <, and | |
261 | * std::lexicographical_compare() is usually used to make the | |
3971a4d2 | 262 | * determination. |
4df6abc6 | 263 | */ |
285b36d6 | 264 | template<typename _Tp, typename _Sequence> |
3971a4d2 PE |
265 | inline bool |
266 | operator<(const queue<_Tp,_Sequence>& __x, const queue<_Tp,_Sequence>& __y) | |
267 | { return __x.c < __y.c; } | |
268 | ||
269 | /// Based on operator== | |
285b36d6 | 270 | template<typename _Tp, typename _Sequence> |
3971a4d2 | 271 | inline bool |
285b36d6 BK |
272 | operator!=(const queue<_Tp,_Sequence>& __x, |
273 | const queue<_Tp,_Sequence>& __y) | |
3971a4d2 PE |
274 | { return !(__x == __y); } |
275 | ||
276 | /// Based on operator< | |
285b36d6 | 277 | template<typename _Tp, typename _Sequence> |
3971a4d2 PE |
278 | inline bool |
279 | operator>(const queue<_Tp,_Sequence>& __x, const queue<_Tp,_Sequence>& __y) | |
280 | { return __y < __x; } | |
281 | ||
282 | /// Based on operator< | |
285b36d6 | 283 | template<typename _Tp, typename _Sequence> |
3971a4d2 | 284 | inline bool |
285b36d6 BK |
285 | operator<=(const queue<_Tp,_Sequence>& __x, |
286 | const queue<_Tp,_Sequence>& __y) | |
3971a4d2 PE |
287 | { return !(__y < __x); } |
288 | ||
289 | /// Based on operator< | |
285b36d6 | 290 | template<typename _Tp, typename _Sequence> |
3971a4d2 | 291 | inline bool |
285b36d6 BK |
292 | operator>=(const queue<_Tp,_Sequence>& __x, |
293 | const queue<_Tp,_Sequence>& __y) | |
3971a4d2 PE |
294 | { return !(__x < __y); } |
295 | ||
296 | ||
4df6abc6 | 297 | /** |
3971a4d2 | 298 | * @brief A standard container automatically sorting its contents. |
4df6abc6 | 299 | * |
3971a4d2 PE |
300 | * @ingroup Containers |
301 | * @ingroup Sequences | |
4df6abc6 | 302 | * |
285b36d6 BK |
303 | * This is not a true container, but an @e adaptor. It holds |
304 | * another container, and provides a wrapper interface to that | |
305 | * container. The wrapper is what enforces sorting and | |
306 | * first-in-first-out %queue behavior. Very few of the standard | |
307 | * container/sequence interface requirements are met (e.g., | |
308 | * iterators). | |
3971a4d2 PE |
309 | * |
310 | * The second template parameter defines the type of the underlying | |
285b36d6 BK |
311 | * sequence/container. It defaults to std::vector, but it can be |
312 | * any type that supports @c front(), @c push_back, @c pop_back, | |
313 | * and random-access iterators, such as std::deque or an | |
314 | * appropriate user-defined type. | |
3971a4d2 | 315 | * |
285b36d6 BK |
316 | * The third template parameter supplies the means of making |
317 | * priority comparisons. It defaults to @c less<value_type> but | |
318 | * can be anything defining a strict weak ordering. | |
3971a4d2 PE |
319 | * |
320 | * Members not found in "normal" containers are @c container_type, | |
285b36d6 BK |
321 | * which is a typedef for the second Sequence parameter, and @c |
322 | * push, @c pop, and @c top, which are standard %queue/FIFO | |
323 | * operations. | |
3971a4d2 | 324 | * |
285b36d6 BK |
325 | * @note No equality/comparison operators are provided for |
326 | * %priority_queue. | |
3971a4d2 | 327 | * |
285b36d6 BK |
328 | * @note Sorting of the elements takes place as they are added to, |
329 | * and removed from, the %priority_queue using the | |
330 | * %priority_queue's member functions. If you access the elements | |
331 | * by other means, and change their data such that the sorting | |
332 | * order would be different, the %priority_queue will not re-sort | |
333 | * the elements for you. (How could it know to do so?) | |
4df6abc6 | 334 | */ |
285b36d6 | 335 | template<typename _Tp, typename _Sequence = vector<_Tp>, |
3971a4d2 PE |
336 | typename _Compare = less<typename _Sequence::value_type> > |
337 | class priority_queue | |
3971a4d2 | 338 | { |
285b36d6 BK |
339 | // concept requirements |
340 | typedef typename _Sequence::value_type _Sequence_value_type; | |
341 | __glibcxx_class_requires(_Tp, _SGIAssignableConcept) | |
342 | __glibcxx_class_requires(_Sequence, _SequenceConcept) | |
343 | __glibcxx_class_requires(_Sequence, _RandomAccessContainerConcept) | |
344 | __glibcxx_class_requires2(_Tp, _Sequence_value_type, _SameTypeConcept) | |
345 | __glibcxx_class_requires4(_Compare, bool, _Tp,_Tp,_BinaryFunctionConcept) | |
346 | ||
347 | public: | |
348 | typedef typename _Sequence::value_type value_type; | |
349 | typedef typename _Sequence::reference reference; | |
350 | typedef typename _Sequence::const_reference const_reference; | |
351 | typedef typename _Sequence::size_type size_type; | |
352 | typedef _Sequence container_type; | |
353 | ||
354 | protected: | |
355 | // See queue::c for notes on these names. | |
356 | _Sequence c; | |
357 | _Compare comp; | |
358 | ||
359 | public: | |
360 | /** | |
361 | * @brief Default constructor creates no elements. | |
362 | */ | |
363 | explicit | |
364 | priority_queue(const _Compare& __x = _Compare(), | |
365 | const _Sequence& __s = _Sequence()) | |
366 | : c(__s), comp(__x) | |
367 | { std::make_heap(c.begin(), c.end(), comp); } | |
368 | ||
369 | /** | |
370 | * @brief Builds a %queue from a range. | |
371 | * @param first An input iterator. | |
372 | * @param last An input iterator. | |
373 | * @param x A comparison functor describing a strict weak ordering. | |
374 | * @param s An initial sequence with which to start. | |
375 | * | |
376 | * Begins by copying @a s, inserting a copy of the elements | |
377 | * from @a [first,last) into the copy of @a s, then ordering | |
378 | * the copy according to @a x. | |
379 | * | |
380 | * For more information on function objects, see the | |
381 | * documentation on @link s20_3_1_base functor base | |
382 | * classes@endlink. | |
383 | */ | |
384 | template<typename _InputIterator> | |
385 | priority_queue(_InputIterator __first, _InputIterator __last, | |
386 | const _Compare& __x = _Compare(), | |
387 | const _Sequence& __s = _Sequence()) | |
388 | : c(__s), comp(__x) | |
389 | { | |
390 | __glibcxx_requires_valid_range(__first, __last); | |
391 | c.insert(c.end(), __first, __last); | |
392 | std::make_heap(c.begin(), c.end(), comp); | |
393 | } | |
394 | ||
395 | /** | |
396 | * Returns true if the %queue is empty. | |
397 | */ | |
398 | bool | |
399 | empty() const { return c.empty(); } | |
400 | ||
401 | /** Returns the number of elements in the %queue. */ | |
402 | size_type | |
403 | size() const { return c.size(); } | |
404 | ||
405 | /** | |
406 | * Returns a read-only (constant) reference to the data at the first | |
407 | * element of the %queue. | |
408 | */ | |
409 | const_reference | |
410 | top() const | |
411 | { | |
412 | __glibcxx_requires_nonempty(); | |
413 | return c.front(); | |
414 | } | |
415 | ||
416 | /** | |
417 | * @brief Add data to the %queue. | |
418 | * @param x Data to be added. | |
419 | * | |
420 | * This is a typical %queue operation. | |
421 | * The time complexity of the operation depends on the underlying | |
422 | * sequence. | |
423 | */ | |
424 | void | |
425 | push(const value_type& __x) | |
426 | { | |
427 | try | |
3971a4d2 PE |
428 | { |
429 | c.push_back(__x); | |
9dd90ac6 | 430 | std::push_heap(c.begin(), c.end(), comp); |
3971a4d2 | 431 | } |
285b36d6 | 432 | catch(...) |
3971a4d2 PE |
433 | { |
434 | c.clear(); | |
435 | __throw_exception_again; | |
436 | } | |
285b36d6 BK |
437 | } |
438 | ||
439 | /** | |
440 | * @brief Removes first element. | |
441 | * | |
442 | * This is a typical %queue operation. It shrinks the %queue | |
443 | * by one. The time complexity of the operation depends on the | |
444 | * underlying sequence. | |
445 | * | |
446 | * Note that no data is returned, and if the first element's | |
447 | * data is needed, it should be retrieved before pop() is | |
448 | * called. | |
449 | */ | |
450 | void | |
451 | pop() | |
452 | { | |
453 | __glibcxx_requires_nonempty(); | |
454 | try | |
3971a4d2 | 455 | { |
9dd90ac6 | 456 | std::pop_heap(c.begin(), c.end(), comp); |
3971a4d2 PE |
457 | c.pop_back(); |
458 | } | |
285b36d6 | 459 | catch(...) |
3971a4d2 PE |
460 | { |
461 | c.clear(); | |
462 | __throw_exception_again; | |
463 | } | |
285b36d6 BK |
464 | } |
465 | }; | |
3971a4d2 PE |
466 | |
467 | // No equality/comparison operators are provided for priority_queue. | |
d53d7f6e | 468 | } // namespace std |
725dc051 | 469 | |
3d7c150e | 470 | #endif /* _QUEUE_H */ |