CopyItems (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (Tags and links) |
||
| Line 1: | Line 1: | ||
{{Template:Stringlist:CopyItems subtitle}} | {{Template:Stringlist:CopyItems subtitle}} | ||
This method copies items from one <var>Stringlist</var> to another. The copied items are added to the end of the method <var>Stringlist</var>. | This method copies items from one <var>Stringlist</var> to another. The copied items are added to the end of the method <var>Stringlist</var>. | ||
<var>CopyItems</var> accepts three arguments and returns a numeric result. It is a callable method. | |||
==Syntax== | ==Syntax== | ||
| Line 14: | Line 16: | ||
<td>The input <var>Stringlist</var>, This is a required argument. </td></tr> | <td>The input <var>Stringlist</var>, This is a required argument. </td></tr> | ||
<tr><th>startitem</th> | <tr><th>startitem</th> | ||
<td>The starting item number in the input <var>Stringlist</var> | <td>The starting item number in the input <var>Stringlist</var>, see <var class="term">inlist</var>, from which items are to be copied. This is an optional argument, and it defaults to the first item in the input <var>Stringlist</var> if not specified. </td></tr> | ||
<tr><th>numitems</th> | <tr><th>numitems</th> | ||
<td>The number of items from | <td>The number of items from <var class="term">inlist</var> that are to be copied. This is an optional argument, and it defaults to the number of items in the input <var>Stringlist</var> after and including the starting item number. If set to a number greater than the number of items after and including the starting item number, all items after and including the starting item number are copied. A zero value for this argument is treated the same as if it were not specified.</td></tr> | ||
</table> | </table> | ||
| Line 23: | Line 25: | ||
<ul> | <ul> | ||
<li>All errors in <var>CopyItems</var> result in request cancellation. | <li>All errors in <var>CopyItems</var> result in request cancellation. | ||
<li><var>CopyItems</var> does an item-for-item copy, so it can be used to compress a <var>Stringlist</var> that has become sparse as the result of heavy Insert, Replace, | <li><var>CopyItems</var> does an item-for-item copy, so it can be used to compress a <var>Stringlist</var> that has become sparse as the result of heavy <var>[[Insert_(Stringlist_function)|Insert]]</var>, <var>[[Replace_(Stringlist_function)|Replace]]</var>, <var>[[ChangeItemLength_(Stringlist_function)|ChangeItemLength]]</var> and/or <var>[[RemoveItem_(Stringlist_function)|RemoveItem]]</var> activity. <var>[[Replace_(Stringlist_function)|Replace]]</var>, <var>[[ChangeItemLength_(Stringlist_function)|ChangeItemLength]]</var> may cause a <var>Stringlist</var> to become sparse only if <var>Stringlist</var> items are replaced with larger <var>Stringlist</var> items or increased in size. The following chunk of code shows how <var>Stringlist</var> <var class="term">%list</var> can be compressed: | ||
<p class="output">%newList = new | <p class="output">%newList = new | ||
%newList:copyItems(%list) | %newList:copyItems(%list) | ||
%list = %newList | %list = %newList | ||
</p> | </p> | ||
<li>If copying an entire <var>Stringlist</var>, and no compression is required, the [[Copy (Stringlist function)]] is more efficient than <var>CopyItems</var> because Copy does a page-for-page copy while <var>CopyItems</var> does an item-for-item copy.</ul> | <li>If copying an entire <var>Stringlist</var>, and no compression is required, the [[Copy (Stringlist function)|Copy]] is more efficient than <var>CopyItems</var> because Copy does a page-for-page copy while <var>CopyItems</var> does an item-for-item copy.</ul> | ||
[[Category:Stringlist methods|CopyItems function]] | [[Category:Stringlist methods|CopyItems function]] | ||
Revision as of 01:11, 26 January 2011
Copy items between Stringlists (Stringlist class)
This method copies items from one Stringlist to another. The copied items are added to the end of the method Stringlist.
CopyItems accepts three arguments and returns a numeric result. It is a callable method.
Syntax
[%count =] sl:CopyItems( inList, [startItem], [numItems])
Syntax terms
| %rc | A numeric variable that is set to the number of items in the output Stringlist after the method is completed. |
|---|---|
| sl | A Stringlist object. |
| inlist | The input Stringlist, This is a required argument. |
| startitem | The starting item number in the input Stringlist, see inlist, from which items are to be copied. This is an optional argument, and it defaults to the first item in the input Stringlist if not specified. |
| numitems | The number of items from inlist that are to be copied. This is an optional argument, and it defaults to the number of items in the input Stringlist after and including the starting item number. If set to a number greater than the number of items after and including the starting item number, all items after and including the starting item number are copied. A zero value for this argument is treated the same as if it were not specified. |
Usage notes
- All errors in CopyItems result in request cancellation.
- CopyItems does an item-for-item copy, so it can be used to compress a Stringlist that has become sparse as the result of heavy Insert, Replace, ChangeItemLength and/or RemoveItem activity. Replace, ChangeItemLength may cause a Stringlist to become sparse only if Stringlist items are replaced with larger Stringlist items or increased in size. The following chunk of code shows how Stringlist %list can be compressed:
%newList = new %newList:copyItems(%list) %list = %newList
- If copying an entire Stringlist, and no compression is required, the Copy is more efficient than CopyItems because Copy does a page-for-page copy while CopyItems does an item-for-item copy.