View source for StartsWith and IsStartOf (String functions)

{{Template:String:StartsWith and IsStartOf subtitle}}
<var>StartsWith</var> can be conveniently used to check whether one string starts with another string; <var>IsStartOf</var> can be conveniently used to check whether a string is an abbreviation of a known string.
 
==Syntax==
{{Template:String:StartsWith syntax}}
{{Template:String:IsStartOf syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%boolean</th>
<td>The <var>[[Boolean enumeration|Boolean]]</var> result is <var>True</var> if <var class="term">abbreviation</var> is the same as the initial substring, whose length is the length of <var class="term">abbreviation</var>, of <var class="term">longerString</var>.

In addition, for <var>IsStartOf</var>, the length of the method object <var class="term">abbreviation</var> is at least the value of the <var>MinLength</var> argument.
</td></tr>
<tr><th>string</th>
<td>The method object string.  Depending upon whether the <var>StartsWith</var> or <var>IsStartOf</var> method is being used, <var class="term">string</var> may be either the:
<ul><li><var class="term">longerString</var>, whose intial characters are examined, for <var>StartsWith</var>
<li><var class="term">abbreviation</var>, for <var>IsStartOf</var></ul></td></tr>

<tr><th>abbreviation</th><td>A string which is examined to see if it is an abbreviation (that is, an initial substring) of <var class="term">string</var>.</td></tr>

<tr><th>longerString</th>
<td>A string which is examined to see if <var class="term">string</var> is an abbreviation of it.</td></tr>

<tr><th><var>MinLength</var></th>
<td>This [[Notation conventions for methods#Named parameters|name required]] argument is a non-negative number, specifying the minimum length of <var class="term">string</var> to be considered an abbreviation of <var class="term">longerString</var>. Note that if this is 0, then the null string is an abbreviation of any value of the <var class="term">longerString</var> argument; if this is non-0, then the null string is never an abbreviation.

This argument is only used by <var>IsStartOf</var>; for <var>StartsWith</var>, <var>MinLength</var> is effectively 0.
</td></tr>
</table>

==Examples==
====Checking whether string starts with some literal====
Hopefully the following fragment is self-evident:
<p class="code">if %name:toUpper:startsWith('DAV') then
   print 'Name is probably Dave or David'
</p>

====Determining if option is valid abbreviation====
A common task is checking user input for a valid abbreviation for one of several longer terms.  This is one motivation for the <var>MinLength</var> argument; there may be overlap in the initial substrings of the longer terms.  Consider the following fragment:
<p class="code">%opt = %(system):[[Arguments (System function)|arguments]]:toUpper
if     %opt:isStartOf('MAXAMOUNT', MinLength=5) then
 ...
elseIf %opt:isStartOf('MAXTIME', MinLenth=5) then
 ...
else PrintText Invalid argument: {%opt}
</p>
If the argument to this proc is <code>max</code>, that would not distinguish it between <code>maxAmount</code> and <code>maxTime</code>; hence the <var>MinLength</var> argument value of 5 is used to enforce that at least <code>maxAm</code> or <code>maxTi</code> is entered (a value of 4 would also have disambiguated the abbreviations in this case).

====Several single-line examples====
The following fragment:
<p class="code">PrintText {~= 'a':IsStartOf('abc', MinLength=1) }
PrintText {~= 'a':IsStartOf('abc', MinLength=2) }
PrintText {~= 'a':IsStartOf('abc', MinLength=0) }
PrintText {~= 'x':IsStartOf('abc', MinLength=1) }
PrintText {~= 'x':IsStartOf('abc', MinLength=0) }
PrintText {~= &#39;':IsStartOf('abc', MinLength=0) }
</p>
produces the following output:
<p class="output">'a':IsStartOf('abc', MinLength=1) = True
'a':IsStartOf('abc', MinLength=2) = False
'a':IsStartOf('abc', MinLength=0) = True
'x':IsStartOf('abc', MinLength=1) = False
'x':IsStartOf('abc', MinLength=0) = False
</p>

==See also==
{{Template:String:StartsWith and IsStartOf footer}}