# $EPIC: tow,v 1.3 2001/07/23 17:53:03 jnelson Exp $
Synopsis:
   $tow(<word> <pattern list>)

Technical:
   * If the <word> argument is omitted this function returns the empty string.
   * The <pattern list> does not actually need to be a list of wildcard
	patterns.  A list of literal words will work just fine.
   * If <word> is not matched by any of the words in <pattern list>, this 
	function returns the empty string.
   * Otherwise, the function behaves "as if" the following had been performed:
	<val> = rmatch(<word> <word/pattern list>) + 1
	<function_return> = leftw(<val> <word/pattern list>)
   * Historically <pattern list> does not support double-quoted words.
     This may change in the future.  Try using /xdebug extractw.

Practical:
   This function lets you get the part of <pattern list> that occurs BEFORE
   AND INCLUDING the pattern that is the "best match" for <word>.  You can 
   of course use this function with a list of literal words.

Returns:
   The portion of <pattern list> before and including the pattern that is the 
   "best match" of <word>.  A word is always "best matched" by itself; see the 
   help file on pattern matching for more detail.

Examples:
   $tow(foobar one two foobar my shoe)    returns "one two foobar"
   $tow(booya one two foobar my shoe)     returns ""  (empty string)
   $tow(foobar o* t* f* m* s*)            returns "m* s* f*"
   $tow(booya o* t* f* m* s*)             returns ""  (empty string)
   $tow(foobar f* fo* foobar foo* foob*)  returns "f* fo* foobar"

History:
   This function first appeared in "plus 2" (post-ircII, pre-EPIC)

See Also:
   rmatch(6); beforew(6); afterw(6); fromw(6); tow(6)
