SelectRange

This function returns an array containing copies of selected items from the input list, in the same order as in the list.

(Optional.) Number of items to return. If omitted, negative, or greater than the maximum number of items selected by Range, all selected items are returned.

If <list> is a collection, an error occurs if it does not support _NewEnum (that is, for each ... next). If <list> is NULL, an empty array is returned.

If <range> is of type Categorical, the values within it are taken as positional indexes of items in <list>. If <range> is of type Long, it is taken as a single positional index. If <range> is of type Text, it is assumed to be a range expression, of the same syntax as a category expression. Numbers in the range expression refer to positional indexes of items in <list>; names are used to identify list items. If <range> is NULL, all list items are returned. If <range> is of any other type, an error occurs.

Positional indexes start at 0 for the first item in <list>. Indexes less than zero or greater than or equal to the number of items in List are ignored. For example, in a list of 4 items, a range of "-1..10" will select all items, the same as "0..3" or "..".

▪For a string item, the name is compared with the string.

▪For an object, the name is first compared with the value of the object's Name property, if it has one. This property is not necessarily called “Name”, but it is defined internally as representing a name for the object. In COM, this is done by giving the property a Dispatch identifier of -800. If the object has no Name property, the name is compared with the value of the object's default property. If the object has no Name or default properties, or their values cannot be determined, or the value is not a string, an error occurs.

▪For any other type of item, an error occurs if Range contains item names. In particular, if List is a Categorical value, only numeric (positional) indexes can be used, not category values or names.

When comparing names, differences between upper and lower case are ignored. Like out-of-range indexes, any name in <range> that does not match an item in List is ignored. For example, if an item called “Good” exists but no item called “Bad”, then the range expression “Good..Bad” is equivalent to “Good..” (selecting all items from “Good” to the end of List), “Bad” selects no items, “^Bad” selects all items, and “^Bad, Good” selects only “Good”.

Function call	List	Range	Result
SelectRange(List, Range)	{8,5,7,1,3,2,9}	2	{7}
SelectRange(List, Range)	{8,5,7,1,3,2,9}	{2,4}	{7,3}
SelectRange(List, Range)	{8,5,7,1,3,2,9}	"2 .. 4"	{7,1,3}
SelectRange(List, Range)	{8,5,7,1,3,2,9}	"2 .., ^4"	{7,1,2,9}
SelectRange(List, Range)	Split("The quick brown fox")	3	{fox}
SelectRange(List, Range)	Split("The quick brown fox")	"quick .. jumped"	{quick,brown,fox}

Function call	List	Range	Count	Result
SelectRange(List, Range, Count)	{8,5,7,1,3,2,9}	"2 .."	4	{7,1,3,2}
SelectRange(List, Range, Count)	{8,5,7,1,3,2,9}	NULL	5	{8,5,7,1,3}
SelectRange(List, Range, Count)	Split("The quick brown fox")	NULL	2	{The,quick}

The Split function is used in some of these examples to create an array of substrings that SelectRange can operate on.