Replace (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (almost re-match syntax diagram to revised template; fix tags.)
Line 1: Line 1:
{{Template:String:Replace subtitle}}
{{Template:String:Replace subtitle}}


This [[Intrinsic classes|intrinsic]] function replaces one or multiple occurrences of a substring of an
Th <var>Replace</var> [[Intrinsic classes|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.
input string (the method object) with a substitute string,
and it returns the modified version of the input string.


The <var>Replace</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:String:Replace syntax}}
{{Template:String:Replace 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 input string.                                           </td></tr>
<td>A string variable to receive the modified input <var class="term">string</var>.</td></tr>
<tr><th>string</th>
<tr><th>string</th>
<td>The string 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>substring</th>
<tr><th>substring</th>
<td>The substring that the method attempts to replace in the input string. If ''string'' contains no occurrences of ''substring'', ''%outStr'' is set to a copy of ''string''.                                                                                                         If ''substring'' is null or longer than 256 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 ''substring''. If ''replacement'' is:<ul><li>not specified, ''%outStr'' is set to a copy of ''string'';<li>longer than 256 characters, the request is cancelled;<li>null, the ''substring'' characters are removed from ''string''.</ul></td></tr>
<td>A string that contains the characters that replace the specified <var class="term">subString</var>. If <var class="term">replacment</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=num</th>
<tr><th>Count</th>
<td>An optional, name-required, argument that is the number of occurrences of ''substring'' to replace. Only values greater than 0 are valid. If ''num'' is<ul><li>less than the number of occurrences of the substring, only the first ''num'' occurrences are substituted;<li>greater than or equal to the number of occurrences of the substring, all occurrences of the given substring are substituted;<li>not specified, all occurrences are substituted.</ul></td></tr>
<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">string</var>, only the first If <i>number</i> 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==
*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.
<ul><li>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 the <var>Replace</var> method with an empty replacement string argument is equivalent to using the [[Remove (String function)|Remove]] method.
<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> 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 substring; the second removes all occurrences of a different substring.
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 substring; the second removes all occurrences of a different substring.
<p class="code">begin
<p class="code">begin
%x is longstring
  %x is longstring
%substr is string len 6
  %substr is string len 6
%repl is string len 2
  %repl is string len 2
%out is longstring
  %out is longstring
 
%x = 'How much wood would a woodchuck chuck'
%substr = 'wo'
%repl = '?'
%out = %x:replace(%substr, %repl, Count=2)
[[Intrinsic classes#printtext|printText]] {~} is {%out}


%substr = ' wood'
  %x = 'How much wood would a woodchuck chuck'
%repl = ''
  %substr = 'wo'
%out = %x:replace(%substr, %repl)
  %repl = '?'
printText {~} is {%out}
  %out = %x:replace(%substr, %repl, Count=2)
%substr = ' wood'
  printText {~} is {%out}
%repl = ''
%out = %x:replace(%substr, %repl)
printText {~} is {%out}


  %substr = ' wood'
  %repl = ''
  %out = %x:replace(%substr, %repl)
  printText {~} is {%out}
  %substr = ' wood'
  %repl = ''
  %out = %x:replace(%substr, %repl)
  printText {~} is {%out}
end
end
</p>
</p>
The request output follows:
The request output follows:
<p class="output">%out is How much ?od ?uld a ?odchuck chuck
<p class="output">%out is How much ?od ?uld a ?odchuck chuck
%out is How much would achuck chuck
%out is How much would achuck chuck
</p></ol>


</p>
==See also==
==See also==
<ul><li>For details of the <var>printtext</var> statement, please see <var>[[Intrinsic classes#printtext|printText]]</var></ul>
{{Template:String:Replace footer}}
{{Template:String:Replace footer}}

Revision as of 05:26, 2 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 replacment is:
  • not specified, %outString is set to a copy of string;
  • longer than 255 characters, the request is cancelled;
  • null, the subString characters are removed from string.
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:
  • less than the number of occurrences of the string, only the first If number occurrences are substituted;
  • greater than or equal to the number of occurrences of the subString, all occurrences of the given subString are substituted;
  • not specified, all occurrences are substituted.

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

  1. 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} %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
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Replace_(String_function)&oldid=1434"