dep/ACE_wrappers/ace/Vector_T.h

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