lq-text: LQT_FindFirstWIDMatchingPattern

API t_WID LQT_FindFirstWIDMatchingPattern ( db, Pattern, PatternLength, PrefixLength, Matcher, Argument ) t_LQTEXT_Database *db; unsigned char *Pattern; int PatternLength; int PrefixLength; int (* Matcher)( # ifdef HAVE_PROTO t_LQTEXT_Database *thedb, unsigned char *theString, int theStringLength, unsigned char *thePattern, int thePatternLength, int thePrefixLength, unsigned char *theArgument # endif ); unsigned char *Argument;

Purpose

Returns the lowest WID whose word matches the given Pattern.

The Pattern need not be NUL-terminated; the given PatternLength argument is used to find the end of the Pattern.

The given PrefixLength argument must specify the number of leading characters, if any, in the given Pattern that form a constant prefix. If there are no such characters, matching is likely to be several orders of magnitude slower, as LQT_FindFirstWIDMatchingPattern will have to try every word in the database vocabulary, one at a time, until it finds one that matches.

The given Matcher argument must be a pointer to a function that will try to match the string to the given pattern, and that will return zero only on a match. The constant LQT_WIDMATCH_FAILED is available in liblqtext.h to be returned by the given Matcher function, indicating that LQT_FindFirstWIDMatchingPattern should fail and return zero immediately. This might be used if the given Matcher function is called with a string lexically greater than the largest that could ever match it, or after reporting an error.

The given Argument is passed on to the Matcher function, for the convenience of the caller.

Returns

The WID on success, and zero on failure.

Errors

Warns if a database format error is detected.