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 */

Generated on Wed Mar 26 00:43:15 2008 for libstdc++ by  doxygen 1.5.1