PositionIn and PositionOf (String functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (match syntax diagram to revised template; fix tags.)
Line 1: Line 1:
{{Template:String:PositionIn and PositionOf subtitle}}
{{Template:String:PositionIn and PositionOf subtitle}}


These functions return the numeric position of the first occurrence of one string inside another.
The <var>PositionIn</var> and <var>PositionOf</var> functions return the numeric position of the first occurrence of one string inside another. The difference between the two methods is that for <var>PositionIn</var>, the method object string is located in the first argument string, whereas for <var>PositionOf</var>, the first argument string is located in the method object string. Which is more convenient to use will be application dependent.
The difference between the two methods is that for PositionIn, the method
object string is located in the first argument string, whereas for
PositionOf, the first argument string is located in the method object
string.
Which is more convenient to use will be application dependent.


These functions are available as of version 7.2 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:String:PositionIn syntax}}
{{Template:String:PositionIn syntax}}
Line 14: Line 8:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%pos                                                                                                    </th>
<tr><th>%position</th>
<td>A variable to receive the position of the first occurrence of the                                       ''needle'' string in the ''haystack'' string, starting at the implicit or explicit starting position.       If ''needle'' is not found in ''haystack'', ''spos'' is set to 0.                                           </td></tr>
<td>A variable to receive the position of the first occurrence of the <var class="term">needle</var> string in the <var class="term">haystack</var> string, starting at the implicit or explicit starting position. If <var class="term">needle</var> is not found in <var class="term">haystack</var>, <var class="term">%position</var> is set to 0. </td></tr>
<tr><th>needle                                                                                                   </th>
<tr><th>string</th>
<td>The string to be located in the ''haystack'' string.                                                     </td></tr>
<td>The method object string.  Depending upon whether the <var>PositionIn</var> or <var>PositionOf</var> method is being used, <var class="term">string</var> may be either the:
<tr><th>haystack                                                                                                 </th>
<ul><li>search target <var class="term">needle</var>, when called as <var>PositionIn</var>
<td>The string in which ''needle'' is to be located.                                                         </td></tr>
<li>the search space <var class="term">haystack</var>, when called as <var>PositionOf</var></ul></td></tr>
<tr><th>Start=spos                                                                                              </th>
<tr><th>needle</th>
<td>This optional, name-required argument is a number that specifies the position in the ''haystack'' string at which to start searching for the ''needle'' string.                                                       ''spos'' defaults to 1, meaning that the search begins at the first character in ''haystack''.</td></tr>
<td>The search target string to be located in the search space <var class="term">haystack</var> string.</td></tr>
<tr><th>haystack</th>
<td>The search space string in which the search target <var class="term">needle</var> is to be located.</td></tr>
<tr><th>Start</th>
<td>This is an optional, but <var class="term">nameRequired</var>, parameter which is a number specifying the position in the search space <var class="term">haystack</var> string at which to start searching for the search target <var class="term">needle</var> string. <var class="term">Start</var> defaults to 1, meaning that the search begins at the first character in <var class="term">haystack</var>.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
*The starting position must be a positive number. A zero or negative number results in request cancellation. Specifying a starting position greater than the length of (''haystack'' plus one minus the length of ''needle'') returns a zero, because there are not enough characters in ''haystack'' to satisfy the search.
<ul><li>The <var class="term">start</var> position must be a positive number. A zero or negative number results in request cancellation. Specifying a <var class="term">start</var> position greater than the length of (<var class="term">haystack</var> plus one minus the length of <var class="term">needle</var>) returns a zero, because there are not enough characters in <var class="term">haystack</var> to satisfy the search.
*The PositionOf and PositionIn methods do exactly the same thing. The only difference between them is that in PositionOf, the ''haystack'' is the method object and the ''needle'' is the first argument. In PositionIn, the method object and first argument are reversed. Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.
<li><var>PositionIn</var> / <var>PositionOf</var> do exactly the same thing. The only difference between them is that in <var>PositionOf</var>, the <var class="term">haystack</var> is the method object <var class="term">string</var> and the <var class="term">needle</var> is the first argument. In <var>PositionIn</var>, the method object <var class="term">string</var> and first argument are reversed. Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.
*The PositionOf and PositionIn methods are the object-oriented equivalents of the User Language $index function.
<li><var>PositionIn</var> / <var>PositionOf</var> are the object-oriented equivalents of the User Language $index function.
<li><var>PositionIn</var> / <var>PositionOf</var> are available as of <var class="product">[[Sirius Mods]]</var> Version 7.2.</ul>
 
