Add (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
 
(44 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<span style="font-size:120%"><b>Add string as new Stringlist item</b></span>
{{Template:Stringlist:Add subtitle}}
This [[Notation conventions for methods#Callable functions|callable]] method adds arbitrary string data to a <var>Stringlist</var>. The <var>Add</var> method accepts one or more arguments and returns a numeric result.
==Syntax==
{{Template:Stringlist:Add syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%number</th>
<td>A numeric variable to contain the number of items in the indicated <var>Stringlist</var> after the strings have been added. <var class="term">%number</var> is also the item number associated with the last added string in the <var>Stringlist</var>.</td></tr>


This callable method adds arbitrary string data to a Stringlist. The Add method accepts one argument and returns a numeric result.
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>


Add is a member of the [[Stringlist class]].
<tr><th>itemList</th>
<td>Under <var class="product">Sirius Mods</var> 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is added to the method object <var>Stringlist</var>. 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>.


==Add syntax==
Under <var class="product">Sirius Mods</var> 7.8 and earlier, <var class="term">itemList</var> could only be a single string that is to be added to the <var>Stringlist</var>.</td></tr>
<pre>
</table>
[%rc =] %sl:Add(string)
</pre>


===Syntax Terms===
==Usage notes==
<dl>
<ul><li>All errors result in request cancellation.
<dt>%rc<dd>A numeric variable to contain the number of items in the indicated Stringlist after the string has been added. '''%rc''' is also the item number associated with the added string in the Stringlist.<dt>%sl<dd>A Stringlist object.<dt>string<dd>A string that is to be added to the Stringlist. </dl>
<li>The <var>[[Push (Stringlist function)|Push]]</var> and <var>[[Enqueue (Stringlist function)|Enqueue]]</var> stringlist methods are the same as the <var>Add</var> method with the exception that (under <var class="product">Sirius Mods</var> 7.9 and later) <var>Add</var> can add more than one item to the method object <var>Stringlist</var> whereas <var>Push</var> and <var>Enqueue</var> can only add one. <var>[[Push (Stringlist function)|Push]]</var> was designed as a convenience for use with <var>[[Pop (Stringlist function)|Pop]]</var>. <var>[[Enqueue (Stringlist function)|Enqueue]]</var> was designed as a convenience for use with <var>[[Dequeue (Stringlist function)|Dequeue]]</var>.
</ul>


===Usage Notes===
==Examples==
<ul><li>All errors result in request cancellation.<li>Before ''[[Sirius Mods]]'' Version 6.6, it was a request cancelling error to try to add a longstring longer than the size limit of a Stringlist item: 6124 bytes. This limitation was eliminated in ''[[Sirius Mods]]'' Version 6.6.<li>The [[Push (Stringlist function)]] and [[Enqueue (Stringlist function)]] are the same as the Add method. Push was designed as a convenience for use with [[Pop (Stringlist function)]]. Enqueue was designed as a convenience for use with [[Dequeue (Stringlist function)]].
</ul>


===Examples===
====Adding a single item to a Stringlist====
In the following example, four comma-delimited field values are added to a Stringlist for each record in a Recordset:<pre>
In the following example, four comma-delimited field values are added to a <var>Stringlist</var> for each record in a <var>Recordset</var>:
%list is object stringList
<p class="code">%list is object stringList
...
...
%list = new
%list = new
for each record in %recset
for each record in %recset
%data = ssn with ',' with lname with ',' -
  %data = ssn with ',' with lname with ',' -
fname with ',' with mi
          fname with ',' with mi
%list:add(%data)
  %list:add(%data)
end for
end for
</pre>
</p>
 
====Adding multiple items to a Stringlist====
 
In the following example, a string literal, the contents of a variable, and the contents of another <var>Stringlist</var> are added to a <var>Stringlist</var>:
<p class="code">begin
  %sl      is object stringlist
  %python  is string len 32
  %stooges is object stringlist
 
  %stooges = list('Moe', 'Larry', 'Curly')
  %sl = list('John', 'Michael', 'Eric')
  %python = 'Graham'
 
  %sl:add('Terry', %python, %stooges)
 
  %sl:print
end
</p>


This outputs:
<p class="output">John
Michael
Eric
Terry
Graham
Moe
Larry
Curly
</p>


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

Latest revision as of 15:01, 10 October 2012

Add strings to Stringlist (Stringlist class)

This callable method adds arbitrary string data to a Stringlist. The Add method accepts one or more arguments and returns a numeric result.

Syntax

[%number =] sl:Add( itemList)

Syntax terms

%number A numeric variable to contain the number of items in the indicated Stringlist after the strings have been added. %number is also the item number associated with the last added string in the Stringlist.
sl A Stringlist object.
itemList Under Sirius Mods 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is added to the method object Stringlist. The items in the list could themselves be Stringlists, in which case each item in the input Stringlist is added to the target Stringlist. Under Sirius Mods 7.8 and earlier, itemList could only be a single string that is to be added to the Stringlist.

Usage notes

  • All errors result in request cancellation.
  • The Push and Enqueue stringlist methods are the same as the Add method with the exception that (under Sirius Mods 7.9 and later) Add can add more than one item to the method object Stringlist whereas Push and Enqueue can only add one. Push was designed as a convenience for use with Pop. Enqueue was designed as a convenience for use with Dequeue.

Examples

Adding a single item to a Stringlist

In the following example, four comma-delimited field values are added to a Stringlist for each record in a Recordset:

%list is object stringList ... %list = new for each record in %recset %data = ssn with ',' with lname with ',' - fname with ',' with mi %list:add(%data) end for

Adding multiple items to a Stringlist

In the following example, a string literal, the contents of a variable, and the contents of another Stringlist are added to a Stringlist:

begin %sl is object stringlist %python is string len 32 %stooges is object stringlist %stooges = list('Moe', 'Larry', 'Curly') %sl = list('John', 'Michael', 'Eric') %python = 'Graham' %sl:add('Terry', %python, %stooges) %sl:print end

This outputs:

John Michael Eric Terry Graham Moe Larry Curly

See also