OSDN Git Service

15f73914a2df33fe98e101434098d0276a22510f
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / include / bits / stl_list.h
1 // List implementation -*- C++ -*-
2
3 // Copyright (C) 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library.  This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 2, or (at your option)
9 // any later version.
10
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 // GNU General Public License for more details.
15
16 // You should have received a copy of the GNU General Public License along
17 // with this library; see the file COPYING.  If not, write to the Free
18 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
19 // USA.
20
21 // As a special exception, you may use this file as part of a free software
22 // library without restriction.  Specifically, if other files instantiate
23 // templates or use macros or inline functions from this file, or you compile
24 // this file and link it with other files to produce an executable, this
25 // file does not by itself cause the resulting executable to be covered by
26 // the GNU General Public License.  This exception does not however
27 // invalidate any other reasons why the executable file might be covered by
28 // the GNU General Public License.
29
30 /*
31  *
32  * Copyright (c) 1994
33  * Hewlett-Packard Company
34  *
35  * Permission to use, copy, modify, distribute and sell this software
36  * and its documentation for any purpose is hereby granted without fee,
37  * provided that the above copyright notice appear in all copies and
38  * that both that copyright notice and this permission notice appear
39  * in supporting documentation.  Hewlett-Packard Company makes no
40  * representations about the suitability of this software for any
41  * purpose.  It is provided "as is" without express or implied warranty.
42  *
43  *
44  * Copyright (c) 1996,1997
45  * Silicon Graphics Computer Systems, Inc.
46  *
47  * Permission to use, copy, modify, distribute and sell this software
48  * and its documentation for any purpose is hereby granted without fee,
49  * provided that the above copyright notice appear in all copies and
50  * that both that copyright notice and this permission notice appear
51  * in supporting documentation.  Silicon Graphics makes no
52  * representations about the suitability of this software for any
53  * purpose.  It is provided "as is" without express or implied warranty.
54  */
55
56 /** @file stl_list.h
57  *  This is an internal header file, included by other library headers.
58  *  You should not attempt to use it directly.
59  */
60
61 #ifndef _LIST_H
62 #define _LIST_H 1
63
64 #include <bits/concept_check.h>
65
66 namespace __gnu_norm
67 {
68   // Supporting structures are split into common and templated types; the
69   // latter publicly inherits from the former in an effort to reduce code
70   // duplication.  This results in some "needless" static_cast'ing later on,
71   // but it's all safe downcasting.
72
73   /// @if maint Common part of a node in the %list.  @endif
74   struct _List_node_base
75   {
76     _List_node_base* _M_next;   ///< Self-explanatory
77     _List_node_base* _M_prev;   ///< Self-explanatory
78
79     static void
80     swap(_List_node_base& __x, _List_node_base& __y);
81
82     void
83     transfer(_List_node_base * const __first,
84              _List_node_base * const __last);
85
86     void
87     reverse();
88
89     void
90     hook(_List_node_base * const __position);
91
92     void
93     unhook();
94   };
95
96   /// @if maint An actual node in the %list.  @endif
97   template<typename _Tp>
98     struct _List_node : public _List_node_base
99     {
100       _Tp _M_data;                ///< User's data.
101     };
102
103   /**
104    *  @brief A list::iterator.
105    *
106    *  @if maint
107    *  All the functions are op overloads.
108    *  @endif
109   */
110   template<typename _Tp>
111     struct _List_iterator
112     {
113       typedef _List_iterator<_Tp>           _Self;
114       typedef _List_node<_Tp>               _Node;
115
116       typedef ptrdiff_t                     difference_type;
117       typedef bidirectional_iterator_tag    iterator_category;
118       typedef _Tp                           value_type;
119       typedef _Tp*                          pointer;
120       typedef _Tp&                          reference;
121
122       _List_iterator() { }
123
124       _List_iterator(_List_node_base* __x)
125       : _M_node(__x) { }
126
127       // Must downcast from List_node_base to _List_node to get to _M_data.
128       reference
129       operator*() const
130       { return static_cast<_Node*>(_M_node)->_M_data; }
131
132       pointer
133       operator->() const
134       { return &static_cast<_Node*>(_M_node)->_M_data; }
135
136       _Self&
137       operator++()
138       {
139         _M_node = _M_node->_M_next;
140         return *this;
141       }
142
143       _Self
144       operator++(int)
145       {
146         _Self __tmp = *this;
147         _M_node = _M_node->_M_next;
148         return __tmp;
149       }
150
151       _Self&
152       operator--()
153       {
154         _M_node = _M_node->_M_prev;
155         return *this;
156       }
157
158       _Self
159       operator--(int)
160       {
161         _Self __tmp = *this;
162         _M_node = _M_node->_M_prev;
163         return __tmp;
164       }
165
166       bool
167       operator==(const _Self& __x) const
168       { return _M_node == __x._M_node; }
169
170       bool
171       operator!=(const _Self& __x) const
172       { return _M_node != __x._M_node; }
173
174       // The only member points to the %list element.
175       _List_node_base* _M_node;
176     };
177
178   /**
179    *  @brief A list::const_iterator.
180    *
181    *  @if maint
182    *  All the functions are op overloads.
183    *  @endif
184   */
185   template<typename _Tp>
186     struct _List_const_iterator
187     {
188       typedef _List_const_iterator<_Tp>     _Self;
189       typedef const _List_node<_Tp>         _Node;
190       typedef _List_iterator<_Tp>           iterator;
191
192       typedef ptrdiff_t                     difference_type;
193       typedef bidirectional_iterator_tag    iterator_category;
194       typedef _Tp                           value_type;
195       typedef const _Tp*                    pointer;
196       typedef const _Tp&                    reference;
197
198       _List_const_iterator() { }
199
200       _List_const_iterator(const _List_node_base* __x)
201       : _M_node(__x) { }
202
203       _List_const_iterator(const iterator& __x)
204       : _M_node(__x._M_node) { }
205
206       // Must downcast from List_node_base to _List_node to get to
207       // _M_data.
208       reference
209       operator*() const
210       { return static_cast<_Node*>(_M_node)->_M_data; }
211
212       pointer
213       operator->() const
214       { return &static_cast<_Node*>(_M_node)->_M_data; }
215
216       _Self&
217       operator++()
218       {
219         _M_node = _M_node->_M_next;
220         return *this;
221       }
222
223       _Self
224       operator++(int)
225       {
226         _Self __tmp = *this;
227         _M_node = _M_node->_M_next;
228         return __tmp;
229       }
230
231       _Self&
232       operator--()
233       {
234         _M_node = _M_node->_M_prev;
235         return *this;
236       }
237
238       _Self
239       operator--(int)
240       {
241         _Self __tmp = *this;
242         _M_node = _M_node->_M_prev;
243         return __tmp;
244       }
245
246       bool
247       operator==(const _Self& __x) const
248       { return _M_node == __x._M_node; }
249
250       bool
251       operator!=(const _Self& __x) const
252       { return _M_node != __x._M_node; }
253
254       // The only member points to the %list element.
255       const _List_node_base* _M_node;
256     };
257
258   template<typename _Val>
259     inline bool
260     operator==(const _List_iterator<_Val>& __x,
261                const _List_const_iterator<_Val>& __y)
262     { return __x._M_node == __y._M_node; }
263
264   template<typename _Val>
265     inline bool
266     operator!=(const _List_iterator<_Val>& __x,
267                const _List_const_iterator<_Val>& __y)
268     { return __x._M_node != __y._M_node; }
269
270
271   /**
272    *  @if maint
273    *  See bits/stl_deque.h's _Deque_base for an explanation.
274    *  @endif
275   */
276   template<typename _Tp, typename _Alloc>
277     class _List_base
278     : public _Alloc::template rebind<_List_node<_Tp> >::other
279     {
280     protected:
281       // NOTA BENE
282       // The stored instance is not actually of "allocator_type"'s
283       // type.  Instead we rebind the type to
284       // Allocator<List_node<Tp>>, which according to [20.1.5]/4
285       // should probably be the same.  List_node<Tp> is not the same
286       // size as Tp (it's two pointers larger), and specializations on
287       // Tp may go unused because List_node<Tp> is being bound
288       // instead.
289       //
290       // We put this to the test in the constructors and in
291       // get_allocator, where we use conversions between
292       // allocator_type and _Node_Alloc_type. The conversion is
293       // required by table 32 in [20.1.5].
294       typedef typename _Alloc::template rebind<_List_node<_Tp> >::other
295
296       _Node_Alloc_type;
297
298       _List_node_base _M_node;
299
300       _List_node<_Tp>*
301       _M_get_node()
302       { return _Node_Alloc_type::allocate(1); }
303
304       void
305       _M_put_node(_List_node<_Tp>* __p)
306       { _Node_Alloc_type::deallocate(__p, 1); }
307
308   public:
309       typedef _Alloc allocator_type;
310
311       allocator_type
312       get_allocator() const
313       { return allocator_type(*static_cast<const _Node_Alloc_type*>(this)); }
314
315       _List_base(const allocator_type& __a)
316       : _Node_Alloc_type(__a)
317       { _M_init(); }
318
319       // This is what actually destroys the list.
320       ~_List_base()
321       { _M_clear(); }
322
323       void
324       _M_clear();
325
326       void
327       _M_init()
328       {
329         this->_M_node._M_next = &this->_M_node;
330         this->_M_node._M_prev = &this->_M_node;
331       }
332     };
333
334   /**
335    *  @brief A standard container with linear time access to elements,
336    *  and fixed time insertion/deletion at any point in the sequence.
337    *
338    *  @ingroup Containers
339    *  @ingroup Sequences
340    *
341    *  Meets the requirements of a <a href="tables.html#65">container</a>, a
342    *  <a href="tables.html#66">reversible container</a>, and a
343    *  <a href="tables.html#67">sequence</a>, including the
344    *  <a href="tables.html#68">optional sequence requirements</a> with the
345    *  %exception of @c at and @c operator[].
346    *
347    *  This is a @e doubly @e linked %list.  Traversal up and down the
348    *  %list requires linear time, but adding and removing elements (or
349    *  @e nodes) is done in constant time, regardless of where the
350    *  change takes place.  Unlike std::vector and std::deque,
351    *  random-access iterators are not provided, so subscripting ( @c
352    *  [] ) access is not allowed.  For algorithms which only need
353    *  sequential access, this lack makes no difference.
354    *
355    *  Also unlike the other standard containers, std::list provides
356    *  specialized algorithms %unique to linked lists, such as
357    *  splicing, sorting, and in-place reversal.
358    *
359    *  @if maint
360    *  A couple points on memory allocation for list<Tp>:
361    *
362    *  First, we never actually allocate a Tp, we allocate
363    *  List_node<Tp>'s and trust [20.1.5]/4 to DTRT.  This is to ensure
364    *  that after elements from %list<X,Alloc1> are spliced into
365    *  %list<X,Alloc2>, destroying the memory of the second %list is a
366    *  valid operation, i.e., Alloc1 giveth and Alloc2 taketh away.
367    *
368    *  Second, a %list conceptually represented as
369    *  @code
370    *    A <---> B <---> C <---> D
371    *  @endcode
372    *  is actually circular; a link exists between A and D.  The %list
373    *  class holds (as its only data member) a private list::iterator
374    *  pointing to @e D, not to @e A!  To get to the head of the %list,
375    *  we start at the tail and move forward by one.  When this member
376    *  iterator's next/previous pointers refer to itself, the %list is
377    *  %empty.  @endif
378   */
379   template<typename _Tp, typename _Alloc = allocator<_Tp> >
380     class list : protected _List_base<_Tp, _Alloc>
381     {
382       // concept requirements
383       __glibcxx_class_requires(_Tp, _SGIAssignableConcept)
384
385       typedef _List_base<_Tp, _Alloc>                   _Base;
386
387     public:
388       typedef _Tp                                       value_type;
389       typedef value_type*                               pointer;
390       typedef const value_type*                         const_pointer;
391       typedef _List_iterator<_Tp>                       iterator;
392       typedef _List_const_iterator<_Tp>                 const_iterator;
393       typedef std::reverse_iterator<const_iterator>     const_reverse_iterator;
394       typedef std::reverse_iterator<iterator>           reverse_iterator;
395       typedef value_type&                               reference;
396       typedef const value_type&                         const_reference;
397       typedef size_t                                    size_type;
398       typedef ptrdiff_t                                 difference_type;
399       typedef typename _Base::allocator_type            allocator_type;
400
401     protected:
402       // Note that pointers-to-_Node's can be ctor-converted to
403       // iterator types.
404       typedef _List_node<_Tp>                           _Node;
405
406       /** @if maint
407        *  One data member plus two memory-handling functions.  If the
408        *  _Alloc type requires separate instances, then one of those
409        *  will also be included, accumulated from the topmost parent.
410        *  @endif
411        */
412       using _Base::_M_node;
413       using _Base::_M_put_node;
414       using _Base::_M_get_node;
415
416       /**
417        *  @if maint
418        *  @param  x  An instance of user data.
419        *
420        *  Allocates space for a new node and constructs a copy of @a x in it.
421        *  @endif
422        */
423       _Node*
424       _M_create_node(const value_type& __x)
425       {
426         _Node* __p = this->_M_get_node();
427         try
428           {
429             std::_Construct(&__p->_M_data, __x);
430           }
431         catch(...)
432           {
433             _M_put_node(__p);
434             __throw_exception_again;
435           }
436         return __p;
437       }
438
439       /**
440        *  @if maint
441        *  Allocates space for a new node and default-constructs a new
442        *  instance of @c value_type in it.
443        *  @endif
444        */
445       _Node*
446       _M_create_node()
447       {
448         _Node* __p = this->_M_get_node();
449         try
450           {
451             std::_Construct(&__p->_M_data);
452           }
453         catch(...)
454           {
455             _M_put_node(__p);
456             __throw_exception_again;
457           }
458         return __p;
459       }
460
461     public:
462       // [23.2.2.1] construct/copy/destroy
463       // (assign() and get_allocator() are also listed in this section)
464       /**
465        *  @brief  Default constructor creates no elements.
466        */
467       explicit
468       list(const allocator_type& __a = allocator_type())
469       : _Base(__a) { }
470
471       /**
472        *  @brief  Create a %list with copies of an exemplar element.
473        *  @param  n  The number of elements to initially create.
474        *  @param  value  An element to copy.
475        *
476        *  This constructor fills the %list with @a n copies of @a value.
477        */
478       list(size_type __n, const value_type& __value,
479            const allocator_type& __a = allocator_type())
480       : _Base(__a)
481       { this->insert(begin(), __n, __value); }
482
483       /**
484        *  @brief  Create a %list with default elements.
485        *  @param  n  The number of elements to initially create.
486        *
487        *  This constructor fills the %list with @a n copies of a
488        *  default-constructed element.
489        */
490       explicit
491       list(size_type __n)
492       : _Base(allocator_type())
493       { this->insert(begin(), __n, value_type()); }
494
495       /**
496        *  @brief  %List copy constructor.
497        *  @param  x  A %list of identical element and allocator types.
498        *
499        *  The newly-created %list uses a copy of the allocation object used
500        *  by @a x.
501        */
502       list(const list& __x)
503       : _Base(__x.get_allocator())
504       { this->insert(begin(), __x.begin(), __x.end()); }
505
506       /**
507        *  @brief  Builds a %list from a range.
508        *  @param  first  An input iterator.
509        *  @param  last  An input iterator.
510        *
511        *  Create a %list consisting of copies of the elements from
512        *  [@a first,@a last).  This is linear in N (where N is
513        *  distance(@a first,@a last)).
514        *
515        *  @if maint
516        *  We don't need any dispatching tricks here, because insert does all of
517        *  that anyway.
518        *  @endif
519        */
520       template<typename _InputIterator>
521         list(_InputIterator __first, _InputIterator __last,
522              const allocator_type& __a = allocator_type())
523         : _Base(__a)
524         { this->insert(begin(), __first, __last); }
525
526       /**
527        *  No explicit dtor needed as the _Base dtor takes care of
528        *  things.  The _Base dtor only erases the elements, and note
529        *  that if the elements themselves are pointers, the pointed-to
530        *  memory is not touched in any way.  Managing the pointer is
531        *  the user's responsibilty.
532        */
533
534       /**
535        *  @brief  %List assignment operator.
536        *  @param  x  A %list of identical element and allocator types.
537        *
538        *  All the elements of @a x are copied, but unlike the copy
539        *  constructor, the allocator object is not copied.
540        */
541       list&
542       operator=(const list& __x);
543
544       /**
545        *  @brief  Assigns a given value to a %list.
546        *  @param  n  Number of elements to be assigned.
547        *  @param  val  Value to be assigned.
548        *
549        *  This function fills a %list with @a n copies of the given
550        *  value.  Note that the assignment completely changes the %list
551        *  and that the resulting %list's size is the same as the number
552        *  of elements assigned.  Old data may be lost.
553        */
554       void
555       assign(size_type __n, const value_type& __val)
556       { _M_fill_assign(__n, __val); }
557
558       /**
559        *  @brief  Assigns a range to a %list.
560        *  @param  first  An input iterator.
561        *  @param  last   An input iterator.
562        *
563        *  This function fills a %list with copies of the elements in the
564        *  range [@a first,@a last).
565        *
566        *  Note that the assignment completely changes the %list and
567        *  that the resulting %list's size is the same as the number of
568        *  elements assigned.  Old data may be lost.
569        */
570       template<typename _InputIterator>
571         void
572         assign(_InputIterator __first, _InputIterator __last)
573         {
574           // Check whether it's an integral type.  If so, it's not an iterator.
575           typedef typename _Is_integer<_InputIterator>::_Integral _Integral;
576           _M_assign_dispatch(__first, __last, _Integral());
577         }
578
579       /// Get a copy of the memory allocation object.
580       allocator_type
581       get_allocator() const
582       { return _Base::get_allocator(); }
583
584       // iterators
585       /**
586        *  Returns a read/write iterator that points to the first element in the
587        *  %list.  Iteration is done in ordinary element order.
588        */
589       iterator
590       begin()
591       { return this->_M_node._M_next; }
592
593       /**
594        *  Returns a read-only (constant) iterator that points to the
595        *  first element in the %list.  Iteration is done in ordinary
596        *  element order.
597        */
598       const_iterator
599       begin() const
600       { return this->_M_node._M_next; }
601
602       /**
603        *  Returns a read/write iterator that points one past the last
604        *  element in the %list.  Iteration is done in ordinary element
605        *  order.
606        */
607       iterator
608       end() { return &this->_M_node; }
609
610       /**
611        *  Returns a read-only (constant) iterator that points one past
612        *  the last element in the %list.  Iteration is done in ordinary
613        *  element order.
614        */
615       const_iterator
616       end() const
617       { return &this->_M_node; }
618
619       /**
620        *  Returns a read/write reverse iterator that points to the last
621        *  element in the %list.  Iteration is done in reverse element
622        *  order.
623        */
624       reverse_iterator
625       rbegin()
626       { return reverse_iterator(end()); }
627
628       /**
629        *  Returns a read-only (constant) reverse iterator that points to
630        *  the last element in the %list.  Iteration is done in reverse
631        *  element order.
632        */
633       const_reverse_iterator
634       rbegin() const
635       { return const_reverse_iterator(end()); }
636
637       /**
638        *  Returns a read/write reverse iterator that points to one
639        *  before the first element in the %list.  Iteration is done in
640        *  reverse element order.
641        */
642       reverse_iterator
643       rend()
644       { return reverse_iterator(begin()); }
645
646       /**
647        *  Returns a read-only (constant) reverse iterator that points to one
648        *  before the first element in the %list.  Iteration is done in reverse
649        *  element order.
650        */
651       const_reverse_iterator
652       rend() const
653       { return const_reverse_iterator(begin()); }
654
655       // [23.2.2.2] capacity
656       /**
657        *  Returns true if the %list is empty.  (Thus begin() would equal
658        *  end().)
659        */
660       bool
661       empty() const
662       { return this->_M_node._M_next == &this->_M_node; }
663
664       /**  Returns the number of elements in the %list.  */
665       size_type
666       size() const
667       { return std::distance(begin(), end()); }
668
669       /**  Returns the size() of the largest possible %list.  */
670       size_type
671       max_size() const
672       { return size_type(-1); }
673
674       /**
675        *  @brief Resizes the %list to the specified number of elements.
676        *  @param new_size Number of elements the %list should contain.
677        *  @param x Data with which new elements should be populated.
678        *
679        *  This function will %resize the %list to the specified number
680        *  of elements.  If the number is smaller than the %list's
681        *  current size the %list is truncated, otherwise the %list is
682        *  extended and new elements are populated with given data.
683        */
684       void
685       resize(size_type __new_size, const value_type& __x);
686
687       /**
688        *  @brief  Resizes the %list to the specified number of elements.
689        *  @param  new_size  Number of elements the %list should contain.
690        *
691        *  This function will resize the %list to the specified number of
692        *  elements.  If the number is smaller than the %list's current
693        *  size the %list is truncated, otherwise the %list is extended
694        *  and new elements are default-constructed.
695        */
696       void
697       resize(size_type __new_size)
698       { this->resize(__new_size, value_type()); }
699
700       // element access
701       /**
702        *  Returns a read/write reference to the data at the first
703        *  element of the %list.
704        */
705       reference
706       front()
707       { return *begin(); }
708
709       /**
710        *  Returns a read-only (constant) reference to the data at the first
711        *  element of the %list.
712        */
713       const_reference
714       front() const
715       { return *begin(); }
716
717       /**
718        *  Returns a read/write reference to the data at the last element
719        *  of the %list.
720        */
721       reference
722       back()
723       { return *(--end()); }
724
725       /**
726        *  Returns a read-only (constant) reference to the data at the last
727        *  element of the %list.
728        */
729       const_reference
730       back() const
731       { return *(--end()); }
732
733       // [23.2.2.3] modifiers
734       /**
735        *  @brief  Add data to the front of the %list.
736        *  @param  x  Data to be added.
737        *
738        *  This is a typical stack operation.  The function creates an
739        *  element at the front of the %list and assigns the given data
740        *  to it.  Due to the nature of a %list this operation can be
741        *  done in constant time, and does not invalidate iterators and
742        *  references.
743        */
744       void
745       push_front(const value_type& __x)
746       { this->_M_insert(begin(), __x); }
747
748       /**
749        *  @brief  Removes first element.
750        *
751        *  This is a typical stack operation.  It shrinks the %list by
752        *  one.  Due to the nature of a %list this operation can be done
753        *  in constant time, and only invalidates iterators/references to
754        *  the element being removed.
755        *
756        *  Note that no data is returned, and if the first element's data
757        *  is needed, it should be retrieved before pop_front() is
758        *  called.
759        */
760       void
761       pop_front()
762       { this->_M_erase(begin()); }
763
764       /**
765        *  @brief  Add data to the end of the %list.
766        *  @param  x  Data to be added.
767        *
768        *  This is a typical stack operation.  The function creates an
769        *  element at the end of the %list and assigns the given data to
770        *  it.  Due to the nature of a %list this operation can be done
771        *  in constant time, and does not invalidate iterators and
772        *  references.
773        */
774       void
775       push_back(const value_type& __x)
776       { this->_M_insert(end(), __x); }
777
778       /**
779        *  @brief  Removes last element.
780        *
781        *  This is a typical stack operation.  It shrinks the %list by
782        *  one.  Due to the nature of a %list this operation can be done
783        *  in constant time, and only invalidates iterators/references to
784        *  the element being removed.
785        *
786        *  Note that no data is returned, and if the last element's data
787        *  is needed, it should be retrieved before pop_back() is called.
788        */
789       void
790       pop_back()
791       { this->_M_erase(this->_M_node._M_prev); }
792
793       /**
794        *  @brief  Inserts given value into %list before specified iterator.
795        *  @param  position  An iterator into the %list.
796        *  @param  x  Data to be inserted.
797        *  @return  An iterator that points to the inserted data.
798        *
799        *  This function will insert a copy of the given value before
800        *  the specified location.  Due to the nature of a %list this
801        *  operation can be done in constant time, and does not
802        *  invalidate iterators and references.
803        */
804       iterator
805       insert(iterator __position, const value_type& __x);
806
807       /**
808        *  @brief  Inserts a number of copies of given data into the %list.
809        *  @param  position  An iterator into the %list.
810        *  @param  n  Number of elements to be inserted.
811        *  @param  x  Data to be inserted.
812        *
813        *  This function will insert a specified number of copies of the
814        *  given data before the location specified by @a position.
815        *
816        *  Due to the nature of a %list this operation can be done in
817        *  constant time, and does not invalidate iterators and
818        *  references.
819        */
820       void
821       insert(iterator __position, size_type __n, const value_type& __x)
822       { _M_fill_insert(__position, __n, __x); }
823
824       /**
825        *  @brief  Inserts a range into the %list.
826        *  @param  position  An iterator into the %list.
827        *  @param  first  An input iterator.
828        *  @param  last   An input iterator.
829        *
830        *  This function will insert copies of the data in the range [@a
831        *  first,@a last) into the %list before the location specified by
832        *  @a position.
833        *
834        *  Due to the nature of a %list this operation can be done in
835        *  constant time, and does not invalidate iterators and
836        *  references.
837        */
838       template<typename _InputIterator>
839         void
840         insert(iterator __position, _InputIterator __first,
841                _InputIterator __last)
842         {
843           // Check whether it's an integral type.  If so, it's not an iterator.
844           typedef typename _Is_integer<_InputIterator>::_Integral _Integral;
845           _M_insert_dispatch(__position, __first, __last, _Integral());
846         }
847
848       /**
849        *  @brief  Remove element at given position.
850        *  @param  position  Iterator pointing to element to be erased.
851        *  @return  An iterator pointing to the next element (or end()).
852        *
853        *  This function will erase the element at the given position and thus
854        *  shorten the %list by one.
855        *
856        *  Due to the nature of a %list this operation can be done in
857        *  constant time, and only invalidates iterators/references to
858        *  the element being removed.  The user is also cautioned that
859        *  this function only erases the element, and that if the element
860        *  is itself a pointer, the pointed-to memory is not touched in
861        *  any way.  Managing the pointer is the user's responsibilty.
862        */
863       iterator
864       erase(iterator __position);
865
866       /**
867        *  @brief  Remove a range of elements.
868        *  @param  first  Iterator pointing to the first element to be erased.
869        *  @param  last  Iterator pointing to one past the last element to be
870        *                erased.
871        *  @return  An iterator pointing to the element pointed to by @a last
872        *           prior to erasing (or end()).
873        *
874        *  This function will erase the elements in the range @a
875        *  [first,last) and shorten the %list accordingly.
876        *
877        *  Due to the nature of a %list this operation can be done in
878        *  constant time, and only invalidates iterators/references to
879        *  the element being removed.  The user is also cautioned that
880        *  this function only erases the elements, and that if the
881        *  elements themselves are pointers, the pointed-to memory is not
882        *  touched in any way.  Managing the pointer is the user's
883        *  responsibilty.
884        */
885       iterator
886       erase(iterator __first, iterator __last)
887       {
888         while (__first != __last)
889           __first = erase(__first);
890         return __last;
891       }
892
893       /**
894        *  @brief  Swaps data with another %list.
895        *  @param  x  A %list of the same element and allocator types.
896        *
897        *  This exchanges the elements between two lists in constant
898        *  time.  Note that the global std::swap() function is
899        *  specialized such that std::swap(l1,l2) will feed to this
900        *  function.
901        */
902       void
903       swap(list& __x)
904       { _List_node_base::swap(this->_M_node,__x._M_node); }
905
906       /**
907        *  Erases all the elements.  Note that this function only erases
908        *  the elements, and that if the elements themselves are
909        *  pointers, the pointed-to memory is not touched in any way.
910        *  Managing the pointer is the user's responsibilty.
911        */
912       void
913       clear()
914       {
915         _Base::_M_clear();
916         _Base::_M_init();
917       }
918
919       // [23.2.2.4] list operations
920       /**
921        *  @brief  Insert contents of another %list.
922        *  @param  position  Iterator referencing the element to insert before.
923        *  @param  x  Source list.
924        *
925        *  The elements of @a x are inserted in constant time in front of
926        *  the element referenced by @a position.  @a x becomes an empty
927        *  list.
928        */
929       void
930       splice(iterator __position, list& __x)
931       {
932         if (!__x.empty())
933           this->_M_transfer(__position, __x.begin(), __x.end());
934       }
935
936       /**
937        *  @brief  Insert element from another %list.
938        *  @param  position  Iterator referencing the element to insert before.
939        *  @param  x  Source list.
940        *  @param  i  Iterator referencing the element to move.
941        *
942        *  Removes the element in list @a x referenced by @a i and
943        *  inserts it into the current list before @a position.
944        */
945       void
946       splice(iterator __position, list&, iterator __i)
947       {
948         iterator __j = __i;
949         ++__j;
950         if (__position == __i || __position == __j)
951           return;
952         this->_M_transfer(__position, __i, __j);
953       }
954
955       /**
956        *  @brief  Insert range from another %list.
957        *  @param  position  Iterator referencing the element to insert before.
958        *  @param  x  Source list.
959        *  @param  first  Iterator referencing the start of range in x.
960        *  @param  last  Iterator referencing the end of range in x.
961        *
962        *  Removes elements in the range [first,last) and inserts them
963        *  before @a position in constant time.
964        *
965        *  Undefined if @a position is in [first,last).
966        */
967       void
968       splice(iterator __position, list&, iterator __first, iterator __last)
969       {
970         if (__first != __last)
971           this->_M_transfer(__position, __first, __last);
972       }
973
974       /**
975        *  @brief  Remove all elements equal to value.
976        *  @param  value  The value to remove.
977        *
978        *  Removes every element in the list equal to @a value.
979        *  Remaining elements stay in list order.  Note that this
980        *  function only erases the elements, and that if the elements
981        *  themselves are pointers, the pointed-to memory is not
982        *  touched in any way.  Managing the pointer is the user's
983        *  responsibilty.
984        */
985       void
986       remove(const _Tp& __value);
987
988       /**
989        *  @brief  Remove all elements satisfying a predicate.
990        *  @param  Predicate  Unary predicate function or object.
991        *
992        *  Removes every element in the list for which the predicate
993        *  returns true.  Remaining elements stay in list order.  Note
994        *  that this function only erases the elements, and that if the
995        *  elements themselves are pointers, the pointed-to memory is
996        *  not touched in any way.  Managing the pointer is the user's
997        *  responsibilty.
998        */
999       template<typename _Predicate>
1000       void
1001       remove_if(_Predicate);
1002
1003       /**
1004        *  @brief  Remove consecutive duplicate elements.
1005        *
1006        *  For each consecutive set of elements with the same value,
1007        *  remove all but the first one.  Remaining elements stay in
1008        *  list order.  Note that this function only erases the
1009        *  elements, and that if the elements themselves are pointers,
1010        *  the pointed-to memory is not touched in any way.  Managing
1011        *  the pointer is the user's responsibilty.
1012        */
1013       void
1014       unique();
1015
1016       /**
1017        *  @brief  Remove consecutive elements satisfying a predicate.
1018        *  @param  BinaryPredicate  Binary predicate function or object.
1019        *
1020        *  For each consecutive set of elements [first,last) that
1021        *  satisfy predicate(first,i) where i is an iterator in
1022        *  [first,last), remove all but the first one.  Remaining
1023        *  elements stay in list order.  Note that this function only
1024        *  erases the elements, and that if the elements themselves are
1025        *  pointers, the pointed-to memory is not touched in any way.
1026        *  Managing the pointer is the user's responsibilty.
1027        */
1028       template<typename _BinaryPredicate>
1029         void
1030         unique(_BinaryPredicate);
1031
1032       /**
1033        *  @brief  Merge sorted lists.
1034        *  @param  x  Sorted list to merge.
1035        *
1036        *  Assumes that both @a x and this list are sorted according to
1037        *  operator<().  Merges elements of @a x into this list in
1038        *  sorted order, leaving @a x empty when complete.  Elements in
1039        *  this list precede elements in @a x that are equal.
1040        */
1041       void
1042       merge(list& __x);
1043
1044       /**
1045        *  @brief  Merge sorted lists according to comparison function.
1046        *  @param  x  Sorted list to merge.
1047        *  @param StrictWeakOrdering Comparison function definining
1048        *  sort order.
1049        *
1050        *  Assumes that both @a x and this list are sorted according to
1051        *  StrictWeakOrdering.  Merges elements of @a x into this list
1052        *  in sorted order, leaving @a x empty when complete.  Elements
1053        *  in this list precede elements in @a x that are equivalent
1054        *  according to StrictWeakOrdering().
1055        */
1056       template<typename _StrictWeakOrdering>
1057         void
1058         merge(list&, _StrictWeakOrdering);
1059
1060       /**
1061        *  @brief  Reverse the elements in list.
1062        *
1063        *  Reverse the order of elements in the list in linear time.
1064        */
1065       void
1066       reverse()
1067       { this->_M_node.reverse(); }
1068
1069       /**
1070        *  @brief  Sort the elements.
1071        *
1072        *  Sorts the elements of this list in NlogN time.  Equivalent
1073        *  elements remain in list order.
1074        */
1075       void
1076       sort();
1077
1078       /**
1079        *  @brief  Sort the elements according to comparison function.
1080        *
1081        *  Sorts the elements of this list in NlogN time.  Equivalent
1082        *  elements remain in list order.
1083        */
1084       template<typename _StrictWeakOrdering>
1085         void
1086         sort(_StrictWeakOrdering);
1087
1088     protected:
1089       // Internal assign functions follow.
1090
1091       // Called by the range assign to implement [23.1.1]/9
1092       template<typename _Integer>
1093         void
1094         _M_assign_dispatch(_Integer __n, _Integer __val, __true_type)
1095         {
1096           _M_fill_assign(static_cast<size_type>(__n),
1097                          static_cast<value_type>(__val));
1098         }
1099
1100       // Called by the range assign to implement [23.1.1]/9
1101       template<typename _InputIterator>
1102         void
1103         _M_assign_dispatch(_InputIterator __first, _InputIterator __last,
1104                            __false_type);
1105
1106       // Called by assign(n,t), and the range assign when it turns out
1107       // to be the same thing.
1108       void
1109       _M_fill_assign(size_type __n, const value_type& __val);
1110
1111
1112       // Internal insert functions follow.
1113
1114       // Called by the range insert to implement [23.1.1]/9
1115       template<typename _Integer>
1116         void
1117         _M_insert_dispatch(iterator __pos, _Integer __n, _Integer __x,
1118                            __true_type)
1119         {
1120           _M_fill_insert(__pos, static_cast<size_type>(__n),
1121                          static_cast<value_type>(__x));
1122         }
1123
1124       // Called by the range insert to implement [23.1.1]/9
1125       template<typename _InputIterator>
1126         void
1127         _M_insert_dispatch(iterator __pos,
1128                            _InputIterator __first, _InputIterator __last,
1129                            __false_type)
1130         {
1131           for ( ; __first != __last; ++__first)
1132             _M_insert(__pos, *__first);
1133         }
1134
1135       // Called by insert(p,n,x), and the range insert when it turns out
1136       // to be the same thing.
1137       void
1138       _M_fill_insert(iterator __pos, size_type __n, const value_type& __x)
1139       {
1140         for ( ; __n > 0; --__n)
1141           _M_insert(__pos, __x);
1142       }
1143
1144
1145       // Moves the elements from [first,last) before position.
1146       void
1147       _M_transfer(iterator __position, iterator __first, iterator __last)
1148       { __position._M_node->transfer(__first._M_node,__last._M_node); }
1149
1150       // Inserts new element at position given and with value given.
1151       void
1152       _M_insert(iterator __position, const value_type& __x)
1153       {
1154         _Node* __tmp = _M_create_node(__x);
1155         __tmp->hook(__position._M_node);
1156       }
1157
1158       // Erases element at position given.
1159       void
1160       _M_erase(iterator __position)
1161       {
1162         __position._M_node->unhook();
1163         _Node* __n = static_cast<_Node*>(__position._M_node);
1164         std::_Destroy(&__n->_M_data);
1165         _M_put_node(__n);
1166       }
1167     };
1168
1169   /**
1170    *  @brief  List equality comparison.
1171    *  @param  x  A %list.
1172    *  @param  y  A %list of the same type as @a x.
1173    *  @return  True iff the size and elements of the lists are equal.
1174    *
1175    *  This is an equivalence relation.  It is linear in the size of
1176    *  the lists.  Lists are considered equivalent if their sizes are
1177    *  equal, and if corresponding elements compare equal.
1178   */
1179   template<typename _Tp, typename _Alloc>
1180     inline bool
1181     operator==(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1182     {
1183       typedef typename list<_Tp,_Alloc>::const_iterator const_iterator;
1184       const_iterator __end1 = __x.end();
1185       const_iterator __end2 = __y.end();
1186
1187       const_iterator __i1 = __x.begin();
1188       const_iterator __i2 = __y.begin();
1189       while (__i1 != __end1 && __i2 != __end2 && *__i1 == *__i2)
1190         {
1191           ++__i1;
1192           ++__i2;
1193         }
1194       return __i1 == __end1 && __i2 == __end2;
1195     }
1196
1197   /**
1198    *  @brief  List ordering relation.
1199    *  @param  x  A %list.
1200    *  @param  y  A %list of the same type as @a x.
1201    *  @return  True iff @a x is lexicographically less than @a y.
1202    *
1203    *  This is a total ordering relation.  It is linear in the size of the
1204    *  lists.  The elements must be comparable with @c <.
1205    *
1206    *  See std::lexicographical_compare() for how the determination is made.
1207   */
1208   template<typename _Tp, typename _Alloc>
1209     inline bool
1210     operator<(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1211     { return std::lexicographical_compare(__x.begin(), __x.end(),
1212                                           __y.begin(), __y.end()); }
1213
1214   /// Based on operator==
1215   template<typename _Tp, typename _Alloc>
1216     inline bool
1217     operator!=(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1218     { return !(__x == __y); }
1219
1220   /// Based on operator<
1221   template<typename _Tp, typename _Alloc>
1222     inline bool
1223     operator>(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1224     { return __y < __x; }
1225
1226   /// Based on operator<
1227   template<typename _Tp, typename _Alloc>
1228     inline bool
1229     operator<=(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1230     { return !(__y < __x); }
1231
1232   /// Based on operator<
1233   template<typename _Tp, typename _Alloc>
1234     inline bool
1235     operator>=(const list<_Tp,_Alloc>& __x, const list<_Tp,_Alloc>& __y)
1236     { return !(__x < __y); }
1237
1238   /// See std::list::swap().
1239   template<typename _Tp, typename _Alloc>
1240     inline void
1241     swap(list<_Tp, _Alloc>& __x, list<_Tp, _Alloc>& __y)
1242     { __x.swap(__y); }
1243 } // namespace __gnu_norm
1244
1245 #endif /* _LIST_H */
1246