Array_Base.h

Go to the documentation of this file.
00001 //=============================================================================
00002 /**
00003  *  @file Array_Base.h
00004  *
00005  *  Array_Base.h,v 4.13 2006/01/29 01:03:26 schmidt Exp
00006  *
00007  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00008  */
00009 //=============================================================================
00010 
00011 #ifndef ACE_ARRAY_BASE_H
00012 #define ACE_ARRAY_BASE_H
00013 
00014 #include /**/ "ace/pre.h"
00015 
00016 #include "ace/config-all.h"
00017 
00018 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00019 # pragma once
00020 #endif /* ACE_LACKS_PRAGMA_ONCE */
00021 
00022 #include "ace/Global_Macros.h"
00023 #include "ace/Malloc_Base.h"
00024 
00025 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00026 
00027 // Forward declaration.
00028 template <class T> class ACE_Array_Iterator;
00029 
00030 /**
00031  * @class ACE_Array_Base
00032  *
00033  * @brief Implement a simple dynamic array
00034  *
00035  * This parametric class implements a simple dynamic array;
00036  * resizing must be controlled by the user. No comparison or find
00037  * operations are implemented.
00038  */
00039 template<class T>
00040 class ACE_Array_Base
00041 {
00042 public:
00043 
00044   // Define a "trait"
00045   typedef T TYPE;
00046   typedef ACE_Array_Iterator<T> ITERATOR;
00047 
00048   // = Initialization and termination methods.
00049 
00050   /// Dynamically create an uninitialized array.
00051   ACE_Array_Base (size_t size = 0,
00052                   ACE_Allocator *the_allocator = 0);
00053 
00054   /// Dynamically initialize the entire array to the <default_value>.
00055   ACE_Array_Base (size_t size,
00056                   const T &default_value,
00057                   ACE_Allocator *the_allocator = 0);
00058 
00059   /**
00060    * The copy constructor performs initialization by making an exact
00061    * copy of the contents of parameter <s>, i.e., *this == s will
00062    * return true.
00063    */
00064   ACE_Array_Base (const ACE_Array_Base<T> &s);
00065 
00066   /**
00067    * Assignment operator performs an assignment by making an exact
00068    * copy of the contents of parameter <s>, i.e., *this == s will
00069    * return true.  Note that if the <max_size_> of <array_> is >= than
00070    * <s.max_size_> we can copy it without reallocating.  However, if
00071    * <max_size_> is < <s.max_size_> we must delete the <array_>,
00072    * reallocate a new <array_>, and then copy the contents of <s>.
00073    */
00074   void operator= (const ACE_Array_Base<T> &s);
00075 
00076   /// Clean up the array (e.g., delete dynamically allocated memory).
00077   ~ACE_Array_Base (void);
00078 
00079   // = Set/get methods.
00080 
00081   /// Set item in the array at location <slot>.  Doesn't
00082   /// perform range checking.
00083   T &operator [] (size_t slot);
00084 
00085   /// Get item in the array at location <slot>.  Doesn't
00086   /// perform range checking.
00087   const T &operator [] (size_t slot) const;
00088 
00089   /// Set an item in the array at location <slot>.  Returns
00090   /// -1 if <slot> is not in range, else returns 0.
00091   int set (const T &new_item, size_t slot);
00092 
00093   /**
00094    * Get an item in the array at location <slot>.  Returns -1 if
00095    * <slot> is not in range, else returns 0.  Note that this function
00096    * copies the item.  If you want to avoid the copy, you can use
00097    * the const operator [], but then you'll be responsible for range checking.
00098    */
00099   int get (T &item, size_t slot) const;
00100 
00101   /// Returns the <cur_size_> of the array.
00102   size_t size (void) const;
00103 
00104   /**
00105    * Changes the size of the array to match <new_size>.
00106    * It copies the old contents into the new array.
00107    * Return -1 on failure.
00108    */
00109   int size (size_t new_size);
00110 
00111   /// Returns the <max_size_> of the array.
00112   size_t max_size (void) const;
00113 
00114   /**
00115    * Changes the size of the array to match <new_size>.
00116    * It copies the old contents into the new array.
00117    * Return -1 on failure.
00118    * It does not affect new_size
00119    */
00120   int max_size (size_t new_size);
00121 
00122 protected:
00123   /// Returns 1 if <slot> is within range, i.e., 0 >= <slot> <
00124   /// <cur_size_>, else returns 0.
00125   int in_range (size_t slot) const;
00126 
00127   /// Maximum size of the array, i.e., the total number of <T> elements
00128   /// in <array_>.
00129   size_t max_size_;
00130 
00131   /**
00132    * Current size of the array.  This starts out being == to
00133    * <max_size_>.  However, if we are assigned a smaller array, then
00134    * <cur_size_> will become less than <max_size_>.  The purpose of
00135    * keeping track of both sizes is to avoid reallocating memory if we
00136    * don't have to.
00137    */
00138   size_t cur_size_;
00139 
00140   /// Pointer to the array's storage buffer.
00141   T *array_;
00142 
00143   /// Allocation strategy of the ACE_Array_Base.
00144   ACE_Allocator *allocator_;
00145 
00146   friend class ACE_Array_Iterator<T>;
00147 };
00148 
00149 // ****************************************************************
00150 
00151 /**
00152  * @class ACE_Array_Iterator
00153  *
00154  * @brief Implement an iterator over an ACE_Array.
00155  *
00156  * This iterator is safe in the face of array element deletions.
00157  * But it is NOT safe if the array is resized (via the ACE_Array
00158  * assignment operator) during iteration.  That would be very
00159  * odd, and dangerous.
00160  */
00161 template <class T>
00162 class ACE_Array_Iterator
00163 {
00164 public:
00165   // = Initialization method.
00166   ACE_Array_Iterator (ACE_Array_Base<T> &);
00167 
00168   // = Iteration methods.
00169 
00170   /// Pass back the <next_item> that hasn't been seen in the Array.
00171   /// Returns 0 when all items have been seen, else 1.
00172   int next (T *&next_item);
00173 
00174   /// Move forward by one element in the Array.  Returns 0 when all the
00175   /// items in the Array have been seen, else 1.
00176   int advance (void);
00177 
00178   /// Returns 1 when all items have been seen, else 0.
00179   int done (void) const;
00180 
00181   /// Dump the state of an object.
00182   void dump (void) const;
00183 
00184   /// Declare the dynamic allocation hooks.
00185   ACE_ALLOC_HOOK_DECLARE;
00186 
00187 private:
00188   /// Pointer to the current item in the iteration.
00189   size_t current_;
00190 
00191   /// Pointer to the Array we're iterating over.
00192   ACE_Array_Base<T> &array_;
00193 };
00194 
00195 ACE_END_VERSIONED_NAMESPACE_DECL
00196 
00197 #if defined (__ACE_INLINE__)
00198 #include "ace/Array_Base.inl"
00199 #endif /* __ACE_INLINE__ */
00200 
00201 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00202 #include "ace/Array_Base.cpp"
00203 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00204 
00205 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00206 #pragma implementation ("Array_Base.cpp")
00207 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00208 
00209 #include /**/ "ace/post.h"
00210 
00211 #endif /* ACE_ARRAY_BASE_H */

Generated on Thu Nov 9 09:41:45 2006 for ACE by doxygen 1.3.6