Because many lists contain nodes with symbolic names attached (via the
ln_Name& field), it is possible to find a node by its name. The
FUNCTION FindName& searches a list for the first node with a given name.
For example, "node& = FindName&(list&, 0&, "sample.node", lstF_TextArg&)"
returns a pointer to the first node named "sample.node".  If no such node
exists, a zero result is returned.  The case of the name characters is
significant: "foo" is different from "Foo", unless you specify the
lstF_NoCase& flag.
  ________________________________________________________________________
 |   ____________       ___________       ___________       ___________   |
 |  |            |____\|           |____\|           |____\|           |__|
 |  |  lh_Head&  |/_  /| ln_Succ&  |/_  /| ln_Succ&  |/_  /| ln_Succ&  |/_
 |  |____________|\ \  |___________|\ \  |___________|\ \  |___________|\ |
 |_\|            |   \ |           |   \ |           |   \ |           |  |
   /| lh_Tail&=0 |    \| ln_Pred&  |    \| ln_Pred&  |    \| ln_Pred&  |  |
    |____________|     |___________|     |___________|     |___________|  |
    |            |     |           |     |           |     |           |  |
    |lh_TailPred&|__   | ln_Type&  |     | ln_Type&  |     | ln_Type&  |  |
    |____________|  |  |___________|     |___________|     |___________|  |
    |            |  |  |           |     |           |     |           |  |
    |  lh_Type&  |  |  | ln_Pri&   |     | ln_Pri&   |     | ln_Pri&   |  |
    |____________|  |  |___________|     |___________|     |___________|  |
    |            |  |  |           |     |           |     |           |  |
    |  lh_Pad&   |  |  | ln_Name&  |     | ln_Name&  |     | ln_Name&  |  |
    |____________|  |  |_ _ _ _ _ _|     |_ _ _ _ _ _|     |_ _ _ _ _ _|  |
                    |  |           |     |           |     |           |  |
                    |  |   Node    |     |   Node    |     |   Node    |  |
                    |  |  Content  |     |  Content  |     |  Content  |  |
                    |  |_ _ _ _ _ _|     |_ _ _ _ _ _|     |_ _ _ _ _ _|  |
                    |_____________________________________________________|

      Figure 4: Complete Sample List Showing all Interconnections

To find multiple occurrences of nodes with identical names, the FUNCTION
FindName& is called multiple times.  For example, if you want to find all
the nodes with a particular name (given as text$):

    SUB DisplayName(list&, text$)
      node& = FindName&(list&, 0&, text$, lstF_TextArg&)
      IF node& <> 0 THEN
        WHILE node& <> 0
          PRINT "Found node "; CHR$(34);
          PRINT PeekSTR$(PeekL&(node&, ln_Name&), 0&); 'read out mstr& pointer
          PRINT CHR$(34); " at address &h"; HEX$(node&); "."
          node& = FindName&(node&, 0&, text$, lstF_TextArg&)
        WEND
      ELSE
        PRINT "No node with name "; CHR$(34); text$; CHR$(34); " found."
      END IF
    END SUB

Notice that the second search uses the node& found by the first search.
FindName& never compares the specified name with that of the starting node.
It always begins the search with the successor of the starting point, hence
if the starting point is the head of a list, then the first real data node
is actually the first node checked, and not the head placeholder node in the
(Min)ListHeader& structure which does not even have a name.  This behavior
allows for the search loop shown above.  If the starting node itself would
be checked, then FindName& would immediately find the same node again, but
because the search starts with the successor of the starting node, it will
begin with the node after the last found node and will continue until the
next node with the given name is found or the list's end is reached.

                                                     Back to List Functions