Site Tools


splice
no way to compare when less than two revisions

Differences

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


splice [2007/03/02 02:32] (current) – created - external edit 127.0.0.1
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 by 127.0.0.1