gml_Array.h

Go to the documentation of this file.
00001 /** @file gml_Array.h
00002  * 
00003  *     Definition of gml_TArray.
00004  * 
00005  *   Copyright (c) 2004 CLIPS-IMAG
00006  * 
00007  *   See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00008  *   of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00009  * 
00010  *   Created in June 2004 (JL).
00011  */
00012 
00013 #ifndef __GML_ARRAY__
00014 #define __GML_ARRAY__
00015 
00016 #include "gml/base/gml_Types.h"
00017 #include "gml/base/gml_Errors.h"
00018 #include "gml/base/gml_Alloc.h"
00019 
00020 #include <stdlib.h>
00021 
00022 /**
00023  *  gml_TArray --
00024  * 
00025  *    Simple fixed-size typed arrays with transparent bounds checking. 
00026  *    If an out-of-bounds index in used, the program terminates immediately.
00027  *    
00028  *    Checks are disabled if the NDEBUG macro is defined (like assertions).
00029  * 
00030  */
00031 template <typename T>
00032 class gml_TArray
00033 {
00034   public:
00035 
00036     ///
00037     /// Constructor --
00038     ///   Zero size and payload address.
00039     ///
00040     gml_TArray() {
00041       fSize = 0UL;
00042       fData = (T*)NULL;
00043     }
00044     
00045     ///
00046     /// Init --
00047     ///   Allocate memory for the array.
00048     ///
00049     gml_TError Init (unsigned size) {
00050       gml_TError err;
00051       
00052       err = gml_NewArray (fData, size);
00053       if (err != gml_cNoError) return err;
00054 
00055       fSize = size;
00056       gml_ZeroArray (fData, fSize);
00057       return gml_cNoError;
00058     }
00059 
00060     ///
00061     /// Dispose --
00062     ///   Release resources claimed by Init().
00063     ///
00064     void Dispose () {
00065       gml_TestAndDeleteArray (fData);
00066       fSize = 0UL;
00067       fData = (T*)NULL;
00068     }
00069 
00070     ///
00071     /// LValue indexing operator --
00072     ///
00073     T &operator[] (unsigned const index) {
00074       #ifndef NDEBUG
00075       if (index >= fSize) abort();
00076       #endif
00077       return fData[index];
00078     }
00079 
00080     ///
00081     /// RValue indexing operator --
00082     ///
00083     T operator[] (unsigned const index) const {
00084       #ifndef NDEBUG
00085       if (index >= fSize) abort();
00086       #endif
00087       return fData[index];
00088     }
00089 
00090     ///
00091     /// Size --
00092     ///   Return the number of elements in the array.
00093     ///
00094     unsigned Size () const {
00095       return fSize;
00096     }
00097 
00098     ///
00099     /// Wrap --
00100     ///   Wrap an existing C array <data> of <size> items into a gml_TArray.
00101     ///   A deep copy of the existing array is performed.
00102     ///   @warning Make sure that the source array actually contains at least
00103     ///            <size> items.
00104     ///
00105     gml_TError Wrap (unsigned size, T const * const data) {
00106       gml_TError err;
00107       
00108       Dispose ();
00109       err = Init (size);
00110       if (err != gml_cNoError) return err;
00111       memcpy (fData, data, size * sizeof(T));
00112       fSize = size;
00113       
00114       return gml_cNoError;
00115     }
00116 
00117     ///
00118     /// Unwrap --
00119     ///   Copy this gml_TArray into an existing C array of size <size>.
00120     ///   The number of objects copied is the smaller of <size> and
00121     ///   the size of this array.
00122     ///   @warning Make sure that the destination array actually can store at
00123     ///            least <size> items.
00124     ///
00125     void Unwrap (unsigned size, T * const data) {
00126       unsigned nbItems = fSize < size ? fSize : size;
00127       memcpy ((void*) data, (const void*) fData, nbItems * sizeof(T));
00128     }
00129     
00130     ///
00131     /// Clone --
00132     ///   Make this array a replicate of the argument array.
00133     ///   Init () must have been called first.
00134     ///   A deep copy of the existing array data is performed.
00135     ///
00136     gml_TError Clone (gml_TArray<T> const source) {
00137       if (fSize != source.Size ()) {
00138         Dispose ();
00139         gml_TError err = this->Init (source.Size ());
00140         if (err != gml_cNoError) return err;
00141       }
00142       
00143       memcpy (fData, source.fData, fSize * sizeof(T));
00144             
00145       return gml_cNoError;
00146     }
00147 
00148     ///
00149     /// Sort --
00150     ///   Sort the underlying C array, using the argument comparison function.
00151     ///
00152     void Sort (int (*comparator) (T*,T*)) {
00153       typedef int (*untyped_comparator) (const void*, const void*);
00154       qsort (fData, fSize, sizeof(T), (untyped_comparator) comparator);
00155     }
00156 
00157 
00158   protected:
00159     unsigned  fSize;  ///< number of elements in array
00160     T*        fData;  ///< array data
00161 
00162 };
00163 
00164 #endif /* __GML_ARRAY__ */
00165