# $EPIC: splice.txt,v 1.3 2007/03/02 02:32:04 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>
   * Remember that <word list> is a list of [[what is a word|words]].

======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:======
<file>
@ 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
</file>