Common List Operations
Go Up to Working with Lists
Although the various list classes contain different types of items and have different ancestries, most of them share a common set of methods for adding, deleting, rearranging, and accessing the items in the list.
Contents
Adding list items
Most list classes have an Add method, which lets you add an item to the end of the list (if it is not sorted) or to its appropriate position (if the list is sorted). Typically, the Add method takes as a parameter the item you are adding to the list and returns the position in the list where the item was added. In the case of bucket lists (TBucketList and TObjectBucketList), Add takes not only the item to add, but also a datum you can associate with that item. In the case of collections, Add takes no parameters, but creates a new item that it adds. The Add method on collections returns the item it added, so that you can assign values to the new item's properties.
Some list classes have an Insert method in addition to the Add method. Insert works the same way as the Add method, but has an additional parameter that lets you specify the position in the list where you want the new item to appear. If a class has an Add method, it also has an Insert method unless the position of items is predetermined. For example, you can't use Insert with sorted lists because items must go in sort order, and you can't use Insert with bucket lists because the hash algorithm determines the item position.
The only classes that do not have an Add method are the ordered lists. Ordered lists are queues and stacks. To add items to an ordered list, use the Push method instead. Push, like Add, takes an item as a parameter and inserts it in the correct position.
Deleting list items
To delete a single item from one of the list classes, use either the Delete method or the Remove method. Delete takes a single parameter, the index of the item to remove. Remove also takes a single parameter, but that parameter is a reference to the item to remove, rather than its index. Some list classes support only a Delete method, some support only a Remove method, and some have both.
As with adding items, ordered lists behave differently than all other lists. Instead of using a Delete or Remove method, you remove an item from an ordered list by calling its Pop method. Pop takes no arguments, because there is only one item that can be removed.
If you want to delete all of the items in the list, you can call the Clear method. Clear is available for all lists except ordered lists.
Accessing list items
All list classes (except TThreadList and the ordered lists) have a property that lets you access the items in the list. Typically, this property is called Items. For string lists, the property is called Strings, and for bucket lists it is called Data. The Items, Strings, or Data property is an indexed property, so that you can specify which item you want to access.
On TThreadList, you must lock the list before you can access items. When you lock the list, the LockList method returns a TList object that you can use to access the items.
Ordered lists only let you access the "top" item of the list. You can obtain a reference to this item by calling the Peek method.
Rearranging list items
Some list classes have methods that let you rearrange the items in the list. Some have an Exchange method, that swaps the position of two items. Some have a Move method that lets you move an item to a specified location. Some have a Sort method that lets you sort the items in the list.
To see what methods are available, check the online Help for the list class you are using.