CopyItems (Stringlist function)

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. The CopyItems method accepts three arguments and returns a numeric result. It is a callable method.

CopyItems is a member of the Stringlist class.

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 %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, Adjust, and/or RemoveItem activity. Replace and Adjust 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 (Stringlist function) is more efficient than CopyItems because Copy does a page-for-page copy while CopyItems does an item-for-item copy.