Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / List Manager Reference

Application-Defined Routines / Match Functions

MyMatchFunction

A match function must have the following syntax:

FUNCTION MyMatchFunction (cellDataPtr, searchDataPtr: Ptr;
                          cellDataLen, searchDataLen: Integer)
                          : Integer;

cellDataPtr

A pointer to the data contained in a cell.

searchDataPtr

A pointer to the data being searched for.

cellDataLen

The number of bytes of data contained in the cell specified by the cellDataPtr parameter.

searchDataLen

The number of bytes of data contained in the cell specified by the searchDataPtr parameter.

DESCRIPTION

A custom match function must compare the data defined by the cellDataPtr and cellDataLen parameters with the data defined by the searchDataPtr and searchDataLen parameters. If the cell data matches the search data, your match function should return 0. Otherwise, your match function should return 1.

Your match function can use any technique you choose to compare the data. For example, your match function might consider the search data to be equivalent to the cell data if both are the same length. Or, your match function might only report a match if the search data can be found somewhere within the cell data.

The default match function, IUMagIDString, returns 0 if the search data exactly matches the cell data, but IUMagIDString considers the strings 'Rose' and 'rosé' to be equivalent. If your application simply needs a match function that works like IUMagIDString but considers 'Rose' to be different from 'rosé', you do not need to write a custom match function. Instead, your application can simply pass @IUMagString as the third parameter to the LSearch function.

SPECIAL CONSIDERATIONS

A custom match function does not execute at interrupt time. Instead, it is called directly by the LSearch function. Thus, a match function can allocate memory, and it does not need to adjust the value contained in the A5 register.

SEE ALSO

For information on the IUMagIDString function and the IUMagString function, see Inside Macintosh: Operating System Utilities.

For examples of match functions, see "Searching a List for a Particular Item" beginning on page 4-34.