CopyItems (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (consistent example formatting) |
m (→Examples) |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 3: | Line 3: | ||
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. | <var>CopyItems</var> accepts three arguments and returns a numeric result. It is a [[Notation conventions for methods#Callable functions|callable]] method. | ||
==Syntax== | ==Syntax== | ||
| Line 12: | Line 12: | ||
<td>A numeric variable that is set to the number of items in the output <var>Stringlist</var> after the method is completed. </td></tr> | <td>A numeric variable that is set to the number of items in the output <var>Stringlist</var> after the method is completed. </td></tr> | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A <var>Stringlist</var> object. </td></tr> | <td>A <var>Stringlist</var> object, to which the selected items from <var class="term">inList</var> are copied. </td></tr> | ||
<tr><th>inList</th> | <tr><th>inList</th> | ||
<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> | ||
| Line 25: | 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 <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> | |||
<li>If copying an entire <var>Stringlist</var>, and no compression is required, [[Copy (Stringlist function)|Copy]] is more efficient than <var>CopyItems</var> because it does a page-for-page copy while <var>CopyItems</var> does an item-for-item copy.</ul> | <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</var> and/or <var>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. | ||
<li>If copying an entire <var>Stringlist</var>, and no compression is required, <var>[[Copy (Stringlist function)|Copy]]</var> is more efficient than <var>CopyItems</var> because it does a page-for-page copy while <var>CopyItems</var> does an item-for-item copy.</ul> | |||
==Examples== | ==Examples== | ||
The following chunk of code shows how <var>Stringlist</var> <code>%list</code> 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> | ||
==See also== | ==See also== | ||
{{Template:Stringlist:CopyItems footer}} | {{Template:Stringlist:CopyItems footer}} | ||
Latest revision as of 15:19, 31 October 2012
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
| %count | A numeric variable that is set to the number of items in the output Stringlist after the method is completed. |
|---|---|
| sl | A Stringlist object, to which the selected items from inList are copied. |
| 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 and/or ChangeItemLength may cause a Stringlist to become sparse only if Stringlist items are replaced with larger Stringlist items or increased in size.
- If copying an entire Stringlist, and no compression is required, Copy is more efficient than CopyItems because it does a page-for-page copy while CopyItems does an item-for-item copy.
Examples
The following chunk of code shows how Stringlist %list can be compressed:
%newList = new %newList:copyItems(%list) %list = %newList