gml_DynamicArray.h

Go to the documentation of this file.
00001 /** 
00002  * @file gml_DynamicArray.h
00003  * 
00004  *    Definition of the gml_TDynamicArray class template.
00005  * 
00006  *    Copyright (c) 1998-2004 CLIPS-IMAG
00007  * 
00008  *    See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00009  *    of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00010  * 
00011  *    Created on August 29, 1998 (FB).
00012  */
00013 
00014 #ifndef __GMLDYNAMICARRAY__
00015 #define __GMLDYNAMICARRAY__
00016 
00017 #include "gml/base/gml_Types.h"
00018 #include "gml/base/gml_Errors.h"
00019 
00020 
00021 
00022 /// gml_TDynamicArray --
00023 ///    An array of fixed sized elements that can grow over time.
00024 ///    Growth is by block of elements (not one element every time).
00025 ///    Finding a free slot in the array is somewhat optimized using a
00026 ///    bitmap of used slots.
00027 
00028 template <class T>
00029 class gml_TDynamicArray
00030 {
00031   public:
00032 
00033     static const gml_TBlockSize sDefaultNbElem     = 20; ///< default starting number of elements in an array
00034     static const gml_TBlockSize sDefaultNbIncrease = 20; ///< default additional slots allocated on array growth
00035 
00036 
00037     /// Init --
00038     ///   Initializes the array with <nbElem> elements of size <elemSize>.
00039     ///   When a new element is required and the array is full, the array
00040     ///   is re-allocated with <nbIncrease> more elements.
00041 
00042     gml_TError        Init (gml_TBlockSize    nbElem      = sDefaultNbElem,
00043                             gml_TBlockSize    nbIncrease  = sDefaultNbIncrease);
00044 
00045 
00046     /// Dispose --
00047     ///   Release the array resources.
00048 
00049     void              Dispose ();
00050 
00051     /// Base --
00052     ///   Returns the base address of the array.
00053     ///
00054     /// @warning
00055     /// The base address in only valid from the Base() call until
00056     /// the next call to GetElem(): GetElem() may require a relocation
00057     /// of the memory if the array is full.
00058 
00059     T*                Base ()
00060                         { return fMem; }
00061 
00062     /// GetElem --
00063     ///   Get a pointer to a new element from the array.
00064     ///   If <index> is not NULL, <*index> recieves the index of the element in the array.
00065     ///
00066     ///   @return
00067     ///     A pointer to the new element everything goes ok.
00068     ///     NULL if there is no more memory to grow the array.
00069 
00070     T*                GetElem (gml_TBlockSize* index = (gml_TBlockSize*)NULL);
00071 
00072     /// ReleaseElem --
00073     ///   Flag <elem> as not being used anymore.
00074 
00075     void              ReleaseElem (T* elem);
00076 
00077 
00078 
00079   protected:
00080 
00081     gml_TError        Allocate (gml_TBlockSize nbElem);
00082 
00083     gml_TBlockSize    fNbIncrease;  ///< size of the increased allocation when a new element is
00084                                     ///<  needed and the array is full
00085 
00086     T*                fMem;         ///< memory allocated for the array
00087     gml_TBlockSize    fNbElem;      ///< number of elements that the current memory can store
00088     gml_TBlockSize    fInUse;       ///< number of current allocated elements
00089 
00090     UInt32*           fBitmap;      ///< bitmap of elements in use
00091     gml_TBlockSize    fBMSize;      ///< size (number of 32 bit words) of used bitmap
00092 };
00093 
00094 
00095 #endif
00096 
00097