ACE/ace/Vector_T.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Vector_T.h
   6  *
   7  *  @author Craig L. Ching <cching@mqsoftware.com>
   8  *  @author Gonzalo Diethelm <gonzalo.diethelm@aditiva.com>
   9  */
  10 //==========================================================================
  11
  12 #ifndef ACE_VECTOR_T_H
  13 #define ACE_VECTOR_T_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/Containers_T.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 /*
  26  * Default size for an ACE_Vector.
  27  */
  28 static constexpr size_t ACE_VECTOR_DEFAULT_SIZE = 32;
  29
  30 // Forward declaration.
  31 template <class T, size_t DEFAULT_SIZE> class ACE_Vector_Iterator;
  32
  33 /**
  34  * @class ACE_Vector
  35  *
  36  * @brief Defines an STL-like vector container.
  37  *
  38  * This is an STL-like template vector container, a wrapper around
  39  * ACE_Array.  It provides at least the basic std::vector look and
  40  * feel: push_back(), clear(), resize(), capacity().  This template
  41  * class uses the copy semantic paradigm, though it is okay to use
  42  * reference counted smart pointers (see ACE_Ptr&lt;T&gt;) with this
  43  * template class.
  44  *
  45  * <b> Requirements and Performance Characteristics</b>
  46  *   - Internal Structure
  47  *       ACE_Array
  48  *   - Duplicates allowed?
  49  *       Yes
  50  *   - Random access allowed?
  51  *       No
  52  *   - Search speed
  53  *       N/A
  54  *   - Insert/replace speed
  55  *       Linear
  56  *   - Iterator still valid after change to container?
  57  *       Yes
  58  *   - Frees memory for removed elements?
  59  *       No
  60  *   - Items inserted by
  61  *       Value
  62  *   - Requirements for contained type
  63  *       -# Default constructor
  64  *       -# Copy constructor
  65  *       -# operator=
  66  */
  67 template<class T, size_t DEFAULT_SIZE = ACE_VECTOR_DEFAULT_SIZE>
  68 class ACE_Vector : public ACE_Array<T>
  69 {
  70 public:
  71   /**
  72    * A short name for iterator for ACE_Vector.
  73    */
  74   typedef ACE_Vector_Iterator<T, DEFAULT_SIZE> Iterator;
  75
  76
  77   /**
  78    * General constructor.
  79    *
  80    * @param init_size Initial size of the vector with the default
  81    *                  value of DEFAULT_SIZE
  82    * @param alloc Pointer to an ACE allocator.  If it is NULL then the
  83    *              default ACE allocator is used
  84    */
  85   ACE_Vector (const size_t init_size = DEFAULT_SIZE,
  86               ACE_Allocator* alloc = 0);
  87
  88   /**
  89    * Destructor.
  90    */
  91   ~ACE_Vector () = default;
  92
  93   /// Declare the dynamic allocation hooks.
  94   ACE_ALLOC_HOOK_DECLARE;
  95
  96   /**
  97    * Returns the current vector capacity, that is, the currently
  98    * allocated buffer size.
  99    *
 100    * @return Current buffer size of the vector
 101    */
 102   size_t capacity () const;
 103
 104   /**
 105    * Returns the vector's dynamic size / actual current size of the
 106    * vector.  Do not confuse it with ACE_Array::size(), which returns
 107    * the array's capacity.  Unfortunately, ACE is not very consistent
 108    * with the function names.
 109    *
 110    * @return Dynamic size / actual current size of the vector.
 111    */
 112   size_t size () const;
 113
 114   /**
 115    * Clears out the vector.  It does not reallocate the vector's
 116    * buffer, it is just sets the vector's dynamic size to 0.
 117    */
 118   void clear ();
 119
 120   /**
 121    * Resizes the vector to the new capacity.  If the vector's current
 122    * capacity is smaller than the size to be specified, then the
 123    * buffer gets reallocated.  If the new capacity is less than the
 124    * current capacity of the vector, the buffer size stays the same.
 125    *
 126    * @param new_size New capacity of the vector
 127    * @param t A filler value (of the class T) for initializing the
 128    *          elements of the vector with.  By default, if this
 129    *          parameter is not specified, the default value of the
 130    *          class T will be used (for more detail, see the
 131    *          initialization clause for this parameter).
 132    */
 133   void resize (const size_t new_size,
 134                const T& t);
 135
 136   /**
 137    * Appends a new element to the vector ("push back").  If the
 138    * dynamic size of the vector is equal to the capacity of the vector
 139    * (vector is at capacity), the vector automatically doubles its
 140    * capacity.
 141    *
 142    * @param elem A reference to the new element to be appended.  By
 143    *             default, this parameters gets initialized with the
 144    *             default value of the class T.
 145    */
 146   void push_back (const T& elem);
 147
 148   /**
 149    * Deletes the last element from the vector ("pop back").  What this
 150    * function really does is decrement the dynamic size of the
 151    * vector.  The vector's buffer does not get reallocated for
 152    * performance.
 153    */
 154   void pop_back ();
 155
 156   /**
 157    * This function dumps the content of the vector.  TO BE MOVED out
 158    * of this class.  It needs to be implemented as a global template
 159    * function that accepts a const ACE_Vector&lt;T&gt;, in order to
 160    * make instances of this class compile on Linux.  G++ and xlC
 161    * have template instantiation algoriths, which are different from
 162    * the one in Visual C++.  The algorithms try to instantiate ALL
 163    * methods declared in the template class, regardless of whether the
 164    * functions are used or not.  That is, all of the classes, that are
 165    * used as elements in ACE_Vector's, have to have the dump() methods
 166    * defined in them (seems to be overkill).
 167    *
 168    * This function calls T::dump() for each element of the vector.
 169    */
 170   void dump () const;
 171
 172   // = Compare operators
 173
 174   /// Equality comparison operator.
 175   /**
 176    * Compare this vector with @arg s for equality.  Two vectors are equal
 177    * if their sizes are equal and all the elements are equal.
 178    */
 179   bool operator== (const ACE_Vector<T, DEFAULT_SIZE> &s) const;
 180
 181   /// Inequality comparison operator.
 182   /**
 183    * Compare this vector with @arg s for inequality such that @c *this !=
 184    * @arg s is always the complement of the boolean return value of
 185    * @c *this == @arg s.
 186    */
 187   bool operator!= (const ACE_Vector<T, DEFAULT_SIZE> &s) const;
 188
 189   void swap (ACE_Vector &rhs);
 190
 191   /*
 192    * Implement our own end functions because Array_Base's end functions use the
 193    * current capacity, not the Vector's actual element count!
 194    */
 195   /// C++ Standard End Iterator
 196   ///{
 197   typename ACE_Array_Base<T>::iterator end ();
 198   typename ACE_Array_Base<T>::const_iterator end () const;
 199   ///}
 200
 201 protected:
 202   /**
 203    * Dynamic size (length) of the vector.
 204    */
 205   size_t length_;
 206
 207   /**
 208    * Current capacity (buffer size) of the vector.
 209    */
 210   size_t curr_max_size_;
 211
 212   friend class ACE_Vector_Iterator<T, DEFAULT_SIZE>;
 213 };
 214
 215 /**
 216  * @class ACE_Vector_Iterator
 217  *
 218  * @brief Implement an iterator over an ACE_Vector.
 219  *
 220  * This iterator is safe in the face of vector element deletions.
 221  * But it is NOT safe if the vector is resized via the assignment
 222  * operator during iteration.  That would be very odd, and dangerous.
 223  */
 224 template <class T, size_t DEFAULT_SIZE = ACE_VECTOR_DEFAULT_SIZE>
 225 class ACE_Vector_Iterator
 226 {
 227 public:
 228   ACE_Vector_Iterator (ACE_Vector<T, DEFAULT_SIZE> &);
 229
 230   // = Iteration methods.
 231
 232   /// Pass back the @a next_item that hasn't been seen in the vector.
 233   /// Returns 0 when all items have been seen, else 1.
 234   int next (T *&next_item);
 235
 236   /// Move forward by one element in the vector.  Returns 0 when all the
 237   /// items in the vector have been seen, else 1.
 238   int advance ();
 239
 240   /// Returns 1 when all items have been seen, else 0.
 241   int done () const;
 242
 243   /// Dump the state of an object.
 244   void dump () const;
 245
 246   /// Declare the dynamic allocation hooks.
 247   ACE_ALLOC_HOOK_DECLARE;
 248
 249 private:
 250   /// Pointer to the current item in the iteration.
 251   size_t current_;
 252
 253   /// Reference to the vector we're iterating over.
 254   ACE_Vector<T, DEFAULT_SIZE> &vector_;
 255 };
 256
 257 ACE_END_VERSIONED_NAMESPACE_DECL
 258
 259 #if defined (__ACE_INLINE__)
 260 #include "ace/Vector_T.inl"
 261 #endif /* __ACE_INLINE__ */
 262
 263 #include "ace/Vector_T.cpp"
 264
 265 #include /**/ "ace/post.h"
 266
 267 #endif /* ACE_VECTOR_T_H */