# $EPIC: wordtoindex.txt,v 1.2 2006/08/20 18:32:13 sthalik Exp $
======Synopsis:======
$__wordtoindex__(<number> <list>)

======Technical:======
   * If the <number> argument is omitted, the empty string is returned.
   * If <number> is negative, then the value 0 is returned.
   * If <number> is greater than the actual number of words in <list>, then the return value of this function is the same as would be returned by $strlen(<list>).
   * There is only one space that separates <number> from <list>.  Any further spaces between <number> and <list> are part of <list> for the purpose of counting.
   * The return value is the character position (as would be returned by $[[index]]() and could be used by $[[right]]() et al) of the first character in the <number>th word in <list>.
   * <number> counts from zero!

======Practical:======
The most practical use of this function is to permit you to find the 
beginning position of a word in a string, especially after you have had
to change the length of some of the words in the list.  This technique is
most obviously used by tab completion scripts which will take the input 
line ($L), the cursor position ($[[curpos]]()), and use the $[[indextoword]]() 
function to figure out where the cursor is.  Then they rewrite the input
line using tab completion, and use $wordtoindex() to figure out where the
cursor is supposed to go after the input line has been rewritten.

======Returns:======
The number of characters before the beginning of the <number>th word
in <list>, where <number> counts from zero.

======Examples:======
<file>
$wordtoindex(2 foo bar blah)           returns 8
$wordtoindex(999 foo bar blah)         returns 12
$wordtoindex(-1 foo bar blah)          returns 0
</file>