ListRange class

A ListRange is a view of a run of items in an ArrayList. It shows those items under indexes that start at its BaseIndex, which it takes from its list when it is made, and it does not copy them: a change made through the view changes the list. GetRange of an ArrayList (or of another ListRange) returns one.

A range is made by GetRange; the class is marked as not creatable. GetRange returns the range as an IListRange, which has no Reverse, LastIndexOf, Capacity, BaseIndex or Items. A range implements IArrayList, ICloneable and the class ArrayList as well; the type IArrayList has all the members of a range except Clone.

Dim list As New ArrayList
list.AddRange Array("a", "b", "c", "d", "e")

Dim r As IArrayList = list.GetRange(1, 3)
r.Reverse
Debug.Print r.Item(0) & r.Item(1) & r.Item(2)
r.RemoveAt 0
Debug.Print list.Count

Dim v As Variant
For Each v In list
    Debug.Print v
Next

When a range stops being valid
A range after the list grows
Properties
Methods
Hidden members
See Also

When a range stops being valid

A range keeps the version number that the list had when the range was made. Each call of the range first compares that number with the list’s. A change that the range makes itself keeps the numbers equal, with the two exceptions below. Any other change to the list — Add, Insert, RemoveAt, Sort, an assignment to an item or an assignment to BaseIndex, for example — makes them differ, and the next call of the range raises error -2146233079 (vbObjectError + 988425) with the text This ArrayList range is no longer valid. Make a new range with GetRange after such a change.

The number is the value that the documentation of the .NET class InvalidOperationException gives for its HRESULT, COR_E_INVALIDOPERATION (&H80131509).

Two changes made through the range itself make it invalid, because they count differently in the range and in the list. An assignment to an item (r.Item(0) = x, or with Set) adds 1 to the range’s version number and nothing to the list’s. SetRange of a range, with a list or a range as its argument, adds 1 to the range’s number and 2 to the list’s. See Known problems.

A change made through one range adds to the version number of the list, so every other range of the same list is invalid afterwards. A range made by GetRange of another range compares its number with the number of that range, not with the list’s: a change made through the outer range makes the inner one invalid, a change made through the inner one leaves the outer one valid, and a change made to the list directly invalidates the outer range and leaves the inner one valid.

A range after the list grows

A range reads the items from the address they had when the range was made. A change made through the range that makes the list enlarge its array, such as Add, AddRange, Insert or InsertRange on a list with no room, can move the array. The range then goes on reading the old array, which has been released, and does not notice: the range and the list keep the same version number.

Warning

After such a change the items that the range shows can be the old ones, or whatever now occupies that memory. A range of two items of a list with room for five, after three calls of Add through the range, showed a b c d and an empty item, where the list held a b X Y Z c d. Make the list large enough first, by giving New a capacity or assigning Capacity, or make a new range with GetRange after the change.

Properties

BaseIndex

The number of the first item of the range. Long, read/write.

Syntax: object.BaseIndex [ = value ]

A range has the BaseIndex that its list or outer range has when the range is made. An assignment changes the numbering of this range only; the list and the other ranges keep theirs, and the range stays valid. See BaseIndex of ArrayList.

Capacity

The capacity of the list. Long, read/write.

Syntax: object.Capacity [ = value ]

Returns the Capacity of the list. An assignment is accepted and has no effect.

Count

The number of items in the range. Long, read-only.

Syntax: object.Count

Raises the error of an invalid range when the list has changed. A range cannot be resized by assigning to Count.

Item

The item at a position in the range. Variant, read/write, and the default member.

Syntax: [ Set ] object.Item ( index ) [ = value ]

index: A Long from BaseIndex to BaseIndex + Count - 1 of the range. A value outside the range raises error 9.

See Item of ArrayList. An assignment makes the range invalid, as described above.

Methods

Add

Adds an item at the end of the range and returns its index in the range.

Syntax: object.Add ( value ) As Long

The item is inserted in the list just after the last item of the range, and the range grows by one. See Add.

AddRange

Adds the items of an array or of another collection at the end of the range.

Syntax: object.AddRange ( Target )

The items are inserted in the list after the last item of the range, and the range grows by their number. See AddRange.

BinarySearch

Searches a sorted run of the range and returns the index of a value, counted from the BaseIndex of the range.

Syntax: object.BinarySearch ( Index, GetCount, Value [ , Comparer ] ) As Long

As BinarySearch of ArrayList, with Index counted from the start of the range and the result too, including the complement of the index that is returned when there is no match. Error 9 is raised when the run does not lie in the range.

Clear

Removes the items of the range from the list.

Syntax: object.Clear ( )

The items are removed from the list, and the range is left with no items. The range stays valid.

Clone

Returns a copy of the items of the range.

Syntax: object.Clone ( ) As Variant

Returns a Variant that holds a new ArrayList with the items of the range and the BaseIndex of the range, as Clone of an ArrayList does. Clone is the member of ICloneable; the interface IArrayList does not have it.

Contains

Returns whether the range holds an item that matches a value.

Syntax: object.Contains ( Value ) As Boolean

As Contains, over the items of the range.

CopyTo

Copies the items of the range to an array, or over the items of another list.

Syntax: object.CopyTo ( Target, Index )

