List (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(52 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Stringlist:List subtitle}}
{{Template:Stringlist:List subtitle}}


This shared function is a virtual constructor, or factory method, for Stringlists. The List method invokes the creation of a new Stringlist instance, then populates that instance with items that are, respectively, the values of the method arguments.
This shared function is a virtual constructor, or factory method, for <var>Stringlists</var>. <var>List</var> invokes the creation of a new <var>Stringlist</var> instance, then populates that instance with items that are, respectively, the values of the method arguments.
 
List is a member of the [[Stringlist class]].


==Syntax==
==Syntax==
Line 9: Line 7:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%sl</th>
<tr><th>%newlist</th>
<td>A declared or existing Stringlist object.</td></tr>
<td>A declared or existing <var>stringlist</var> object.</td></tr>
<tr><th>itemlist</th>
<tr><th nowrap="true"><var>[%(Stringlist):]</var></th>
<td>A comma-delimited set of strings, each of which, from left to right, becomes an item in the resultant new Stringlist, '''%sl'''.</td></tr>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Shared methods|virtual constructor]] method. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Stringlist</var> constructor.</td></tr>
<tr><th>itemList</th>
<td>A comma-delimited set of strings, each of which, from left to right, becomes an item in the resultant new <var>Stringlist</var>, <var class="term">%newlist</var>.
 
