gml_List.h

Go to the documentation of this file.
00001 /** @file gml_List.h
00002  * 
00003  *     Definition of gml_TListElem and gml_TList.
00004  * 
00005  *   Copyright (c) 2003-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 on May 21, 2003 (FB).
00011  */
00012 #ifndef __GML_LIST__
00013 #define __GML_LIST__
00014 
00015 #include "gml/base/gml_Types.h"
00016 #include "gml/base/gml_Errors.h"
00017 
00018 
00019 
00020 /// gml_TListSortFunc --
00021 ///   The prototype of functions that compare two elements <left> and <right>,
00022 ///   and return an integer that is greater than, equal to, or less than 0, according as
00023 ///   <left> is greater than, equal to, or less than <right>.
00024 
00025 typedef int (gml_TListSortFunc) (void* left, void* right);
00026 
00027 
00028 /// gml_ListSortStringFunc --
00029 ///
00030 ///  Element-sorting routine that compares C (0-terminated) strings using strcmp.
00031 
00032 extern "C"
00033 int gml_ListSortStringFunc (void* left, void* right);
00034 
00035 
00036 /// gml_ListSortIntFunc --
00037 ///
00038 ///  Element-sorting routine that compares signed integers.
00039 
00040 extern "C"
00041 int gml_ListSortIntFunc (void* left, void* right);
00042 
00043 
00044 class gml_TList;
00045 
00046 /// gml_TListElem --
00047 ///
00048 ///  An element of a gml_TList.
00049 
00050 class gml_TListElem
00051 {
00052   public:
00053 
00054     /// Zero all fields.
00055     virtual gml_TError  Init ();
00056     
00057     /// Call RemoveFromList()
00058     virtual void        Dispose ();
00059     
00060     virtual ~gml_TListElem () {}
00061 
00062     /// If this element is inside a list, remove it from the list
00063     inline void         RemoveFromList ();
00064     inline void         Reset ();
00065 
00066     /// Return the next element in the list (possibly NULL).
00067     gml_TListElem*      Next ()
00068                           { return fNext; }
00069 
00070     /// Return the previous element in the list (possibly NULL).
00071     gml_TListElem*      Previous ()
00072                           { return fPrevious; }
00073 
00074     /// Return the element's associated value.
00075     void*               Value ()
00076                           { return fValue; }
00077 
00078     /// The element's associated value.
00079     void*               fValue;
00080 
00081   protected:
00082 
00083     friend class gml_TList;
00084   
00085     gml_TList*          fList;      ///< pointer to the containing list
00086     gml_TListElem*      fNext;      ///< pointer to the next list element
00087     gml_TListElem*      fPrevious;  ///< pointer to the previous list element
00088 };
00089 
00090 
00091 
00092 /// gml_TList --
00093 ///   A list of gml_TListElem elements.
00094 
00095 class gml_TList
00096 {
00097   public:
00098 
00099     /// Init --
00100     ///
00101     ///   Initializes the list to an empty state.
00102 
00103     inline gml_TError         Init ();
00104 
00105     /// Dispose --
00106     ///
00107     ///   Disposes the list resources, which includes disposing and deleting all
00108     ///   the list elements.
00109 
00110     void                      Dispose ();
00111 
00112     /// Reset --
00113     ///
00114     ///   Resets the list to an empty state. Does not affect the list elements that
00115     ///   where in the list before the call.
00116 
00117     inline void               Reset ();
00118 
00119     /// Head --
00120     ///
00121     ///   Returns the first element in the list.
00122 
00123     gml_TListElem*            Head ()
00124                                 { return fHead; }
00125 
00126     /// Tail --
00127     ///
00128     ///   Returns the last element in the list.
00129 
00130     gml_TListElem*            Tail ()
00131                                 { return fTail; }
00132     
00133     /// AppendElem --
00134     ///
00135     ///   Inserts <elem> at the end of the list. <elem> should not be NULL.
00136 
00137     inline void               AppendElem    (gml_TListElem* elem);
00138 
00139     /// InsertElem --
00140     ///
00141     ///   Inserts <elem> at the beginning of the list. <elem> should not be NULL.
00142 
00143     inline void               InsertElem    (gml_TListElem* elem);
00144 
00145     /// RemoveElem --
00146     ///
00147     ///   Removes <elem> from the list. <elem> should not be NULL.
00148 
00149     inline void               RemoveElem    (gml_TListElem* elem);
00150 
00151     /// RemoveElem --
00152     ///
00153     ///   Checks if the element <elem> is a member of the list.
00154     ///   Returns <gml_cTrue> if <elem> is in the list, <gml_cFalse> otherwise.
00155     ///   <elem> should not be NULL.
00156 
00157     inline gml_TBoolean       IsElemMember  (gml_TListElem* elem);
00158     
00159     /// InsertListAfterElem --
00160     ///
00161     ///   Inserts the elements of <list> after <elem>.
00162     ///   If <elem> is NULL, insert <list> elements at the beginning of this list.
00163     ///   Does nothing if <elem> is not an element of the list.
00164     ///   Doesn't allocate any element, just change <list> elements to belong to this list.
00165     ///   Finally, <list> is reset (to an empty list).
00166 
00167     void                      InsertListAfterElem (gml_TList* list, gml_TListElem* elem);
00168 
00169 
00170 
00171     /// AppendValue --
00172     ///
00173     ///   Allocates a new element and append it to the list.
00174     ///   Set the value of the element to <value>.
00175     ///   If <newElem> is not NULL, it will receive the address of the newly allocated element.
00176 
00177     gml_TError                AppendValue   (void* value, gml_TListElem** newElem = (gml_TListElem**)NULL);
00178 
00179     /// InsertValue --
00180     ///
00181     ///   Allocates a new element and insert it at the beginning of the list. 
00182     ///   Set the value of the element to <value>.
00183     ///   If <newElem> is not NULL, it will receive the address of the newly allocated element.
00184 
00185     gml_TError                InsertValue   (void* value, gml_TListElem** newElem = (gml_TListElem**)NULL);
00186 
00187     /// ValueElem --
00188     ///
00189     ///   Returns a pointer to the first element in the list which value is <value>, or NULL if no
00190     ///   element have such a value.
00191 
00192     gml_TListElem*            ValueElem     (void* value);
00193 
00194     /// AppendValueAfterElem --
00195     ///
00196     ///   Allocates a new element and insert it in the list just after <elem>.
00197     ///   If <elem> is NULL, insert the new element at the head of the list.
00198     ///   Set the value of the element to <value>.
00199     ///   If <newElem> is not NULL, it will receive the address of the newly allocated element.
00200     
00201     gml_TError                AppendValueAfterElem (void* value, gml_TListElem* elem, gml_TListElem** newElem = (gml_TListElem**)NULL);
00202     
00203     /// RemoveValue --
00204     ///
00205     ///   Finds the first element in the list that has the value <value>, removes it from the list
00206     ///   and free it. Do nothing if no element of the list have value <value>.
00207 
00208     void                      RemoveValue   (void* value);
00209 
00210     /// IsValueMember --
00211     ///
00212     ///   Returns "gml_cTrue" if at least one element in list has the value <value>.
00213 
00214     inline gml_TBoolean       IsValueMember (void* value);
00215 
00216     /// IsEquivalentValueMember --
00217     ///
00218     ///   Returns "gml_cTrue" if at least one element in list has a value that is equivalent to
00219     ///   <value>. The equivalence function must be provided in <func>. By default, <func> is
00220     ///   the C-string equivalent functions (2 values are equivalent if they point to C-strings
00221     ///   that have the same characters).
00222 
00223     gml_TBoolean              IsEquivalentValueMember (void* value,
00224                                                         gml_TListSortFunc* func = &gml_ListSortStringFunc);
00225 
00226     /// Sort --
00227     ///
00228     ///   Sorts the list according to the <func> comparison function.
00229 
00230     gml_TError                Sort (gml_TListSortFunc* func = &gml_ListSortStringFunc);
00231 
00232   protected:
00233 
00234     gml_TListElem*      fHead;  ///< the first element in this list
00235     gml_TListElem*      fTail;  ///< the last element in this list
00236 };
00237 
00238 
00239 
00240 // gml_TListElem Inline function definitions.
00241 
00242 // gml_TListElem::RemoveFromList --
00243 
00244 void gml_TListElem::RemoveFromList ()
00245 {
00246   if (fList != (gml_TList*)NULL)
00247     fList->RemoveElem (this);
00248 };
00249 
00250 
00251 
00252 // gml_TListElem::Reset --
00253 
00254 void gml_TListElem::Reset ()
00255 {
00256   fNext         = (gml_TListElem*)NULL;
00257   fPrevious     = (gml_TListElem*)NULL;
00258   fList         = (gml_TList*)NULL;
00259   fValue        = (void*)NULL;
00260 };
00261 
00262 
00263 
00264 // gml_TList Inline function definitions.
00265 
00266 // gml_TList::Init --
00267 
00268 gml_TError gml_TList::Init ()
00269 {
00270   this->Reset ();
00271 
00272   return gml_cNoError;
00273 };
00274 
00275 // gml_TList::Reset --
00276 
00277 void gml_TList::Reset ()
00278 {
00279   fHead = (gml_TListElem*)NULL;
00280   fTail = (gml_TListElem*)NULL;
00281 };
00282 
00283 
00284 
00285 // gml_TList::AppendElem --
00286 
00287 void gml_TList::AppendElem (gml_TListElem* elem)
00288 {
00289   elem->fList       = this;
00290   elem->fPrevious   = fTail;
00291   elem->fNext       = (gml_TListElem*)NULL;
00292   
00293   if (fTail != (gml_TListElem*)NULL)
00294     fTail->fNext    = elem;
00295   else
00296     fHead           = elem;
00297   fTail             = elem;
00298 }
00299 
00300 
00301 
00302 // gml_TList::InsertElem --
00303 
00304 void gml_TList::InsertElem (gml_TListElem* elem)
00305 {
00306   elem->fList         = this;
00307   elem->fNext         = fHead;
00308   elem->fPrevious     = (gml_TListElem*)NULL;
00309   
00310   if (fHead != (gml_TListElem*)NULL)
00311     fHead->fPrevious  = elem;
00312   else
00313     fTail             = elem;
00314   fHead               = elem;
00315 
00316   return;
00317 }
00318 
00319 // gml_TList::RemoveElem --
00320 
00321 void gml_TList::RemoveElem (gml_TListElem* elem)
00322 {
00323   if (elem->fList != this)
00324     return;
00325 
00326   if (elem != fHead)
00327     elem->fPrevious->fNext = elem->fNext;
00328   else
00329     fHead = elem->fNext;
00330 
00331   if (elem != fTail)
00332     elem->fNext->fPrevious = elem->fPrevious;
00333   else
00334     fTail         = elem->fPrevious;
00335 
00336   elem->Reset ();
00337 }
00338 
00339 
00340 
00341 // gml_TList::IsElemMember --
00342 
00343 gml_TBoolean gml_TList::IsElemMember (gml_TListElem* elem)
00344 {
00345   return (gml_TBoolean)(elem->fList == this);
00346 }
00347 
00348 
00349 
00350 // gml_TList::IsValueMember --
00351 
00352 gml_TBoolean gml_TList::IsValueMember (void* value)
00353 {
00354   return (gml_TBoolean)((this->ValueElem (value) != (gml_TListElem*)NULL));
00355 }
00356 
00357 
00358 
00359 
00360 #endif
Generated on Tue Jun 12 14:03:27 2007 for gml by Doxygen 1.5.2.