# stl_queue.h

Go to the documentation of this file.

    00001 // Queue implementation -*- C++ -*-
    00002
    00003 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
    00004 // Free Software Foundation, Inc.
    00005 //
    00006 // This file is part of the GNU ISO C++ Library.  This library is free
    00007 // software; you can redistribute it and/or modify it under the
    00008 // terms of the GNU General Public License as published by the
    00009 // Free Software Foundation; either version 2, or (at your option)
    00010 // any later version.
    00011
    00012 // This library is distributed in the hope that it will be useful,
    00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00015 // GNU General Public License for more details.
    00016
    00017 // You should have received a copy of the GNU General Public License along
    00018 // with this library; see the file COPYING.  If not, write to the Free
    00019 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
    00020 // USA.
    00021
    00022 // As a special exception, you may use this file as part of a free software
    00023 // library without restriction.  Specifically, if other files instantiate
    00024 // templates or use macros or inline functions from this file, or you compile
    00025 // this file and link it with other files to produce an executable, this
    00026 // file does not by itself cause the resulting executable to be covered by
    00027 // the GNU General Public License.  This exception does not however
    00028 // invalidate any other reasons why the executable file might be covered by
    00029 // the GNU General Public License.
    00030
    00031 /*
    00032  *
    00033  * Copyright (c) 1994
    00034  * Hewlett-Packard Company
    00035  *
    00036  * Permission to use, copy, modify, distribute and sell this software
    00037  * and its documentation for any purpose is hereby granted without fee,
    00038  * provided that the above copyright notice appear in all copies and
    00039  * that both that copyright notice and this permission notice appear
    00040  * in supporting documentation.  Hewlett-Packard Company makes no
    00041  * representations about the suitability of this software for any
    00042  * purpose.  It is provided "as is" without express or implied warranty.
    00043  *
    00044  *
    00045  * Copyright (c) 1996,1997
    00046  * Silicon Graphics Computer Systems, Inc.
    00047  *
    00048  * Permission to use, copy, modify, distribute and sell this software
    00049  * and its documentation for any purpose is hereby granted without fee,
    00050  * provided that the above copyright notice appear in all copies and
    00051  * that both that copyright notice and this permission notice appear
    00052  * in supporting documentation.  Silicon Graphics makes no
    00053  * representations about the suitability of this software for any
    00054  * purpose.  It is provided "as is" without express or implied warranty.
    00055  */
    00056
    00057 /** @file stl_queue.h
    00058  *  This is an internal header file, included by other library headers.
    00059  *  You should not attempt to use it directly.
    00060  */
    00061
    00062 #ifndef _STL_QUEUE_H
    00063 #define _STL_QUEUE_H 1
    00064
    00065 #include <bits/concept_check.h>
    00066 #include <debug/debug.h>
    00067
    00068 _GLIBCXX_BEGIN_NAMESPACE(std)
    00069
    00070   /**
    00071    *  @brief  A standard container giving FIFO behavior.
    00072    *
    00073    *  @ingroup Containers
    00074    *  @ingroup Sequences
    00075    *
    00076    *  Meets many of the requirements of a
    00077    *  <a href="tables.html#65">container</a>,
    00078    *  but does not define anything to do with iterators.  Very few of the
    00079    *  other standard container interfaces are defined.
    00080    *
    00081    *  This is not a true container, but an @e adaptor.  It holds another
    00082    *  container, and provides a wrapper interface to that container.  The
    00083    *  wrapper is what enforces strict first-in-first-out %queue behavior.
    00084    *
    00085    *  The second template parameter defines the type of the underlying
    00086    *  sequence/container.  It defaults to std::deque, but it can be any type
    00087    *  that supports @c front, @c back, @c push_back, and @c pop_front,
    00088    *  such as std::list or an appropriate user-defined type.
    00089    *
    00090    *  Members not found in "normal" containers are @c container_type,
    00091    *  which is a typedef for the second Sequence parameter, and @c push and
    00092    *  @c pop, which are standard %queue/FIFO operations.
    00093   */
    00094   template<typename _Tp, typename _Sequence = deque<_Tp> >
    00095     class queue
    00096     {
    00097       // concept requirements
    00098       typedef typename _Sequence::value_type _Sequence_value_type;
    00099       __glibcxx_class_requires(_Tp, _SGIAssignableConcept)
    00100       __glibcxx_class_requires(_Sequence, _FrontInsertionSequenceConcept)
    00101       __glibcxx_class_requires(_Sequence, _BackInsertionSequenceConcept)
    00102       __glibcxx_class_requires2(_Tp, _Sequence_value_type, _SameTypeConcept)
    00103
    00104       template<typename _Tp1, typename _Seq1>
    00105         friend bool
    00106         operator==(const queue<_Tp1, _Seq1>&, const queue<_Tp1, _Seq1>&);
    00107
    00108       template<typename _Tp1, typename _Seq1>
    00109         friend bool
    00110         operator<(const queue<_Tp1, _Seq1>&, const queue<_Tp1, _Seq1>&);
    00111
    00112     public:
    00113       typedef typename _Sequence::value_type                value_type;
    00114       typedef typename _Sequence::reference                 reference;
    00115       typedef typename _Sequence::const_reference           const_reference;
    00116       typedef typename _Sequence::size_type                 size_type;
    00117       typedef          _Sequence                            container_type;
    00118
    00119     protected:
    00120       /**
    00121        *  'c' is the underlying container.  Maintainers wondering why
    00122        *  this isn't uglified as per style guidelines should note that
    00123        *  this name is specified in the standard, [23.2.3.1].  (Why?
    00124        *  Presumably for the same reason that it's protected instead
    00125        *  of private: to allow derivation.  But none of the other
    00126        *  containers allow for derivation.  Odd.)
    00127        */
    00128       _Sequence c;
    00129
    00130     public:
    00131       /**
    00132        *  @brief  Default constructor creates no elements.
    00133        */
    00134 #ifndef __GXX_EXPERIMENTAL_CXX0X__
    00135       explicit
    00136       queue(const _Sequence& __c = _Sequence())
    00137       : c(__c) { }
    00138 #else
    00139       explicit
    00140       queue(const _Sequence& __c)
    00141       : c(__c) { }
    00142
    00143       explicit
    00144       queue(_Sequence&& __c = _Sequence())
    00145       : c(std::move(__c)) { }
    00146
    00147       queue(queue&& __q)
    00148       : c(std::move(__q.c)) { }
    00149
    00150       queue&
    00151       operator=(queue&& __q)
    00152       {
    00153     c = std::move(__q.c);
    00154     return *this;
    00155       }
    00156 #endif
    00157
    00158       /**
    00159        *  Returns true if the %queue is empty.
    00160        */
    00161       bool
    00162       empty() const
    00163       { return c.empty(); }
    00164
    00165       /**  Returns the number of elements in the %queue.  */
    00166       size_type
    00167       size() const
    00168       { return c.size(); }
    00169
    00170       /**
    00171        *  Returns a read/write reference to the data at the first
    00172        *  element of the %queue.
    00173        */
    00174       reference
    00175       front()
    00176       {
    00177     __glibcxx_requires_nonempty();
    00178     return c.front();
    00179       }
    00180
    00181       /**
    00182        *  Returns a read-only (constant) reference to the data at the first
    00183        *  element of the %queue.
    00184        */
    00185       const_reference
    00186       front() const
    00187       {
    00188     __glibcxx_requires_nonempty();
    00189     return c.front();
    00190       }
    00191
    00192       /**
    00193        *  Returns a read/write reference to the data at the last
    00194        *  element of the %queue.
    00195        */
    00196       reference
    00197       back()
    00198       {
    00199     __glibcxx_requires_nonempty();
    00200     return c.back();
    00201       }
    00202
    00203       /**
    00204        *  Returns a read-only (constant) reference to the data at the last
    00205        *  element of the %queue.
    00206        */
    00207       const_reference
    00208       back() const
    00209       {
    00210     __glibcxx_requires_nonempty();
    00211     return c.back();
    00212       }
    00213
    00214       /**
    00215        *  @brief  Add data to the end of the %queue.
    00216        *  @param  x  Data to be added.
    00217        *
    00218        *  This is a typical %queue operation.  The function creates an
    00219        *  element at the end of the %queue and assigns the given data
    00220        *  to it.  The time complexity of the operation depends on the
    00221        *  underlying sequence.
    00222        */
    00223 #ifndef __GXX_EXPERIMENTAL_CXX0X__
    00224       void
    00225       push(const value_type& __x)
    00226       { c.push_back(__x); }
    00227 #else
    00228       // NB: DR 756.
    00229       template<typename... _Args>
    00230         void
    00231         push(_Args&&... __args)
    00232     { c.push_back(std::forward<_Args>(__args)...); }
    00233 #endif
    00234
    00235       /**
    00236        *  @brief  Removes first element.
    00237        *
    00238        *  This is a typical %queue operation.  It shrinks the %queue by one.
    00239        *  The time complexity of the operation depends on the underlying
    00240        *  sequence.
    00241        *
    00242        *  Note that no data is returned, and if the first element's
    00243        *  data is needed, it should be retrieved before pop() is
    00244        *  called.
    00245        */
    00246       void
    00247       pop()
    00248       {
    00249     __glibcxx_requires_nonempty();
    00250     c.pop_front();
    00251       }
    00252
    00253 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00254       void
    00255       swap(queue&& __q)
    00256       { c.swap(__q.c); }
    00257 #endif
    00258     };
    00259
    00260   /**
    00261    *  @brief  Queue equality comparison.
    00262    *  @param  x  A %queue.
    00263    *  @param  y  A %queue of the same type as @a x.
    00264    *  @return  True iff the size and elements of the queues are equal.
    00265    *
    00266    *  This is an equivalence relation.  Complexity and semantics depend on the
    00267    *  underlying sequence type, but the expected rules are:  this relation is
    00268    *  linear in the size of the sequences, and queues are considered equivalent
    00269    *  if their sequences compare equal.
    00270   */
    00271   template<typename _Tp, typename _Seq>
    00272     inline bool
    00273     operator==(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00274     { return __x.c == __y.c; }
    00275
    00276   /**
    00277    *  @brief  Queue ordering relation.
    00278    *  @param  x  A %queue.
    00279    *  @param  y  A %queue of the same type as @a x.
    00280    *  @return  True iff @a x is lexicographically less than @a y.
    00281    *
    00282    *  This is an total ordering relation.  Complexity and semantics
    00283    *  depend on the underlying sequence type, but the expected rules
    00284    *  are: this relation is linear in the size of the sequences, the
    00285    *  elements must be comparable with @c <, and
    00286    *  std::lexicographical_compare() is usually used to make the
    00287    *  determination.
    00288   */
    00289   template<typename _Tp, typename _Seq>
    00290     inline bool
    00291     operator<(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00292     { return __x.c < __y.c; }
    00293
    00294   /// Based on operator==
    00295   template<typename _Tp, typename _Seq>
    00296     inline bool
    00297     operator!=(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00298     { return !(__x == __y); }
    00299
    00300   /// Based on operator<
    00301   template<typename _Tp, typename _Seq>
    00302     inline bool
    00303     operator>(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00304     { return __y < __x; }
    00305
    00306   /// Based on operator<
    00307   template<typename _Tp, typename _Seq>
    00308     inline bool
    00309     operator<=(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00310     { return !(__y < __x); }
    00311
    00312   /// Based on operator<
    00313   template<typename _Tp, typename _Seq>
    00314     inline bool
    00315     operator>=(const queue<_Tp, _Seq>& __x, const queue<_Tp, _Seq>& __y)
    00316     { return !(__x < __y); }
    00317
    00318 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00319   template<typename _Tp, typename _Seq>
    00320     inline void
    00321     swap(queue<_Tp, _Seq>& __x, queue<_Tp, _Seq>& __y)
    00322     { __x.swap(__y); }
    00323
    00324   template<typename _Tp, typename _Seq>
    00325     inline void
    00326     swap(queue<_Tp, _Seq>&& __x, queue<_Tp, _Seq>& __y)
    00327     { __x.swap(__y); }
    00328
    00329   template<typename _Tp, typename _Seq>
    00330     inline void
    00331     swap(queue<_Tp, _Seq>& __x, queue<_Tp, _Seq>&& __y)
    00332     { __x.swap(__y); }
    00333 #endif
    00334
    00335   /**
    00336    *  @brief  A standard container automatically sorting its contents.
    00337    *
    00338    *  @ingroup Containers
    00339    *  @ingroup Sequences
    00340    *
    00341    *  This is not a true container, but an @e adaptor.  It holds
    00342    *  another container, and provides a wrapper interface to that
    00343    *  container.  The wrapper is what enforces priority-based sorting
    00344    *  and %queue behavior.  Very few of the standard container/sequence
    00345    *  interface requirements are met (e.g., iterators).
    00346    *
    00347    *  The second template parameter defines the type of the underlying
    00348    *  sequence/container.  It defaults to std::vector, but it can be
    00349    *  any type that supports @c front(), @c push_back, @c pop_back,
    00350    *  and random-access iterators, such as std::deque or an
    00351    *  appropriate user-defined type.
    00352    *
    00353    *  The third template parameter supplies the means of making
    00354    *  priority comparisons.  It defaults to @c less<value_type> but
    00355    *  can be anything defining a strict weak ordering.
    00356    *
    00357    *  Members not found in "normal" containers are @c container_type,
    00358    *  which is a typedef for the second Sequence parameter, and @c
    00359    *  push, @c pop, and @c top, which are standard %queue operations.
    00360    *
    00361    *  @note No equality/comparison operators are provided for
    00362    *  %priority_queue.
    00363    *
    00364    *  @note Sorting of the elements takes place as they are added to,
    00365    *  and removed from, the %priority_queue using the
    00366    *  %priority_queue's member functions.  If you access the elements
    00367    *  by other means, and change their data such that the sorting
    00368    *  order would be different, the %priority_queue will not re-sort
    00369    *  the elements for you.  (How could it know to do so?)
    00370   */
    00371   template<typename _Tp, typename _Sequence = vector<_Tp>,
    00372        typename _Compare  = less<typename _Sequence::value_type> >
    00373     class priority_queue
    00374     {
    00375       // concept requirements
    00376       typedef typename _Sequence::value_type _Sequence_value_type;
    00377       __glibcxx_class_requires(_Tp, _SGIAssignableConcept)
    00378       __glibcxx_class_requires(_Sequence, _SequenceConcept)
    00379       __glibcxx_class_requires(_Sequence, _RandomAccessContainerConcept)
    00380       __glibcxx_class_requires2(_Tp, _Sequence_value_type, _SameTypeConcept)
    00381       __glibcxx_class_requires4(_Compare, bool, _Tp, _Tp,
    00382                 _BinaryFunctionConcept)
    00383
    00384     public:
    00385       typedef typename _Sequence::value_type                value_type;
    00386       typedef typename _Sequence::reference                 reference;
    00387       typedef typename _Sequence::const_reference           const_reference;
    00388       typedef typename _Sequence::size_type                 size_type;
    00389       typedef          _Sequence                            container_type;
    00390
    00391     protected:
    00392       //  See queue::c for notes on these names.
    00393       _Sequence  c;
    00394       _Compare   comp;
    00395
    00396     public:
    00397       /**
    00398        *  @brief  Default constructor creates no elements.
    00399        */
    00400 #ifndef __GXX_EXPERIMENTAL_CXX0X__
    00401       explicit
    00402       priority_queue(const _Compare& __x = _Compare(),
    00403              const _Sequence& __s = _Sequence())
    00404       : c(__s), comp(__x)
    00405       { std::make_heap(c.begin(), c.end(), comp); }
    00406 #else
    00407       explicit
    00408       priority_queue(const _Compare& __x,
    00409              const _Sequence& __s)
    00410       : c(__s), comp(__x)
    00411       { std::make_heap(c.begin(), c.end(), comp); }
    00412
    00413       explicit
    00414       priority_queue(const _Compare& __x = _Compare(),
    00415              _Sequence&& __s = _Sequence())
    00416       : c(std::move(__s)), comp(__x)
    00417       { std::make_heap(c.begin(), c.end(), comp); }
    00418 #endif
    00419
    00420       /**
    00421        *  @brief  Builds a %queue from a range.
    00422        *  @param  first  An input iterator.
    00423        *  @param  last  An input iterator.
    00424        *  @param  x  A comparison functor describing a strict weak ordering.
    00425        *  @param  s  An initial sequence with which to start.
    00426        *
    00427        *  Begins by copying @a s, inserting a copy of the elements
    00428        *  from @a [first,last) into the copy of @a s, then ordering
    00429        *  the copy according to @a x.
    00430        *
    00431        *  For more information on function objects, see the
    00432        *  documentation on @link s20_3_1_base functor base
    00433        *  classes@endlink.
    00434        */
    00435 #ifndef __GXX_EXPERIMENTAL_CXX0X__
    00436       template<typename _InputIterator>
    00437         priority_queue(_InputIterator __first, _InputIterator __last,
    00438                const _Compare& __x = _Compare(),
    00439                const _Sequence& __s = _Sequence())
    00440     : c(__s), comp(__x)
    00441         {
    00442       __glibcxx_requires_valid_range(__first, __last);
    00443       c.insert(c.end(), __first, __last);
    00444       std::make_heap(c.begin(), c.end(), comp);
    00445     }
    00446 #else
    00447       template<typename _InputIterator>
    00448         priority_queue(_InputIterator __first, _InputIterator __last,
    00449                const _Compare& __x,
    00450                const _Sequence& __s)
    00451     : c(__s), comp(__x)
    00452         {
    00453       __glibcxx_requires_valid_range(__first, __last);
    00454       c.insert(c.end(), __first, __last);
    00455       std::make_heap(c.begin(), c.end(), comp);
    00456     }
    00457
    00458       template<typename _InputIterator>
    00459         priority_queue(_InputIterator __first, _InputIterator __last,
    00460                const _Compare& __x = _Compare(),
    00461                _Sequence&& __s = _Sequence())
    00462     : c(std::move(__s)), comp(__x)
    00463         {
    00464       __glibcxx_requires_valid_range(__first, __last);
    00465       c.insert(c.end(), __first, __last);
    00466       std::make_heap(c.begin(), c.end(), comp);
    00467     }
    00468
    00469       priority_queue(priority_queue&& __pq)
    00470       : c(std::move(__pq.c)), comp(std::move(__pq.comp)) { }
    00471
    00472       priority_queue&
    00473       operator=(priority_queue&& __pq)
    00474       {
    00475     c = std::move(__pq.c);
    00476     comp = std::move(__pq.comp);
    00477     return *this;
    00478       }
    00479 #endif
    00480
    00481       /**
    00482        *  Returns true if the %queue is empty.
    00483        */
    00484       bool
    00485       empty() const
    00486       { return c.empty(); }
    00487
    00488       /**  Returns the number of elements in the %queue.  */
    00489       size_type
    00490       size() const
    00491       { return c.size(); }
    00492
    00493       /**
    00494        *  Returns a read-only (constant) reference to the data at the first
    00495        *  element of the %queue.
    00496        */
    00497       const_reference
    00498       top() const
    00499       {
    00500     __glibcxx_requires_nonempty();
    00501     return c.front();
    00502       }
    00503
    00504       /**
    00505        *  @brief  Add data to the %queue.
    00506        *  @param  x  Data to be added.
    00507        *
    00508        *  This is a typical %queue operation.
    00509        *  The time complexity of the operation depends on the underlying
    00510        *  sequence.
    00511        */
    00512 #ifndef __GXX_EXPERIMENTAL_CXX0X__
    00513       void
    00514       push(const value_type& __x)
    00515       {
    00516     c.push_back(__x);
    00517     std::push_heap(c.begin(), c.end(), comp);
    00518       }
    00519 #else
    00520       // NB: DR 756.
    00521       template<typename... _Args>
    00522         void
    00523         push(_Args&&... __args)
    00524     {
    00525       c.push_back(std::forward<_Args>(__args)...);
    00526       std::push_heap(c.begin(), c.end(), comp);
    00527     }
    00528 #endif
    00529
    00530       /**
    00531        *  @brief  Removes first element.
    00532        *
    00533        *  This is a typical %queue operation.  It shrinks the %queue
    00534        *  by one.  The time complexity of the operation depends on the
    00535        *  underlying sequence.
    00536        *
    00537        *  Note that no data is returned, and if the first element's
    00538        *  data is needed, it should be retrieved before pop() is
    00539        *  called.
    00540        */
    00541       void
    00542       pop()
    00543       {
    00544     __glibcxx_requires_nonempty();
    00545     std::pop_heap(c.begin(), c.end(), comp);
    00546     c.pop_back();
    00547       }
    00548
    00549 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00550       void
    00551       swap(priority_queue&& __pq)
    00552       {
    00553     using std::swap;
    00554     c.swap(__pq.c);
    00555     swap(comp, __pq.comp);
    00556       }
    00557 #endif
    00558     };
    00559
    00560   // No equality/comparison operators are provided for priority_queue.
    00561
    00562 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00563   template<typename _Tp, typename _Sequence, typename _Compare>
    00564     inline void
    00565     swap(priority_queue<_Tp, _Sequence, _Compare>& __x,
    00566      priority_queue<_Tp, _Sequence, _Compare>& __y)
    00567     { __x.swap(__y); }
    00568
    00569   template<typename _Tp, typename _Sequence, typename _Compare>
    00570     inline void
    00571     swap(priority_queue<_Tp, _Sequence, _Compare>&& __x,
    00572      priority_queue<_Tp, _Sequence, _Compare>& __y)
    00573     { __x.swap(__y); }
    00574
    00575   template<typename _Tp, typename _Sequence, typename _Compare>
    00576     inline void
    00577     swap(priority_queue<_Tp, _Sequence, _Compare>& __x,
    00578      priority_queue<_Tp, _Sequence, _Compare>&& __y)
    00579     { __x.swap(__y); }
    00580 #endif
    00581
    00582 _GLIBCXX_END_NAMESPACE
    00583
    00584 #endif /* _STL_QUEUE_H */