splice

# Differences

This shows you the differences between two versions of the page.

 — splice [2007/03/02 02:32] (current) Line 1: Line 1: + # \$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 be the number of words in \$<​variable name>; \\ Let all word indexes count from zero: + * If <​index>​ is greater than \\ Part 1 -- Words 0 through of <​orig>​ (eg, all of <​orig>​) \\ Part 2 -- The empty string \\ Part 3 -- The empty string \\ + * If is greater than \\ Part 1 -- Words 0 through (<​index>​ - 1) from <​orig> ​ \\ Part 2 -- Words <​index>​ through from orig \\ Part 3 -- The empty string + * If is less than \\ Part 1 -- Words 0 through (<​index>​ - 1) \\ Part 2 -- Words <​index>​ through (<​index>​ + <​count>​ - 1) from <​orig>​ \\ Part 3 -- Words (<​index>​ + <​count>​) through from <​orig>​ \\ * Let Part 4 be <​text>​ + * The new value of \$<​variable name> is created as: \\ @ <​variable name> = \\ push <​variable name> \\ push <​variable name> + * The return value of the function is + * Remember that 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 +