# $EPIC: before,v 1.5 2003/09/22 20:31:00 nsx Exp $
Synopsis:
   $before([<count>] <char> <text>)

Technical:
   * The <count> argument is optional, the default value is 1.  <count> must
     be some non-zero number to be recognized as a count.  If <count> is 0,
     it will be taken as the <char> argument, and <count> will default to 1!
   * If <count> is positive, then the return value of this function is the
     initial portion of <text> that is before the <count>th occurrence of any
     of the characters in <char>.
   * If <count> is negative, then the return value of this function is the
     initial port of <text> that is before the <count>th-to-last occurrence of
     any of the characters in <char>. (eg. counting backwards from the end)

Practical:
   There are many cases where you need to break apart strings that contain
   certain characters as delimiters.  The $userhost() function returns a 
   "user@host" and if you want the username, then $before(@ $userhost())
   will give it to you.  If you want the hostname, check out $after().

Returns:
   The input string <text> before the <count>th occurrence of any character
	in <char>.  The default value for <count> is 1.  Negative <count>s
        count going backwards from the end.

History:
   This function first appeared in "+10" (post ircII, pre-EPIC)
   Support for the <count> argument first appeared in "+11"

Examples:
   $before(@ hop!jnelson@wicked.neato.org)     returns "hop!jnelson"
   $before(-1 ! hop!jnelson@wicked.neato.org)  returns "hop"
   $before(-2 . hop!jnelson@wicked.neato.org)  returns "hop!jnelson@wicked"
   $before(2 . hop!jnelson@wicked.neato.org)   
					 returns "hop!jnelson@wicked.neato"
   $before(3 !@. hop!jnelson@wicked.neato.org) returns "hop!jnelson@wicked"
