forward_list.h

Go to the documentation of this file.
00001 // <forward_list.h> -*- C++ -*-
00002 
00003 // Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc.
00004 //
00005 // This file is part of the GNU ISO C++ Library.  This library is free
00006 // software; you can redistribute it and/or modify it under the
00007 // terms of the GNU General Public License as published by the
00008 // Free Software Foundation; either version 3, or (at your option)
00009 // any later version.
00010 
00011 // This library is distributed in the hope that it will be useful,
00012 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014 // GNU General Public License for more details.
00015 
00016 // Under Section 7 of GPL version 3, you are granted additional
00017 // permissions described in the GCC Runtime Library Exception, version
00018 // 3.1, as published by the Free Software Foundation.
00019 
00020 // You should have received a copy of the GNU General Public License and
00021 // a copy of the GCC Runtime Library Exception along with this program;
00022 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
00023 // <http://www.gnu.org/licenses/>.
00024 
00025 /** @file forward_list.h
00026  *  This is a Standard C++ Library header.
00027  */
00028 
00029 #ifndef _FORWARD_LIST_H
00030 #define _FORWARD_LIST_H 1
00031 
00032 #pragma GCC system_header
00033 
00034 #include <memory>
00035 #include <initializer_list>
00036 
00037 _GLIBCXX_BEGIN_NESTED_NAMESPACE(std, _GLIBCXX_STD_D)
00038 
00039   /**
00040    *  @brief  A helper basic node class for %forward_list.
00041    *          This is just a linked list with nothing inside it.
00042    *          There are purely list shuffling utility methods here.
00043    */
00044   struct _Fwd_list_node_base
00045   {
00046     _Fwd_list_node_base() : _M_next(0) { }
00047 
00048     _Fwd_list_node_base* _M_next;
00049 
00050     static void
00051     swap(_Fwd_list_node_base& __x, _Fwd_list_node_base& __y)
00052     { std::swap(__x._M_next, __y._M_next); }
00053 
00054     _Fwd_list_node_base*
00055     _M_transfer_after(_Fwd_list_node_base* __begin)
00056     {
00057       _Fwd_list_node_base* __end = __begin;
00058       while (__end && __end->_M_next)
00059     __end = __end->_M_next;
00060       return _M_transfer_after(__begin, __end);
00061     }
00062 
00063     _Fwd_list_node_base*
00064     _M_transfer_after(_Fwd_list_node_base* __begin,
00065               _Fwd_list_node_base* __end)
00066     {
00067       _Fwd_list_node_base* __keep = __begin->_M_next;
00068       if (__end)
00069     {
00070       __begin->_M_next = __end->_M_next;
00071       __end->_M_next = _M_next;
00072     }
00073       else
00074     __begin->_M_next = 0;
00075       _M_next = __keep;
00076       return __end;
00077     }
00078 
00079     void
00080     _M_reverse_after()
00081     {
00082       _Fwd_list_node_base* __tail = _M_next;
00083       if (!__tail)
00084     return;
00085       while (_Fwd_list_node_base* __temp = __tail->_M_next)
00086     {
00087       _Fwd_list_node_base* __keep = _M_next;
00088       _M_next = __temp;
00089       __tail->_M_next = __temp->_M_next;
00090       _M_next->_M_next = __keep;
00091     }
00092     }
00093   };
00094 
00095   /**
00096    *  @brief  A helper node class for %forward_list.
00097    *          This is just a linked list with a data value in each node.
00098    *          There is a sorting utility method.
00099    */
00100   template<typename _Tp>
00101     struct _Fwd_list_node
00102     : public _Fwd_list_node_base
00103     {
00104       template<typename... _Args>
00105         _Fwd_list_node(_Args&&... __args)
00106         : _Fwd_list_node_base(), 
00107           _M_value(std::forward<_Args>(__args)...) { }
00108 
00109       _Tp _M_value;
00110     };
00111 
00112   /**
00113    *   @brief A forward_list::iterator.
00114    * 
00115    *   All the functions are op overloads.
00116    */
00117   template<typename _Tp>
00118     struct _Fwd_list_iterator
00119     {
00120       typedef _Fwd_list_iterator<_Tp>            _Self;
00121       typedef _Fwd_list_node<_Tp>                _Node;
00122 
00123       typedef _Tp                                value_type;
00124       typedef _Tp*                               pointer;
00125       typedef _Tp&                               reference;
00126       typedef ptrdiff_t                          difference_type;
00127       typedef std::forward_iterator_tag          iterator_category;
00128 
00129       _Fwd_list_iterator()
00130       : _M_node() { }
00131 
00132       explicit
00133       _Fwd_list_iterator(_Fwd_list_node_base* __n) 
00134       : _M_node(__n) { }
00135 
00136       reference
00137       operator*() const
00138       { return static_cast<_Node*>(this->_M_node)->_M_value; }
00139 
00140       pointer
00141       operator->() const
00142       { return std::__addressof(static_cast<_Node*>
00143                 (this->_M_node)->_M_value); }
00144 
00145       _Self&
00146       operator++()
00147       {
00148         _M_node = _M_node->_M_next;
00149         return *this;
00150       }
00151 
00152       _Self
00153       operator++(int)
00154       {
00155         _Self __tmp(*this);
00156         _M_node = _M_node->_M_next;
00157         return __tmp;
00158       }
00159 
00160       bool
00161       operator==(const _Self& __x) const
00162       { return _M_node == __x._M_node; }
00163 
00164       bool
00165       operator!=(const _Self& __x) const
00166       { return _M_node != __x._M_node; }
00167 
00168       _Self
00169       _M_next() const
00170       {
00171         if (_M_node)
00172           return _Fwd_list_iterator(_M_node->_M_next);
00173         else
00174           return _Fwd_list_iterator(0);
00175       }
00176 
00177       _Fwd_list_node_base* _M_node;
00178     };
00179 
00180   /**
00181    *   @brief A forward_list::const_iterator.
00182    * 
00183    *   All the functions are op overloads.
00184    */
00185   template<typename _Tp>
00186     struct _Fwd_list_const_iterator
00187     {
00188       typedef _Fwd_list_const_iterator<_Tp>      _Self;
00189       typedef const _Fwd_list_node<_Tp>          _Node;
00190       typedef _Fwd_list_iterator<_Tp>            iterator;
00191 
00192       typedef _Tp                                value_type;
00193       typedef const _Tp*                         pointer;
00194       typedef const _Tp&                         reference;
00195       typedef ptrdiff_t                          difference_type;
00196       typedef std::forward_iterator_tag          iterator_category;
00197 
00198       _Fwd_list_const_iterator()
00199       : _M_node() { }
00200 
00201       explicit
00202       _Fwd_list_const_iterator(const _Fwd_list_node_base* __n) 
00203       : _M_node(__n) { }
00204 
00205       _Fwd_list_const_iterator(const iterator& __iter)
00206       : _M_node(__iter._M_node) { }
00207 
00208       reference
00209       operator*() const
00210       { return static_cast<_Node*>(this->_M_node)->_M_value; }
00211 
00212       pointer
00213       operator->() const
00214       { return std::__addressof(static_cast<_Node*>
00215                 (this->_M_node)->_M_value); }
00216 
00217       _Self&
00218       operator++()
00219       {
00220         _M_node = _M_node->_M_next;
00221         return *this;
00222       }
00223 
00224       _Self
00225       operator++(int)
00226       {
00227         _Self __tmp(*this);
00228         _M_node = _M_node->_M_next;
00229         return __tmp;
00230       }
00231 
00232       bool
00233       operator==(const _Self& __x) const
00234       { return _M_node == __x._M_node; }
00235 
00236       bool
00237       operator!=(const _Self& __x) const
00238       { return _M_node != __x._M_node; }
00239 
00240       _Self
00241       _M_next() const
00242       {
00243         if (this->_M_node)
00244           return _Fwd_list_const_iterator(_M_node->_M_next);
00245         else
00246           return _Fwd_list_const_iterator(0);
00247       }
00248 
00249       const _Fwd_list_node_base* _M_node;
00250     };
00251 
00252   /**
00253    *  @brief  Forward list iterator equality comparison.
00254    */
00255   template<typename _Tp>
00256     inline bool
00257     operator==(const _Fwd_list_iterator<_Tp>& __x,
00258                const _Fwd_list_const_iterator<_Tp>& __y)
00259     { return __x._M_node == __y._M_node; }
00260 
00261   /**
00262    *  @brief  Forward list iterator inequality comparison.
00263    */
00264   template<typename _Tp>
00265     inline bool
00266     operator!=(const _Fwd_list_iterator<_Tp>& __x,
00267                const _Fwd_list_const_iterator<_Tp>& __y)
00268     { return __x._M_node != __y._M_node; }
00269 
00270   /**
00271    *  @brief  Base class for %forward_list.
00272    */
00273   template<typename _Tp, typename _Alloc>
00274     struct _Fwd_list_base
00275     {
00276     protected:
00277       typedef typename _Alloc::template rebind<_Tp>::other _Tp_alloc_type;
00278 
00279       typedef typename _Alloc::template 
00280         rebind<_Fwd_list_node<_Tp>>::other _Node_alloc_type;
00281 
00282       struct _Fwd_list_impl 
00283       : public _Node_alloc_type
00284       {
00285         _Fwd_list_node_base _M_head;
00286 
00287         _Fwd_list_impl()
00288         : _Node_alloc_type(), _M_head()
00289         { }
00290 
00291         _Fwd_list_impl(const _Node_alloc_type& __a)
00292         : _Node_alloc_type(__a), _M_head()
00293         { }
00294       };
00295 
00296       _Fwd_list_impl _M_impl;
00297 
00298     public:
00299       typedef _Fwd_list_iterator<_Tp>                 iterator;
00300       typedef _Fwd_list_const_iterator<_Tp>           const_iterator;
00301       typedef _Fwd_list_node<_Tp>                     _Node;
00302 
00303       _Node_alloc_type&
00304       _M_get_Node_allocator()
00305       { return *static_cast<_Node_alloc_type*>(&this->_M_impl); }
00306 
00307       const _Node_alloc_type&
00308       _M_get_Node_allocator() const
00309       { return *static_cast<const _Node_alloc_type*>(&this->_M_impl); }
00310 
00311       _Fwd_list_base()
00312       : _M_impl()
00313       { this->_M_impl._M_head._M_next = 0; }
00314 
00315       _Fwd_list_base(const _Alloc& __a)
00316       : _M_impl(__a)
00317       { this->_M_impl._M_head._M_next = 0; }
00318 
00319       _Fwd_list_base(const _Fwd_list_base& __lst, const _Alloc& __a);
00320 
00321       _Fwd_list_base(_Fwd_list_base&& __lst, const _Alloc& __a)
00322       : _M_impl(__a)
00323       { _Fwd_list_node_base::swap(this->_M_impl._M_head,
00324                   __lst._M_impl._M_head); }
00325 
00326       _Fwd_list_base(_Fwd_list_base&& __lst)
00327       : _M_impl(__lst._M_get_Node_allocator())
00328       { _Fwd_list_node_base::swap(this->_M_impl._M_head,
00329                   __lst._M_impl._M_head); }
00330 
00331       ~_Fwd_list_base()
00332       { _M_erase_after(&_M_impl._M_head, 0); }
00333 
00334     protected:
00335 
00336       _Node*
00337       _M_get_node()
00338       { return _M_get_Node_allocator().allocate(1); }
00339 
00340       template<typename... _Args>
00341         _Node*
00342         _M_create_node(_Args&&... __args)
00343         {
00344           _Node* __node = this->_M_get_node();
00345           __try
00346             {
00347               _M_get_Node_allocator().construct(__node,
00348                                               std::forward<_Args>(__args)...);
00349               __node->_M_next = 0;
00350             }
00351           __catch(...)
00352             {
00353               this->_M_put_node(__node);
00354               __throw_exception_again;
00355             }
00356           return __node;
00357         }
00358 
00359       template<typename... _Args>
00360         _Fwd_list_node_base*
00361         _M_insert_after(const_iterator __pos, _Args&&... __args);
00362 
00363       void
00364       _M_put_node(_Node* __p)
00365       { _M_get_Node_allocator().deallocate(__p, 1); }
00366 
00367       void
00368       _M_erase_after(_Fwd_list_node_base* __pos);
00369 
00370       void
00371       _M_erase_after(_Fwd_list_node_base* __pos, 
00372                      _Fwd_list_node_base* __last);
00373     };
00374 
00375   /**
00376    *  @brief A standard container with linear time access to elements,
00377    *  and fixed time insertion/deletion at any point in the sequence.
00378    *
00379    *  @ingroup sequences
00380    *
00381    *  Meets the requirements of a <a href="tables.html#65">container</a>, a
00382    *  <a href="tables.html#67">sequence</a>, including the
00383    *  <a href="tables.html#68">optional sequence requirements</a> with the
00384    *  %exception of @c at and @c operator[].
00385    *
00386    *  This is a @e singly @e linked %list.  Traversal up the
00387    *  %list requires linear time, but adding and removing elements (or
00388    *  @e nodes) is done in constant time, regardless of where the
00389    *  change takes place.  Unlike std::vector and std::deque,
00390    *  random-access iterators are not provided, so subscripting ( @c
00391    *  [] ) access is not allowed.  For algorithms which only need
00392    *  sequential access, this lack makes no difference.
00393    *
00394    *  Also unlike the other standard containers, std::forward_list provides
00395    *  specialized algorithms %unique to linked lists, such as
00396    *  splicing, sorting, and in-place reversal.
00397    *
00398    *  A couple points on memory allocation for forward_list<Tp>:
00399    *
00400    *  First, we never actually allocate a Tp, we allocate
00401    *  Fwd_list_node<Tp>'s and trust [20.1.5]/4 to DTRT.  This is to ensure
00402    *  that after elements from %forward_list<X,Alloc1> are spliced into
00403    *  %forward_list<X,Alloc2>, destroying the memory of the second %list is a
00404    *  valid operation, i.e., Alloc1 giveth and Alloc2 taketh away.
00405    */
00406   template<typename _Tp, typename _Alloc = allocator<_Tp> >
00407     class forward_list : private _Fwd_list_base<_Tp, _Alloc>
00408     {
00409     private:
00410       typedef _Fwd_list_base<_Tp, _Alloc>                  _Base;
00411       typedef _Fwd_list_node<_Tp>                          _Node;
00412       typedef _Fwd_list_node_base                          _Node_base;
00413       typedef typename _Base::_Tp_alloc_type               _Tp_alloc_type;
00414 
00415     public:
00416       // types:
00417       typedef _Tp                                          value_type;
00418       typedef typename _Tp_alloc_type::pointer             pointer;
00419       typedef typename _Tp_alloc_type::const_pointer       const_pointer;
00420       typedef typename _Tp_alloc_type::reference           reference;
00421       typedef typename _Tp_alloc_type::const_reference     const_reference;
00422  
00423       typedef _Fwd_list_iterator<_Tp>                      iterator;
00424       typedef _Fwd_list_const_iterator<_Tp>                const_iterator;
00425       typedef std::size_t                                  size_type;
00426       typedef std::ptrdiff_t                               difference_type;
00427       typedef _Alloc                                       allocator_type;
00428 
00429       // 23.2.3.1 construct/copy/destroy:
00430 
00431       /**
00432        *  @brief  Creates a %forward_list with no elements.
00433        *  @param  al  An allocator object.
00434        */
00435       explicit
00436       forward_list(const _Alloc& __al = _Alloc())
00437       : _Base(__al)
00438       { }
00439 
00440       /**
00441        *  @brief  Copy constructor with allocator argument.
00442        *  @param  list  Input list to copy.
00443        *  @param  al    An allocator object.
00444        */
00445       forward_list(const forward_list& __list, const _Alloc& __al)
00446       : _Base(__list, __al)
00447       { }
00448 
00449       /**
00450        *  @brief  Move constructor with allocator argument.
00451        *  @param  list  Input list to move.
00452        *  @param  al    An allocator object.
00453        */
00454       forward_list(forward_list&& __list, const _Alloc& __al)
00455       : _Base(std::move(__list), __al)
00456       { }
00457 
00458       /**
00459        *  @brief  Creates a %forward_list with default constructed elements.
00460        *  @param  n  The number of elements to initially create.
00461        *
00462        *  This constructor creates the %forward_list with @a n default
00463        *  constructed elements.
00464        */
00465       explicit
00466       forward_list(size_type __n)
00467       : _Base()
00468       { _M_default_initialize(__n); }
00469 
00470       /**
00471        *  @brief  Creates a %forward_list with copies of an exemplar element.
00472        *  @param  n      The number of elements to initially create.
00473        *  @param  value  An element to copy.
00474        *  @param  al     An allocator object.
00475        *
00476        *  This constructor fills the %forward_list with @a n copies of @a
00477        *  value.
00478        */
00479       forward_list(size_type __n, const _Tp& __value,
00480                    const _Alloc& __al = _Alloc())
00481       : _Base(__al)
00482       { _M_fill_initialize(__n, __value); }
00483 
00484       /**
00485        *  @brief  Builds a %forward_list from a range.
00486        *  @param  first  An input iterator.
00487        *  @param  last   An input iterator.
00488        *  @param  al     An allocator object.
00489        *
00490        *  Create a %forward_list consisting of copies of the elements from
00491        *  [@a first,@a last).  This is linear in N (where N is
00492        *  distance(@a first,@a last)).
00493        */
00494       template<typename _InputIterator>
00495         forward_list(_InputIterator __first, _InputIterator __last,
00496                      const _Alloc& __al = _Alloc())
00497         : _Base(__al)
00498         {
00499           // Check whether it's an integral type.  If so, it's not an iterator.
00500           typedef typename std::__is_integer<_InputIterator>::__type _Integral;
00501           _M_initialize_dispatch(__first, __last, _Integral());
00502         }
00503 
00504       /**
00505        *  @brief  The %forward_list copy constructor.
00506        *  @param  list  A %forward_list of identical element and allocator
00507        *                types.
00508        *
00509        *  The newly-created %forward_list uses a copy of the allocation
00510        *  object used by @a list.
00511        */
00512       forward_list(const forward_list& __list)
00513       : _Base(__list._M_get_Node_allocator())
00514       { _M_initialize_dispatch(__list.begin(), __list.end(), __false_type()); }
00515 
00516       /**
00517        *  @brief  The %forward_list move constructor.
00518        *  @param  list  A %forward_list of identical element and allocator
00519        *                types.
00520        *
00521        *  The newly-created %forward_list contains the exact contents of @a
00522        *  forward_list. The contents of @a list are a valid, but unspecified
00523        *  %forward_list.
00524        */
00525       forward_list(forward_list&& __list)
00526       : _Base(std::move(__list)) { }
00527 
00528       /**
00529        *  @brief  Builds a %forward_list from an initializer_list
00530        *  @param  il  An initializer_list of value_type.
00531        *  @param  al  An allocator object.
00532        *
00533        *  Create a %forward_list consisting of copies of the elements
00534        *  in the initializer_list @a il.  This is linear in il.size().
00535        */
00536       forward_list(std::initializer_list<_Tp> __il,
00537                    const _Alloc& __al = _Alloc())
00538       : _Base(__al)
00539       { _M_initialize_dispatch(__il.begin(), __il.end(), __false_type()); }
00540 
00541       /**
00542        *  @brief  The forward_list dtor.
00543        */
00544       ~forward_list()
00545       { }
00546 
00547       /**
00548        *  @brief  The %forward_list assignment operator.
00549        *  @param  list  A %forward_list of identical element and allocator
00550        *                types.
00551        *
00552        *  All the elements of @a list are copied, but unlike the copy
00553        *  constructor, the allocator object is not copied.
00554        */
00555       forward_list&
00556       operator=(const forward_list& __list);
00557 
00558       /**
00559        *  @brief  The %forward_list move assignment operator.
00560        *  @param  list  A %forward_list of identical element and allocator
00561        *                types.
00562        *
00563        *  The contents of @a list are moved into this %forward_list
00564        *  (without copying). @a list is a valid, but unspecified
00565        *  %forward_list
00566        */
00567       forward_list&
00568       operator=(forward_list&& __list)
00569       {
00570     // NB: DR 1204.
00571     // NB: DR 675.
00572     this->clear();
00573     this->swap(__list);
00574     return *this;
00575       }
00576 
00577       /**
00578        *  @brief  The %forward_list initializer list assignment operator.
00579        *  @param  il  An initializer_list of value_type.
00580        *
00581        *  Replace the contents of the %forward_list with copies of the
00582        *  elements in the initializer_list @a il.  This is linear in
00583        *  il.size().
00584        */
00585       forward_list&
00586       operator=(std::initializer_list<_Tp> __il)
00587       {
00588         assign(__il);
00589         return *this;
00590       }
00591 
00592       /**
00593        *  @brief  Assigns a range to a %forward_list.
00594        *  @param  first  An input iterator.
00595        *  @param  last   An input iterator.
00596        *
00597        *  This function fills a %forward_list with copies of the elements
00598        *  in the range [@a first,@a last).
00599        *
00600        *  Note that the assignment completely changes the %forward_list and
00601        *  that the resulting %forward_list's size is the same as the number
00602        *  of elements assigned.  Old data may be lost.
00603        */
00604       template<typename _InputIterator>
00605         void
00606         assign(_InputIterator __first, _InputIterator __last)
00607         {
00608           clear();
00609           insert_after(cbefore_begin(), __first, __last);
00610         }
00611 
00612       /**
00613        *  @brief  Assigns a given value to a %forward_list.
00614        *  @param  n  Number of elements to be assigned.
00615        *  @param  val  Value to be assigned.
00616        *
00617        *  This function fills a %forward_list with @a n copies of the given
00618        *  value.  Note that the assignment completely changes the
00619        *  %forward_list and that the resulting %forward_list's size is the
00620        *  same as the number of elements assigned.  Old data may be lost.
00621        */
00622       void
00623       assign(size_type __n, const _Tp& __val)
00624       {
00625         clear();
00626         insert_after(cbefore_begin(), __n, __val);
00627       }
00628 
00629       /**
00630        *  @brief  Assigns an initializer_list to a %forward_list.
00631        *  @param  il  An initializer_list of value_type.
00632        *
00633        *  Replace the contents of the %forward_list with copies of the
00634        *  elements in the initializer_list @a il.  This is linear in
00635        *  il.size().
00636        */
00637       void
00638       assign(std::initializer_list<_Tp> __il)
00639       {
00640         clear();
00641         insert_after(cbefore_begin(), __il);
00642       }
00643 
00644       /// Get a copy of the memory allocation object.
00645       allocator_type
00646       get_allocator() const
00647       { return this->_M_get_Node_allocator(); }
00648 
00649       // 23.2.3.2 iterators:
00650 
00651       /**
00652        *  Returns a read/write iterator that points before the first element
00653        *  in the %forward_list.  Iteration is done in ordinary element order.
00654        */
00655       iterator
00656       before_begin()
00657       { return iterator(&this->_M_impl._M_head); }
00658 
00659       /**
00660        *  Returns a read-only (constant) iterator that points before the
00661        *  first element in the %forward_list.  Iteration is done in ordinary
00662        *  element order.
00663        */
00664       const_iterator
00665       before_begin() const
00666       { return const_iterator(&this->_M_impl._M_head); }
00667 
00668       /**
00669        *  Returns a read/write iterator that points to the first element
00670        *  in the %forward_list.  Iteration is done in ordinary element order.
00671        */
00672       iterator
00673       begin()
00674       { return iterator(this->_M_impl._M_head._M_next); }
00675 
00676       /**
00677        *  Returns a read-only (constant) iterator that points to the first
00678        *  element in the %forward_list.  Iteration is done in ordinary
00679        *  element order.
00680        */
00681       const_iterator
00682       begin() const
00683       { return const_iterator(this->_M_impl._M_head._M_next); }
00684 
00685       /**
00686        *  Returns a read/write iterator that points one past the last
00687        *  element in the %forward_list.  Iteration is done in ordinary
00688        *  element order.
00689        */
00690       iterator
00691       end()
00692       { return iterator(0); }
00693 
00694       /**
00695        *  Returns a read-only iterator that points one past the last
00696        *  element in the %forward_list.  Iteration is done in ordinary
00697        *  element order.
00698        */
00699       const_iterator
00700       end() const
00701       { return const_iterator(0); }
00702 
00703       /**
00704        *  Returns a read-only (constant) iterator that points to the
00705        *  first element in the %forward_list.  Iteration is done in ordinary
00706        *  element order.
00707        */
00708       const_iterator
00709       cbegin() const
00710       { return const_iterator(this->_M_impl._M_head._M_next); }
00711 
00712       /**
00713        *  Returns a read-only (constant) iterator that points before the
00714        *  first element in the %forward_list.  Iteration is done in ordinary
00715        *  element order.
00716        */
00717       const_iterator
00718       cbefore_begin() const
00719       { return const_iterator(&this->_M_impl._M_head); }
00720 
00721       /**
00722        *  Returns a read-only (constant) iterator that points one past
00723        *  the last element in the %forward_list.  Iteration is done in
00724        *  ordinary element order.
00725        */
00726       const_iterator
00727       cend() const
00728       { return const_iterator(0); }
00729 
00730       /**
00731        *  Returns true if the %forward_list is empty.  (Thus begin() would
00732        *  equal end().)
00733        */
00734       bool
00735       empty() const
00736       { return this->_M_impl._M_head._M_next == 0; }
00737 
00738       /**
00739        *  Returns the largest possible size of %forward_list.
00740        */
00741       size_type
00742       max_size() const
00743       { return this->_M_get_Node_allocator().max_size(); }
00744 
00745       // 23.2.3.3 element access:
00746 
00747       /**
00748        *  Returns a read/write reference to the data at the first
00749        *  element of the %forward_list.
00750        */
00751       reference
00752       front()
00753       {
00754         _Node* __front = static_cast<_Node*>(this->_M_impl._M_head._M_next);
00755         return __front->_M_value;
00756       }
00757 
00758       /**
00759        *  Returns a read-only (constant) reference to the data at the first
00760        *  element of the %forward_list.
00761        */
00762       const_reference
00763       front() const
00764       {
00765         _Node* __front = static_cast<_Node*>(this->_M_impl._M_head._M_next);
00766         return __front->_M_value;
00767       }
00768 
00769       // 23.2.3.4 modifiers:
00770 
00771       /**
00772        *  @brief  Constructs object in %forward_list at the front of the
00773        *          list.
00774        *  @param  args  Arguments.
00775        *
00776        *  This function will insert an object of type Tp constructed
00777        *  with Tp(std::forward<Args>(args)...) at the front of the list
00778        *  Due to the nature of a %forward_list this operation can
00779        *  be done in constant time, and does not invalidate iterators
00780        *  and references.
00781        */
00782       template<typename... _Args>
00783         void
00784         emplace_front(_Args&&... __args)
00785         { this->_M_insert_after(cbefore_begin(),
00786                                 std::forward<_Args>(__args)...); }
00787 
00788       /**
00789        *  @brief  Add data to the front of the %forward_list.
00790        *  @param  val  Data to be added.
00791        *
00792        *  This is a typical stack operation.  The function creates an
00793        *  element at the front of the %forward_list and assigns the given
00794        *  data to it.  Due to the nature of a %forward_list this operation
00795        *  can be done in constant time, and does not invalidate iterators
00796        *  and references.
00797        */
00798       void
00799       push_front(const _Tp& __val)
00800       { this->_M_insert_after(cbefore_begin(), __val); }
00801 
00802       /**
00803        *
00804        */
00805       void
00806       push_front(_Tp&& __val)
00807       { this->_M_insert_after(cbefore_begin(), std::move(__val)); }
00808 
00809       /**
00810        *  @brief  Removes first element.
00811        *
00812        *  This is a typical stack operation.  It shrinks the %forward_list
00813        *  by one.  Due to the nature of a %forward_list this operation can
00814        *  be done in constant time, and only invalidates iterators/references
00815        *  to the element being removed.
00816        *
00817        *  Note that no data is returned, and if the first element's data
00818        *  is needed, it should be retrieved before pop_front() is
00819        *  called.
00820        */
00821       void
00822       pop_front()
00823       { this->_M_erase_after(&this->_M_impl._M_head); }
00824 
00825       /**
00826        *  @brief  Constructs object in %forward_list after the specified
00827        *          iterator.
00828        *  @param  pos  A const_iterator into the %forward_list.
00829        *  @param  args  Arguments.
00830        *  @return  An iterator that points to the inserted data.
00831        *
00832        *  This function will insert an object of type T constructed
00833        *  with T(std::forward<Args>(args)...) after the specified
00834        *  location.  Due to the nature of a %forward_list this operation can
00835        *  be done in constant time, and does not invalidate iterators
00836        *  and references.
00837        */
00838       template<typename... _Args>
00839         iterator
00840         emplace_after(const_iterator __pos, _Args&&... __args)
00841         { return iterator(this->_M_insert_after(__pos,
00842                                           std::forward<_Args>(__args)...)); }
00843 
00844       /**
00845        *  @brief  Inserts given value into %forward_list after specified
00846        *          iterator.
00847        *  @param  pos  An iterator into the %forward_list.
00848        *  @param  val  Data to be inserted.
00849        *  @return  An iterator that points to the inserted data.
00850        *
00851        *  This function will insert a copy of the given value after
00852        *  the specified location.  Due to the nature of a %forward_list this
00853        *  operation can be done in constant time, and does not
00854        *  invalidate iterators and references.
00855        */
00856       iterator
00857       insert_after(const_iterator __pos, const _Tp& __val)
00858       { return iterator(this->_M_insert_after(__pos, __val)); }
00859 
00860       /**
00861        *
00862        */
00863       iterator
00864       insert_after(const_iterator __pos, _Tp&& __val)
00865       { return iterator(this->_M_insert_after(__pos, std::move(__val))); }
00866 
00867       /**
00868        *  @brief  Inserts a number of copies of given data into the
00869        *          %forward_list.
00870        *  @param  pos  An iterator into the %forward_list.
00871        *  @param  n  Number of elements to be inserted.
00872        *  @param  val  Data to be inserted.
00873        *  @return  An iterator pointing to the last inserted copy of
00874        *           @a val or @a pos if @a n == 0.
00875        *
00876        *  This function will insert a specified number of copies of the
00877        *  given data after the location specified by @a pos.
00878        *
00879        *  This operation is linear in the number of elements inserted and
00880        *  does not invalidate iterators and references.
00881        */
00882       iterator
00883       insert_after(const_iterator __pos, size_type __n, const _Tp& __val);
00884 
00885       /**
00886        *  @brief  Inserts a range into the %forward_list.
00887        *  @param  position  An iterator into the %forward_list.
00888        *  @param  first  An input iterator.
00889        *  @param  last   An input iterator.
00890        *  @return  An iterator pointing to the last inserted element or
00891        *           @a pos if @a first == @a last.
00892        *
00893        *  This function will insert copies of the data in the range [@a
00894        *  first,@a last) into the %forward_list after the location specified
00895        *  by @a pos.
00896        *
00897        *  This operation is linear in the number of elements inserted and
00898        *  does not invalidate iterators and references.
00899        */
00900       template<typename _InputIterator>
00901         iterator
00902         insert_after(const_iterator __pos,
00903                      _InputIterator __first, _InputIterator __last);
00904 
00905       /**
00906        *  @brief  Inserts the contents of an initializer_list into
00907        *          %forward_list after the specified iterator.
00908        *  @param  pos  An iterator into the %forward_list.
00909        *  @param  il  An initializer_list of value_type.
00910        *  @return  An iterator pointing to the last inserted element
00911        *           or @a pos if @a il is empty.
00912        *
00913        *  This function will insert copies of the data in the
00914        *  initializer_list @a il into the %forward_list before the location
00915        *  specified by @a pos.
00916        *
00917        *  This operation is linear in the number of elements inserted and
00918        *  does not invalidate iterators and references.
00919        */
00920       iterator
00921       insert_after(const_iterator __pos, std::initializer_list<_Tp> __il);
00922 
00923       /**
00924        *  @brief  Removes the element pointed to by the iterator following
00925        *          @c pos.
00926        *  @param  pos  Iterator pointing before element to be erased.
00927        *
00928        *  This function will erase the element at the given position and
00929        *  thus shorten the %forward_list by one.
00930        *
00931        *  Due to the nature of a %forward_list this operation can be done
00932        *  in constant time, and only invalidates iterators/references to
00933        *  the element being removed.  The user is also cautioned that
00934        *  this function only erases the element, and that if the element
00935        *  is itself a pointer, the pointed-to memory is not touched in
00936        *  any way.  Managing the pointer is the user's responsibility.
00937        */
00938       void
00939       erase_after(const_iterator __pos)
00940       { this->_M_erase_after(const_cast<_Node_base*>(__pos._M_node)); }
00941 
00942       /**
00943        *  @brief  Remove a range of elements.
00944        *  @param  pos  Iterator pointing before the first element to be
00945        *               erased.
00946        *  @param  last  Iterator pointing to one past the last element to be
00947        *                erased.
00948        *
00949        *  This function will erase the elements in the range @a
00950        *  (pos,last) and shorten the %forward_list accordingly.
00951        *
00952        *  This operation is linear time in the size of the range and only
00953        *  invalidates iterators/references to the element being removed.
00954        *  The user is also cautioned that this function only erases the
00955        *  elements, and that if the elements themselves are pointers, the
00956        *  pointed-to memory is not touched in any way.  Managing the pointer
00957        *  is the user's responsibility.
00958        */
00959       void
00960       erase_after(const_iterator __pos, const_iterator __last)
00961       { this->_M_erase_after(const_cast<_Node_base*>(__pos._M_node),
00962                  const_cast<_Node_base*>(__last._M_node)); }
00963 
00964       /**
00965        *  @brief  Swaps data with another %forward_list.
00966        *  @param  list  A %forward_list of the same element and allocator
00967        *                types.
00968        *
00969        *  This exchanges the elements between two lists in constant
00970        *  time.  Note that the global std::swap() function is
00971        *  specialized such that std::swap(l1,l2) will feed to this
00972        *  function.
00973        */
00974       void
00975       swap(forward_list& __list)
00976       { _Node_base::swap(this->_M_impl._M_head, __list._M_impl._M_head); }
00977 
00978       /**
00979        *  @brief Resizes the %forward_list to the specified number of
00980        *         elements.
00981        *  @param sz Number of elements the %forward_list should contain.
00982        *
00983        *  This function will %resize the %forward_list to the specified
00984        *  number of elements.  If the number is smaller than the
00985        *  %forward_list's current size the %forward_list is truncated,
00986        *  otherwise the %forward_list is extended and the new elements
00987        *  are default constructed.
00988        */
00989       void
00990       resize(size_type __sz);
00991 
00992       /**
00993        *  @brief Resizes the %forward_list to the specified number of
00994        *         elements.
00995        *  @param sz Number of elements the %forward_list should contain.
00996        *  @param val Data with which new elements should be populated.
00997        *
00998        *  This function will %resize the %forward_list to the specified
00999        *  number of elements.  If the number is smaller than the
01000        *  %forward_list's current size the %forward_list is truncated,
01001        *  otherwise the %forward_list is extended and new elements are
01002        *  populated with given data.
01003        */
01004       void
01005       resize(size_type __sz, const value_type& __val);
01006 
01007       /**
01008        *  @brief  Erases all the elements.
01009        *
01010        *  Note that this function only erases
01011        *  the elements, and that if the elements themselves are
01012        *  pointers, the pointed-to memory is not touched in any way.
01013        *  Managing the pointer is the user's responsibility.
01014        */
01015       void
01016       clear()
01017       { this->_M_erase_after(&this->_M_impl._M_head, 0); }
01018 
01019       // 23.2.3.5 forward_list operations:
01020 
01021       /**
01022        *  @brief  Insert contents of another %forward_list.
01023        *  @param  pos  Iterator referencing the element to insert after.
01024        *  @param  list  Source list.
01025        *
01026        *  The elements of @a list are inserted in constant time after
01027        *  the element referenced by @a pos.  @a list becomes an empty
01028        *  list.
01029        *
01030        *  Requires this != @a x.
01031        */
01032       void
01033       splice_after(const_iterator __pos, forward_list&& __list)
01034       {
01035     if (!__list.empty())
01036       _M_splice_after(__pos, std::move(__list));
01037       }
01038 
01039       /**
01040        *  @brief  Insert element from another %forward_list.
01041        *  @param  pos  Iterator referencing the element to insert after.
01042        *  @param  list  Source list.
01043        *  @param  i   Iterator referencing the element before the element
01044        *              to move.
01045        *
01046        *  Removes the element in list @a list referenced by @a i and
01047        *  inserts it into the current list after @a pos.
01048        */
01049       void
01050       splice_after(const_iterator __pos, forward_list&& __list,
01051                    const_iterator __i)
01052       {
01053     const_iterator __j = __i;
01054     ++__j;
01055     if (__pos == __i || __pos == __j)
01056       return;
01057 
01058     splice_after(__pos, std::move(__list), __i, __j);
01059       }
01060 
01061       /**
01062        *  @brief  Insert range from another %forward_list.
01063        *  @param  pos  Iterator referencing the element to insert after.
01064        *  @param  list  Source list.
01065        *  @param  before  Iterator referencing before the start of range
01066        *                  in list.
01067        *  @param  last  Iterator referencing the end of range in list.
01068        *
01069        *  Removes elements in the range (before,last) and inserts them
01070        *  after @a pos in constant time.
01071        *
01072        *  Undefined if @a pos is in (before,last).
01073        */
01074       void
01075       splice_after(const_iterator __pos, forward_list&& __list,
01076                    const_iterator __before, const_iterator __last);
01077 
01078       /**
01079        *  @brief  Remove all elements equal to value.
01080        *  @param  val  The value to remove.
01081        *
01082        *  Removes every element in the list equal to @a value.
01083        *  Remaining elements stay in list order.  Note that this
01084        *  function only erases the elements, and that if the elements
01085        *  themselves are pointers, the pointed-to memory is not
01086        *  touched in any way.  Managing the pointer is the user's
01087        *  responsibility.
01088        */
01089       void
01090       remove(const _Tp& __val);
01091 
01092       /**
01093        *  @brief  Remove all elements satisfying a predicate.
01094        *  @param  pred  Unary predicate function or object.
01095        *
01096        *  Removes every element in the list for which the predicate
01097        *  returns true.  Remaining elements stay in list order.  Note
01098        *  that this function only erases the elements, and that if the
01099        *  elements themselves are pointers, the pointed-to memory is
01100        *  not touched in any way.  Managing the pointer is the user's
01101        *  responsibility.
01102        */
01103       template<typename _Pred>
01104         void
01105         remove_if(_Pred __pred);
01106 
01107       /**
01108        *  @brief  Remove consecutive duplicate elements.
01109        *
01110        *  For each consecutive set of elements with the same value,
01111        *  remove all but the first one.  Remaining elements stay in
01112        *  list order.  Note that this function only erases the
01113        *  elements, and that if the elements themselves are pointers,
01114        *  the pointed-to memory is not touched in any way.  Managing
01115        *  the pointer is the user's responsibility.
01116        */
01117       void
01118       unique()
01119       { this->unique(std::equal_to<_Tp>()); }
01120 
01121       /**
01122        *  @brief  Remove consecutive elements satisfying a predicate.
01123        *  @param  binary_pred  Binary predicate function or object.
01124        *
01125        *  For each consecutive set of elements [first,last) that
01126        *  satisfy predicate(first,i) where i is an iterator in
01127        *  [first,last), remove all but the first one.  Remaining
01128        *  elements stay in list order.  Note that this function only
01129        *  erases the elements, and that if the elements themselves are
01130        *  pointers, the pointed-to memory is not touched in any way.
01131        *  Managing the pointer is the user's responsibility.
01132        */
01133       template<typename _BinPred>
01134         void
01135         unique(_BinPred __binary_pred);
01136 
01137       /**
01138        *  @brief  Merge sorted lists.
01139        *  @param  list  Sorted list to merge.
01140        *
01141        *  Assumes that both @a list and this list are sorted according to
01142        *  operator<().  Merges elements of @a list into this list in
01143        *  sorted order, leaving @a list empty when complete.  Elements in
01144        *  this list precede elements in @a list that are equal.
01145        */
01146       void
01147       merge(forward_list&& __list)
01148       { this->merge(std::move(__list), std::less<_Tp>()); }
01149 
01150       /**
01151        *  @brief  Merge sorted lists according to comparison function.
01152        *  @param  list  Sorted list to merge.
01153        *  @param  comp Comparison function defining sort order.
01154        *
01155        *  Assumes that both @a list and this list are sorted according to
01156        *  comp.  Merges elements of @a list into this list
01157        *  in sorted order, leaving @a list empty when complete.  Elements
01158        *  in this list precede elements in @a list that are equivalent
01159        *  according to comp().
01160        */
01161       template<typename _Comp>
01162         void
01163         merge(forward_list&& __list, _Comp __comp);
01164 
01165       /**
01166        *  @brief  Sort the elements of the list.
01167        *
01168        *  Sorts the elements of this list in NlogN time.  Equivalent
01169        *  elements remain in list order.
01170        */
01171       void
01172       sort()
01173       { this->sort(std::less<_Tp>()); }
01174 
01175       /**
01176        *  @brief  Sort the forward_list using a comparison function.
01177        *
01178        *  Sorts the elements of this list in NlogN time.  Equivalent
01179        *  elements remain in list order.
01180        */
01181       template<typename _Comp>
01182         void
01183         sort(_Comp __comp);
01184 
01185       /**
01186        *  @brief  Reverse the elements in list.
01187        *
01188        *  Reverse the order of elements in the list in linear time.
01189        */
01190       void
01191       reverse()
01192       { this->_M_impl._M_head._M_reverse_after(); }
01193 
01194     private:
01195       template<typename _Integer>
01196         void
01197         _M_initialize_dispatch(_Integer __n, _Integer __x, __true_type)
01198         { _M_fill_initialize(static_cast<size_type>(__n), __x); }
01199 
01200       // Called by the range constructor to implement [23.1.1]/9
01201       template<typename _InputIterator>
01202         void
01203         _M_initialize_dispatch(_InputIterator __first, _InputIterator __last,
01204                                __false_type);
01205 
01206       // Called by forward_list(n,v,a), and the range constructor when it
01207       // turns out to be the same thing.
01208       void
01209       _M_fill_initialize(size_type __n, const value_type& __value);
01210 
01211       // Called by splice_after and insert_after.
01212       iterator
01213       _M_splice_after(const_iterator __pos, forward_list&& __list);
01214 
01215       // Called by forward_list(n).
01216       void
01217       _M_default_initialize(size_type __n);
01218 
01219       // Called by resize(sz).
01220       void
01221       _M_default_insert_after(const_iterator __pos, size_type __n);
01222     };
01223 
01224   /**
01225    *  @brief  Forward list equality comparison.
01226    *  @param  lx  A %forward_list
01227    *  @param  ly  A %forward_list of the same type as @a lx.
01228    *  @return  True iff the size and elements of the forward lists are equal.
01229    *
01230    *  This is an equivalence relation.  It is linear in the size of the
01231    *  forward lists.  Deques are considered equivalent if corresponding
01232    *  elements compare equal.
01233    */
01234   template<typename _Tp, typename _Alloc>
01235     bool
01236     operator==(const forward_list<_Tp, _Alloc>& __lx,
01237                const forward_list<_Tp, _Alloc>& __ly);
01238 
01239   /**
01240    *  @brief  Forward list ordering relation.
01241    *  @param  lx  A %forward_list.
01242    *  @param  ly  A %forward_list of the same type as @a lx.
01243    *  @return  True iff @a lx is lexicographically less than @a ly.
01244    *
01245    *  This is a total ordering relation.  It is linear in the size of the
01246    *  forward lists.  The elements must be comparable with @c <.
01247    *
01248    *  See std::lexicographical_compare() for how the determination is made.
01249    */
01250   template<typename _Tp, typename _Alloc>
01251     inline bool
01252     operator<(const forward_list<_Tp, _Alloc>& __lx,
01253               const forward_list<_Tp, _Alloc>& __ly)
01254     { return std::lexicographical_compare(__lx.cbegin(), __lx.cend(),
01255                       __ly.cbegin(), __ly.cend()); }
01256 
01257   /// Based on operator==
01258   template<typename _Tp, typename _Alloc>
01259     inline bool
01260     operator!=(const forward_list<_Tp, _Alloc>& __lx,
01261                const forward_list<_Tp, _Alloc>& __ly)
01262     { return !(__lx == __ly); }
01263 
01264   /// Based on operator<
01265   template<typename _Tp, typename _Alloc>
01266     inline bool
01267     operator>(const forward_list<_Tp, _Alloc>& __lx,
01268               const forward_list<_Tp, _Alloc>& __ly)
01269     { return (__ly < __lx); }
01270 
01271   /// Based on operator<
01272   template<typename _Tp, typename _Alloc>
01273     inline bool
01274     operator>=(const forward_list<_Tp, _Alloc>& __lx,
01275                const forward_list<_Tp, _Alloc>& __ly)
01276     { return !(__lx < __ly); }
01277 
01278   /// Based on operator<
01279   template<typename _Tp, typename _Alloc>
01280     inline bool
01281     operator<=(const forward_list<_Tp, _Alloc>& __lx,
01282                const forward_list<_Tp, _Alloc>& __ly)
01283     { return !(__ly < __lx); }
01284 
01285   /// See std::forward_list::swap().
01286   template<typename _Tp, typename _Alloc>
01287     inline void
01288     swap(forward_list<_Tp, _Alloc>& __lx,
01289      forward_list<_Tp, _Alloc>& __ly)
01290     { __lx.swap(__ly); }
01291 
01292 _GLIBCXX_END_NESTED_NAMESPACE // namespace std
01293 
01294 #endif // _FORWARD_LIST_H