List (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (more consistent layout and better tagging)
 
(34 intermediate revisions by 6 users not shown)
Line 9: Line 9:
<tr><th>%newlist</th>
<tr><th>%newlist</th>
<td>A declared or existing <var>stringlist</var> object.</td></tr>
<td>A declared or existing <var>stringlist</var> object.</td></tr>
<tr><th nowrap="true"><var>[%(Stringlist):]</var></th>
<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>
<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>.</td></tr>
<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><var>list</var> requires at least one argument, which may be null.<li>If an existing <var>stringlist</var> is set to receive the result of <var>list</var>, then any existing item(s) in that <var>stringlist</var> are entirely removed before the new item(s) are added.<li>The maximum number of <var class="term">itemList</var> values is 62.<li>See factory methods for more information.</ul>
<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:
<p class="code">%sl = List(<var class="term">items</var>)
 
%sl = %(Stringlist):List(<var class="term">items</var>)
 
%sl = %sl:List(<var class="term">items</var>)
</p>
<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>


==Examples==
==Examples==
<ol><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:
<ol>
<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:
<p class="output">%sl = list(<i>itemlist</i>)
<p class="output">%sl = list(<i>itemlist</i>)
%sl = %(Stringlist):list(<i>itemlist</i>)
%sl = %(Stringlist):list(<i>itemlist</i>)
%sl = %sl2:list(<i>itemlist</i>)
%sl = %sl2:list(<i>itemlist</i>)
</p>
</p>
<li>The following <var>list</var> method call creates a new <var>stringlist</var> instance whose three items are, respectively, the strings <var class="term">Moe</var>, <var class="term">Larry</var>, and <var class="term">Curly</var>:
 
<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
<p class="code">%sl is object stringlist
%sl = list('Moe', 'Larry', 'Curly')
%sl = list('Moe', 'Larry', 'Curly')
</p>
</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</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:
 
<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>:
<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
<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
</p>
</p>


However, in this example, it is necessary above to specify the class <var class="term">%(Stringlist):</var> preceding the keyword <var>list</var>, because strings are also valid in the first argument for <var>[[Run (Daemon function)|Run]]</var>, and <var>list</var>; without a qualifier it could be interpreted as a field called <var class="term">list</var>.<li>
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>.
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 Stuffit takes a <var>stringlist</var> input:
 
<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:


<p class="code">%foo:stuffit(list('Hickory', 'Dickory', 'Doc'))
<p class="code">%foo:stuffit(list('Hickory', 'Dickory', 'Doc'))

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