Replace (String function): Difference between revisions
m (almost re-match syntax diagram to revised template; fix tags.) |
m (match syntax diagram to revised template; fix tags.) |
||
Line 11: | Line 11: | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>The <var class="term">string</var> to which the method is applied.</td></tr> | <td>The <var class="term">string</var> to which the method is applied.</td></tr> | ||
<tr><th> | <tr><th>subString</th> | ||
<td>The <var class="term">subString</var> that the method attempts to replace in the input <var class="term">string</var>. If <var class="term">string</var> contains no occurrences of <var class="term">subString</var>, <var class="term">%outString</var> is set to a copy of <var class="term">string</var>. If <var class="term">subString</var> is null or longer than 255 characters, the request is cancelled.</td></tr> | <td>The <var class="term">subString</var> that the method attempts to replace in the input <var class="term">string</var>. If <var class="term">string</var> contains no occurrences of <var class="term">subString</var>, <var class="term">%outString</var> is set to a copy of <var class="term">string</var>. If <var class="term">subString</var> is null or longer than 255 characters, the request is cancelled.</td></tr> | ||
<tr><th>replacement</th> | <tr><th>replacement</th> | ||
<td>A string that contains the characters that replace the specified <var class="term">subString</var>. If <var class="term"> | <td>A string that contains the characters that replace the specified <var class="term">subString</var>. If <var class="term">replacement</var> is:<ul><li><b><i>not specified</i></b>, <var class="term">%outString</var> is set to a copy of <var class="term">string</var>;<li><b><i>longer than 255 characters</i></b>, the request is cancelled;<li><b><i>null</i></b>, the <var class="term">subString</var> characters are removed from <var class="term">string</var>.</ul></td></tr> | ||
<tr><th>Count</th> | <tr><th>Count</th> | ||
<td>An optional, but <var>[[Methods#Named parameters|NameRequired]]</var>, argument that is the number of occurrences of <var class="term">subString</var> to replace. Only values greater than 0 are valid. If <i>number</i> is:<ul><li><b><i>less</i></b> than the number of occurrences of the <var class="term"> | <td>An optional, but <var>[[Methods#Named parameters|NameRequired]]</var>, argument that is the number of occurrences of <var class="term">subString</var> to replace. Only values greater than 0 are valid. If <i>number</i> is:<ul><li><b><i>less</i></b> than the number of occurrences of the <var class="term">subString</var>, only the first <i>number</i> of occurrences are substituted;<li><b><i>greater</i></b> than or <b><i>equal</i></b> to the number of occurrences of the <var class="term">subString</var>, all occurrences of the given <var class="term">subString</var> are substituted;<li><b><i>not specified</i></b>, all occurrences are substituted.</ul></td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>The search for the target | <ul><li>The search for the target <var class="term">subString</var> is context sensitive; <b><i>case matters</i></b> in the attempt to find, as well as in the replacement of, the target characters. | ||
<li>Calling <var>Replace</var> with an empty replacement string argument is equivalent to using <var>[[Remove (String function)|Remove]]</var>. | <li>Calling <var>Replace</var> with an empty replacement string argument is equivalent to using <var>[[Remove (String function)|Remove]]</var>. | ||
<li><var>Replace</var> is available as of <var class="product">Sirius Mods</var> | <li><var>Replace</var> is available as of <var class="product">[[Sirius Mods]]</var> Version 7.3.</ul> | ||
==Examples== | ==Examples== | ||
<ol><li>The following request shows two examples of <var>Replace</var> calls against the same input string: the first call replaces two occurrences of a specified | <ol><li>The following request shows two examples of <var>Replace</var> calls against the same input string: the first call replaces two occurrences of a specified <var class="term">subString</var>; the second removes all occurrences of a different <var class="term">subString</var>. | ||
<p class="code">begin | <p class="code">begin | ||
%x is longstring | %x is longstring | ||
Line 39: | Line 39: | ||
%substr = ' wood' | %substr = ' wood' | ||
%repl = '' | %repl = <nowiki>''</nowiki> | ||
%out = %x:replace(%substr, %repl) | %out = %x:replace(%substr, %repl) | ||
printText {~} is {%out} | printText {~} is {%out} |
Revision as of 00:51, 3 February 2011
Replace occurrences of a substring with a substitute string (String class)
Th Replace intrinsic function replaces one, or multiple, occurrences of a substring within the method object input string with a substitute string, returning the modified version of the input string.
Syntax
%outString = string:Replace( substring, replacement, [Count= number])
Syntax terms
%outString | A string variable to receive the modified input string. |
---|---|
string | The string to which the method is applied. |
subString | The subString that the method attempts to replace in the input string. If string contains no occurrences of subString, %outString is set to a copy of string. If subString is null or longer than 255 characters, the request is cancelled. |
replacement | A string that contains the characters that replace the specified subString. If replacement is:
|
Count | An optional, but NameRequired, argument that is the number of occurrences of subString to replace. Only values greater than 0 are valid. If number is:
|
Usage notes
- The search for the target subString is context sensitive; case matters in the attempt to find, as well as in the replacement of, the target characters.
- Calling Replace with an empty replacement string argument is equivalent to using Remove.
- Replace is available as of Sirius Mods Version 7.3.
Examples
- The following request shows two examples of Replace calls against the same input string: the first call replaces two occurrences of a specified subString; the second removes all occurrences of a different subString.
begin %x is longstring %substr is string len 6 %repl is string len 2 %out is longstring %x = 'How much wood would a woodchuck chuck' %substr = 'wo' %repl = '?' %out = %x:replace(%substr, %repl, Count=2) printText {~} is {%out} %substr = ' wood' %repl = '' %out = %x:replace(%substr, %repl) printText {~} is {%out} end
The request output follows:
%out is How much ?od ?uld a ?odchuck chuck %out is How much would achuck chuck
See also
- For details of the printtext statement, please see printText