Site Tools


splice

Differences

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

Link to this comparison view

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 <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>​
  
splice.txt ยท Last modified: 2007/03/02 02:32 (external edit)