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