home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / prog_c / suplib.lzh / SUPLIB / DOC / LISTS.DOC < prev    next >
Text File  |  1991-08-16  |  2KB  |  85 lines
  1.  
  2.                  LISTS.DOC
  3.               (SUP32.LIB and DRES.LIBRARY)
  4.  
  5.  
  6.     These are general list handling routines that should have been provided
  7. in EXEC.  In addition to basic additions, I provide support for structures
  8. whos Nodes are not at the base of the structure.  These are the infamous
  9. 'sptr's below.  Such routines take a pointer to the structure, add an
  10. offset to it to get to the Node, do the specified operation, then subtract
  11. the offset to return to the 'sptr's actual base.  In otherwords, it allows
  12. you to deal with such structures without having to do these hacks in your
  13. source.
  14.  
  15. GetHead                             GetHead
  16. GetSucc                             GetSucc
  17.  
  18.     node = GetHead(list)
  19.     node = GetSucc(node)    (physically the same routine as GetHead()).
  20.  
  21.     This routine returns the successor of a node in the list.  If a list is
  22.     specified, the first node in the list is returned.    NULL is returned if
  23.     the list is empty or one has reached the end of the list.
  24.  
  25.  
  26. GetTail                             GetTail
  27.  
  28.     node = GetTail(list)
  29.  
  30.     This routine returns the last node in the list, or NULL if the list
  31.     is empty.
  32.  
  33.  
  34. GetPred                             GetPred
  35.  
  36.     node = GetPred(node)
  37.  
  38.     This routine returns the previous node from the given node, or NULL
  39.     if we are at the head of the list.
  40.  
  41.  
  42. GetHeadOff                            GetHeadOff
  43.  
  44.     sptr = GetHeadOff(list, offset)
  45.  
  46.     This routine retrieves the first node in the list and subtracts the
  47.     specified offset to get to the base of the structure (where 'offset'
  48.     is the offset into the structure where the Node has been placed rather
  49.     than placing it as the first object in the structure).
  50.  
  51.     NULL is returned is the list is empty.  NOTE!  Unlike GetHead(), only
  52.     a valid list pointer may be specified here.
  53.  
  54.  
  55. GetTailOff                            GetTailOff
  56.  
  57.     sptr = GetTailOff(list, offset)
  58.  
  59.     This routine works the same as GetHeadOff() but works on the last
  60.     node in the list.
  61.  
  62.  
  63. GetSuccOff                            GetSuccOff
  64.  
  65.     sptr = GetSuccOff(sptr, offset)
  66.  
  67.     Given a structure pointer where the Node is offset from the structure
  68.     base, add the offset to the pointer, determine the successor if any,
  69.     then subtract the offset from the successor to get back to the
  70.     structure base for the successor.
  71.  
  72.     NULL is returned if there is no successor.
  73.  
  74.  
  75. GetPredOff                            GetPredOff
  76.  
  77.     sptr = GetPredOff(sptr, offset)
  78.  
  79.     This routine works the same as GetSuccOff() but works on the previous
  80.     node rather than the next.    NULL is returned if we are at the head
  81.     of the list;
  82.  
  83.  
  84.  
  85.