Defined in List.Def Mixes in with ObjectList
SortedList is a mixin class that's designed to be added to list classes. Elements in a sorted list are always maintained in a sorted order. You determine the nature of the sorting by overriding a comparison method.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
You'll never use objects of class SortedList, since this class is a mixin. You can interact with classes that inherit from SortedList the same way you'd interact with any list object.
Instantiate: never Subclass: always Call its methods: sometimes
The SortedList mixin makes a list class maintain its elements in sorted order. You should mix SortedList into your subclass if you want its elements to be kept in sorted order. You must determine how the elements are sorted by overriding the CompareItems method.
The SortedList mixin has the following methods you might Call:
| Method | Description |
|---|---|
| AddSorted | Adds an item in sorted order, returning its position |
| AddTo | Adds an item in sorted order |
| AddUnique | Adds an item in sorted order only if the item isn't already in the list |
| ItemChanged | Re-sorts a changed item |
| MakeSorted | Re-sorts all items |
| FindExactMatch | Finds matches quickly, taking advantage of the sort |
| SearchForMatch | Finds matching items, not just matching objectid |
| Validate | Makes sure list is indeed sorted |
Whenever you create a new class using the SortedList mixin, you should override the following methods:
| Method | Description |
|---|---|
| CompareItems | Override to define the sorting criterion |
The SortedList mixin doesn't define any fields.
operation AddSorted(newItem: Object): Unsigned, safe, common Call: rarely Override: rarely
Call AddSorted if you want to add newItem to the list in the correct position and find out where newItem was placed. AddSorted returns the position that newItem was placed in as the function result. Elements at the insertion point and after are shifted down to make room for the new element.
If you don't care where newItem was added, call AddTo instead.
For example, assume this list is testList, with the objects ordered by their values:
| List position | Object | Value |
|---|---|---|
| 1 | object A | 100 |
| 2 | object X | 105 |
| 3 | object K | 234 |
| 4 | object B | 1023 |
After executing this code:
SetValue(objectZ, 257); ulong newPos = AddSorted(testList, objectZ); /* newPos is 4 */
the list will look like this:
| List position | Object | Value |
|---|---|---|
| 1 | object A | 100 |
| 2 | object X | 105 |
| 3 | object K | 234 |
| 4 | object Z | 257 |
| 5 | object B | 1023 |
overrides AddTo Call: sometimes Override: rarely
Call AddTo if you want to add newItem to the list in the correct position and you don't care where newItem was added. AddTo works the same way AddSorted does, without the return value. <<<Clean me up.>>>.
If you need to know the position where newItem was added, call AddSorted.
Assume this list is testList, with the objects ordered by their values:
| List position | Object | Value |
|---|---|---|
| 1 | object A | 100 |
| 2 | object X | 105 |
| 3 | object K | 234 |
| 4 | object B | 1023 |
After you run this code:
SetValue(objectZ, 103); AddTo(testList, objectZ);
the list will look like this:
| List position | Object | Value |
|---|---|---|
| 1 | object A | 100 |
| 2 | object Z | 103 |
| 2 | object X | 105 |
| 3 | object K | 234 |
| 5 | object B | 1023 |
operation ItemChanged(item: Object) Call: rarely Override: rarely
Call ItemChanged after the list element at the index position has changed in a way that might cause it to be moved in the sorted list.
operation CompareItems(element1: Object; element2: Object): SignedShort Call: rarely Override: sometimes
When you add or update the position of a list element, the SortedList class calls CompareItems to determine how two elements be ordered. You should override CompareItems to compare two elements of your list and return a value that indicates which element should come first in the sorted list.
Your overridden version of CompareItems should return 1 if element1 should be placed before element2 in the sorted list. Your function should return -1 if element2 should come before element1. If the elements have the same sorted value, your function should return 0.
Here's an example that orders the list based on the values of the elements:
Method short
TestList_CompareItems(ObjectID element1, ObjectID element2)
{
ulong value1 = GetValue(element1);
ulong value2 = GetValue(element2);
if (value1 > value2) return 1; /* element1 sorts first */
if (value2 > value1) return -1; /* element2 sorts first */
return 0; /* sort keys are the same; order doesn't matter */
}
overrides Find Call: sometimes Override: rarely
Call Find to find the position in the list that contains theElement. If theElement isn't in the list, Find returns zero.
For example, to find the position of an object named testObject in testList, you could make this Call:
ulong listPosition = Find(testList, testObject);
overrides Validate() Call: rarely Override: sometimes
SortedList_Validate checks to make sure that the elements in the list are in the proper sorted order. If not, Validate writes a debugging message.
SortedList_Validate calls the inherited method.
You should override Validate if you want objects of your class to perform any additional validity checking. See Object_Validate for more information.