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, as described below. 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 as described below. 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 simply compared with the string.

▪For an item that is 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” will select no items, “^Bad” will select all items, and “^Bad, Good” will select 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.