Insert (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(27 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Template:String:Insert subtitle}}
{{Template:String:Insert subtitle}}


This [[Intrinsic classes|intrinsic]] function inserts an argument string inside the method object string,
<var>Insert</var> is an [[Intrinsic classes|intrinsic]] function that inserts an argument string inside the method object <var class="term">string</var>, starting before the specified position in the method object <var class="term">string</var>.
starting before the specified position in the method object string.


Insert is available as of version 7.6 of the [[Sirius Mods]].
==Syntax==
==Syntax==
{{Template:String:Insert syntax}}
{{Template:String:Insert syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outStr                                                                                              </th>
<tr><th>%outString</th>
<td>A string variable to receive the modified method object string.                                     </td></tr>
<td>A string variable to receive the modified method object <var class="term">string</var>.</td></tr>
<tr><th>string                                                                                               </th>
<tr><th>string</th>
<td>The input string or Longstring.                                                                      </td></tr>
<td>The input string</td></tr>
<tr><th>%insrtString                                                                                        </th>
<tr><th>insertedString</th>
<td>The byte number in the method object that is the starting point of the                              substring that is returned.                                                                             </td></tr>
<td>The new text string to be inserted into method object <var class="term">string</var>.</td></tr>
<tr><th>%before                                                                                              </th>
<tr><th>position</th>
<td>The numeric value of the position in the method object string before which                           to insert ''%insrtString''.                                                                             The first character from the left in the method object is position ''''1''''.                                                                                                                                     The value of ''%before'' must be between 1 and the number                                               of characters in the method object string plus one.                                                     An invalid position produces a request cancellation.</td></tr>
<td>The numeric value of the position in the method object <var class="term">string</var> <b><i>before</i></b> which to insert <var class="term">insertedString</var>. The first character from the left in the method object is position 1. The value of <var class="term">position</var> must be between 1 and the number of characters in the method object <var class="term">string</var> plus one. An invalid position produces a request cancellation.</td></tr>
</table>
</table>
==Usage Notes==
<ul><li><var>Insert</var> is available as of <var class="product">Sirius Mods</var> Version 7.6.</ul>


==Examples==
==Examples==
The following request contains four <var>Insert</var> method calls:
<p class="code">begin
  [[PrintText statement|printText]] {~} = {&#39;':insert('xyz', 1)}
  printText {~} = {'ABC':insert('xyz', 3)}
  printText {~} = {'ABC':insert('xyz', 4)}
  printText {~} = {'ABC':insert('xyz', 5)}
end
</p>
The request result is:
<p class="output">&#39;':insert('xyz', 1) = xyz
'abc':insert('xyz', 3) = ABxyzC
'abc':insert('xyz', 4) = ABCxyz
'abc':insert('xyz', 5) =
  ***  1  CANCELLING REQUEST: MSIR.0750: Class STRING,
  function INSERT: insertion position greater than length
  of input string plus one in line 5
</p>
If you're converting old code to replace <var>$subIns</var> calls with calls to the <var>Insert</var> method, note that <var>$subIns</var> pads out to the required length when insertions are requested past the length of the initial string, whereas the <var>Insert</var> method treats this as an error.


The following request contains four Insert method calls:
In other words, using <var>$subIns</var> you could insert a string into position 10 of a 4 character string, like this:
    Begin
    [[Intrinsic classes#printtext|printText]] {~} = {'':insert('xyz', 1)}
    printText {~} = {'ABC':insert('xyz', 3)}
    printText {~} = {'ABC':insert('xyz', 4)}
    printText {~} = {'ABC':insert('xyz', 5)}
    End


The request result is:
<p class="code">begin
    '':insert('xyz', 1) = xyz
  %x is string len 255
    'abc':insert('xyz', 3) = ABxyzC
  %x = $subIns('Meat',' and Potatoes',10)
    'abc':insert('xyz', 4) = ABCxyz
end
     'abc':insert('xyz', 5) =
</p>
      ***  1  CANCELLING REQUEST: MSIR.0750: Class STRING,
 
      function INSERT: insertion position greater than length
resulting in:
      of input string plus one in line 5
<p class="code">Meat     and Potatoes
</p>
 
If you substitute the <var>Insert</var> method into the above request it will fail.  To make the <var>Insert</var> method work you would have to right-pad the original string to 10 characters before inserting the string.


==See also==
==See also==
[[List of intrinsic String methods]]
{{Template:String:Insert footer}}
 
[[Category:String methods|Insert function]]
[[Category:Intrinsic methods]]

Latest revision as of 21:03, 2 November 2012

Insert argument string inside the method object string (String class)


Insert is an intrinsic function that inserts an argument string inside the method object string, starting before the specified position in the method object string.

Syntax

%outString = string:Insert( insertedString, position)

Syntax terms

%outString A string variable to receive the modified method object string.
string The input string
insertedString The new text string to be inserted into method object string.
position The numeric value of the position in the method object string before which to insert insertedString. The first character from the left in the method object is position 1. The value of position must be between 1 and the number of characters in the method object string plus one. An invalid position produces a request cancellation.

Usage Notes

  • Insert is available as of Sirius Mods Version 7.6.

Examples

The following request contains four Insert method calls:

begin printText {~} = {'':insert('xyz', 1)} printText {~} = {'ABC':insert('xyz', 3)} printText {~} = {'ABC':insert('xyz', 4)} printText {~} = {'ABC':insert('xyz', 5)} end

The request result is:

'':insert('xyz', 1) = xyz 'abc':insert('xyz', 3) = ABxyzC 'abc':insert('xyz', 4) = ABCxyz 'abc':insert('xyz', 5) = *** 1 CANCELLING REQUEST: MSIR.0750: Class STRING, function INSERT: insertion position greater than length of input string plus one in line 5

If you're converting old code to replace $subIns calls with calls to the Insert method, note that $subIns pads out to the required length when insertions are requested past the length of the initial string, whereas the Insert method treats this as an error.

In other words, using $subIns you could insert a string into position 10 of a 4 character string, like this:

begin %x is string len 255 %x = $subIns('Meat',' and Potatoes',10) end

resulting in:

Meat and Potatoes

If you substitute the Insert method into the above request it will fail. To make the Insert method work you would have to right-pad the original string to 10 characters before inserting the string.

See also