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