home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 177.lha / DRes_v1.3 / docs / lists.doc < prev    next >
Encoding:
Text File  |  1988-04-28  |  5.7 KB  |  165 lines
  1.  
  2.                  LISTS.DOC
  3.  
  4.     These are general list handling routines that should have been provided
  5. in EXEC.  In addition to basic additions, I provide support for structures
  6. whos Nodes are not at the base of the structure.  These are the infamous
  7. 'sptr's below.  Such routines take a pointer to the structure, add an
  8. offset to it to get to the Node, do the specified operation, then subtract
  9. the offset to return to the 'sptr's actual base.  In otherwords, it allows
  10. you to deal with such structures without having to do these hacks in your
  11. source.
  12.  
  13. GetHead                             GetHead
  14. GetSucc                             GetSucc
  15.  
  16.     node = GetHead(list)
  17.     node = GetSucc(node)    (physically the same routine as GetHead()).
  18.  
  19.     This routine returns the successor of a node in the list.  If a list is
  20.     specified, the first node in the list is returned.    NULL is returned if
  21.     the list is empty or one has reached the end of the list.
  22.  
  23. GetTail                             GetTail
  24.  
  25.     node = GetTail(list)
  26.  
  27.     This routine returns the last node in the list, or NULL if the list
  28.     is empty.
  29.  
  30. GetPred                             GetPred
  31.  
  32.     node = GetPred(node)
  33.  
  34.     This routine returns the previous node from the given node, or NULL
  35.     if we are at the head of the list.
  36.  
  37. GetHeadOff                            GetHeadOff
  38.  
  39.     sptr = GetHeadOff(list, offset)
  40.  
  41.     This routine retrieves the first node in the list and subtracts the
  42.     specified offset to get to the base of the structure (where 'offset'
  43.     is the offset into the structure where the Node has been placed rather
  44.     than placing it as the first object in the structure).
  45.  
  46.     NULL is returned is the list is empty.  NOTE!  Unlike GetHead(), only
  47.     a valid list pointer may be specified here.
  48.  
  49. GetTailOff                            GetTailOff
  50.  
  51.     sptr = GetTailOff(list, offset)
  52.  
  53.     This routine works the same as GetHeadOff() but works on the last
  54.     node in the list.
  55.  
  56. GetSuccOff                            GetSuccOff
  57.  
  58.     sptr = GetSuccOff(sptr, offset)
  59.  
  60.     Given a structure pointer where the Node is offset from the structure
  61.     base, add the offset to the pointer, determine the successor if any,
  62.     then subtract the offset from the successor to get back to the
  63.     structure base for the successor.
  64.  
  65.     NULL is returned if there is no successor.
  66.  
  67. GetPredOff                            GetPredOff
  68.  
  69.     sptr = GetPredOff(sptr, offset)
  70.  
  71.     This routine works the same as GetSuccOff() but works on the previous
  72.     node rather than the next.    NULL is returned if we are at the head
  73.     of the list;
  74.  
  75. EnqueueLong                            EnqueueLong
  76.  
  77.     (void) EnqueueLong(list, startnode, node, valoff)
  78.  
  79.     This routine queues a node into a list beginning its search at the
  80.     startnode (first element if startnode == NULL).  The list is assumed
  81.     to be sorted by the longword valoff from the node structure.  I.E.
  82.     If you had a graphic structure with a Node at its base and where
  83.     coordinates were stored in longwords, you insert nodes sorted by
  84.     one of the coordinates into a list.
  85.  
  86.     valoff is the offset from the node base where the longword value
  87.     the list is sorted by exists.
  88.  
  89. EnqueueOffLong                            EnqueueOffLong
  90.  
  91.     (void) EnqueueOffLong(list, startnode, sptr, off, valoff)
  92.  
  93.     This works just like EnqueueLong() but an extra parameter, 'off', is
  94.     provided to inform the routine where in the structure the Node is.
  95.     Does that make sense?
  96.  
  97. SearchFwdNode                            SearchFwdNode
  98.  
  99.     retval = SearchFwdNode(node, function, arg)
  100.     MINNODE *node;
  101.     long (*function)();
  102.     long arg;
  103.  
  104.     This routine searches a list in the forward direction beginning at
  105.     the specified node, calling the function vector for every node.  The
  106.     function is called C-fashion (A4 and A5 are intact to support the
  107.     small code model and D2/D3 may be destroyed in addition to standard
  108.     scratch variables to support Aztec C).  The function is given two
  109.     arguments:    the node, and the arg passed to SearchFwdNode():
  110.  
  111.     (*function)(current_srch_node, arg)
  112.  
  113.     The search is terminated if the function vector returns a non-zero
  114.     value.  If the search reaches the end of the list, NULL is returned.
  115.     NOTE: you may pass a NULL as the node to SearchFwdNode() which results
  116.     in a NULL being immediately returned.
  117.  
  118. SearchRvsNode                            SearchRvsNode
  119.  
  120.     retval = SearchFwdNode(node, function, arg)
  121.  
  122.     This function works exactly the same as SearchFwdNode() but works
  123.     in reverse begining at the specified node.
  124.  
  125. SearchFwdList                            SearchFwdList
  126.  
  127.     retval = SearchFwdList(list, function, arg)
  128.  
  129.     This function works exactly the same as SearchFwdNode() but you give
  130.     it a pointer to a list rather than to a node.
  131.  
  132.     A valid list pointer must be specified, but the list may be empty.
  133.  
  134. SearchRvsList                            SearchRvsList
  135.  
  136.     retval = SearchRvsList(list, function, arg)
  137.  
  138.     This function works exactly the same as SearchRvsNode() but you give
  139.     it a pointer to a list rather than to a node.
  140.  
  141.     A valid list pointer must be specified, but the list may be empty.
  142.  
  143. SearchFwdNodeOff                        SearchFwdNodeOff
  144. SearchRvsNodeOff                        SearchRvsNodeOff
  145. SearchFwdListOff                        SearchFwdListOff
  146. SearchRvsListOff                        SearchRvsListOff
  147.  
  148.     rval    =    SearchFwdNodeOff(sptr, function, off, arg)
  149.     rval    =    SearchRvsNodeOff(sptr, function, off, arg)
  150.     rval    =    SearchFwdListOff(list, function, off, arg)
  151.     rval    =    SearchRvsListOff(list, function, off, arg)
  152.  
  153.     These routines work like those shown above, but an additional
  154.     argument, an offset, is supplied.  This is the offset into the
  155.     structure pointer where the Node structure is embedded.  In otherwords,
  156.     the other routines were simply special cases of this one with off == 0.
  157.  
  158.     Note that for *NodeOff() routines a pointer to a structure containing
  159.     the Node structure in it somewhere is supplied, whereas in the
  160.     *ListOff() routines a pointer to the list base is given (this hasn't
  161.     changed).
  162.  
  163.  
  164.  
  165.