Delphi in a Nutshell

by Ray Lischner

Cltn50 package

[ Tempest Software | Delphi in a Nutshell | Examples | NutShl50 package ]

The Cltn50 runtime package is a suite of collection interfaces and classes. To store something in a collection, you must implement the ICollectible interface. The interface can then be stored in any collection. The framework is extensible: you can add new collection interfaces and new implementations. See Printable.pas for an example of using the collection classes.

The ICollectible interface declares only two methods:

type
  THashValue = 0..MaxInt;
  ICollectible = interface
  ['{618977E1-1ADA-11D3-B1A8-00105AA9C2AD}']
    // Return a value < 0 if Self<Obj
    //                = 0 if Self=Obj
    //                > 0 if Self>Obj
    function CompareTo(const Obj: ICollectible): Integer;
    // Return a unique hash value. If two objects are equal (CompareTo=0)
    // their hash values must also be equal, but the reverse is not
    // necessarily true.
    function HashValue: THashValue;
  end;

All collection inherit the same ICollection interface. Different collections define interfaces that are appropriate:

• ISet is the most basic collection, being an unordered set of objects
• IList is an ordered, indexed list of collectible objects
• IStack is ordered, but accessible only at one end
• IMap maps keys to values

All collections have enumerators, which let you access all the elements of a collection. All enumerators inherit from IEnumerator.

The interfaces define the abstract collection behavior. Different classes provide concrete implementations of these interfaces using arrays, linked lists, hash tables, and red-black trees. The following units make up the package:

Cltn.pas

Declares the basic collection interfaces and a number of useful classes.

• ICollectible, ICollection, and IEnumerator are the key interfaces for the collection framework.
• IList, IStack, ISet, and IMap are the collection interfaces.
• IAssociation maps keys and values, for use by IMap.
• TCltnSort declares the Sort class method, which you can use to sort any IList collection.
• TCollection is a useful base class for implementing collections. It define several of the ICollection methods, so you need to implement only Add, Enumerator, Find, and Remove. Most collection classes will implement other methods for performance.
• TEnumerator is a useful base class for implementing enumerators. It define several of the IEnumerator methods, so you need to implement only HasNext, Next, Remove, and Reset. Most enumerator classes will implement other methods for performance.
• TEnumMap inherits from TEnumerator and implements IEnumMap, implementing the additional methods needed to enumerate the key/value associations.
• TMap implements IMap using any collection to store the key/value associations.
• TSet implements ISet using any collection to store set members.
• IString and its implementation TString facilitate storing strings in a collection.
• IObject and its implementation TWrapper facilitate storing objects in a collection when you do not control the object's source code.
• IInterface and its implementation IInterfaceWrapper facilitate storing interfaces in a collection when you do not control the interface's source code and you don't want to mess around with COM-style aggregation.
• IInteger, IDouble and their implementations TInteger and TDouble facilitate storing numbers in a collection.
• TReverseWrapper implements ICollectible and defines CompareTo to reverse the order of the comparison. It wraps another ICollectible interface. Use this wrapper to sort in descending order.
• TAssociation implements IAssociation.
• TCltnStrings inherits from TStrings, allowing you to use any IList as a TStrings string list.
• TSortedCltnStrings inherits from TCltnStrings, but uses a sorted collection.
• ECollectionError is an exception class for use by the collection classes.
• ECollectionItem error inherits from ECollectionError, and takes an ICollectible as an argument in its constructors.
• Several functions create new wrapper objects:
  • function MakeAssociation(Key: ICollectible; Value: IUnknown = nil): IAssociation;
  • function MakeString(const Str: string): IString;
  • function MakeWrapper(Obj: TObject): IObject;
  • function MakeReverse(Obj: ICollectible): ICollectible;
  • function MakeInteger(Value: Integer): IInteger;
  • function MakeDouble(Value: Double): IDouble;
• The HashString function is a convenience for computing hash values from strings.

CltnArrays.pas

Implements collections using arrays.

• TArrayList uses an array to implement IList and IStack.
• TSortedList uses an array kept in sorted order to implement IList.
• TArraySet uses an array to implement ISet. The array is not sorted, so this is suitable only for the tiniest of sets.
• TSortedArraySet uses a sorted array to implement ISet with much better performance than TArraySet.
• TArrayMap uses an array to implement IMap. The array is not sorted, so this is suitable only for the tiniest of maps.
• TSortedArrayMap uses a sorted array to implement IMap with much better performance than TArrayMap.

CltnHash.pas

Implements hash tables using open hashing.

• THashSet implements ISet.
• THashMap implements IMap.

CltnList.pas

Implements doubly-linked lists.

• TLinkedList implements IList and IStack.

CltnRbTree.pas

Implements red-black trees.

• TRbTreeSet implements ISet.
• TRbTreeMap implements IMap.

[ Tempest Software | Delphi in a Nutshell | Examples | NutShl50 package ]