Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / List Manager Reference

List Manager Routines / Searching a List for a Particular Item

LSearch

You can use the LSearch function to find a cell whose data matches data that you specify.

FUNCTION LSearch (dataPtr: Ptr; dataLen: Integer; searchProc: Ptr;
                  VAR theCell: Cell; lHandle: ListHandle)
                  : Boolean;

dataPtr

A pointer to the data being searched for.

dataLen

The length in bytes of the data being searched for.

searchProc

A pointer to a function to be used to compare the data being searched for with cell data. If NIL, the Text Utilities Package function IUMagIDString is used.

theCell

The first cell to be searched. If LSearch finds a match, it returns in this parameter the coordinates of the first cell whose data matches the data being searched for.

lHandle

The list to be searched.

DESCRIPTION

Your application can use the LSearch function to search the list specified by the lHandle parameter beginning at the cell specified by the parameter theCell for a match. If LSearch finds a match, it returns TRUE and sets the parameter theCell to the coordinates of the first cell whose data matches the data specified by the dataPtr and dataLen parameters. Otherwise, LSearch returns FALSE.

The LSearch function determines whether a cell's data matches the search data by calling the IUMagIDString function, or the function specified by the searchProc parameter. If that function returns 0, LSearch has found a match; otherwise, LSearch checks the next cell in the list.

SPECIAL CONSIDERATIONS

You should not call the LSearch function from within an interrupt, such as in a completion routine or VBL task.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the LSearch function are

Trap macro	Selector
_Pack0	$0054

SEE ALSO

For examples of use of the LSearch function, see "Searching a List for a Particular Item" beginning on page 4-34. For information on the syntax of a custom match function, see "Match Functions" beginning on page 4-89. For information on the IUMagIDString function, see Inside Macintosh: Text.