interface/wx/vector.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        vector.h
   3 // Purpose:     interface of wxVector<T>
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11     wxVector<T> is a template class which implements most of the @c std::vector
  12     class and can be used like it.
  13
  14     If wxWidgets is compiled in STL mode, wxVector will just be a typedef to
  15     @c std::vector. Just like for @c std::vector, objects stored in wxVector<T>
  16     need to be @e assignable but don't have to be @e "default constructible".
  17
  18     Please refer to the STL documentation for further information.
  19
  20     @nolibrary
  21     @category{containers}
  22
  23     @see @ref overview_container, wxList<T>, wxArray<T>, wxVectorSort<T>
  24 */
  25 template<typename T>
  26 class wxVector<T>
  27 {
  28 public:
  29     typedef size_t size_type;
  30     typedef size_t difference_type;
  31     typedef T value_type;
  32     typedef value_type* pointer;
  33     typedef value_type* iterator;
  34     typedef const value_type* const_iterator;
  35     typedef value_type& reference;
  36
  37     /**
  38         Constructor.
  39     */
  40     wxVector();
  41
  42     /**
  43         Constructor initializing the vector with the given number of
  44         default-constructed objects.
  45      */
  46     wxVector(size_type size);
  47
  48     /**
  49         Constructor initializing the vector with the given number of
  50         copies of the given object.
  51      */
  52     wxVector(size_type size, const value_type& value);
  53
  54     /**
  55         Constructor initializing the vector with the elements in the given
  56         range.
  57
  58         The @a InputIterator template parameter must be an input iterator type.
  59         This constructor adds all elements from @a first until, not not
  60         including, @a last to the vector.
  61
  62         @since 2.9.5
  63      */
  64     template <class InputIterator>
  65     wxVector(InputIterator first, InputIterator last);
  66
  67     /**
  68         Copy constructor.
  69     */
  70     wxVector(const wxVector<T>& c);
  71
  72     /**
  73         Destructor.
  74     */
  75     ~wxVector();
  76
  77     /**
  78         Resizes the vector to @a n and assigns @a v to all elements.
  79
  80         @see resize()
  81
  82         @since 2.9.5
  83      */
  84     void assign(size_type n, const value_type& v);
  85
  86     /**
  87         Assigns the elements in the given range to the vector.
  88
  89         The @a InputIterator template parameter must be an input iterator type.
  90         This method clears the vector and then adds all elements from @a first
  91         until, not not including, @a last to it.
  92
  93         @since 2.9.5
  94      */
  95     template <class InputIterator>
  96     void assign(InputIterator first, InputIterator last);
  97
  98     /**
  99         Returns item at position @a idx.
 100     */
 101     const value_type& at(size_type idx) const;
 102
 103     /**
 104         Returns item at position @a idx.
 105     */
 106     value_type& at(size_type idx);
 107
 108     /**
 109         Return the last item.
 110     */
 111     const value_type& back() const;
 112
 113     /**
 114         Return the last item.
 115     */
 116     value_type& back();
 117
 118     /**
 119         Return iterator to beginning of the vector.
 120     */
 121     const_iterator begin() const;
 122
 123     /**
 124         Return iterator to beginning of the vector.
 125     */
 126     iterator begin();
 127
 128     /**
 129         Return reverse iterator to end of the vector.
 130     */
 131     reverse_iterator rbegin();
 132
 133     /**
 134         Return reverse iterator to beginning of the vector.
 135     */
 136     reverse_iterator rend();
 137
 138
 139     /**
 140         Returns vector's current capacity, i.e.\ how much memory is allocated.
 141
 142         @see reserve()
 143     */
 144     size_type capacity() const;
 145
 146     /**
 147         Clears the vector.
 148     */
 149     void clear();
 150
 151     /**
 152         Returns @true if the vector is empty.
 153     */
 154     bool empty() const;
 155
 156     /**
 157         Returns iterator to the end of the vector.
 158     */
 159     const_iterator end() const;
 160
 161     /**
 162         Returns iterator to the end of the vector.
 163     */
 164     iterator end();
 165
 166     /**
 167         Erase item pointed to by iterator @a it.
 168
 169         @return Iterator pointing to the item immediately after the erased one.
 170     */
 171     iterator erase(iterator it);
 172
 173     /**
 174         Erase items in the range @a first to @a last (@a last is not erased).
 175
 176         @return Iterator pointing to the item immediately after the erased
 177                 range.
 178     */
 179     iterator erase(iterator first, iterator last);
 180
 181     /**
 182         Returns the first item.
 183     */
 184     const value_type& front() const;
 185
 186     /**
 187         Returns the first item.
 188     */
 189     value_type& front();
 190
 191     /**
 192         Insert item @a v at given position @a it.
 193
 194         @return Iterator for the inserted item.
 195     */
 196     iterator insert(iterator it, const value_type& v = value_type());
 197
 198     /**
 199         Assignment operator.
 200     */
 201     wxVector& operator=(const wxVector& vb);
 202
 203     /**
 204         Returns item at position @a idx.
 205     */
 206     const value_type& operator[](size_type idx) const;
 207
 208     /**
 209         Returns item at position @a idx.
 210     */
 211     value_type& operator[](size_type idx);
 212
 213     /**
 214         Removes the last item.
 215     */
 216     void pop_back();
 217
 218     /**
 219         Adds an item to the end of the vector.
 220     */
 221     void push_back(const value_type& v);
 222
 223     /**
 224         Reserves memory for at least @a n items.
 225
 226         @see capacity()
 227     */
 228     void reserve(size_type n);
 229
 230     /**
 231         Makes the vector of size @a n.
 232
 233         If @a n is less than the current size(), the elements at the end of the
 234         vector are erased. If it is greater, then the vector is completed with
 235         either the copies of the given object @a v or @c value_type() objects
 236         until it becomes of size @a n.
 237      */
 238     //@{
 239     void resize(size_type n);
 240     void resize(size_type n, const value_type& v);
 241     //@}
 242
 243     /**
 244         Returns the size of the vector.
 245     */
 246     size_type size() const;
 247
 248     /**
 249         Efficiently exchanges contents of this vector with another one.
 250
 251         After the execution of this function the contents of this vector is
 252         equal to the original contents of @a v and the contents of @a v becomes
 253         the original contents of this vector without copying the data.
 254
 255         @since 2.9.1
 256      */
 257     void swap(wxVector& v);
 258 };
 259
 260
 261 /**
 262    Sort the contents of a @c wxVector<T>.  In a STL build this function will
 263    be defined as a thin wrapper around std::sort.  To be sortable the
 264    contained type must support the less-than operator.
 265
 266    @code
 267    wxVector<SomeClass> v;
 268    ... // items are added to the vector v...
 269    wxVectorSort(v);
 270    @endcode
 271
 272    @see wxVector<T>
 273 */
 274 template<typename T>
 275 void wxVectorSort(wxVector<T>& v);