BaseCLX includes many classes that represents lists or collections of items. They vary depending on the types of items they contain, what operations they support, and whether they are persistent. The following lists various list classes, and indicates the types of items they contain:

• TListn - A list of pointers
• TThreadList - A thread-safe list of pointers
• TBucketList - A hashed list of pointers
• TObjectBucketList - A hashed list of object instances
• TObjectList - A memory-managed list of object instances
• TComponentList - A memory-managed list of components (that is, instances of classes descended from TComponent)
• TClassList - A list of class references
• TInterfaceList - A list of interface pointers.
• TQueue - A first-in first-out list of pointers
• TStack - A last-in first-out list of pointers
• TObjectQueue~ - A first-in first-out list of objects
• TObjectStack~ - A last-in first-out list of objects
• TCollection - Base class for many specialized classes of typed items.
• TStringList - A list of strings
• THashedStringList - A list of strings with the form Name=Value, hashed for performance.

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.

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.

Persistent lists

Persistent lists can be saved to a form file. Because of this, they are often used as the type of a published property on a component. You can add items to the list at design time, and those items are saved with the object so that they are there when the component that uses them is loaded into memory at runtime.

There are two main types of persistent lists: string lists and collections. Examples of string lists include TStringList and THashedStringList. String lists, as the name implies, contain strings.

They provide special support for strings of the form Name=Value, so that you can look up the value associated with a name. In addition, most string lists let you associate an object with each string in the list.

Collections descend from the class TCollection. Each TCollection descendant is specialized to manage a specific class of items, where that class descends from TCollectionItem. Collections support many of the common list operations.

All collections are designed to be the type of a published property, and many can not function independently of the object that uses them to implement on of its properties.

At design time, the property whose value is a collection can use the collection editor to let you add, remove, and rearrange items. The collection editor provides a common user interface for manipulating collections.