ListToItem (Stringlist function): Difference between revisions

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


This method converts the contents of one Stringlist into a separator-delimited string which is overlayed on a single item of a second Stringlist.
This method converts the contents of one <var>stringlist</var> into a separator-delimited string which is overlayed onto a single item of a second <var>stringlist</var>.
 
ListToItem is a member of the [[Stringlist class]].


==Syntax==
==Syntax==
{{Template:Stringlist:ListToItem syntax}}
{{Template:Stringlist:ListToItem syntax}}
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt>%rc
<tr><th>%count</th>
<dd>A numeric variable that is set to the number of Stringlist items overlayed on a single item in the output Stringlist ('''strList2'''), or it is set to a negative error code if an error has occurred.
<td>A numeric variable which is set to the number of <var>stringlist</var> items overlayed onto a single item in the output <var>stringlist</var> (<var class="term">strList2</var>), or it is set to a negative error code if an error has occurred. </td></tr>
<dt>%sl
<tr><th>sl</th>
<dd>A Stringlist object.<dt>strList2<dd>The Stringlist that contains the item to be overlayed by the delimiter-separated string generated from '''%sl''', the method Stringlist.
<td>A <var>Stringlist</var> object.</td></tr>
<dt>itemnum
<tr><th>strList2</th>
<dd>The number of the item from '''%strList2''' to be overlayed by the delimiter-separated string generated from '''%sl''', the method Stringlist. Each '''%sl''' item that does not appear in the delimiter-separated string becomes an item in the resultant Stringlist, '''%outlist'''.
<td>The <var>Stringlist</var> that contains the item to be overlayed by the delimiter-separated string generated from <var class="term">sl</var>, the method <var>Stringlist</var>. </td></tr>
<dt>separator
<tr><th>itemNum</th>
<dd>The delimiter character or characters to be used in the generated Stringlist item string. This optional argument defaults to comma (<tt>.,</tt>), and it can be the null string. Specifying '''separator''' as a null string is different from not specifying the argument at all, since in the latter case it defaults to a comma.  
<td>The number of the item from <var class="term">strList2</var> to be overlayed by the delimiter-separated string generated from <var class="term">sl</var>, the method <var>stringlist</var>. Each <var class="term">sl</var> item that does not appear in the delimiter-separated string becomes an item in the resultant <var>Stringlist</var>, <var class="term">strList2</var>. </td></tr>
</dl>
<tr><th>separator</th>
<td>The delimiter character or characters to be used in the generated <var>Stringlist</var> item string. This optional argument defaults to comma (<tt>,</tt>) and it can be the null string. Specifying <var class="term">separator</var> as a null string is different from not specifying the argument at all, since in the latter case it defaults to a comma.</td></tr>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>All errors in ListToItem result in request cancellation.
<li>All errors in <var>ListToItem</var> result in request cancellation.
<li>The target item in the output Stringlist is cleared to blanks before the overlay is done. If the target item is too short to hold the input Stringlist items, as many items and their trailing delimiters as will fit are placed in the target item, and the result of the ListToItem method is the number of items copied.
<li>The target item in the output <var>Stringlist</var> is cleared to blanks before the overlay is done. If the target item is too short to hold the input <var>Stringlist</var> items, as many items and their trailing delimiters as will fit are placed in the target item, and the result of the <var>ListToItem</var> method is the number of items copied.
<li>The delimiter-separated string generated by ListToItem can be longer than 255 bytes; its maximum is 6124 bytes.
<li>The delimiter-separated string generated by <var>ListToItem</var> can be longer than 255 bytes; its maximum is 6124 bytes.
<li>Since no partial Stringlist items are placed into the target item, a good test for success of this method is a comparison of the result of ListToItem with a Count of the input Stringlist:
<li>Since no partial <var>Stringlist</var> items are placed into the target item, a good test for success of this method is a comparison of the result of <var>ListToItem</var> with a Count of the input <var>Stringlist</var>:


<pre>
<p class="code">if %list1:listToItem(%list2, %n) ne %list1:count then
if %list1:listToItem(%list2, %n) ne -
  <i>( error code )</i>
%list1:count then
( error code )
end if
end if
</pre>
</p></ul>


As an example of the use of this method, suppose Stringlist %list1 contained these three items:
==Examples==
<ol><li>As an example of the use of this method, suppose <var>stringlist</var> <code>%list1</code> contained these three items:


<pre>
<p class="code">LLL
LLL
MMMMM
MMMMM
NN
NN
</pre>
</p>


Suppose %list2 contained these two items:
Suppose <code>%list2</code> contained these two items:
<pre>
<p class="code">A,B,C,
A,B,C,
123456789012345678901234567890
123456789012345678901234567890
</pre>
</p>


If this is the ListToItem invocation:
If this is the <var>ListToItem</var> invocation:


<pre>
<p class="code">%cnt = %list1:listToItem(%list2, 2)
%cnt = %list1:listToItem(%list2, 2)
</p>
</pre>


