DEFINITION - FUNCTION
    node& = FindName&(list&, mstr&, text$, flags&)
                                -- find a ListNode& with a given name

OPERATION
    Traverse a list until a ListNode& with the given name is found.
    To find multiple occurrences of a name, this function may be called
    with a node starting point.

ARGUMENTS
    list&  -- pointer to a (Min)ListHeader& or a ListNode& to start the
              search (if node, then the given one is skipped)
    mstr&  -- pointer to a zero terminated name string (as returned
              by CreateGPMString& from the memory.bm include file)
    text$  -- or a regular QB64 string containing the name (without the
              zero termination)
    flags& -- a bit field with any special characteristics (see below)

RESULT
    node&  -- pointer to the first ListNode& with the same name as given
              by either mstr& or text$, else zero to indicate that no
              node with the given name was found

NOTES
    1.) The starting point for the search (the list& argument) may also
        be any node& within that list.
    2.) The arguments mstr& and text$ are mutually exclusive, you may
        choose the one which fits best for you from case to case.
        You must tell the function exclusively to use the QB64 text$ by
        specifying the flags& value lstF_TextArg& defined in lists.bi,
        to use mstr& simply omit the flag.

FLAGS
    The flags& defined in the include file lists.bi are bit-coded values,
    hence they can easily combined by ORing or adding them:

    lstF_TextArg& -- as already mentioned in NOTES 2.), this flag must be
                     set to force the use of text$ rather than mstr& to
                     specify the node name to search
    lstF_NoCase&  -- set this flag to force case-insensitive comparing of
                     the node names with the given search name

    The next three flags are mutually exclusive, they all do cause the
    function to check for a partial name rather than the entire name:

    lstF_Left&    -- the given name must match to the left side of the
                     node names (eg. a prefix)
    lstF_Mid&     -- the given name must appear in any position within
                     the node names
    lstF_Right&   -- the given name must match to the right side of the
                     node names (eg. a sufix / file extension)

SEE ALSO
    Searching by Name

                                                 Back to Function Reference