Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / Using the List Manager

Searching a List for a Particular Item

Sometimes, your application might need to search through a list for a particular item. For example, your application might need to search a list of pictures to see which cell contains a certain picture, or your application might wish to search for an item that matches a certain string. You can use the LSearch function and specify your own match function to make this possible.

The LSearch function returns TRUE if it is able to find the specified data in a cell greater than or equal to the specified cell. If it does find the data, it also returns the coordinates of the cell that contains the data.

In addition to specifying the cell to search, your application also specifies a pointer to a match function, the data to search for, and the length of the data, as parameters to the LSearch function.

If your application specifies NIL for the match function, the LSearch function searches the list for the first cell whose data matches the specified data. In particular, the LSearch function calls the Text Utilities IUMagIDString function to compare each cell's data with the specified data until IUMagIDString returns 0. Because IUMagIDString compares strings for equality without regard for secondary ordering, using this default match function is useful only for text-only lists. For more information on IUMagIDString, see Inside Macintosh: Text.

Your application can use a different match function from IUMagIDString as long as it is defined just like IUMagIDString. For example, your application could use the IUMagString function so that secondary ordering is taken into consideration. To do so, your application might use the following code:

found := LSearch(myData, myLength, @IUMagString, myCell, myList);

You can also write your own match function. Listing 4-15 shows an example match function.

Listing 4-15 A match function

FUNCTION MySearchPartialMatch 
                  (cellDataPtr, searchDataPtr: Ptr;
                   cellDataLen, searchDataLen: Integer): Integer;
BEGIN
   IF (cellDataLen > 0) AND (cellDataLen >= searchDataLen) THEN
      MySearchPartialMatch := 
                        IUMagIDString(cellDataPtr, searchDataPtr, 
                                     searchDataLen, searchDataLen)
   ELSE
      MySearchPartialMatch := 1;
END;

Your match function should return 0 if it finds a match and 1 otherwise. The match function defined in Listing 4-15 works just like the default match function but allows the cell data to be longer than the data being searched for. For example, a search for the text "rose" would match a cell containing the text "Rosebud".

Listing 4-16 defines a more complex but potentially more useful match function for text-only lists.

Listing 4-16 Searching a list for a cell containing certain text or the next cell alphabetically

FUNCTION MyMatchNextAlphabetically 
               (cellDataPtr, searchDataPtr: Ptr;
                cellDataLen, searchDataLen: Integer): Integer;
BEGIN
   MyMatchNextAlphabetically := 1;     {set default return value}
   IF (cellDataLen > 0) THEN
   BEGIN
      IF IUMagIDString(cellDataPtr, searchDataPtr,
                        searchDataLen, searchDataLen) = 0 THEN
         MyMatchNextAlphabetically := 0{strings are equal}
      ELSE IF IUMagString(cellDataPtr, searchDataPtr, 
                           cellDataLen, searchDataLen) = 1 THEN
      MyMatchNextAlphabetically := 0;  {search data is after }
                                       { cell data}
   END;
END;

Using the LSearch function with the MyMatchNextAlphabetically function defined in Listing 4-16 results in the finding of the cell that is alphabetically greater than or equal to the search text. For example, if you use the LSearch function with this match function to search a list of the 50 states (not including the District of Columbia) for the text "Washington, D.C.", then the LSearch function returns the coordinates of the cell containing the text "West Virginia".

Note

The MyMatchNextAlphabetically function defined in Listing 4-16 works only for lists that are alphabetically arranged.