==Examples==
==Examples==
*If ''''%s'''' contains "This is a test", the following statements
<ol><li>If <code>%s</code> contains <code>"This is a test"</code>, the following statements
    [[Intrinsic classes#printtext|printText]] {%s:positionOf('is')}
<p class="code">    printText {%s:positionOf('is')}
     printText {%s:positionOf('is', start=4)}
     printText {%s:positionOf('is', start=4)}
     printText {%s:positionOf('is', start=7)}
     printText {%s:positionOf('is', start=7)}
</p>
will display
will display
    3
<p class="code">    3
     6
     6
     0
     0
*If ''''%s'''' contains "ver", the following statements
</p>
    printText {%s:positionIn('Never say never')}
<li>If <code>%s</code> contains <code>"ver"</code>, the following statements
<p class="code">    printText {%s:positionIn('Never say never')}
     printText {%s:positionIn('Never say never', start=4)}
     printText {%s:positionIn('Never say never', start=4)}
     printText {%s:positionIn('Never say never', start=14)}
     printText {%s:positionIn('Never say never', start=14)}
 
</p>
will display
will display
    3
<p class="code">    3
     13
     13
     0
     0
</p></ol>


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

Revision as of 00:16, 3 February 2011

The position of one string inside another (String class)


The PositionIn and PositionOf functions return the numeric position of the first occurrence of one string inside another. The difference between the two methods is that for PositionIn, the method object string is located in the first argument string, whereas for PositionOf, the first argument string is located in the method object string. Which is more convenient to use will be application dependent.

Syntax

%position = string:PositionIn( haystack, [Start= number])

%position = string:PositionOf( needle, [Start= number])

Syntax terms

%position A variable to receive the position of the first occurrence of the needle string in the haystack string, starting at the implicit or explicit starting position. If needle is not found in haystack, %position is set to 0.
string The method object string. Depending upon whether the PositionIn or PositionOf method is being used, string may be either the:
  • search target needle, when called as PositionIn
  • the search space haystack, when called as PositionOf
needle The search target string to be located in the search space haystack string.
haystack The search space string in which the search target needle is to be located.
Start This is an optional, but nameRequired, parameter which is a number specifying the position in the search space haystack string at which to start searching for the search target needle string. Start defaults to 1, meaning that the search begins at the first character in haystack.

Usage notes

  • The start position must be a positive number. A zero or negative number results in request cancellation. Specifying a start position greater than the length of (haystack plus one minus the length of needle) returns a zero, because there are not enough characters in haystack to satisfy the search.
  • PositionIn / PositionOf do exactly the same thing. The only difference between them is that in PositionOf, the haystack is the method object string and the needle is the first argument. In PositionIn, the method object string and first argument are reversed. Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.
  • PositionIn / PositionOf are the object-oriented equivalents of the User Language $index function.
  • PositionIn / PositionOf are available as of Sirius Mods Version 7.2.

Examples

  1. If %s contains "This is a test", the following statements

    printText {%s:positionOf('is')} printText {%s:positionOf('is', start=4)} printText {%s:positionOf('is', start=7)}

    will display

    3 6 0

  2. If %s contains "ver", the following statements

    printText {%s:positionIn('Never say never')} printText {%s:positionIn('Never say never', start=4)} printText {%s:positionIn('Never say never', start=14)}

    will display

    3 13 0

See also