Defined in List.Def Abstract Inherits from Object, HasCount
AbstractList is an abstract class defining the behavior of a collection of data elements in an ordered list. It is a low-level class that descends directly from class Object and provides the foundation for a large family of more specialized list classes, as shown in the hierarchy above. Note that although class AbstractList itself is descended from class Object, the data elements belonging to the list need not be. (The subclass ObjectList represents a list whose elements are all objects.)
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
You'll never directly instantiate any objects of class AbstractList. Instead, you'll probably use one of its many system-defined subclasses. For example, class TaskList represents a chronologically sorted list of "to-do" tasks for the Datebook, and class ObjectList (the most popular of the list classes) defines a list of arbitrary objects.
Instantiate: never Subclass: sometimes Call its methods: sometimes
The elements of a list are arranged in a definite sequential order. Each element can be accessed by its index, which is an integer value indicating the element's location within the list. The index numbering is one-based: that is, the first element in the list is number one, which is the way most actual humans (as opposed to C programmers) think. The list's length field keeps a count of the number of elements it contains, which is also the maximum valid index value.
Class AbstractList has the following methods that you might call:
| Method | Description |
|---|---|
| List structure | |
| Length | Get number of elements in list |
| SetLength | Change number of elements in list |
| Count | Get number of elements in list |
| SetCount | Change number of elements in list |
| DisplayCount | Get number of elements in list for display |
| Element access | |
| FirstElem | Get first element in list |
| LastElem | Get last element in list |
| Adding and removing elements | |
| AddElem | Add an element to list |
| AddUniqueElem | Add an element if it isn't already in list |
| AddElemFirst | Add an element at beginning of list |
| AddElemLast | Add an element at end of list |
| RemoveElem | Remove an element from list |
| Clear | Set the length of the list to zero |
| Searching | |
| FindElem | Search list for a given element |
Some of the methods in class AbstractList rely on the following other methods in order to work. AbstractList itself does not define the methods listed below, but expects them to be provided at the subclass level. The system-defined subclasses FixedList and StringList both include definitions for these methods; be sure to provide them if you define a list subclass of your own. See the chapter on class FixedList for more detailed descriptions.
| Method | Description |
|---|---|
| ElementAt | Get element at a given index |
| AddElemAt | Add an element at a given index |
| FindElemAfter | Search for an element, beginning at a given index |
Class AbstractList defines just one field:
| Field | Type | Description |
|---|---|---|
| length | Unsigned | Number of elements in list |
Objects of class AbstractList have the following attributes:
| Attribute | Type | Description |
|---|---|---|
| Length | Unsigned | Number of elements in list |
| Count | LongInt | Number of elements in list |
This section describes the methods of class AbstractList that you're likely to call or override.
Version Note: The methods in this section are redundant. Eventually either the Length or the Count attribute will be eliminated, and the methods pertaining to it will depart with it.
attribute length: Unsigned // operation Length: Unsigned Call: sometimes Override: rarely
Call Length to find out the number of elements in a list.
attribute length: Unsigned // operation SetLength (newLength: Unsigned) Call: sometimes Override: rarely
Call SetLength to change the number of elements in a list. This operation simply changes the value of the list's Length attribute, without physically adding or removing any elements.
If newLength is smaller than the previous length, some elements at the end of the list are forgotten; they continue to take up memory, but are no longer accessible as part of the list. (The unused space might eventually be reclaimed through a Compact method defined in a subclass.) For example, you can quickly remove the last 100 elements in a list with the following call:
SetLength (theList, Length(theList) - 100);
The memory occupied by the last 100 elements remains allocated, but the elements themselves will become inaccessible. (Programmers who are parsimonious with memory probably don't want to shorten their lists this way.)
WARNING! If newLength is larger than the previous length of the list, no new space is allocated for the additional elements. Attempting to access the values of these elements will yield unpredictable results; storing into them is likely to be disastrous.
attribute Count: Unsigned // operation Count: Unsigned Call: sometimes Override: rarely
Call Count to find out the number of elements in a list.
attribute Count: Unsigned // operation SetCount (newCount: Unsigned) Call: sometimes Override: rarely
Call SetCount to change the number of elements in a list.
If newCount is smaller than the previous element count, some elements at the end of the list are forgotten; they will continue to take up memory, but are no longer accessible as part of the list. (The unused space might eventually be reclaimed through a Compact method defined in a subclass.)
Version Note: This case is not yet implemented; attempting to reduce a list's element count with SetCount currently has no effect.
If newCount is greater than the previous element count, new elements are added to the end of the list and initialized to zero. For example, suppose you have a list named testList that contains the following elements
| Index | Element |
|---|---|
| 1 | $9A 79 |
| 2 | $4C 77 |
| 3 | $20 9E |
If you make this call
SetCount (testList, Count(testList) + 3);
testList will look like this:
| Index | Element |
|---|---|
| 1 | $9A 79 |
| 2 | $4C 77 |
| 3 | $20 9E |
| 4 | $00 00 |
| 5 | $00 00 |
| 6 | $00 00 |
DisplayCount: Unsigned Call: sometimes Override: rarely
To be written.
operation FirstElem (returnElement: Pointer) Call: sometimes Override: rarely
Call FirstElem to get the first element in a list.
The parameter returnElement should point to a variable of the appropriate type for the elements of the list; FirstElem copies the value of the first list element into this variable. For example, the following function returns the value of the first element in a list of long integers:
long ReturnFirstElem (ObjectID theList)
{
long result;
FirstElem (theList, &result);
return (result);
}
The identity of the list's current element remains unchanged.
operation LastElem (returnElement: Pointer) Call: rarely Override: rarely
Call LastElem to get the last element in a list.
The parameter returnElement should point to a variable of the appropriate type for the elements of the list; LastElem copies the value of the last list element into this variable. For example, the following function returns the value of the last element in a list of objects:
ObjectID ReturnLastElem (ObjectID theList)
{
ObjectID result;
LastElem (theList, &result);
return (result);
}
The identity of the list's current element remains unchanged.
operation AddElem (newElement: Pointer) Call: sometimes Override: rarely
AddElem adds an element to a list. newElement is a pointer to the value to be added. AddElem adds a new element with that value at the end of the list, following the last existing element.
For example, suppose you have a list named testList, containing the following elements
| Index | Element |
|---|---|
| 1 | $01 23 |
| 2 | $44 72 |
| 3 | $9A A9 |
If you execute this code
newValue = 0x1234; AddElem (testList, &newValue);
testList will look like this:
| Index | Element |
|---|---|
| 1 | $01 23 |
| 2 | $44 72 |
| 3 | $9A A9 |
| 4 | $12 34 |
You probably shouldn't call AddElem directly to add elements. Instead, use AddElem as a framework method to define other methods. For example, you can't just add objects to a list without calling MakeStorable, which AbstractList_AddElem doesn't do. See the documentation for ObjectList_AddTo for an example. This comment applies to all the element-adding methods of AbstractList. (A similar comment also applies to element access methods: they should call MakeUsable if the list elements are objects.)
operation AddUniqueElem (newElement: Pointer) Call: rarely Override: rarely
Call AddUniqueElem to add an element to a list if it is not already there. newElement is a pointer to the value to be added; if the list does not already contain an element with this value, one is added at the end of the list, following the last existing element. If an element with the specified value already exists, AddUniqueElem has no effect.
operation AddElemFirst (newElement: Pointer) Call: rarely Override: rarely
Call AddElemFirst to add an element to the beginning of a list. newElement is a pointer to the value to be added; a new element with that value is added before the first existing element in the list. All existing elements are moved back one position.
For example, suppose you have a list named testList, containing the following elements
| Index | Element |
|---|---|
| 1 | $32 65 |
| 2 | $78 AA |
| 3 | $E3 3E |
If you execute this code
newValue = 0x1234; AddElemFirst (testList, &newValue);
testList will look like this:
| Index | Element |
|---|---|
| 1 | $12 34 |
| 2 | $32 65 |
| 3 | $78 AA |
| 4 | $E3 3E |
operation AddElemLast (newElement: Pointer) Call: sometimes Override: rarely
Call AddElemLast to add an element to the end of a list. newElement is a pointer to the value to be added; a new element with that value is added after the last existing element in the list.
For example, suppose you have a list named testList, containing the following elements
| Index | Element |
|---|---|
| 1 | $55 66 |
| 2 | $EF 2A |
| 3 | $87 7B |
If you execute this code
newValue = 0x9876; AddElemLast (testList, &newValue);
testList will look like this:
| Index | Element |
|---|---|
| 1 | $55 66 |
| 2 | $EF 2A |
| 3 | $87 7B |
| 4 | $98 76 |
operation RemoveElem (theElement: Pointer) Call: sometimes Override: rarely
Call RemoveElem to remove an element from a list. theElement is a pointer to the value to be removed; the first element with this value is removed from the list. If no such element exists, the operation fails, with the exception cannotFindElement.
All elements following the one being removed are moved forward one position in the list. The extra space previously occupied by the last element in the list is not deallocated, but is cleared to zeroes; since the list's element count is reduced by one, this space becomes inaccessible as part of the list. (It might eventually be reclaimed through a Compact method defined in a subclass.)
operation Clear (), noFail, safe; Call: sometimes Override: rarely
Clear simply sets the length of the list to 0, thus effectively clearing the list.
operation FindElem (theElement: Pointer): Unsigned; noFail Call: sometimes Override: sometimes
Call FindElem to search a list for a given element value. theElement is a pointer to the desired value; FindElem returns the index of the first element in the list with this value. If no such element exists, the result is zero.
For example, to find the index of an element equal to testValue in a list named testList, you could make this call:
ulong listIndex = FindElem (testList, &testValue);