interface/wx/vector.h

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