Under <var class="product">Sirius Mods</var> 7.9 and later, some or all of the items in the list could themselves be <var>Stringlists</var>, in which case each item in the input <var>Stringlist</var> is added to the target <var>Stringlist</var>.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The List method requires at least one argument, which may be null.
<li><var>List</var> is a [[Object variables#Virtual Constructor methods|virtual constructor]] and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:
<li>If an existing Stringlist is set to receive the result of the List method, the items in that Stringlist are entirely removed; then the new items are added.<li>The maximum number of '''itemlist''' values is 62.<li>List is a constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:
<p class="code">%sl = List(<var class="term">items</var>)
<pre>
 
%sl = List(<i>itemlist</i></i>
%sl = %(Stringlist):List(<var class="term">items</var>)
%sl = %(Stringlist):List(<i>itemlist</i></i>
 
%sl = %sl2:List(<i>itemlist</i></i>
%sl = %sl:List(<var class="term">items</var>)
</pre>
</p>
<li>See factory methods for more information.
<li>The <var class="term">itemList</var> argument must contain at least one value, which may be null. The maximum number of <var class="term">itemList</var> values is 62.
<li>If an existing <var>Stringlist</var> is set to receive the result of <var>List</var>, any existing item(s) in that <var>Stringlist</var> are entirely removed before the new item(s) are added.
</ul>
</ul>


==Examples==
==Examples==
<ul>
<ol>
<li>The following List method call creates a new Stringlist instance whose three items are, respectively, the strings <tt>.Moe</tt>, <tt>.Larry</tt>, and <tt>.Curly</tt>:
<li><var>List</var> is a constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:
<pre>
<p class="output">%sl = list(<i>itemlist</i>)
%sl is object stringlist
%sl = %(Stringlist):list(<i>itemlist</i>)
%sl = %sl2:list(<i>itemlist</i>)
</p>
 
<li>The following <var>list</var> method call creates a new <var>stringlist</var> instance whose three items are, respectively, the strings <code>Moe</code>, <code>Larry</code>, and <code>Curly</code>:
<p class="code">%sl is object stringlist
%sl = list('Moe', 'Larry', 'Curly')
%sl = list('Moe', 'Larry', 'Curly')
</pre>
</p>
<li>You can use the List method in contexts where a Stringlist is a method parameter. For example, the Run method of the Daemon class takes a Stringlist object as an argument. A List method call can be used for such an argument, as shown below:
 
<pre>
<li>The following <var>list</var> method call creates a new <var>Stringlist</var> instance whose first three items are, respectively, the strings <code>Moe</code>, <code>Larry</code>, and <code>Curly</code>, and then contains a copy of all the items in <var>Stringlist</var> <code>%sl2</code>:
%d is object daemon
<p class="code">%sl  is object stringlist
%sl2 is object stringlist global
%sl = list('Moe', 'Larry', 'Curly', %sl2)
</p>
 
<li>You can use the <var>list</var> method in contexts where a <var>stringlist</var> is a method parameter. For example, the <var>[[Run (Daemon function)|Run]]</var> method of the <var>[[Daemon class|Daemon]]</var> class takes a <var>stringlist</var> object as an argument. A <var>list</var> method call can be used for such an argument, as shown below:
<p class="code">%d is object daemon
...
...
%d:run(%(stringlist):list('*LOWER', 'b', -
%d:run(%(stringlist):list('*LOWER', 'b', -
'printText Whatever', 'printText More', 'end')):print
  'printText Whatever', 'printText More', 'end')):print
</pre>
</p>


It is necessary above to specify the class <tt>.%(Stringlist):</tt> preceding the keyword <tt>.List</tt>, because Strings are also valid in the first argument for Run, and <tt>.List</tt> without a qualifier could be interpreted as a field called <tt>.List</tt>.
However, in this example, it is necessary above to specify the class <code>%(Stringlist):</code> preceding the keyword <var>list</var>, because strings are also valid in the first argument for <var>Run</var>, and <var>list</var>; without a qualifier it could be interpreted as a field called <var class="term">list</var>.
However, in a case where a Stringlist argument is expected, you can specify the <tt>.List</tt> keyword without a qualifier. For example, a user method called Stuffit takes a Stringlist input:


<pre>
<li>In cases where a <var>Stringlist</var> argument is expected, you can specify the <var>List</var> keyword without a qualifier. For example, a user method called <code>Stuffit</code> takes a <var>Stringlist</var> input:
%foo:stuffit(list('Hickory', 'Dickory', 'Doc'))
 
</pre>
<p class="code">%foo:stuffit(list('Hickory', 'Dickory', 'Doc'))
</ul>
</p>
</ol>


[[Category:Stringlist methods|List function]]
==See also==
{{Template:Stringlist:List footer}}

Latest revision as of 16:14, 31 October 2012

Construct a new Stringlist from list of strings (Stringlist class)


This shared function is a virtual constructor, or factory method, for Stringlists. List invokes the creation of a new Stringlist instance, then populates that instance with items that are, respectively, the values of the method arguments.

Syntax

%newList = [%(Stringlist):]List( itemList)

Syntax terms

%newlist A declared or existing stringlist object.
[%(Stringlist):] The optional class name in parentheses denotes a virtual constructor method. See "Usage notes", below, for more information about invoking a Stringlist constructor.
itemList A comma-delimited set of strings, each of which, from left to right, becomes an item in the resultant new Stringlist, %newlist. Under Sirius Mods 7.9 and later, some or all of the items in the list could themselves be Stringlists, in which case each item in the input Stringlist is added to the target Stringlist.

Usage notes

  • List is a virtual constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:

    %sl = List(items) %sl = %(Stringlist):List(items) %sl = %sl:List(items)

  • The itemList argument must contain at least one value, which may be null. The maximum number of itemList values is 62.
  • If an existing Stringlist is set to receive the result of List, any existing item(s) in that Stringlist are entirely removed before the new item(s) are added.

Examples

  1. List is a constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is null:

    %sl = list(itemlist) %sl = %(Stringlist):list(itemlist) %sl = %sl2:list(itemlist)

  2. The following list method call creates a new stringlist instance whose three items are, respectively, the strings Moe, Larry, and Curly:

    %sl is object stringlist %sl = list('Moe', 'Larry', 'Curly')

  3. The following list method call creates a new Stringlist instance whose first three items are, respectively, the strings Moe, Larry, and Curly, and then contains a copy of all the items in Stringlist %sl2:

    %sl is object stringlist %sl2 is object stringlist global %sl = list('Moe', 'Larry', 'Curly', %sl2)

  4. You can use the list method in contexts where a stringlist is a method parameter. For example, the Run method of the Daemon class takes a stringlist object as an argument. A list method call can be used for such an argument, as shown below:

    %d is object daemon ... %d:run(%(stringlist):list('*LOWER', 'b', - 'printText Whatever', 'printText More', 'end')):print

    However, in this example, it is necessary above to specify the class %(Stringlist): preceding the keyword list, because strings are also valid in the first argument for Run, and list; without a qualifier it could be interpreted as a field called list.

  5. In cases where a Stringlist argument is expected, you can specify the List keyword without a qualifier. For example, a user method called Stuffit takes a Stringlist input:

    %foo:stuffit(list('Hickory', 'Dickory', 'Doc'))

See also