ACE/ace/Array_Base.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file Array_Base.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_ARRAY_BASE_H
  12 #define ACE_ARRAY_BASE_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/config-all.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Global_Macros.h"
  23 #include "ace/Malloc_Base.h"
  24 #include <iterator>  /* For reverse_iterator adapters */
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 // Forward declaration.
  29 template <class T> class ACE_Array_Iterator;
  30
  31 /**
  32  * @class ACE_Array_Base
  33  *
  34  * @brief Implement a simple dynamic array
  35  *
  36  * This parametric class implements a simple dynamic array;
  37  * resizing must be controlled by the user. No comparison or find
  38  * operations are implemented.
  39  */
  40 template<class T>
  41 class ACE_Array_Base
  42 {
  43 public:
  44   // Old/ACE-style traits.
  45   typedef T TYPE;
  46   typedef ACE_Array_Iterator<T> ITERATOR;
  47
  48   // STL-style typedefs/traits.
  49   typedef T                              value_type;
  50   typedef value_type *                   iterator;
  51   typedef value_type const *             const_iterator;
  52   typedef value_type &                   reference;
  53   typedef value_type const &             const_reference;
  54   typedef value_type *                   pointer;
  55   typedef value_type const *             const_pointer;
  56   typedef ptrdiff_t                      difference_type;
  57   typedef ACE_Allocator::size_type       size_type;
  58   typedef std::reverse_iterator<iterator>       reverse_iterator;
  59   typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
  60
  61   /// Dynamically create an uninitialized array.
  62   ACE_Array_Base (size_type size = 0,
  63                   ACE_Allocator * the_allocator = 0);
  64
  65   /// Dynamically initialize the entire array to the @a default_value.
  66   ACE_Array_Base (size_type size,
  67                   T const & default_value,
  68                   ACE_Allocator * the_allocator = 0);
  69
  70   /**
  71    * The copy constructor performs initialization by making an exact
  72    * copy of the contents of parameter @a s, i.e., *this == s will
  73    * return true.
  74    */
  75   ACE_Array_Base (ACE_Array_Base<T> const & s);
  76
  77   /**
  78    * Assignment operator performs an assignment by making an exact
  79    * copy of the contents of parameter @a s, i.e., *this == s will
  80    * return true.  Note that if the <max_size_> of <array_> is >= than
  81    * <s.max_size_> we can copy it without reallocating.  However, if
  82    * <max_size_> is < <s.max_size_> we must delete the <array_>,
  83    * reallocate a new <array_>, and then copy the contents of <s>.
  84    */
  85   void operator= (ACE_Array_Base<T> const & s);
  86
  87   /// Clean up the array (e.g., delete dynamically allocated memory).
  88   ~ACE_Array_Base ();
  89
  90   // = Set/get methods.
  91
  92   /// Set item in the array at location @a slot.  Doesn't
  93   /// perform range checking.
  94   T & operator[] (size_type slot);
  95
  96   /// Get item in the array at location @a slot.  Doesn't
  97   /// perform range checking.
  98   T const & operator[] (size_type slot) const;
  99
 100   /// Set an item in the array at location @a slot.  Returns
 101   /// -1 if @a slot is not in range, else returns 0.
 102   int set (T const & new_item, size_type slot);
 103
 104   /**
 105    * Get an item in the array at location @a slot.  Returns -1 if
 106    * @a slot is not in range, else returns 0.  Note that this function
 107    * copies the item.  If you want to avoid the copy, you can use
 108    * the const operator [], but then you'll be responsible for range checking.
 109    */
 110   int get (T & item, size_type slot) const;
 111
 112   /// Returns the <cur_size_> of the array.
 113   size_type size () const;
 114
 115   /**
 116    * Changes the size of the array to match @a new_size.
 117    * It copies the old contents into the new array.
 118    * Return -1 on failure.
 119    */
 120   int size (size_type new_size);
 121
 122   /// Returns the <max_size_> of the array.
 123   size_type max_size () const;
 124
 125   /**
 126    * Changes the size of the array to match @a new_size.
 127    * It copies the old contents into the new array.
 128    * Return -1 on failure.
 129    * It does not affect new_size
 130    */
 131   int max_size (size_type new_size);
 132
 133   /**
 134    * @name Forward Iterator Accessors
 135    *
 136    * Forward iterator accessors.
 137    */
 138   //@{
 139   iterator begin ();
 140   iterator end   ();
 141   const_iterator begin () const;
 142   const_iterator end   () const;
 143   //@}
 144
 145   /**
 146    * @name Reverse Iterator Accessors
 147    *
 148    * Reverse iterator accessors.
 149    */
 150   //@{
 151   reverse_iterator rbegin ();
 152   reverse_iterator rend   ();
 153   const_reverse_iterator rbegin () const;
 154   const_reverse_iterator rend   () const;
 155   //@}
 156
 157   /// Swap the contents of this array with the given @a array in
 158   /// an exception-safe manner.
 159   void swap (ACE_Array_Base<T> & array);
 160
 161 protected:
 162   /// Returns 1 if @a slot is within range, i.e., 0 >= @a slot <
 163   /// @c cur_size_, else returns 0.
 164   bool in_range (size_type slot) const;
 165
 166   /// Maximum size of the array, i.e., the total number of @c T elements
 167   /// in @c array_.
 168   size_type max_size_;
 169
 170   /**
 171    * Current size of the array.  This starts out being == to
 172    * <max_size_>.  However, if we are assigned a smaller array, then
 173    * <cur_size_> will become less than <max_size_>.  The purpose of
 174    * keeping track of both sizes is to avoid reallocating memory if we
 175    * don't have to.
 176    */
 177   size_type cur_size_;
 178
 179   /// Pointer to the array's storage buffer.
 180   value_type * array_;
 181
 182   /// Allocation strategy of the ACE_Array_Base.
 183   ACE_Allocator * allocator_;
 184
 185   friend class ACE_Array_Iterator<T>;
 186 };
 187
 188 // ****************************************************************
 189
 190 /**
 191  * @class ACE_Array_Iterator
 192  *
 193  * @brief Implement an iterator over an ACE_Array.
 194  *
 195  * This iterator is safe in the face of array element deletions.
 196  * But it is NOT safe if the array is resized (via the ACE_Array
 197  * assignment operator) during iteration.  That would be very
 198  * odd, and dangerous.
 199  */
 200 template <class T>
 201 class ACE_Array_Iterator
 202 {
 203 public:
 204   ACE_Array_Iterator (ACE_Array_Base<T> &);
 205
 206   // = Iteration methods.
 207
 208   /// Pass back the @a next_item that hasn't been seen in the Array.
 209   /// Returns 0 when all items have been seen, else 1.
 210   int next (T *&next_item);
 211
 212   /// Move forward by one element in the Array.  Returns 0 when all the
 213   /// items in the Array have been seen, else 1.
 214   int advance ();
 215
 216   /// Returns 1 when all items have been seen, else 0.
 217   int done () const;
 218
 219   /// Dump the state of an object.
 220   void dump () const;
 221
 222   /// Declare the dynamic allocation hooks.
 223   ACE_ALLOC_HOOK_DECLARE;
 224
 225 private:
 226   /// Pointer to the current item in the iteration.
 227   size_t current_;
 228
 229   /// Pointer to the Array we're iterating over.
 230   ACE_Array_Base<T> &array_;
 231 };
 232
 233 ACE_END_VERSIONED_NAMESPACE_DECL
 234
 235 #if defined (__ACE_INLINE__)
 236 #include "ace/Array_Base.inl"
 237 #endif /* __ACE_INLINE__ */
 238
 239 #include "ace/Array_Base.cpp"
 240
 241 #include /**/ "ace/post.h"
 242
 243 #endif /* ACE_ARRAY_BASE_H */