The resulting %list2 has two items, the second of which is blank-padded to 30 characters, and %cnt is set to 3.
The resulting <code>%list2</code> has two items, the second of which is blank-padded to 30 characters, and <code>%cnt</code> is set to 3.


<pre>
<p class="code">A,B,C,
A,B,C,
LLL,MMMMM,NN,
LLL,MMMMM,NN,
</pre>
</p>


Suppose Stringlist %list1 contains five items:
<li>Suppose <var>Stringlist</var> <code>%list1</code> contains five items:


<pre>
<p class="code">EVERY
EVERY
GOOD
GOOD
BOY
BOY
DOES
DOES
FINE
FINE
</pre>
</p>


And Stringlist %list2 contains these three items, each padded to 22 characters:
And <var>Stringlist</var> <code>%list2</code> contains these three items, each padded to 22 characters:


<pre>
<p class="code">1234567890123456789012
1234567890123456789012
<nowiki>***JUNK****</nowiki>
***JUNK****
THE,ITSY,BITSY,SPIDER,
THE,ITSY,BITSY,SPIDER,
</pre>
</p>


If this is the ListToItem invocation:
If this is the <var>ListToItem</var> invocation:


<pre>
<p class="code">%cnt = %list1:listToItem(%list2, 3, '++')
%cnt = %list1:listToItem(%list2, 3, '++')
</p>
</pre>


The resulting %list2 has three items, each still padded to 22 characters, and %cnt is set to 3:
The resulting <code>%list2</code> has three items, each still padded to 22 characters, and <code>%cnt</code> is set to 3:


<pre>
<p class="code">1234567890123456789012
1234567890123456789012
<nowiki>***JUNK****</nowiki>
***JUNK****
EVERY++GOOD++BOY++
EVERY++GOOD++BOY++
</pre>
</p>


The third item, above, contains only three separated entries because there is insufficient space for the item "DOES" and the item delimiter characters.
The third item, above, contains only three separated entries because there is insufficient space for the item "DOES" and the item delimiter characters.
</ul>
</ol>


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

Latest revision as of 16:15, 31 October 2012

Convert Stringlist to single delimited Stringlist item (Stringlist class)


This method converts the contents of one stringlist into a separator-delimited string which is overlayed onto a single item of a second stringlist.

Syntax

%count = sl:ListToItem( strList2, itemNum, [separator])

Syntax terms

%count A numeric variable which is set to the number of stringlist items overlayed onto a single item in the output stringlist (strList2), or it is set to a negative error code if an error has occurred.
sl A Stringlist object.
strList2 The Stringlist that contains the item to be overlayed by the delimiter-separated string generated from sl, the method Stringlist.
itemNum The number of the item from strList2 to be overlayed by the delimiter-separated string generated from sl, the method stringlist. Each sl item that does not appear in the delimiter-separated string becomes an item in the resultant Stringlist, strList2.
separator The delimiter character or characters to be used in the generated Stringlist item string. This optional argument defaults to comma (,) and it can be the null string. Specifying separator as a null string is different from not specifying the argument at all, since in the latter case it defaults to a comma.

Usage notes

  • All errors in ListToItem result in request cancellation.
  • The target item in the output Stringlist is cleared to blanks before the overlay is done. If the target item is too short to hold the input Stringlist items, as many items and their trailing delimiters as will fit are placed in the target item, and the result of the ListToItem method is the number of items copied.
  • The delimiter-separated string generated by ListToItem can be longer than 255 bytes; its maximum is 6124 bytes.
  • Since no partial Stringlist items are placed into the target item, a good test for success of this method is a comparison of the result of ListToItem with a Count of the input Stringlist:

    if %list1:listToItem(%list2, %n) ne %list1:count then ( error code ) end if

Examples

  1. As an example of the use of this method, suppose stringlist %list1 contained these three items:

    LLL MMMMM NN

    Suppose %list2 contained these two items:

    A,B,C, 123456789012345678901234567890

    If this is the ListToItem invocation:

    %cnt = %list1:listToItem(%list2, 2)

    The resulting %list2 has two items, the second of which is blank-padded to 30 characters, and %cnt is set to 3.

    A,B,C, LLL,MMMMM,NN,

  2. Suppose Stringlist %list1 contains five items:

    EVERY GOOD BOY DOES FINE

    And Stringlist %list2 contains these three items, each padded to 22 characters:

    1234567890123456789012 ***JUNK**** THE,ITSY,BITSY,SPIDER,

    If this is the ListToItem invocation:

    %cnt = %list1:listToItem(%list2, 3, '++')

    The resulting %list2 has three items, each still padded to 22 characters, and %cnt is set to 3:

    1234567890123456789012 ***JUNK**** EVERY++GOOD++BOY++

    The third item, above, contains only three separated entries because there is insufficient space for the item "DOES" and the item delimiter characters.

See also