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         Copy constructor.
  56     */
  57     wxVector(const wxVector<T>& c);
  58
  59     /**
  60         Destructor.
  61     */
  62     ~wxVector();
  63
  64     /**
  65         Returns item at position @a idx.
  66     */
  67     const value_type& at(size_type idx) const;
  68
  69     /**
  70         Returns item at position @a idx.
  71     */
  72     value_type& at(size_type idx);
  73
  74     /**
  75         Return the last item.
  76     */
  77     const value_type& back() const;
  78
  79     /**
  80         Return the last item.
  81     */
  82     value_type& back();
  83
  84     /**
  85         Return iterator to beginning of the vector.
  86     */
  87     const_iterator begin() const;
  88
  89     /**
  90         Return iterator to beginning of the vector.
  91     */
  92     iterator begin();
  93
  94     /**
  95         Return reverse iterator to end of the vector.
  96     */
  97     reverse_iterator rbegin();
  98
  99     /**
 100         Return reverse iterator to beginning of the vector.
 101     */
 102     reverse_iterator rend();
 103
 104
 105     /**
 106         Returns vector's current capacity, i.e. how much memory is allocated.
 107
 108         @see reserve()
 109     */
 110     size_type capacity() const;
 111
 112     /**
 113         Clears the vector.
 114     */
 115     void clear();
 116
 117     /**
 118         Returns @true if the vector is empty.
 119     */
 120     bool empty() const;
 121
 122     /**
 123         Returns iterator to the end of the vector.
 124     */
 125     const_iterator end() const;
 126
 127     /**
 128         Returns iterator to the end of the vector.
 129     */
 130     iterator end();
 131
 132     /**
 133         Erase item pointed to by iterator @a it.
 134
 135         @return Iterator pointing to the item immediately after the erased one.
 136     */
 137     iterator erase(iterator it);
 138
 139     /**
 140         Erase items in the range @a first to @a last (@a last is not erased).
 141
 142         @return Iterator pointing to the item immediately after the erased
 143                 range.
 144     */
 145     iterator erase(iterator first, iterator last);
 146
 147     /**
 148         Returns the first item.
 149     */
 150     const value_type& front() const;
 151
 152     /**
 153         Returns the first item.
 154     */
 155     value_type& front();
 156
 157     /**
 158         Insert item @a v at given position @a it.
 159
 160         @return Iterator for the inserted item.
 161     */
 162     iterator insert(iterator it, const value_type& v = value_type());
 163
 164     /**
 165         Assignment operator.
 166     */
 167     wxVector& operator=(const wxVector& vb);
 168
 169     /**
 170         Returns item at position @a idx.
 171     */
 172     const value_type& operator[](size_type idx) const;
 173
 174     /**
 175         Returns item at position @a idx.
 176     */
 177     value_type& operator[](size_type idx);
 178
 179     /**
 180         Removes the last item.
 181     */
 182     void pop_back();
 183
 184     /**
 185         Adds an item to the end of the vector.
 186     */
 187     void push_back(const value_type& v);
 188
 189     /**
 190         Reserves memory for at least @a n items.
 191
 192         @see capacity()
 193     */
 194     void reserve(size_type n);
 195
 196     /**
 197         Makes the vector of size @a n.
 198
 199         If @a n is less than the current size(), the elements at the end of the
 200         vector are erased. If it is greater, then the vector is completed with
 201         either the copies of the given object @a v or @c value_type() objects
 202         until it becomes of size @a n.
 203      */
 204     //@{
 205     void resize(size_type n);
 206     void resize(size_type n, const value_type& v);
 207     //@}
 208
 209     /**
 210         Returns the size of the vector.
 211     */
 212     size_type size() const;
 213
 214     /**
 215         Efficiently exchanges contents of this vector with another one.
 216
 217         After the execution of this function the contents of this vector is
 218         equal to the original contents of @a v and the contents of @a v becomes
 219         the original contents of this vector without copying the data.
 220
 221         @since 2.9.1
 222      */
 223     void swap(wxVector& v);
 224 };
 225
 226
 227 /**
 228    Sort the contents of a @c wxVector<T>.  In a STL build this function will
 229    be defined as a thin wrapper around std::sort.  To be sortable the
 230    contained type must support the less-than operator.
 231
 232    @code
 233    wxVector<SomeClass> v;
 234    ... // items are added to the vector v...
 235    wxVectorSort(v);
 236    @endcode
 237
 238    @see wxVector<T>
 239 */
 240 template<typename T>
 241 void wxVectorSort(wxVector<T>& v);