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