As CopyTo, for the items of the range, including the check that refuses an array with exactly the room needed.

GetEnumerator

Returns the enumerator that For Each uses over the items of the range.

Syntax: object.GetEnumerator ( [ Index ] [ , GetCount ] [ , GetStep ] [ , ThisEnumerator ] ) As stdole.IUnknown

As GetEnumerator, with Index counted from the first item of the range, which is 0 whatever the BaseIndex of the range is. The range keeps two enumerators in the same way as a list, with the same effects: see the warning there. A range with no items has no enumerator, and a For Each over it raises an error.

GetRange

Returns a view of a run of items of the range.

Syntax: object.GetRange ( Index, GetCount ) As IListRange

Index is counted from the BaseIndex of the range. Error 9 is raised when the run does not lie in the range. A range of a range is a view of the same items of the list. See When a range stops being valid for which changes make which range invalid.

IndexOf

Returns the index in the range of the first item that matches a value, or -1.

Syntax: object.IndexOf ( Value [ , Index [ , GetCount ] ] ) As Long

As IndexOf, with Index and the result counted from the BaseIndex of the range. The default of Index is that BaseIndex. Error 9 is raised when Index is outside the range or the run does not fit in it.

Insert

Inserts an item at a position of the range.

Syntax: object.Insert ( Index, Value )

Index is counted from the BaseIndex of the range, and the item is inserted in the list at that position. The range grows by one. Index is not checked against the range. The call is passed on to the list, so Insert of the list applies, with its failure at the first position of a list that has little room, and the range can be left reading released memory: see A range after the list grows.

InsertRange

Inserts the items of an array or of another collection at a position of the range.

Syntax: object.InsertRange ( Index, Target )

As InsertRange, with Index counted from the start of the range. The range grows by the number of items.

LastIndexOf

Returns the index in the range of the last item that matches a value, or -1.

Syntax: object.LastIndexOf ( Value [ , Index [ , GetCount ] ] ) As Long

As LastIndexOf, with Index and the result counted from the BaseIndex of the range. The default of Index is the last item of the range.

Remove

Removes the first item of the range that matches a value.

Syntax: object.Remove ( Value )

As Remove, including its failure with a BaseIndex below 0. The item is removed from the list, and the range shrinks by one.

RemoveAt

Removes the item at a position of the range.

Syntax: object.RemoveAt ( Index )

Index is counted from the start of the range; a value outside the range raises error 9. The item is removed from the list, and the range shrinks by one.

RemoveRange

Removes a run of items of the range.

Syntax: object.RemoveRange ( Index, GetCount )

Index is counted from the start of the range. Error 9 is raised when the run does not lie in the range. The items are removed from the list, and the range shrinks by their number.

Reverse

Reverses the order of the items of the range, or of a run of them.

Syntax: object.Reverse ( [ Index ] [ , GetCount ] )

As Reverse, with Index counted from the BaseIndex of the range, and with the same loop. A run with an even number of items keeps its two middle items in place: see the warning there.

SetRange

Replaces items of the range with the items of an array or of another collection.

Syntax: object.SetRange ( Index, Target )

As SetRange, with Index counted from the start of the range. Error 9 is raised when Index is outside the range. The check of the number of items is made against the list, not the range, so a Target longer than the rest of the range replaces items of the list after the range.

Sort

Sorts the items of the range, or a run of them.

Syntax: object.Sort ( [ Index ] [ , GetCount ] [ , Comparer ] )

As Sort, with Index counted from the start of the range. Unlike the list, the range checks that the run lies in it and raises error 9 otherwise.

ToArray

Returns the items of the range as an array.

Syntax: object.ToArray ( ) As Variant()

As ToArray, for the items of the range. The lower bound of the array is the BaseIndex of the range.

ToString

Returns the items of the range as text.

Syntax: object.ToString ( [ TextQualifier ] [ , UseNullAsEmpty ] ) As String

As ToString, for the items of the range. Through a variable of type IListRange or IArrayList both arguments are required. It never returns for a range with no items.

Hidden members

Bind

Makes the range a view of a run of a list.

Syntax: object.Bind ( TargetList [ , Index [ , GetCount ] ] ) As ListRange

TargetList: required An IArrayList: the list or range to look at.
Index: optional A Long: the index in TargetList of the first item, counted from the BaseIndex of TargetList. The default is that BaseIndex. The parameter is declared as a Variant, so that a call can leave it out and give GetCount.
GetCount: optional The number of items. The default is all the items from Index.

Returns the range itself, and gives it the BaseIndex of TargetList. GetRange calls Bind; a program has no reason to.

IndexOf_2, IndexOf_3, LastIndexOf_2, LastIndexOf_3, BinarySearch_2, BinarySearch_3, Sort_2

The hidden overloads of ArrayList, over the items of the range, with the same arguments.

IsFixedSize, IsReadOnly, IsSynchronized

Always False, as for ArrayList.

Items

Returns the items of the range as an array that shares their memory.

Syntax: object.Items ( ) As Variant()

As Items: use the result only as the subject of For Each. Its lower bound is 0.

SyncRoot

Always Nothing, as for ArrayList.

Version

The version number that the range expects the list to have. Long, read-only.