lq-text: LQT_ReadWordFromStringPointer

Purpose

Returns the next natural-language word from the given NUL-terminated string.

The definition of a word for the purpose of this routine is determined partly by the definitions for LQT_Starts­Word, LQT_Only­Within­Word and LQT_Ends­Word in the header file <wordrules.h>, and partly on the configuration file in the database directory, where indexnumbers, minwordlength and maxwordlength may be set.

If the arguments are all null, the effect is to reset the routine ready to start a new string, and no useful value is returned in that case.

The given Flags argument may either be zero or any combination of LQT_READWORD_IGNORE_COMMON and LQT_READWORD_WILDCARDS, or'd together.

Characters are read from the string, incrementing *Stringpp as each byte is processed, until a recognised word is found. If the LQT_READWORD_IGNORE_COMMON flag was set in Flags, LQT_Read­Word­From­String­Pointer continues until either a word is found that has not been registered as being too common to index, or the end of the string is reached.

If Startp is not a NULL pointer, *Startp is set to point to the first character in the word that has been found in the given Stringpp (not to the malloc'd copy in the result).

If Endp is a NULL pointer, the string is considered to be terminated by the first zero byte reached; otherwise, Endp must point to the first character not in the string; normally, Endp would be set to point to the terminating NUL byte.

If the LQT_READWORD_WILDCARDS flag is set, the `Wild Card' characters * and ? are allowed within words. Such characters do not count as punctuation for the returned WordInfo flags.