Initial import of the ircii-pana-1.1-final source tree.

git-svn-id: svn://svn.code.sf.net/p/bitchx/code/tags/ircii-pana-1.1-final@1 13b04d17-f746-0410-82c6-800466cd88b0

bitchx-docs/6_Functions/splice

@@ -0,0 +1,29 @@
+Synopsis:
+   $splice(<variable name> <index> <count> [<text>])
+
+Technical:
+   This function removes words from within a string, and then optionally
+   replace them with something else.  It requires that a variable name be
+   given, not an actual variable (meaning the '$' is omitted).  If no
+   replacement text is given, the words are simply removed.  The index
+   counts from zero.
+
+Practical:
+   This function is useful for changing parts of a string without
+   rewriting the whole thing.  Used in conjunction with the matching
+   functions, it can serve as a search-and-replace function that operates
+   on whole words ($sar() operates on individual characters).
+
+Returns:
+   text removed from string
+
+Examples:
+   @ 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
+
+See Also:
+   sar(6)
+