<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqtext">
<Function File="../../src/liblqtext/wordinfo.c">
<Name>LQT_FindFirstWIDMatchingPattern</Name>
<Class>Database/Retrieval, Database/Words
<Purpose>
<P>Returns the lowest WID whose word matches the given Pattern.</P>
<P>The Pattern need not be NUL-terminated; the given PatternLength
argument is used to find the end of the Pattern.</P>
<P>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.
<P>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 &lt;liblqtext.h&gt; 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.
<P>The given Argument is passed on to the Matcher function, for the
convenience of the caller.</P>
<Returns>
The WID on success, and zero on failure.
<Errors>
Warns if a database format error is detected.
<SeeAlso>
LQT_WordToWID
</Function>
<Decl>
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
	/* prefix with `the' in order to avoid old gcc bug */
	t_LQTEXT_Database *thedb,
	unsigned char *theString,
	int theStringLength,
	unsigned char *thePattern,
	int thePatternLength,
	int thePrefixLength,
	unsigned char *theArgument
# endif
    );
    unsigned char *Argument;
</Decl>
</Entry>
