List (Stringlist function)

From m204wiki
Revision as of 19:47, 31 December 2010 by Dme (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Construct and populate a new Stringlist

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.

List is a member of the Stringlist class.

List Syntax

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

Syntax Terms

%sl
A declared or existing Stringlist object.
itemlist
A comma-delimited set of strings, each of which, from left to right, becomes an item in the resultant new Stringlist, %sl.

Usage Notes

  • The List method requires at least one argument, which may be null.
  • 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.
  • The maximum number of itemlist values is 62.
  • 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(<i>itemlist</i></i>
    %sl = %(Stringlist):List(<i>itemlist</i></i>
    %sl = %sl2:List(<i>itemlist</i></i>
    
  • See factory methods for more information.

Examples

  • 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')
    
  • 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
    

    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 could be interpreted as a field called .List. However, in a case 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'))