1# $EPIC: splice,v 1.4 2001/07/23 18:17:05 jnelson Exp $
2Synopsis:
3   $splice(<variable name> <index> <count> [<text>])
4
5Technical:
6   * If the <variable name> argument is omitted the empty string is returned.
7   * If the <index> argument is omitted the empty string is returned.
8   * If the <count> argument is omitted the empty string is returned.
9   * If the <text> argument is omitted it is taken as the empty string.
10   * <variable name> is taken as the name of an ASSIGN variable.
11   * <index> and <count> are taken as integers.
12   * If <index> is negative, and the absolute value of <index> is greater
13     than the number of words in $<variable name> the empty string is
14     returned.
15   * If <index> is negative, then the number of words in $<variable name> is
16     added to it, to simulate <index> words from the end.
17   * It is not easy to explain how this function works using bullet points.
18     There are four values created using $<variable name> and <text>, and
19     three of the four are put together to create a new $<variable name> and
20     the fourth value is the return value.
21   * Let <orig> be the value of $<variable name>;
22     Let <L> be the number of words in $<variable name>;
23     Let all word indexes count from zero:
24	* If <index> is greater than <L>
25	  Part 1 -- Words 0 through <L> of <orig> (eg, all of <orig>)
26	  Part 2 -- The empty string
27	  Part 3 -- The empty string
28	* If <index + count> is greater than <L>
29	  Part 1 -- Words 0 through (<index> - 1) from <orig>
30	  Part 2 -- Words <index> through <L> from orig
31	  Part 3 -- The empty string
32       * If <index + count> is less than <L>
33	  Part 1 -- Words 0 through (<index> - 1)
34	  Part 2 -- Words <index> through (<index> + <count> - 1) from <orig>
35	  Part 3 -- Words (<index> + <count>) through <L> from <orig>
36       * Let Part 4 be <text>
37   * The new value of $<variable name> is created as:
38	@ <variable name> = <part 1>
39	push <variable name> <part 4>
40	push <variable name> <part 3>
41   * The return value of the function is <part 2>
42   * Historically this function does not support double-quoted words.  This
43     may change in the future.  Try using /xdebug extracw.
44
45Practical:
46   Whew.  The above technical description is a mouthful and is very confusing.
47   In practical terms, what this function does is "splice" a variable by
48   removing some words from the variable and pasting in other words in their
49   place.  It will remove <count> words starting at word <index> (counting
50   from zero, of course), and put <text> in their place.  You can chop off the
51   end of a string by using an unreasonably large value of <count>.  You can
52   start counting from the end of the string by using a negative <index>.
53   The return value of the function is the text that was removed from the
54   variable.
55
56   When you get down to the bottom line, you can use this function to change
57   one or more words in a function without having to rewrite the whole thing.
58   If you have a word index returned by the matching functions, you could use
59   it to search-and-replace words in a variable.
60
61Returns:
62   The <index> through <index>+<count>th (counting from 0) words from the
63   variable $<variable name>.  As a side effect, the <index> through
64   <index>+<count>th words in $<variable name> are replaced with <text>.
65   If any error occurs, $<variable name> is UNCHANGED.
66
67Examples:
68   @ foo = [one two three four five]
69   $splice(foo 1 3 foo bar blah)       returns "two three four"
70   $splice(foo 0 2)                    returns "one foo"
71   $splice(foo 2 1)                    returns "five"
72   echo $foo                           shows "bar blah", end result
73
74See Also:
75   sar(6)
76
77