stl_vector.h

Go to the documentation of this file.
00001 // Vector implementation -*- C++ -*-
00002 
00003 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
00004 // Free Software Foundation, Inc.
00005 //
00006 // This file is part of the GNU ISO C++ Library.  This library is free
00007 // software; you can redistribute it and/or modify it under the
00008 // terms of the GNU General Public License as published by the
00009 // Free Software Foundation; either version 3, or (at your option)
00010 // any later version.
00011 
00012 // This library is distributed in the hope that it will be useful,
00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015 // GNU General Public License for more details.
00016 
00017 // Under Section 7 of GPL version 3, you are granted additional
00018 // permissions described in the GCC Runtime Library Exception, version
00019 // 3.1, as published by the Free Software Foundation.
00020 
00021 // You should have received a copy of the GNU General Public License and
00022 // a copy of the GCC Runtime Library Exception along with this program;
00023 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
00024 // <http://www.gnu.org/licenses/>.
00025 
00026 /*
00027  *
00028  * Copyright (c) 1994
00029  * Hewlett-Packard Company
00030  *
00031  * Permission to use, copy, modify, distribute and sell this software
00032  * and its documentation for any purpose is hereby granted without fee,
00033  * provided that the above copyright notice appear in all copies and
00034  * that both that copyright notice and this permission notice appear
00035  * in supporting documentation.  Hewlett-Packard Company makes no
00036  * representations about the suitability of this software for any
00037  * purpose.  It is provided "as is" without express or implied warranty.
00038  *
00039  *
00040  * Copyright (c) 1996
00041  * Silicon Graphics Computer Systems, Inc.
00042  *
00043  * Permission to use, copy, modify, distribute and sell this software
00044  * and its documentation for any purpose is hereby granted without fee,
00045  * provided that the above copyright notice appear in all copies and
00046  * that both that copyright notice and this permission notice appear
00047  * in supporting documentation.  Silicon Graphics makes no
00048  * representations about the suitability of this  software for any
00049  * purpose.  It is provided "as is" without express or implied warranty.
00050  */
00051 
00052 /** @file stl_vector.h
00053  *  This is an internal header file, included by other library headers.
00054  *  You should not attempt to use it directly.
00055  */
00056 
00057 #ifndef _STL_VECTOR_H
00058 #define _STL_VECTOR_H 1
00059 
00060 #include <bits/stl_iterator_base_funcs.h>
00061 #include <bits/functexcept.h>
00062 #include <bits/concept_check.h>
00063 #include <initializer_list>
00064 
00065 _GLIBCXX_BEGIN_NESTED_NAMESPACE(std, _GLIBCXX_STD_D)
00066 
00067   /// See bits/stl_deque.h's _Deque_base for an explanation.
00068   template<typename _Tp, typename _Alloc>
00069     struct _Vector_base
00070     {
00071       typedef typename _Alloc::template rebind<_Tp>::other _Tp_alloc_type;
00072 
00073       struct _Vector_impl 
00074       : public _Tp_alloc_type
00075       {
00076     typename _Tp_alloc_type::pointer _M_start;
00077     typename _Tp_alloc_type::pointer _M_finish;
00078     typename _Tp_alloc_type::pointer _M_end_of_storage;
00079 
00080     _Vector_impl()
00081     : _Tp_alloc_type(), _M_start(0), _M_finish(0), _M_end_of_storage(0)
00082     { }
00083 
00084     _Vector_impl(_Tp_alloc_type const& __a)
00085     : _Tp_alloc_type(__a), _M_start(0), _M_finish(0), _M_end_of_storage(0)
00086     { }
00087       };
00088       
00089     public:
00090       typedef _Alloc allocator_type;
00091 
00092       _Tp_alloc_type&
00093       _M_get_Tp_allocator()
00094       { return *static_cast<_Tp_alloc_type*>(&this->_M_impl); }
00095 
00096       const _Tp_alloc_type&
00097       _M_get_Tp_allocator() const
00098       { return *static_cast<const _Tp_alloc_type*>(&this->_M_impl); }
00099 
00100       allocator_type
00101       get_allocator() const
00102       { return allocator_type(_M_get_Tp_allocator()); }
00103 
00104       _Vector_base()
00105       : _M_impl() { }
00106 
00107       _Vector_base(const allocator_type& __a)
00108       : _M_impl(__a) { }
00109 
00110       _Vector_base(size_t __n)
00111       : _M_impl()
00112       {
00113     this->_M_impl._M_start = this->_M_allocate(__n);
00114     this->_M_impl._M_finish = this->_M_impl._M_start;
00115     this->_M_impl._M_end_of_storage = this->_M_impl._M_start + __n;
00116       }
00117 
00118       _Vector_base(size_t __n, const allocator_type& __a)
00119       : _M_impl(__a)
00120       {
00121     this->_M_impl._M_start = this->_M_allocate(__n);
00122     this->_M_impl._M_finish = this->_M_impl._M_start;
00123     this->_M_impl._M_end_of_storage = this->_M_impl._M_start + __n;
00124       }
00125 
00126 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00127       _Vector_base(_Vector_base&& __x)
00128       : _M_impl(__x._M_get_Tp_allocator())
00129       {
00130     this->_M_impl._M_start = __x._M_impl._M_start;
00131     this->_M_impl._M_finish = __x._M_impl._M_finish;
00132     this->_M_impl._M_end_of_storage = __x._M_impl._M_end_of_storage;
00133     __x._M_impl._M_start = 0;
00134     __x._M_impl._M_finish = 0;
00135     __x._M_impl._M_end_of_storage = 0;
00136       }
00137 #endif
00138 
00139       ~_Vector_base()
00140       { _M_deallocate(this->_M_impl._M_start, this->_M_impl._M_end_of_storage
00141               - this->_M_impl._M_start); }
00142 
00143     public:
00144       _Vector_impl _M_impl;
00145 
00146       typename _Tp_alloc_type::pointer
00147       _M_allocate(size_t __n)
00148       { return __n != 0 ? _M_impl.allocate(__n) : 0; }
00149 
00150       void
00151       _M_deallocate(typename _Tp_alloc_type::pointer __p, size_t __n)
00152       {
00153     if (__p)
00154       _M_impl.deallocate(__p, __n);
00155       }
00156     };
00157 
00158 
00159   /**
00160    *  @brief A standard container which offers fixed time access to
00161    *  individual elements in any order.
00162    *
00163    *  @ingroup sequences
00164    *
00165    *  Meets the requirements of a <a href="tables.html#65">container</a>, a
00166    *  <a href="tables.html#66">reversible container</a>, and a
00167    *  <a href="tables.html#67">sequence</a>, including the
00168    *  <a href="tables.html#68">optional sequence requirements</a> with the
00169    *  %exception of @c push_front and @c pop_front.
00170    *
00171    *  In some terminology a %vector can be described as a dynamic
00172    *  C-style array, it offers fast and efficient access to individual
00173    *  elements in any order and saves the user from worrying about
00174    *  memory and size allocation.  Subscripting ( @c [] ) access is
00175    *  also provided as with C-style arrays.
00176   */
00177   template<typename _Tp, typename _Alloc = std::allocator<_Tp> >
00178     class vector : protected _Vector_base<_Tp, _Alloc>
00179     {
00180       // Concept requirements.
00181       typedef typename _Alloc::value_type                _Alloc_value_type;
00182       __glibcxx_class_requires(_Tp, _SGIAssignableConcept)
00183       __glibcxx_class_requires2(_Tp, _Alloc_value_type, _SameTypeConcept)
00184       
00185       typedef _Vector_base<_Tp, _Alloc>          _Base;
00186       typedef typename _Base::_Tp_alloc_type         _Tp_alloc_type;
00187 
00188     public:
00189       typedef _Tp                    value_type;
00190       typedef typename _Tp_alloc_type::pointer           pointer;
00191       typedef typename _Tp_alloc_type::const_pointer     const_pointer;
00192       typedef typename _Tp_alloc_type::reference         reference;
00193       typedef typename _Tp_alloc_type::const_reference   const_reference;
00194       typedef __gnu_cxx::__normal_iterator<pointer, vector> iterator;
00195       typedef __gnu_cxx::__normal_iterator<const_pointer, vector>
00196       const_iterator;
00197       typedef std::reverse_iterator<const_iterator>  const_reverse_iterator;
00198       typedef std::reverse_iterator<iterator>        reverse_iterator;
00199       typedef size_t                     size_type;
00200       typedef ptrdiff_t                  difference_type;
00201       typedef _Alloc                                 allocator_type;
00202 
00203     protected:
00204       using _Base::_M_allocate;
00205       using _Base::_M_deallocate;
00206       using _Base::_M_impl;
00207       using _Base::_M_get_Tp_allocator;
00208 
00209     public:
00210       // [23.2.4.1] construct/copy/destroy
00211       // (assign() and get_allocator() are also listed in this section)
00212       /**
00213        *  @brief  Default constructor creates no elements.
00214        */
00215       vector()
00216       : _Base() { }
00217 
00218       /**
00219        *  @brief  Creates a %vector with no elements.
00220        *  @param  a  An allocator object.
00221        */
00222       explicit
00223       vector(const allocator_type& __a)
00224       : _Base(__a) { }
00225 
00226 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00227       /**
00228        *  @brief  Creates a %vector with default constructed elements.
00229        *  @param  n  The number of elements to initially create.
00230        *
00231        *  This constructor fills the %vector with @a n default
00232        *  constructed elements.
00233        */
00234       explicit
00235       vector(size_type __n)
00236       : _Base(__n)
00237       { _M_default_initialize(__n); }
00238 
00239       /**
00240        *  @brief  Creates a %vector with copies of an exemplar element.
00241        *  @param  n  The number of elements to initially create.
00242        *  @param  value  An element to copy.
00243        *  @param  a  An allocator.
00244        *
00245        *  This constructor fills the %vector with @a n copies of @a value.
00246        */
00247       vector(size_type __n, const value_type& __value,
00248          const allocator_type& __a = allocator_type())
00249       : _Base(__n, __a)
00250       { _M_fill_initialize(__n, __value); }
00251 #else
00252       /**
00253        *  @brief  Creates a %vector with copies of an exemplar element.
00254        *  @param  n  The number of elements to initially create.
00255        *  @param  value  An element to copy.
00256        *  @param  a  An allocator.
00257        *
00258        *  This constructor fills the %vector with @a n copies of @a value.
00259        */
00260       explicit
00261       vector(size_type __n, const value_type& __value = value_type(),
00262          const allocator_type& __a = allocator_type())
00263       : _Base(__n, __a)
00264       { _M_fill_initialize(__n, __value); }
00265 #endif
00266 
00267       /**
00268        *  @brief  %Vector copy constructor.
00269        *  @param  x  A %vector of identical element and allocator types.
00270        *
00271        *  The newly-created %vector uses a copy of the allocation
00272        *  object used by @a x.  All the elements of @a x are copied,
00273        *  but any extra memory in
00274        *  @a x (for fast expansion) will not be copied.
00275        */
00276       vector(const vector& __x)
00277       : _Base(__x.size(), __x._M_get_Tp_allocator())
00278       { this->_M_impl._M_finish =
00279       std::__uninitialized_copy_a(__x.begin(), __x.end(),
00280                       this->_M_impl._M_start,
00281                       _M_get_Tp_allocator());
00282       }
00283 
00284 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00285       /**
00286        *  @brief  %Vector move constructor.
00287        *  @param  x  A %vector of identical element and allocator types.
00288        *
00289        *  The newly-created %vector contains the exact contents of @a x.
00290        *  The contents of @a x are a valid, but unspecified %vector.
00291        */
00292       vector(vector&& __x)
00293       : _Base(std::forward<_Base>(__x)) { }
00294 
00295       /**
00296        *  @brief  Builds a %vector from an initializer list.
00297        *  @param  l  An initializer_list.
00298        *  @param  a  An allocator.
00299        *
00300        *  Create a %vector consisting of copies of the elements in the
00301        *  initializer_list @a l.
00302        *
00303        *  This will call the element type's copy constructor N times
00304        *  (where N is @a l.size()) and do no memory reallocation.
00305        */
00306       vector(initializer_list<value_type> __l,
00307          const allocator_type& __a = allocator_type())
00308       : _Base(__a)
00309       {
00310     _M_range_initialize(__l.begin(), __l.end(),
00311                 random_access_iterator_tag());
00312       }
00313 #endif
00314 
00315       /**
00316        *  @brief  Builds a %vector from a range.
00317        *  @param  first  An input iterator.
00318        *  @param  last  An input iterator.
00319        *  @param  a  An allocator.
00320        *
00321        *  Create a %vector consisting of copies of the elements from
00322        *  [first,last).
00323        *
00324        *  If the iterators are forward, bidirectional, or
00325        *  random-access, then this will call the elements' copy
00326        *  constructor N times (where N is distance(first,last)) and do
00327        *  no memory reallocation.  But if only input iterators are
00328        *  used, then this will do at most 2N calls to the copy
00329        *  constructor, and logN memory reallocations.
00330        */
00331       template<typename _InputIterator>
00332         vector(_InputIterator __first, _InputIterator __last,
00333            const allocator_type& __a = allocator_type())
00334     : _Base(__a)
00335         {
00336       // Check whether it's an integral type.  If so, it's not an iterator.
00337       typedef typename std::__is_integer<_InputIterator>::__type _Integral;
00338       _M_initialize_dispatch(__first, __last, _Integral());
00339     }
00340 
00341       /**
00342        *  The dtor only erases the elements, and note that if the
00343        *  elements themselves are pointers, the pointed-to memory is
00344        *  not touched in any way.  Managing the pointer is the user's
00345        *  responsibility.
00346        */
00347       ~vector()
00348       { std::_Destroy(this->_M_impl._M_start, this->_M_impl._M_finish,
00349               _M_get_Tp_allocator()); }
00350 
00351       /**
00352        *  @brief  %Vector assignment operator.
00353        *  @param  x  A %vector of identical element and allocator types.
00354        *
00355        *  All the elements of @a x are copied, but any extra memory in
00356        *  @a x (for fast expansion) will not be copied.  Unlike the
00357        *  copy constructor, the allocator object is not copied.
00358        */
00359       vector&
00360       operator=(const vector& __x);
00361 
00362 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00363       /**
00364        *  @brief  %Vector move assignment operator.
00365        *  @param  x  A %vector of identical element and allocator types.
00366        *
00367        *  The contents of @a x are moved into this %vector (without copying).
00368        *  @a x is a valid, but unspecified %vector.
00369        */
00370       vector&
00371       operator=(vector&& __x)
00372       {
00373     // NB: DR 1204.
00374     // NB: DR 675.
00375     this->clear();
00376     this->swap(__x);
00377     return *this;
00378       }
00379 
00380       /**
00381        *  @brief  %Vector list assignment operator.
00382        *  @param  l  An initializer_list.
00383        *
00384        *  This function fills a %vector with copies of the elements in the
00385        *  initializer list @a l.
00386        *
00387        *  Note that the assignment completely changes the %vector and
00388        *  that the resulting %vector's size is the same as the number
00389        *  of elements assigned.  Old data may be lost.
00390        */
00391       vector&
00392       operator=(initializer_list<value_type> __l)
00393       {
00394     this->assign(__l.begin(), __l.end());
00395     return *this;
00396       }
00397 #endif
00398 
00399       /**
00400        *  @brief  Assigns a given value to a %vector.
00401        *  @param  n  Number of elements to be assigned.
00402        *  @param  val  Value to be assigned.
00403        *
00404        *  This function fills a %vector with @a n copies of the given
00405        *  value.  Note that the assignment completely changes the
00406        *  %vector and that the resulting %vector's size is the same as
00407        *  the number of elements assigned.  Old data may be lost.
00408        */
00409       void
00410       assign(size_type __n, const value_type& __val)
00411       { _M_fill_assign(__n, __val); }
00412 
00413       /**
00414        *  @brief  Assigns a range to a %vector.
00415        *  @param  first  An input iterator.
00416        *  @param  last   An input iterator.
00417        *
00418        *  This function fills a %vector with copies of the elements in the
00419        *  range [first,last).
00420        *
00421        *  Note that the assignment completely changes the %vector and
00422        *  that the resulting %vector's size is the same as the number
00423        *  of elements assigned.  Old data may be lost.
00424        */
00425       template<typename _InputIterator>
00426         void
00427         assign(_InputIterator __first, _InputIterator __last)
00428         {
00429       // Check whether it's an integral type.  If so, it's not an iterator.
00430       typedef typename std::__is_integer<_InputIterator>::__type _Integral;
00431       _M_assign_dispatch(__first, __last, _Integral());
00432     }
00433 
00434 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00435       /**
00436        *  @brief  Assigns an initializer list to a %vector.
00437        *  @param  l  An initializer_list.
00438        *
00439        *  This function fills a %vector with copies of the elements in the
00440        *  initializer list @a l.
00441        *
00442        *  Note that the assignment completely changes the %vector and
00443        *  that the resulting %vector's size is the same as the number
00444        *  of elements assigned.  Old data may be lost.
00445        */
00446       void
00447       assign(initializer_list<value_type> __l)
00448       { this->assign(__l.begin(), __l.end()); }
00449 #endif
00450 
00451       /// Get a copy of the memory allocation object.
00452       using _Base::get_allocator;
00453 
00454       // iterators
00455       /**
00456        *  Returns a read/write iterator that points to the first
00457        *  element in the %vector.  Iteration is done in ordinary
00458        *  element order.
00459        */
00460       iterator
00461       begin()
00462       { return iterator(this->_M_impl._M_start); }
00463 
00464       /**
00465        *  Returns a read-only (constant) iterator that points to the
00466        *  first element in the %vector.  Iteration is done in ordinary
00467        *  element order.
00468        */
00469       const_iterator
00470       begin() const
00471       { return const_iterator(this->_M_impl._M_start); }
00472 
00473       /**
00474        *  Returns a read/write iterator that points one past the last
00475        *  element in the %vector.  Iteration is done in ordinary
00476        *  element order.
00477        */
00478       iterator
00479       end()
00480       { return iterator(this->_M_impl._M_finish); }
00481 
00482       /**
00483        *  Returns a read-only (constant) iterator that points one past
00484        *  the last element in the %vector.  Iteration is done in
00485        *  ordinary element order.
00486        */
00487       const_iterator
00488       end() const
00489       { return const_iterator(this->_M_impl._M_finish); }
00490 
00491       /**
00492        *  Returns a read/write reverse iterator that points to the
00493        *  last element in the %vector.  Iteration is done in reverse
00494        *  element order.
00495        */
00496       reverse_iterator
00497       rbegin()
00498       { return reverse_iterator(end()); }
00499 
00500       /**
00501        *  Returns a read-only (constant) reverse iterator that points
00502        *  to the last element in the %vector.  Iteration is done in
00503        *  reverse element order.
00504        */
00505       const_reverse_iterator
00506       rbegin() const
00507       { return const_reverse_iterator(end()); }
00508 
00509       /**
00510        *  Returns a read/write reverse iterator that points to one
00511        *  before the first element in the %vector.  Iteration is done
00512        *  in reverse element order.
00513        */
00514       reverse_iterator
00515       rend()
00516       { return reverse_iterator(begin()); }
00517 
00518       /**
00519        *  Returns a read-only (constant) reverse iterator that points
00520        *  to one before the first element in the %vector.  Iteration
00521        *  is done in reverse element order.
00522        */
00523       const_reverse_iterator
00524       rend() const
00525       { return const_reverse_iterator(begin()); }
00526 
00527 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00528       /**
00529        *  Returns a read-only (constant) iterator that points to the
00530        *  first element in the %vector.  Iteration is done in ordinary
00531        *  element order.
00532        */
00533       const_iterator
00534       cbegin() const
00535       { return const_iterator(this->_M_impl._M_start); }
00536 
00537       /**
00538        *  Returns a read-only (constant) iterator that points one past
00539        *  the last element in the %vector.  Iteration is done in
00540        *  ordinary element order.
00541        */
00542       const_iterator
00543       cend() const
00544       { return const_iterator(this->_M_impl._M_finish); }
00545 
00546       /**
00547        *  Returns a read-only (constant) reverse iterator that points
00548        *  to the last element in the %vector.  Iteration is done in
00549        *  reverse element order.
00550        */
00551       const_reverse_iterator
00552       crbegin() const
00553       { return const_reverse_iterator(end()); }
00554 
00555       /**
00556        *  Returns a read-only (constant) reverse iterator that points
00557        *  to one before the first element in the %vector.  Iteration
00558        *  is done in reverse element order.
00559        */
00560       const_reverse_iterator
00561       crend() const
00562       { return const_reverse_iterator(begin()); }
00563 #endif
00564 
00565       // [23.2.4.2] capacity
00566       /**  Returns the number of elements in the %vector.  */
00567       size_type
00568       size() const
00569       { return size_type(this->_M_impl._M_finish - this->_M_impl._M_start); }
00570 
00571       /**  Returns the size() of the largest possible %vector.  */
00572       size_type
00573       max_size() const
00574       { return _M_get_Tp_allocator().max_size(); }
00575 
00576 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00577       /**
00578        *  @brief  Resizes the %vector to the specified number of elements.
00579        *  @param  new_size  Number of elements the %vector should contain.
00580        *
00581        *  This function will %resize the %vector to the specified
00582        *  number of elements.  If the number is smaller than the
00583        *  %vector's current size the %vector is truncated, otherwise
00584        *  default constructed elements are appended.
00585        */
00586       void
00587       resize(size_type __new_size)
00588       {
00589     if (__new_size > size())
00590       _M_default_append(__new_size - size());
00591     else if (__new_size < size())
00592       _M_erase_at_end(this->_M_impl._M_start + __new_size);
00593       }
00594 
00595       /**
00596        *  @brief  Resizes the %vector to the specified number of elements.
00597        *  @param  new_size  Number of elements the %vector should contain.
00598        *  @param  x  Data with which new elements should be populated.
00599        *
00600        *  This function will %resize the %vector to the specified
00601        *  number of elements.  If the number is smaller than the
00602        *  %vector's current size the %vector is truncated, otherwise
00603        *  the %vector is extended and new elements are populated with
00604        *  given data.
00605        */
00606       void
00607       resize(size_type __new_size, const value_type& __x)
00608       {
00609     if (__new_size > size())
00610       insert(end(), __new_size - size(), __x);
00611     else if (__new_size < size())
00612       _M_erase_at_end(this->_M_impl._M_start + __new_size);
00613       }
00614 #else
00615       /**
00616        *  @brief  Resizes the %vector to the specified number of elements.
00617        *  @param  new_size  Number of elements the %vector should contain.
00618        *  @param  x  Data with which new elements should be populated.
00619        *
00620        *  This function will %resize the %vector to the specified
00621        *  number of elements.  If the number is smaller than the
00622        *  %vector's current size the %vector is truncated, otherwise
00623        *  the %vector is extended and new elements are populated with
00624        *  given data.
00625        */
00626       void
00627       resize(size_type __new_size, value_type __x = value_type())
00628       {
00629     if (__new_size > size())
00630       insert(end(), __new_size - size(), __x);
00631     else if (__new_size < size())
00632       _M_erase_at_end(this->_M_impl._M_start + __new_size);
00633       }
00634 #endif
00635 
00636 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00637       /**  A non-binding request to reduce capacity() to size().  */
00638       void
00639       shrink_to_fit()
00640       { std::__shrink_to_fit<vector>::_S_do_it(*this); }
00641 #endif
00642 
00643       /**
00644        *  Returns the total number of elements that the %vector can
00645        *  hold before needing to allocate more memory.
00646        */
00647       size_type
00648       capacity() const
00649       { return size_type(this->_M_impl._M_end_of_storage
00650              - this->_M_impl._M_start); }
00651 
00652       /**
00653        *  Returns true if the %vector is empty.  (Thus begin() would
00654        *  equal end().)
00655        */
00656       bool
00657       empty() const
00658       { return begin() == end(); }
00659 
00660       /**
00661        *  @brief  Attempt to preallocate enough memory for specified number of
00662        *          elements.
00663        *  @param  n  Number of elements required.
00664        *  @throw  std::length_error  If @a n exceeds @c max_size().
00665        *
00666        *  This function attempts to reserve enough memory for the
00667        *  %vector to hold the specified number of elements.  If the
00668        *  number requested is more than max_size(), length_error is
00669        *  thrown.
00670        *
00671        *  The advantage of this function is that if optimal code is a
00672        *  necessity and the user can determine the number of elements
00673        *  that will be required, the user can reserve the memory in
00674        *  %advance, and thus prevent a possible reallocation of memory
00675        *  and copying of %vector data.
00676        */
00677       void
00678       reserve(size_type __n);
00679 
00680       // element access
00681       /**
00682        *  @brief  Subscript access to the data contained in the %vector.
00683        *  @param n The index of the element for which data should be
00684        *  accessed.
00685        *  @return  Read/write reference to data.
00686        *
00687        *  This operator allows for easy, array-style, data access.
00688        *  Note that data access with this operator is unchecked and
00689        *  out_of_range lookups are not defined. (For checked lookups
00690        *  see at().)
00691        */
00692       reference
00693       operator[](size_type __n)
00694       { return *(this->_M_impl._M_start + __n); }
00695 
00696       /**
00697        *  @brief  Subscript access to the data contained in the %vector.
00698        *  @param n The index of the element for which data should be
00699        *  accessed.
00700        *  @return  Read-only (constant) reference to data.
00701        *
00702        *  This operator allows for easy, array-style, data access.
00703        *  Note that data access with this operator is unchecked and
00704        *  out_of_range lookups are not defined. (For checked lookups
00705        *  see at().)
00706        */
00707       const_reference
00708       operator[](size_type __n) const
00709       { return *(this->_M_impl._M_start + __n); }
00710 
00711     protected:
00712       /// Safety check used only from at().
00713       void
00714       _M_range_check(size_type __n) const
00715       {
00716     if (__n >= this->size())
00717       __throw_out_of_range(__N("vector::_M_range_check"));
00718       }
00719 
00720     public:
00721       /**
00722        *  @brief  Provides access to the data contained in the %vector.
00723        *  @param n The index of the element for which data should be
00724        *  accessed.
00725        *  @return  Read/write reference to data.
00726        *  @throw  std::out_of_range  If @a n is an invalid index.
00727        *
00728        *  This function provides for safer data access.  The parameter
00729        *  is first checked that it is in the range of the vector.  The
00730        *  function throws out_of_range if the check fails.
00731        */
00732       reference
00733       at(size_type __n)
00734       {
00735     _M_range_check(__n);
00736     return (*this)[__n]; 
00737       }
00738 
00739       /**
00740        *  @brief  Provides access to the data contained in the %vector.
00741        *  @param n The index of the element for which data should be
00742        *  accessed.
00743        *  @return  Read-only (constant) reference to data.
00744        *  @throw  std::out_of_range  If @a n is an invalid index.
00745        *
00746        *  This function provides for safer data access.  The parameter
00747        *  is first checked that it is in the range of the vector.  The
00748        *  function throws out_of_range if the check fails.
00749        */
00750       const_reference
00751       at(size_type __n) const
00752       {
00753     _M_range_check(__n);
00754     return (*this)[__n];
00755       }
00756 
00757       /**
00758        *  Returns a read/write reference to the data at the first
00759        *  element of the %vector.
00760        */
00761       reference
00762       front()
00763       { return *begin(); }
00764 
00765       /**
00766        *  Returns a read-only (constant) reference to the data at the first
00767        *  element of the %vector.
00768        */
00769       const_reference
00770       front() const
00771       { return *begin(); }
00772 
00773       /**
00774        *  Returns a read/write reference to the data at the last
00775        *  element of the %vector.
00776        */
00777       reference
00778       back()
00779       { return *(end() - 1); }
00780       
00781       /**
00782        *  Returns a read-only (constant) reference to the data at the
00783        *  last element of the %vector.
00784        */
00785       const_reference
00786       back() const
00787       { return *(end() - 1); }
00788 
00789       // _GLIBCXX_RESOLVE_LIB_DEFECTS
00790       // DR 464. Suggestion for new member functions in standard containers.
00791       // data access
00792       /**
00793        *   Returns a pointer such that [data(), data() + size()) is a valid
00794        *   range.  For a non-empty %vector, data() == &front().
00795        */
00796 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00797       _Tp*
00798 #else
00799       pointer
00800 #endif
00801       data()
00802       { return std::__addressof(front()); }
00803 
00804 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00805       const _Tp*
00806 #else
00807       const_pointer
00808 #endif
00809       data() const
00810       { return std::__addressof(front()); }
00811 
00812       // [23.2.4.3] modifiers
00813       /**
00814        *  @brief  Add data to the end of the %vector.
00815        *  @param  x  Data to be added.
00816        *
00817        *  This is a typical stack operation.  The function creates an
00818        *  element at the end of the %vector and assigns the given data
00819        *  to it.  Due to the nature of a %vector this operation can be
00820        *  done in constant time if the %vector has preallocated space
00821        *  available.
00822        */
00823       void
00824       push_back(const value_type& __x)
00825       {
00826     if (this->_M_impl._M_finish != this->_M_impl._M_end_of_storage)
00827       {
00828         this->_M_impl.construct(this->_M_impl._M_finish, __x);
00829         ++this->_M_impl._M_finish;
00830       }
00831     else
00832       _M_insert_aux(end(), __x);
00833       }
00834 
00835 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00836       void
00837       push_back(value_type&& __x)
00838       { emplace_back(std::move(__x)); }
00839 
00840       template<typename... _Args>
00841         void
00842         emplace_back(_Args&&... __args);
00843 #endif
00844 
00845       /**
00846        *  @brief  Removes last element.
00847        *
00848        *  This is a typical stack operation. It shrinks the %vector by one.
00849        *
00850        *  Note that no data is returned, and if the last element's
00851        *  data is needed, it should be retrieved before pop_back() is
00852        *  called.
00853        */
00854       void
00855       pop_back()
00856       {
00857     --this->_M_impl._M_finish;
00858     this->_M_impl.destroy(this->_M_impl._M_finish);
00859       }
00860 
00861 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00862       /**
00863        *  @brief  Inserts an object in %vector before specified iterator.
00864        *  @param  position  An iterator into the %vector.
00865        *  @param  args  Arguments.
00866        *  @return  An iterator that points to the inserted data.
00867        *
00868        *  This function will insert an object of type T constructed
00869        *  with T(std::forward<Args>(args)...) before the specified location.
00870        *  Note that this kind of operation could be expensive for a %vector
00871        *  and if it is frequently used the user should consider using
00872        *  std::list.
00873        */
00874       template<typename... _Args>
00875         iterator
00876         emplace(iterator __position, _Args&&... __args);
00877 #endif
00878 
00879       /**
00880        *  @brief  Inserts given value into %vector before specified iterator.
00881        *  @param  position  An iterator into the %vector.
00882        *  @param  x  Data to be inserted.
00883        *  @return  An iterator that points to the inserted data.
00884        *
00885        *  This function will insert a copy of the given value before
00886        *  the specified location.  Note that this kind of operation
00887        *  could be expensive for a %vector and if it is frequently
00888        *  used the user should consider using std::list.
00889        */
00890       iterator
00891       insert(iterator __position, const value_type& __x);
00892 
00893 #ifdef __GXX_EXPERIMENTAL_CXX0X__
00894       /**
00895        *  @brief  Inserts given rvalue into %vector before specified iterator.
00896        *  @param  position  An iterator into the %vector.
00897        *  @param  x  Data to be inserted.
00898        *  @return  An iterator that points to the inserted data.
00899        *
00900        *  This function will insert a copy of the given rvalue before
00901        *  the specified location.  Note that this kind of operation
00902        *  could be expensive for a %vector and if it is frequently
00903        *  used the user should consider using std::list.
00904        */
00905       iterator
00906       insert(iterator __position, value_type&& __x)
00907       { return emplace(__position, std::move(__x)); }
00908 
00909       /**
00910        *  @brief  Inserts an initializer_list into the %vector.
00911        *  @param  position  An iterator into the %vector.
00912        *  @param  l  An initializer_list.
00913        *
00914        *  This function will insert copies of the data in the 
00915        *  initializer_list @a l into the %vector before the location
00916        *  specified by @a position.
00917        *
00918        *  Note that this kind of operation could be expensive for a
00919        *  %vector and if it is frequently used the user should
00920        *  consider using std::list.
00921        */
00922       void
00923       insert(iterator __position, initializer_list<value_type> __l)
00924       { this->insert(__position, __l.begin(), __l.end()); }
00925 #endif
00926 
00927       /**
00928        *  @brief  Inserts a number of copies of given data into the %vector.
00929        *  @param  position  An iterator into the %vector.
00930        *  @param  n  Number of elements to be inserted.
00931        *  @param  x  Data to be inserted.
00932        *
00933        *  This function will insert a specified number of copies of
00934        *  the given data before the location specified by @a position.
00935        *
00936        *  Note that this kind of operation could be expensive for a
00937        *  %vector and if it is frequently used the user should
00938        *  consider using std::list.
00939        */
00940       void
00941       insert(iterator __position, size_type __n, const value_type& __x)
00942       { _M_fill_insert(__position, __n, __x); }
00943 
00944       /**
00945        *  @brief  Inserts a range into the %vector.
00946        *  @param  position  An iterator into the %vector.
00947        *  @param  first  An input iterator.
00948        *  @param  last   An input iterator.
00949        *
00950        *  This function will insert copies of the data in the range
00951        *  [first,last) into the %vector before the location specified
00952        *  by @a pos.
00953        *
00954        *  Note that this kind of operation could be expensive for a
00955        *  %vector and if it is frequently used the user should
00956        *  consider using std::list.
00957        */
00958       template<typename _InputIterator>
00959         void
00960         insert(iterator __position, _InputIterator __first,
00961            _InputIterator __last)
00962         {
00963       // Check whether it's an integral type.  If so, it's not an iterator.
00964       typedef typename std::__is_integer<_InputIterator>::__type _Integral;
00965       _M_insert_dispatch(__position, __first, __last, _Integral());
00966     }
00967 
00968       /**
00969        *  @brief  Remove element at given position.
00970        *  @param  position  Iterator pointing to element to be erased.
00971        *  @return  An iterator pointing to the next element (or end()).
00972        *
00973        *  This function will erase the element at the given position and thus
00974        *  shorten the %vector by one.
00975        *
00976        *  Note This operation could be expensive and if it is
00977        *  frequently used the user should consider using std::list.
00978        *  The user is also cautioned that this function only erases
00979        *  the element, and that if the element is itself a pointer,
00980        *  the pointed-to memory is not touched in any way.  Managing
00981        *  the pointer is the user's responsibility.
00982        */
00983       iterator
00984       erase(iterator __position);
00985 
00986       /**
00987        *  @brief  Remove a range of elements.
00988        *  @param  first  Iterator pointing to the first element to be erased.
00989        *  @param  last  Iterator pointing to one past the last element to be
00990        *                erased.
00991        *  @return  An iterator pointing to the element pointed to by @a last
00992        *           prior to erasing (or end()).
00993        *
00994        *  This function will erase the elements in the range [first,last) and
00995        *  shorten the %vector accordingly.
00996        *
00997        *  Note This operation could be expensive and if it is
00998        *  frequently used the user should consider using std::list.
00999        *  The user is also cautioned that this function only erases
01000        *  the elements, and that if the elements themselves are
01001        *  pointers, the pointed-to memory is not touched in any way.
01002        *  Managing the pointer is the user's responsibility.
01003        */
01004       iterator
01005       erase(iterator __first, iterator __last);
01006 
01007       /**
01008        *  @brief  Swaps data with another %vector.
01009        *  @param  x  A %vector of the same element and allocator types.
01010        *
01011        *  This exchanges the elements between two vectors in constant time.
01012        *  (Three pointers, so it should be quite fast.)
01013        *  Note that the global std::swap() function is specialized such that
01014        *  std::swap(v1,v2) will feed to this function.
01015        */
01016       void
01017       swap(vector& __x)
01018       {
01019     std::swap(this->_M_impl._M_start, __x._M_impl._M_start);
01020     std::swap(this->_M_impl._M_finish, __x._M_impl._M_finish);
01021     std::swap(this->_M_impl._M_end_of_storage,
01022           __x._M_impl._M_end_of_storage);
01023 
01024     // _GLIBCXX_RESOLVE_LIB_DEFECTS
01025     // 431. Swapping containers with unequal allocators.
01026     std::__alloc_swap<_Tp_alloc_type>::_S_do_it(_M_get_Tp_allocator(),
01027                             __x._M_get_Tp_allocator());
01028       }
01029 
01030       /**
01031        *  Erases all the elements.  Note that this function only erases the
01032        *  elements, and that if the elements themselves are pointers, the
01033        *  pointed-to memory is not touched in any way.  Managing the pointer is
01034        *  the user's responsibility.
01035        */
01036       void
01037       clear()
01038       { _M_erase_at_end(this->_M_impl._M_start); }
01039 
01040     protected:
01041       /**
01042        *  Memory expansion handler.  Uses the member allocation function to
01043        *  obtain @a n bytes of memory, and then copies [first,last) into it.
01044        */
01045       template<typename _ForwardIterator>
01046         pointer
01047         _M_allocate_and_copy(size_type __n,
01048                  _ForwardIterator __first, _ForwardIterator __last)
01049         {
01050       pointer __result = this->_M_allocate(__n);
01051       __try
01052         {
01053           std::__uninitialized_copy_a(__first, __last, __result,
01054                       _M_get_Tp_allocator());
01055           return __result;
01056         }
01057       __catch(...)
01058         {
01059           _M_deallocate(__result, __n);
01060           __throw_exception_again;
01061         }
01062     }
01063 
01064 
01065       // Internal constructor functions follow.
01066 
01067       // Called by the range constructor to implement [23.1.1]/9
01068 
01069       // _GLIBCXX_RESOLVE_LIB_DEFECTS
01070       // 438. Ambiguity in the "do the right thing" clause
01071       template<typename _Integer>
01072         void
01073         _M_initialize_dispatch(_Integer __n, _Integer __value, __true_type)
01074         {
01075       this->_M_impl._M_start = _M_allocate(static_cast<size_type>(__n));
01076       this->_M_impl._M_end_of_storage =
01077         this->_M_impl._M_start + static_cast<size_type>(__n);
01078       _M_fill_initialize(static_cast<size_type>(__n), __value);
01079     }
01080 
01081       // Called by the range constructor to implement [23.1.1]/9
01082       template<typename _InputIterator>
01083         void
01084         _M_initialize_dispatch(_InputIterator __first, _InputIterator __last,
01085                    __false_type)
01086         {
01087       typedef typename std::iterator_traits<_InputIterator>::
01088         iterator_category _IterCategory;
01089       _M_range_initialize(__first, __last, _IterCategory());
01090     }
01091 
01092       // Called by the second initialize_dispatch above
01093       template<typename _InputIterator>
01094         void
01095         _M_range_initialize(_InputIterator __first,
01096                 _InputIterator __last, std::input_iterator_tag)
01097         {
01098       for (; __first != __last; ++__first)
01099         push_back(*__first);
01100     }
01101 
01102       // Called by the second initialize_dispatch above
01103       template<typename _ForwardIterator>
01104         void
01105         _M_range_initialize(_ForwardIterator __first,
01106                 _ForwardIterator __last, std::forward_iterator_tag)
01107         {
01108       const size_type __n = std::distance(__first, __last);
01109       this->_M_impl._M_start = this->_M_allocate(__n);
01110       this->_M_impl._M_end_of_storage = this->_M_impl._M_start + __n;
01111       this->_M_impl._M_finish =
01112         std::__uninitialized_copy_a(__first, __last,
01113                     this->_M_impl._M_start,
01114                     _M_get_Tp_allocator());
01115     }
01116 
01117       // Called by the first initialize_dispatch above and by the
01118       // vector(n,value,a) constructor.
01119       void
01120       _M_fill_initialize(size_type __n, const value_type& __value)
01121       {
01122     std::__uninitialized_fill_n_a(this->_M_impl._M_start, __n, __value, 
01123                       _M_get_Tp_allocator());
01124     this->_M_impl._M_finish = this->_M_impl._M_end_of_storage;
01125       }
01126 
01127 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01128       // Called by the vector(n) constructor.
01129       void
01130       _M_default_initialize(size_type __n)
01131       {
01132     std::__uninitialized_default_n_a(this->_M_impl._M_start, __n, 
01133                      _M_get_Tp_allocator());
01134     this->_M_impl._M_finish = this->_M_impl._M_end_of_storage;
01135       }
01136 #endif
01137 
01138       // Internal assign functions follow.  The *_aux functions do the actual
01139       // assignment work for the range versions.
01140 
01141       // Called by the range assign to implement [23.1.1]/9
01142 
01143       // _GLIBCXX_RESOLVE_LIB_DEFECTS
01144       // 438. Ambiguity in the "do the right thing" clause
01145       template<typename _Integer>
01146         void
01147         _M_assign_dispatch(_Integer __n, _Integer __val, __true_type)
01148         { _M_fill_assign(__n, __val); }
01149 
01150       // Called by the range assign to implement [23.1.1]/9
01151       template<typename _InputIterator>
01152         void
01153         _M_assign_dispatch(_InputIterator __first, _InputIterator __last,
01154                __false_type)
01155         {
01156       typedef typename std::iterator_traits<_InputIterator>::
01157         iterator_category _IterCategory;
01158       _M_assign_aux(__first, __last, _IterCategory());
01159     }
01160 
01161       // Called by the second assign_dispatch above
01162       template<typename _InputIterator>
01163         void
01164         _M_assign_aux(_InputIterator __first, _InputIterator __last,
01165               std::input_iterator_tag);
01166 
01167       // Called by the second assign_dispatch above
01168       template<typename _ForwardIterator>
01169         void
01170         _M_assign_aux(_ForwardIterator __first, _ForwardIterator __last,
01171               std::forward_iterator_tag);
01172 
01173       // Called by assign(n,t), and the range assign when it turns out
01174       // to be the same thing.
01175       void
01176       _M_fill_assign(size_type __n, const value_type& __val);
01177 
01178 
01179       // Internal insert functions follow.
01180 
01181       // Called by the range insert to implement [23.1.1]/9
01182 
01183       // _GLIBCXX_RESOLVE_LIB_DEFECTS
01184       // 438. Ambiguity in the "do the right thing" clause
01185       template<typename _Integer>
01186         void
01187         _M_insert_dispatch(iterator __pos, _Integer __n, _Integer __val,
01188                __true_type)
01189         { _M_fill_insert(__pos, __n, __val); }
01190 
01191       // Called by the range insert to implement [23.1.1]/9
01192       template<typename _InputIterator>
01193         void
01194         _M_insert_dispatch(iterator __pos, _InputIterator __first,
01195                _InputIterator __last, __false_type)
01196         {
01197       typedef typename std::iterator_traits<_InputIterator>::
01198         iterator_category _IterCategory;
01199       _M_range_insert(__pos, __first, __last, _IterCategory());
01200     }
01201 
01202       // Called by the second insert_dispatch above
01203       template<typename _InputIterator>
01204         void
01205         _M_range_insert(iterator __pos, _InputIterator __first,
01206             _InputIterator __last, std::input_iterator_tag);
01207 
01208       // Called by the second insert_dispatch above
01209       template<typename _ForwardIterator>
01210         void
01211         _M_range_insert(iterator __pos, _ForwardIterator __first,
01212             _ForwardIterator __last, std::forward_iterator_tag);
01213 
01214       // Called by insert(p,n,x), and the range insert when it turns out to be
01215       // the same thing.
01216       void
01217       _M_fill_insert(iterator __pos, size_type __n, const value_type& __x);
01218 
01219 #ifdef __GXX_EXPERIMENTAL_CXX0X__
01220       // Called by resize(n).
01221       void
01222       _M_default_append(size_type __n);
01223 #endif
01224 
01225       // Called by insert(p,x)
01226 #ifndef __GXX_EXPERIMENTAL_CXX0X__
01227       void
01228       _M_insert_aux(iterator __position, const value_type& __x);
01229 #else
01230       template<typename... _Args>
01231         void
01232         _M_insert_aux(iterator __position, _Args&&... __args);
01233 #endif
01234 
01235       // Called by the latter.
01236       size_type
01237       _M_check_len(size_type __n, const char* __s) const
01238       {
01239     if (max_size() - size() < __n)
01240       __throw_length_error(__N(__s));
01241 
01242     const size_type __len = size() + std::max(size(), __n);
01243     return (__len < size() || __len > max_size()) ? max_size() : __len;
01244       }
01245 
01246       // Internal erase functions follow.
01247 
01248       // Called by erase(q1,q2), clear(), resize(), _M_fill_assign,
01249       // _M_assign_aux.
01250       void
01251       _M_erase_at_end(pointer __pos)
01252       {
01253     std::_Destroy(__pos, this->_M_impl._M_finish, _M_get_Tp_allocator());
01254     this->_M_impl._M_finish = __pos;
01255       }
01256     };
01257 
01258 
01259   /**
01260    *  @brief  Vector equality comparison.
01261    *  @param  x  A %vector.
01262    *  @param  y  A %vector of the same type as @a x.
01263    *  @return  True iff the size and elements of the vectors are equal.
01264    *
01265    *  This is an equivalence relation.  It is linear in the size of the
01266    *  vectors.  Vectors are considered equivalent if their sizes are equal,
01267    *  and if corresponding elements compare equal.
01268   */
01269   template<typename _Tp, typename _Alloc>
01270     inline bool
01271     operator==(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01272     { return (__x.size() == __y.size()
01273           && std::equal(__x.begin(), __x.end(), __y.begin())); }
01274 
01275   /**
01276    *  @brief  Vector ordering relation.
01277    *  @param  x  A %vector.
01278    *  @param  y  A %vector of the same type as @a x.
01279    *  @return  True iff @a x is lexicographically less than @a y.
01280    *
01281    *  This is a total ordering relation.  It is linear in the size of the
01282    *  vectors.  The elements must be comparable with @c <.
01283    *
01284    *  See std::lexicographical_compare() for how the determination is made.
01285   */
01286   template<typename _Tp, typename _Alloc>
01287     inline bool
01288     operator<(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01289     { return std::lexicographical_compare(__x.begin(), __x.end(),
01290                       __y.begin(), __y.end()); }
01291 
01292   /// Based on operator==
01293   template<typename _Tp, typename _Alloc>
01294     inline bool
01295     operator!=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01296     { return !(__x == __y); }
01297 
01298   /// Based on operator<
01299   template<typename _Tp, typename _Alloc>
01300     inline bool
01301     operator>(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01302     { return __y < __x; }
01303 
01304   /// Based on operator<
01305   template<typename _Tp, typename _Alloc>
01306     inline bool
01307     operator<=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01308     { return !(__y < __x); }
01309 
01310   /// Based on operator<
01311   template<typename _Tp, typename _Alloc>
01312     inline bool
01313     operator>=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
01314     { return !(__x < __y); }
01315 
01316   /// See std::vector::swap().
01317   template<typename _Tp, typename _Alloc>
01318     inline void
01319     swap(vector<_Tp, _Alloc>& __x, vector<_Tp, _Alloc>& __y)
01320     { __x.swap(__y); }
01321 
01322 _GLIBCXX_END_NESTED_NAMESPACE
01323 
01324 #endif /* _STL_VECTOR_H */