$splice(<variable name> <index> <count> [<text>])

• 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 words.

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.

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.

@ 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