strins - Returns string B inserted into string A at position X.

git-svn-id: svn://svn.code.sf.net/p/actiongame/code/trunk/ac@6384 e016b1c5-ed68-44aa-a2f7-31cac88cffde

config/docs.cfg

@@ -152,6 +152,13 @@ docexample [if (strstr "Hello world!" Hello) [echo found Hello in Hello world!]
 docident [strlen] [Returns the length (in characters, including whitespace) of string S.];
 docargument [S] [The string to check.] [] [0];
 docexample [echo (strlen "Hello world!")] [output: 12];
+docident [strins] [Returns string B inserted into string A at position X.];
+docargument [A] [the original string] [] [0];
+docargument [B] [the string to insert into the original] [] [0];
+docargument [P] [the position at which to insert string B into string A] [] [0];
+docexample [echo (strins "Hello world" " cruel" 5)] [Output: Hello cruel world];
+docexample [tmp = "Hello world"; echo (strins $tmp " cruel" (strlen $tmp))] [Output: -1];
+docremark [];
 docident [substr] [Copies a substring out of the original];
 docargument [S] [The original string.] [] [0];
 docargument [A] [The starting position.] [] [0];

config/scripts.cfg

@@ -419,6 +419,19 @@ storesets = [
   ]
 ]
 
+// strins - Inserts a string into another string, at position x.
+strins = [
+  if (> $numargs 2) [
+    if (&& (> $arg3 -1) (< $arg3 (strlen $arg1))) [
+      tmp_output = ""
+      loop sil (strlen $arg1) [
+        if (= $sil $arg3) [ tmp_output = (concatword $tmp_output $arg2 (substr $arg1 $sil 1)) ] [ tmp_output = (concatword $tmp_output (substr $arg1 $sil 1)) ]
+      ]
+      result $tmp_output
+    ] [ result -1 ]
+  ]
+]
+
 // cleanshot - Take a "clean" screenshot with no HUD items.
 cs_sets = "clockdisplay crosshairsize hidecompass hideconsole hidectfhud hidedamageindicator hidehudequipment hidehudmsgs hideradar hidespecthud hideteam hidevote hudgun spechudgun showstats"
 cs_newsets = "0 0 1 1 1 1 1 1 1 1 1 1 0 0 0"

docs/reference.xml

@@ -429,7 +429,35 @@
             <identifierReference identifier="substr"/>
           </references>
 				</command>
-
+        
+        <command name="strins">
+          <description>Returns string B inserted into string A at position X.</description>
+          <examples>
+            <example>
+              <code><![CDATA[echo (strins "Hello world" " cruel" 5)]]></code>
+              <explanation>Output: Hello cruel world</explanation>
+            </example>
+            <example>
+              <code><![CDATA[tmp = "Hello world"; echo (strins $tmp " cruel" (strlen $tmp))]]></code>
+              <explanation>Output: -1</explanation>
+            </example>
+          </examples>
+          <arguments>
+            <argument token="A" description="the original string"/>
+            <argument token="B" description="the string to insert into the original"/>
+            <argument token="P" description="the position at which to insert string B into string A"/>
+          </arguments>
+          <remarks>
+            <remark>The third argument must be at least greater than -1, and 1 less than the length "(in characters)" of string A, otherwise use concat or concatword.</remark>
+          </remarks>
+          <references>
+            <identifierReference identifier="concat"/>
+            <identifierReference identifier="concatword"/>
+            <identifierReference identifier="strlen"/>
+            <identifierReference identifier="substr"/>
+          </references>
+        </command>
+        
               <command name="strpos">
                 <description>Returns the position of a substring into another</description>
                 <arguments>