list.h

<Win2k系统编程>源码.次数为国人自编,内容丰富,还是不错的.

  int APIENTRY List_ItemLength(LPVOID Curs);
  /* Return the length of the object identified by the cursor Curs */

  /*------------------------------------------------------------------
  | TRAVERSING THE ULIST
  |
  | LIST lst;
  | object * Curs;
  | . . .
  | Curs = List_First(lst);
  | while (Curs!=NULL)
  | {  DoSomething(*Curs);   (* Curs points to YOUR data not to chain ptrs *)
  |    Curs = List_Next(Curs);
  | }
  |
  | This is identically equal to
  | List_TRAVERSE(lst, Curs)  // note NO SEMI COLON!
  | {  DoSomething(*Curs); }
   -------------------------------------------------------------------*/

  #define List_TRAVERSE(lst, curs)  for(  curs=List_First(lst)            \
                                       ;  curs!=NULL                      \
                                       ;  curs = List_Next((LPVOID)curs)  \
                                       )

  LPVOID APIENTRY List_First(LIST lst);
  /*------------------------------------------------------------------
  | Return the address of the first object in lst
  |  If lst is empty then Return NULL.
  --------------------------------------------------------------------*/

  LPVOID APIENTRY List_Last(LIST lst);
  /*------------------------------------------------------------------
  | Return the address of the last object in lst
  | If lst is empty then return NULL.
  --------------------------------------------------------------------*/

  LPVOID APIENTRY List_Next(LPVOID Curs);
  /*------------------------------------------------------------------
  | Return the address of the object after Curs^.
  | List_Next(List_Last(lst)) == NULL;  List_Next(NULL) is an error.
  | List_Next(List_Prev(curs)) is illegal if curs identifies first el
  --------------------------------------------------------------------*/

  LPVOID APIENTRY List_Prev(LPVOID Curs);
  /*------------------------------------------------------------------
  | Return the address of the object after Curs^.
  | List_Prev(List_First(L)) == NULL;  List_Prev(NULL) is an error.
  | List_Prev(List_Next(curs)) is illegal if curs identifies last el
  --------------------------------------------------------------------*/

  /*------------------------------------------------------------------
  |  Whole list operations
   -----------------------------------------------------------------*/
  void APIENTRY List_Clear(LIST lst);
  /* arrange that lst is empty after this */

  BOOL APIENTRY List_IsEmpty(LIST lst);
  /* Return TRUE if and only if lst is empty */

  void APIENTRY List_Join(LIST l1, LIST l2);
  /*-----------------------------------------------------------------------
  | l1 := l1||l2; l2 := empty
  | The elements themselves are not moved, so pointers to them remain valid.
  |
  | l1 gets all the elements of l1 in their original order followed by
  | all the elements of l2 in the order they were in in l2.
  | l2 becomes empty.
   ------------------------------------------------------------------------*/

  void APIENTRY List_InsertListAfter(LIST l1, LIST l2, LPVOID Curs);
  /*-----------------------------------------------------------------------
  | l1 := l1[...Curs] || l2 || l1[Curs+1...]; l2 := empty
  | Curs=NULL means insert l2 at the start of l1
  | The elements themselves are not moved, so pointers to them remain valid.
  |
  | l1 gets the elements of l1 from the start up to and including the element
  | that Curs points at, in their original order,
  | followed by all the elements that were in l2, in their original order,
  | followed by the rest of l1
   ------------------------------------------------------------------------*/

  void APIENTRY List_InsertListBefore(LIST l1, LIST l2, LPVOID Curs);
  /*-----------------------------------------------------------------------
  | l1 := l1[...Curs-1] || l2 || l1[Curs...]; l2 := empty
  | Curs=NULL means insert l2 at the end of l1
  | The elements themselves are not moved, so pointers to them remain valid.
  |
  | l1 gets the elements of l1 from the start up to but not including the
  | element that Curs points at, in their original order,
  | followed by all the elements that were in l2, in their original order,
  | followed by the rest of l1.
   ------------------------------------------------------------------------*/

  void APIENTRY List_SplitAfter(LIST l1, LIST l2, LPVOID Curs);
  /*-----------------------------------------------------------------------
  | Let l1 be l1 and l2 be l2
  | Split l2 off from the front of l1:    final l2,l1 = original l1
  |
  | Split l1 into l2: objects of l1 up to and including Curs object
  |               l1: objects of l1 after Curs
  | Any original contents of l2 are freed.
  | List_Spilt(l1, l2, NULL) splits l1 before the first object so l1 gets all.
  | The elements themselves are not moved.
   ------------------------------------------------------------------------*/

  void APIENTRY List_SplitBefore(LIST l1, LIST l2, LPVOID Curs);
  /*----------------------------------------------------------------------
  | Split l2 off from the back of l1:  final l1,l2 = original l1
  |
  | Split l1 into l1: objects of l1 up to but not including Curs object
  |               l2: objects of l1 from Curs onwards
  | Any original contants of l2 are freed.
  | List_Spilt(l1, l2, NULL) splits l1 after the last object so l1 gets all.
  | The elements themselves are not moved.
   -----------------------------------------------------------------------*/

  int APIENTRY List_Card(LIST lst);
  /* Return the number of items in L */

  /*------------------------------------------------------------------
  | Error handling.
  |
  | Each list has within it a flag which indicates whether any illegal
  | operation has been detected (e.g. DeleteFirst when empty).
  | Rather than have a flag on every operation, there is a flag held
  | within the list that can be queried when convenient.  Many operations
  | do not have enough redundancy to allow any meaningful check.  This
  | is a design compromise (for instance to allow P = List_Next(P);
  | rather than P = List_Next(L, P); which is more awkward, especially
  | if L is actually a lengthy phrase).
  |
  | List_IsOK tests this flag (so is a very simple, quick operation).
  | MakeOK sets the flag to TRUE, in other words to accept the current
  | state of the list.
  |
  | It is possible for a list to be damaged (whether or not the flag
  | says OK) for instance by the storage being overwritten.
  |
  | List_Check attempts to verify that the list is sound (for instance where
  | there are both forward and backward pointers they should agree).
  |
  | List_Recover attempts to make a sound list out of whatever debris is left.
  | If the list is damaged, Recover may trap (e.g. address error) but
  | if the list was damaged then ANY operation on it may trap.
  | If Check succeeds without trapping then so will Recover.
   -----------------------------------------------------------------*/

  BOOL APIENTRY List_IsOK(LIST lst);
  /* Check return code */

  void APIENTRY List_MakeOK(LIST lst);
  /* Set return code to good */

  BOOL APIENTRY List_Check(LIST lst);
  /* Attempt to validate the chains */

  void APIENTRY List_Recover(PLIST plst);
  /* Desperate stuff.  Attempt to reconstruct something */

/*------------------------------------------------------------------
|  It is designed to be as easy to USE as possible, consistent
|  only with being an opaque type.
|
|  In particular, the decision to use the address of an object a list cursor
|  means that there is a small amount of extra arithmetic (in the
|  IMPLEMENTATION) in cursor operations (e.g. Next and Prev).
|  and spurious arguments are avoided whenever possible, even though
|  it would allow greater error checking.
|
| Of the "whole list" operations, Clear is given because it seems to be
| a common operation, even though the caller can implement it with almost
| the same efficiency as the List implementation module.
| Join, Split and InsertListXxx cannot be implemented efficiently without
| knowing the representation.
 --------------------------------------------------------------------*/