# $EPIC: splice,v 1.4 2001/07/23 18:17:05 jnelson Exp $
Synopsis:
   $splice(<variable name> <index> <count> [<text>])

Technical:
   * If the <variable name> argument is omitted the empty string is returned.
   * If the <index> argument is omitted the empty string is returned.
   * If the <count> argument is omitted the empty string is returned.
   * If the <text> argument is omitted it is taken as the empty string.
   * <variable name> is taken as the name of an ASSIGN variable.
   * <index> and <count> are taken as integers.
   * If <index> is negative, and the absolute value of <index> is greater
     than the number of words in $<variable name> the empty string is 
     returned.
   * If <index> is negative, then the number of words in $<variable name> is
     added to it, to simulate <index> words from the end.
   * It is not easy to explain how this function works using bullet points.
     There are four values created using $<variable name> and <text>, and
     three of the four are put together to create a new $<variable name> and
     the fourth value is the return value.
   * Let <orig> be the value of $<variable name>;
     Let <L> be the number of words in $<variable name>;
     Let all word indexes count from zero:
	* If <index> is greater than <L>
	  Part 1 -- Words 0 through <L> of <orig> (eg, all of <orig>)
	  Part 2 -- The empty string
	  Part 3 -- The empty string
	* If <index + count> is greater than <L>
	  Part 1 -- Words 0 through (<index> - 1) from <orig> 
	  Part 2 -- Words <index> through <L> from orig
	  Part 3 -- The empty string
       * If <index + count> is less than <L>
	  Part 1 -- Words 0 through (<index> - 1)
	  Part 2 -- Words <index> through (<index> + <count> - 1) from <orig>
	  Part 3 -- Words (<index> + <count>) through <L> from <orig>
       * Let Part 4 be <text>
   * The new value of $<variable name> is created as:
	@ <variable name> = <part 1>
	push <variable name> <part 4>
	push <variable name> <part 3>
   * The return value of the function is <part 2>
   * Historically this function does not support double-quoted words.  This
     may change in the future.  Try using /xdebug extracw.

Practical:
   Whew.  The above technical description is a mouthful and is very confusing.
   In practical terms, what this function does is "splice" a variable by 
   removing some words from the variable and pasting in other words in their
   place.  It will remove <count> words starting at word <index> (counting 
   from zero, of course), and put <text> in their place.  You can chop off the
   end of a string by using an unreasonably large value of <count>.  You can 
   start counting from the end of the string by using a negative <index>.
   The return value of the function is the text that was removed from the
   variable.

   When you get down to the bottom line, you can use this function to change
   one or more words in a function without having to rewrite the whole thing.
   If you have a word index returned by the matching functions, you could use
   it to search-and-replace words in a variable.

Returns:
   The <index> through <index>+<count>th (counting from 0) words from the
   variable $<variable name>.  As a side effect, the <index> through 
   <index>+<count>th words in $<variable name> are replaced with <text>.
   If any error occurs, $<variable name> is UNCHANGED.

Examples:
   @ foo = [one two three four five]
   $splice(foo 1 3 foo bar blah)       returns "two three four"
   $splice(foo 0 2)                    returns "one foo"
   $splice(foo 2 1)                    returns "five"
   echo $foo                           shows "bar blah", end result

See Also:
   sar(6)