# $EPIC: indextoword,v 1.2 2001/06/22 17:44:04 jnelson Exp $
Synopsis:
   $indextoword(<position> <text>)

Technical:
   * If the <position> argument is omitted the empty string is returned.
   * If the <position> argument is a negative number the empty string
     is returned.
   * If the <text> argument is omitted the empty string is returned.
   * If the length of <text> is less than <position> the empty string 
     is returned.
   * Otherwise, the return value returns a value suitable for use with the
     $word() function (or other word functions) representing the word that
     contains the <position>th character which should be a value returned 
     by $index() or the like.
   * Remember that <position> counts from zero!
   * Remember that the return value counts from zero!

Practical:
   The most obvious application of this function is to find the word on the
   input line underneath the cursor.  $L is the contents of the input line 
   and $curpos() tells you where the cursor is; you can then use something
   like this:
	$word($indextoword($curpos() $L) $L)
   to extract the word "underneath" the cursor.  This is the fundamental
   mechanics of how tab completion scripts know what to complete.

Returns:
   A number suitable for use with the word manipulation functions that
   represents the word that contains the <position>th character in <text>.
   Both <position> and the return value count from zero.

Examples:
   $word($indextoword($curpos() $L) $L)   returns the word under the cursor
   @ foo = [one two. three.]
   $indextoword($index(. $foo) $foo)	  returns 1 (the . in ``two.'')
   $indextoword($rindex(. $foo) $foo)	  returns 2 (the . in ``three.'')
   $indextoword(100 testing)		  returns the empty string

See Also:
   wordtoindex(6); index(6); rindex(6); curpos(6)
