Various general purpose classes: stack, queue, objectlists

The contnrs unit implements various general-purpose classes:

Object lists: lists that manage objects instead of pointers, and which automatically dispose of the objects.
Component lists: lists that manage components instead of pointers, and which automatically dispose the components.
Class lists: lists that manage class pointers instead of pointers.
Stacks: Stack classes to push/pop pointers or objects
Queues: Classes to manage a FIFO list of pointers or objects
Hash lists: General-purpose Hash lists.

For exception support For basic lists TFPList descendent which manages objects.

TFPObjectList is a TFPList based list which has as the default array property TObjects instead of pointers. By default it also manages the objects: when an object is deleted or removed from the list, it is automatically freed. This behaviour can be disabled when the list is created.

In difference with , TFPObjectList offers no notification mechanism of list operations, allowing it to be faster than TObjectList. For the same reason, it is also not a descendent of TFPList (although it uses one internally).

Create a new object list Create instantiates a new object list. The FreeObjects parameter determines whether objects that are removed from the list should also be freed from memory. By default this is True. This behaviour can be changed after the list was instantiated. None. Should objects be freed when removing them from the list Clears the list and destroys the list instance Destroy clears the list, freeing all objects in the list if OwnsObjects is True. Clear all elements in the list. Removes all objects from the list, freeing all objects in the list if OwnsObjects is True. Add an object to the list.

Add adds AObject to the list and returns the index of the object in the list.

Note that when OwnsObjects is True, an object should not be added twice to the list: this will result in memory corruption when the object is freed (as it will be freed twice). The Add method does not check this, however.

None. The index of the object in the list. The object to add Delete an element from the list. Delete removes the object at index Index from the list. When OwnsObjects is True, the object is also freed. An access violation may occur when OwnsObjects is True and either the object was freed externally, or when the same object is in the same list twice. Index of the object to delete. Exchange the location of two objects Exchange exchanges the objects at indexes Index1 and Index2 in a direct operation (i.e. no delete/add is performed). If either Index1 or Index2 is invalid, an exception will be raised. Location of first object Location of second object Expand the capacity of the list. Expand increases the capacity of the list. It calls and then returns a reference to itself. If there is not enough memory to expand the list, an exception will be raised. A reference to the expanded list. Extract an object from the list

Extract removes Item from the list, if it is present in the list. It returns Item if it was found, Nil if item was not present in the list.

Note that the object is not freed, and that only the first found object is removed from the list.

None. The extracted object, or Nil if none was extracted. The object to extract Remove an item from the list.

Remove removes Item from the list, if it is present in the list. It frees Item if OwnsObjects is True, and returns the index of the object that was found in the list, or -1 if the object was not found.

Note that only the first found object is removed from the list.

None. Index of the removed object or -1 if none was removed. Object to remove from the list. Search for an object in the list IndexOf searches for the presence of AObject in the list, and returns the location (index) in the list. The index is 0-based, and -1 is returned if AObject was not found in the list. None. Index of the object in the list, -1 if not present. Object instance to search for. Search for an instance of a certain class

FindInstanceOf will look through the instances in the list and will return the first instance which is a descendent of class AClass if AExact is False. If AExact is true, then the instance should be of class AClass.

If no instance of the requested class is found, Nil is returned.

None. The first instance of the requested class. The class to look for Should the class match exact or nor Index to start the search at Insert a new object in the list Insert inserts AObject at position Index in the list. All elements in the list after this position are shifted. The index is zero based, i.e. an insert at position 0 will insert an object at the first position of the list. None. Position Index to insert the object in Object to insert in the list Return the first non-nil object in the list First returns a reference to the first non-Nil element in the list. If no non-Nil element is found, Nil is returned. None. The first non-nil element in the list. Return the last non-nil object in the list. Last returns a reference to the last non-Nil element in the list. If no non-Nil element is found, Nil is returned. None. The last non-nil object in the list. Move an object to another location in the list.

Move moves the object at current location CurIndex to location NewIndex. Note that the NewIndex is determined after the object was removed from location CurIndex, and can hence be shifted with 1 position if CurIndex is less than NewIndex.

Contrary to exchange, the move operation is done by extracting the object from it's current location and inserting it at the new location.

If either CurIndex or NewIndex is out of range, an exception may occur. The current index of the object The new index of the object Copy the contents of a list. Assign copies the contents of Obj if Obj is of type TFPObjectList None. The source list to copy from. Remove all Nil references from the list Pack removes all Nil elements from the list. None. Sort the list of objects

Sort will perform a quick-sort on the list, using Compare as the compare algorithm. This function should accept 2 pointers and should return the following result:

less than 0: If the first pointer comes before the second.
equal to 0: If the pointers have the same value.
larger than 0: If the first pointer comes after the second.

The function should be able to deal with Nil values.

None. Compare function for two objects. Capacity of the list Capacity is the number of elements that the list can contain before it needs to expand itself, i.e., reserve more memory for pointers. It is always equal or larger than Count. Number of elements in the list. Count is the number of elements in the list. Note that this includes Nil elements. Should the list free elements when they are removed.

OwnsObjects determines whether the objects in the list should be freed when they are removed (not extracted) from the list, or when the list is cleared. If the property is True then they are freed. If the property is False the elements are not freed.

The value is usually set in the constructor, and is seldom changed during the lifetime of the list. It defaults to True.

Indexed access to the elements of the list. Items is the default property of the list. It provides indexed access to the elements in the list. The index Index is zero based, i.e., runs from 0 (zero) to Count-1. Index of the element. Internal list used to keep the objects. List is a reference to the TFPList instance used to manage the elements in the list. List to manage object instances.

TObjectList is a TList descendent which has as the default array property TObjects instead of pointers. By default it also manages the objects: when an object is deleted or removed from the list, it is automatically freed. This behaviour can be disabled when the list is created.

In difference with , TObjectList offers a notification mechanism of list change operations: insert, delete. This slows down bulk operations, so if the notifications are not needed, TFPObjectList may be more appropriate.

Create a new object list. Create instantiates a new object list. The FreeObjects parameter determines whether objects that are removed from the list should also be freed from memory. By default this is True. This behaviour can be changed after the list was instantiated. None. Should removed items be freed from memory Add an object to the list.

Add overrides the TList implementation to accept objects (AObject) instead of pointers.

The function returns the index of the position where the object was added.

If the list must be expanded, and not enough memory is available, an exception may be raised. Position at which the object was added Object to add to the list. Extract an object from the list.

Extract removes the object Item from the list if it is present in the list. Contrary to Remove, Extract does not free the extracted element if OwnsObjects is True

The function returns a reference to the item which was removed from the list, or Nil if no element was removed.

None. The removed element, or Nil Element to remove from the list. Remove (and possibly free) an element from the list.

Note that only the first found object is removed from the list.

None. Index of the removed object, or -1 if none was removed. Object to remove from the list. Search for an object in the list

IndexOf overrides the TList implementation to accept an object instance instead of a pointer.

The function returns the index of the first match for AObject in the list, or -1 if no match was found.

None. Position (index) at which object was found Object to search for. Search for an instance of a certain class

If no instance of the requested class is found, Nil is returned.

None. Instance found or Nil if none was found Class of which result should be a descendent Should the class of the result be exactly the requested class. Index to start the search Insert an object in the list. Insert inserts AObject in the list at position Index. The index is zero-based. This method overrides the implementation in TList to accept objects instead of pointers. If an invalid Index is specified, an exception is raised. Position to insert object at. Object to insert Return the first non-nil object in the list First returns a reference to the first non-Nil element in the list. If no non-Nil element is found, Nil is returned. None. First non-nil object in the list. Return the last non-nil object in the list. Last returns a reference to the last non-Nil element in the list. If no non-Nil element is found, Nil is returned. None. Last non-nil object in the list. Should the list free elements when they are removed.

The value is usually set in the constructor, and is seldom changed during the lifetime of the list. It defaults to True.

TComponentList is a descendent which has as the default array property TComponents instead of objects. It overrides some methods so only components can be added.

In difference with , TComponentList removes any TComponent from the list if the TComponent instance was freed externally. It uses the FreeNotification mechanism for this.

Destroys the instance Destroy unhooks the free notification handler and then calls the inherited destroy to clean up the TComponentList instance. None. Add a component to the list.

Add overrides the Add operation of it's ancestors, so it only accepts TComponent instances. It introduces no new behaviour.

The function returns the index at which the component was added.

If not enough memory is available to expand the list, an exception may be raised. Index at which the component was added. The component to add. Remove a component from the list without destroying it.

Extract removes a component (Item) from the list, without destroying it. It overrides the implementation of so only TComponent descendents can be extracted. It introduces no new behaviour.

Extract returns the instance that was extracted, or Nil if no instance was found.

The extracted component, or Nil if none was found. The component to extract. Remove a component from the list, possibly destroying it.

Remove removes item from the list, and if the list owns it's items, it also destroys it. It returns the index of the item that was removed, or -1 if no item was removed.

Remove simply overrides the implementation in so it only accepts TComponent descendents. It introduces no new behaviour.

None. The index of the removed instance Component to remove from the list Search for an instance in the list

IndexOf searches for an instance in the list and returns it's position in the list. The position is zero-based. If no instance is found, -1 is returned.

IndexOf just overrides the implementation of the parent class so it accepts only TComponent instances. It introduces no new behaviour.

None. Index of the found instance Instance to look for. First non-nil instance in the list. First overrides the implementation of it's ancestors to return the first non-nil instance of TComponent in the list. If no non-nil instance is found, Nil is returned. None. The first non-nil instance in the list, or Nil Last non-nil instance in the list. Last overrides the implementation of it's ancestors to return the last non-nil instance of TComponent in the list. If no non-nil instance is found, Nil is returned. None. The last non-nil instance in the list, or Nil Insert a new component in the list Insert inserts a TComponent instance (AComponent) in the list at position Index. It simply overrides the parent implementation so it only accepts TComponent instances. It introduces no new behaviour. None. Position in the list where the component should be inserted Component instance to insert. Index-based access to the elements in the list. Items provides access to the components in the list using an index. It simply overrides the default property of the parent classes so it returns/accepts TComponent instances only. Note that the index is zero based. Index in the array. List of classes.

TClassList is a Tlist descendent which stores class references instead of pointers. It introduces no new behaviour other than ensuring all stored pointers are class pointers.

The OwnsObjects property as found in TComponentList and TObjectList is not implemented as there are no actual instances.

Add a new class pointer to the list. Add adds AClass to the list, and returns the position at which it was added. It simply overrides the TList bevahiour, and introduces no new functionality. If not enough memory is available to expand the list, an exception may be raised. Index at which the class pointer was added. Class pointer to add. Extract a class pointer from the list. Extract extracts a class pointer Item from the list, if it is present in the list. It returns the extracted class pointer, or Nil if the class pointer was not present in the list. It simply overrides the implementation in TList so it accepts a class pointer instead of a simple pointer. No new behaviour is introduced. None. The extracted class pointer or Nil if none was found. Class pointer to extract from the list Remove a class pointer from the list. Remove removes a class pointer Item from the list, if it is present in the list. It returns the index of the removed class pointer, or -1 if the class pointer was not present in the list. It simply overrides the implementation in TList so it accepts a class pointer instead of a simple pointer. No new behaviour is introduced. None. Index of the removed item Class pointer to remove from the list. Search for a class pointer in the list. IndexOf searches for AClass in the list, and returns it's position if it was found, or -1 if it was not found in the list. None. Position of the class pointer, or -1 if not found. Class pointer to search for Return first non-nil class pointer First returns a reference to the first non-Nil class pointer in the list. If no non-Nil element is found, Nil is returned. None. The first non-Nil class pointer in the list. Return last non-Nil class pointer Last returns a reference to the last non-Nil class pointer in the list. If no non-Nil element is found, Nil is returned. None. The last non-Nil class pointer in the list. Insert a new class pointer in the list. Insert inserts a class pointer in the list at position Index. It simply overrides the parent implementation so it only accepts class pointers. It introduces no new behaviour. None. Position to insert class pointer at. Class pointer to insert. Index based access to class pointers. Items provides index-based access to the class pointers in the list. TClassList overrides the default Items implementation of TList so it returns class pointers instead of pointers. Position in the list. Base class for queues and stacks.

TOrderedList provides the base class for and . It provides an interface for pushing and popping elements on or off the list, and manages the internal list of pointers.

Note that TOrderedList does not manage objects on the stack, i.e. objects are not freed when the ordered list is destroyed.

Create a new ordered list Create instantiates a new ordered list. It initializes the internal pointer list. None. Free an ordered list Destroy cleans up the internal pointer list, and removes the TOrderedList instance from memory. None. Number of elements on the list. Count is the number of pointers in the list. None. Number of elements on the list. Check whether the list contains a certain number of elements. AtLeast returns True if the number of elements in the list is equal to or bigger than ACount. It returns False otherwise. None. True if ACount or more elements in the list. Required number of elements Push another element on the list. Push adds AItem to the list, and returns AItem. If not enough memory is available to expand the list, an exception may be raised. The element added to the list. Item to add to the list. Remove an element from the list. Pop removes an element from the list, and returns the element that was removed from the list. If no element is on the list, Nil is returned. None. The element removed from the list. Return the next element to be popped from the list. Peek returns the element that will be popped from the list at the next call to Pop, without actually popping it from the list. None. Next element to be popped from the list. Pointer Stack

TStack is a descendent of which implements Push and Pop behaviour as a stack: what is last pushed on the stack, is popped of first (LIFO: Last in, first out).

TStack offers no new methods, it merely implements some abstract methods introduced by

Object instances stack

TObjectStack is a stack implementation which manages pointers only.

TObjectStack introduces no new behaviour, it simply overrides some methods to accept and/or return TObject instances instead of pointers.

Push an object on the stack. Push pushes another object on the stack. It overrides the Push method as implemented in TStack so it accepts only objects as arguments. If not enough memory is available to expand the stack, an exception may be raised. The element pushed on the stack. The object instance to push on the stack. Pop the top object of the stack. Pop pops the top object of the stack, and returns the object instance. If there are no more objects on the stack, Nil is returned. None The top object on the stack, or Nil if the stack is empty. Look at the top object in the stack. Peek returns the top object of the stack, without removing it from the stack. If there are no more objects on the stack, Nil is returned. None The top object on the stack, or Nil if the stack is empty. Pointer queue

TQueue is a descendent of which implements Push and Pop behaviour as a queue: what is first pushed on the queue, is popped of first (FIFO: First in, first out).

TQueue offers no new methods, it merely implements some abstract methods introduced by

Push an object on the queue Push pushes another object on the queue. It overrides the Push method as implemented in TQueue so it accepts only objects as arguments. If not enough memory is available to expand the queue, an exception may be raised. The element just pushed on the queue Object to push on the queue Pop the first element off the queue Pop removes the first element in the queue, and returns a reference to the instance. If the queue is empty, Nil is returned. None. The first element in the queue, or Nil if the queue is empty Look at the first object in the queue. Peek returns the first object in the queue, without removing it from the queue. If there are no more objects in the queue, Nil is returned. None The first element in the queue, or Nil if the queue is empty Method callback type for TFPObjectList.ForEachCall TObjectListCallback is used as the prototype for the link call when a method should be called. The Data argument will contain each of the objects in the list in turn, and the Data argument will contain the data passed to the ForEachCall call. Object from the list Data passed to ForEachCall Plan procedure callback type for TFPObjectList.ForEachCall TObjectListCallback is used as the prototype for the link call when a plain procedure should be called. The Data argument will contain each of the objects in the list in turn, and the Data argument will contain the data passed to the ForEachCall call. Object from the list Data passed to ForEachCall For each object in the list, call a method or procedure, passing it the object. ForEachCall loops through all objects in the list, and calls proc2call, passing it the object in the list. Additionally, arg is also passed to the procedure. Proc2call can be a plain procedure or can be a method of a class. None. Procedure or method to be called. Additional pointer passed to proc2call Hash calculation function. THashFunction is the prototype for a hash calculation function. It should calculate a hash of string S, where the hash table size is TableSize. The return value should be the hash value. Hash value String to calculate hash value from. Hash table size. Iterator prototype for TFPCustomHashTable TIteratorMethod is used in an internal method. Hash item Key value Should the iterator continue after processing this item or not Single item in the hash table. THTCustomNode is used by the class to store the keys and associated values. Create a new instance of THTCustomNode CreateWith creates a new instance of THTCustomNode and stores the string AString in it. It should never be necessary to call this method directly, it will be called by the class when needed. If no more memory is available, an exception may be raised. Key value for this node. Check whether this node matches the given key. HasKey checks whether this node matches the given key AKey, by comparing it with the stored key. It returns True if it does, False if not. None. True if the key matches, False if not. Key to check for Key value associated with this hash item. Key is the key value associated with this hash item. It is stored when the item is created, and is read-only. Data associated with this hash value. Data is the (optional) data associated with this hash value. It will be set by the method. Hash class

TFPCustomHashTable is a general-purpose hashing class. It can store string keys and pointers associated with these strings. The hash mechanism is configurable and can be optionally be specified when a new instance of the class is created; A default hash mechanism is implemented in .

A TFPHasList should be used when fast lookup of data based on some key is required. The other container objects only offer linear search methods, while the hash list offers faster search mechanisms.

Instantiate a new TFPCustomHashTable instance using the default hash mechanism Create creates a new instance of TFPCustomHashTable with hash size 196613 and hash algorithm If no memory is available, an exception may be raised. CreateWith Instantiate a new TFPCustomHashTable instance with given algorithm and size CreateWith creates a new instance of TFPCustomHashTable with hash size AHashTableSize and hash calculating algorithm aHashFunc. If no memory is available, an exception may be raised. Create Size of the hash table. Hash calculating function. Free the hash table. Destroy removes the hash table from memory. If any data was associated with the keys in the hash table, then this data is not freed. This must be done by the programmer. None. Destroy Create Create Change the table size of the hash table. ChangeTableSize changes the size of the hash table: it recomputes the hash value for all of the keys in the table, so this is an expensive operation. If no memory is available, an exception may be raised. HashTableSize New hash table size Clear the hash table. Clear removes all keys and their associated data from the hash table. The data itself is not freed from memory, this should be done by the programmer. None. Destroy Add a new key and its associated data to the hash.

Add calculates the hash value of aKey and adds key and it's associated data to the corresponding hash chain.

A given key can only be added once. It is an error to attempt to add the same key value twice.

If the key is already in the list, adding it a second time will raise an . Key to add Data to associate with key Delete a key from the hash list. Delete deletes all keys with value AKey from the hash table. It does not free the data associated with key. If AKey is not in the list, nothing is removed. None. Key to delete from the list Search for an item with a certain key value.

Find searches for the instance with key value equal to Akey and if it finds it, it returns the instance. If no matching value is found, Nil is returned.

Note that the instance returned by this function cannot be freed; If it should be removed from the hash table, the Delete method should be used instead.

None. Add Delete THTCustomNode instance matching AKey Key value to look for. Check if the hash table is empty. IsEmpty returns True if the hash table contains no elements, or False if there are still elements in the hash table. True if there are zero keys in the hashtable Hash function currently in use HashFunction is the hash function currently in use to calculate hash values from keys. The property can be set, this simply calls SetHashFunction. Note that setting the hash function does NOT the hash value of all keys to be recomputed, so changing the value while there are still keys in the table is not a good idea. SetHashFunction HashTableSize Number of items in the hash table. Count is the number of items in the hash table. Size of the hash table HashTableSize is the size of the hash table. It can be set, in which case it will be rounded to the nearest prime number suitable for RSHash. Indexed access to the data pointer. Item allows indexed access to the data pointers. When reading the property, if Index exists, then the associated data pointer is returned. If it does not exist, Nil is returned. When writing the property, if Index does not exist, a new item is added with the associated data pointer. If it existed, then the associated data pointer is overwritten with the new value. Key for which data pointer should be returned. Hash table instance TFPCustomHashTable is the internal list object ( used for the hash table. Each element in this table is again a instance or Nil. Number of empty slots in the hash table. VoidSlots is the number of empty slots in the hash table. Calculating this is an expensive operation. Fraction of count versus size LoadFactor is the ratio of elements in the table versus table size. Ideally, this should be as small as possible. Average chain length AVGChainLen is the average chain length, i.e. the ratio of elements in the table versus the number of filled slots. Calculating this is an expensive operation. Maximum chain length MaxChainLength is the length of the longest chain in the hash table. Calculating this is an expensive operation. Number of extra items NumberOfCollisions is the number of items which are not the first item in a chain. If this number is too big, the hash size may be too small. Number of filled slots Density is the number of filled slots in the hash table. Exception raised when a key is stored twice in a hash table. Exception raised when a key is not found. Standard hash value calculating function. RSHash is the standard hash calculating function used in the hash class. It's Robert Sedgwick's "Algorithms in C" hash function. None. Hash value String to calculate hash value from Hash table size Record used to maintain an item in the hash list THashItem is used internally in the hash list. It should never be used directly. Key hash value Index of the string value Next value index Data associated with the key. Pointer to THashItem PHashItem is a pointer type, pointing to the record. Maximum size of hash list. MaxHashListSize is the maximum number of elements a hash list can contain. Maximum string size MaxHashStrSize is the maximum amount of data for the key string values. The key strings are kept in a continuous memory area. This constant determines the maximum size of this memory area. Maximum size of the hash table. MaxHashTableSize is the maximum number of elements in the hash. Maximum number of items in each hash bucket. MaxItemsPerHash is the threshold above which the hash is expanded. If the number of elements in a hash bucket becomes larger than this value, the hash size is increased. Pointer to THashItemList array PHashItemList is a pointer to the . It's used in the as a pointer to the memory area containing the hash item records. array of THashItem records. THashItemList is an array type, primarily used to be able to define the type. It's used in the class. Pointer to THashTable array. PHashTable is a pointer to the . It's used in the as a pointer to the memory area containing the hash values. Array of hash values THashTable defines an array of integers, used to hold hash values. It's mainly used to define the class. Hash list class for pointer data

TFPHashList implements a fast hash class. The class is built for speed, therefore the key values can be shortstrings only, and the data can only be pointers.

if a base class for an own hash class is wanted, the class can be used. If a hash class for objects is needed instead of pointers, the class can be used.

Create a new instance of the hashlist Create creates a new instance of TFPHashList on the heap and sets the hash capacity to 1. Removes an instance of the hashlist from the heap

Destroy cleans up the memory structures maintained by the hashlist and removes the TFPHashList instance from the heap.

Destroy should not be called directly, it's better to use Free or FreeAndNil instead.

Add a new key/data pair to the list Add adds a new data pointer (Item) with key AName to the list. It returns the position of the item in the list. If not enough memory is available to hold the key and data, an exception may be raised. Position of the new item in the list Key name associated with data. Data pointer Clear the list Clear removes all items from the list. It does not free the data items themselves. It frees all memory needed to contain the items. None. Returns the key name of an item by index NameOfIndex returns the key name of the item at position Index. If Index is out of the valid range, an exception is raised. Key name of item Index Index of item for which to return name Return the hash valye of an item by index HashOfIndex returns the hash value of the item at position Index. If Index is out of the valid range, an exception is raised. Hash value of item Index Index of item for which to return hash value Delete an item from the list. Delete deletes the item at position Index. The data to which it points is not freed from memory. Index of item to remove from the list Raise an error Error raises an EListError exception, with message Msg. The Data pointer is used to format the message. Message string Data pointer Expand the list Expand enlarges the capacity of the list if the maximum capacity was reached. It returns itself. If not enough memory is available, an exception may be raised. Returns self Extract a pointer from the list

Extract removes the data item from the list, if it is in the list. It returns the pointer if it was removed from the list, Nil otherwise.

Extract does a linear search, and is not very efficient.

The removed pointer or nil. Pointer to be removed. Return the index of the data pointer

IndexOf returns the index of the first occurrence of pointer Item. If the item is not in the list, -1 is returned.

The performed search is linear, and not very efficient.

Index of Item in the list. Data pointer to search for. Find data associated with key Find searches (using the hash) for the data item associated with item AName and returns the data pointer associated with it. If the item is not found, Nil is returned. It uses the hash value of the key to perform the search. Data associated with AName or Nil if it does not exist. Key name to search for. Return index of named item. FindIndexOf returns the index of the key AName, or -1 if the key does not exist in the list. It uses the hash value to search for the key. Index of the key Key value to look for Find first element with given name and hash value FindWithHash searches for the item with key AName. It uses the provided hash value AHash to perform the search. If the item exists, the data pointer is returned, if not, the result is Nil. Data pointer associated with key AName Key value to search for. Hash value of the key AName Rename a key Rename renames key AOldname to ANewName. The hash value is recomputed and the item is moved in the list to it's new position. If an item with ANewName already exists, an exception will be raised. New position in the list Key to rename New name of key Remove first instance of a pointer Remove removes the first occurence of the data pointer Item in the list, if it is present. The return value is the removed data pointer, or Nil if no data pointer was removed. Data pointer which was removed Item to remove from the list. Remove nil pointers from the list Pack removes all Nil items from the list, and frees all unused memory. Return some statistics for the list.

ShowStatistics prints some information about the hash list to standard output. It prints the following values:

HashSize: Size of the hash table
HashMean: Mean hash value
HashStdDev: Standard deviation of hash values
ListSize: Size and capacity of the list
StringSize: Size and capacity of key strings

Call a procedure for each element in the list ForEachCall loops over the items in the list and calls proc2call, passing it the item and arg. Callback procedure Additional argument passed to proc2call Capacity of the list. Capacity returns the current capacity of the list. The capacity is expanded as more elements are added to the list. If a good estimate of the number of elements that will be added to the list, the property can be set to a sufficiently large value to avoid reallocation of memory each time the list needs to grow. Count Items Current number of elements in the list. Count is the current number of elements in the list. Capacity Items Indexed array with pointers Items provides indexed access to the pointers, the index runs from 0 to Count-1. Specifying an invalid index will result in an exception. Capacity Count 0-based index Low-level hash list List exposes the low-level item list. It should not be used directly. Strs Low-level memory area with strings. Strs exposes the raw memory area with the strings. List Hash-list aware object TFPHashObject is a TObject descendent which is aware of the class. It has a name property and an owning list: if the name is changed, it will reposition itself in the list which owns it. It offers methods to change the owning list: the object will correctly remove itself from the list which currently owns it, and insert itself in the new list. Create an instance not owned by any list. CreateNotOwned creates an instance of TFPHashObject which is not owned by any hash list. It also has no name when created in this way. Create a named instance, and insert in a hash list. Create creates an instance of TFPHashObject, gives it the name S and inserts it in the hash list HashObjectList. CreateNotOwned Hash list to which the object should be added. Name for the object Change the list owning the object. ChangeOwner can be used to move the object between hash lists: The object will be removed correctly from the hash list that currently owns it, and will be inserted in the list HashObjectList. If an object with the same name already is present in the new hash list, an exception will be raised. ChangeOwnerAndName Name Hash list in which to insert object. Simultaneously change the list owning the object and the name of the object. ChangeOwnerAndName can be used to move the object between hash lists: The object will be removed correctly from the hash list that currently owns it (using the current name), and will be inserted in the list HashObjectList with the new name S. If the new name already is present in the new hash list, an exception will be raised. ChangeOwner Name Hash list in which to insert object. New name with which to insert object. Rename the object Rename changes the name of the object, and notifies the hash list of this change. If the new name already is present in the hash list, an exception will be raised. ChangeOwner ChangeOwnerAndName Name New name for the object Current name of the object Name is the name of the object, it is stored in the hash list using this name as the key. Rename ChangeOwnerAndName Hash value Hash is the hash value of the object in the hash list that owns it. Name Create a new instance of the hashlist

Create creates a new instance of TFPHashObjectList on the heap and sets the hash capacity to 1.

If FreeObjects is True (the default), then the list owns the objects: when an object is removed from the list, it is destroyed (freed from memory). Clearing the list will free all objects in the list.

Does the list own the objects Does the list own the objects it contains

OwnsObjects determines what to do when an object is removed from the list: if it is True (the default), then the list owns the objects: when an object is removed from the list, it is destroyed (freed from memory). Clearing the list will free all objects in the list.

The value of OwnsObjects is set when the hash list is created, and cannot be changed during the lifetime of the hash list.

Removes an instance of the hashlist from the heap

Destroy cleans up the memory structures maintained by the hashlist and removes the TFPHashObjectList instance from the heap. If the list owns its objects, they are freed from memory as well.

Destroy should not be called directly, it's better to use Free or FreeAndNil instead.

Add a new key/data pair to the list Add adds a new object instance (AObject) with key AName to the list. It returns the position of the object in the list. If not enough memory is available to hold the key and data, an exception may be raised. If an object with this name already exists in the list, an exception is raised. Position of the new object in the list Key name associated with object instance. object instance Clear the list Clear removes all objects from the list. It does not free the objects themselves, unless OwnsObjects is True. It always frees all memory needed to contain the objects. None. Returns the key name of an object by index NameOfIndex returns the key name of the object at position Index. If Index is out of the valid range, an exception is raised. Key name of object at position Index Index of object for which to return name Return the hash valye of an object by index HashOfIndex returns the hash value of the object at position Index. If Index is out of the valid range, an exception is raised. Hash value of object at position Index Index of object for which to return hash value Delete an object from the list. Delete deletes the object at position Index. If OwnsObjects is True, then the object itself is also freed from memory. OwnsObjects Index of object to remove from the list Expand the list Expand enlarges the capacity of the list if the maximum capacity was reached. It returns itself. If not enough memory is available, an exception may be raised. Returns self Extract a object instance from the list

Extract removes the data object from the list, if it is in the list. It returns the object instance if it was removed from the list, Nil otherwise. The object is not freed from memory, regardless of the value of OwnsObjects.

Extract does a linear search, and is not very efficient.

The removed object instance or nil. Object instance to be removed. Return the index of the object instance

IndexOf returns the index of the first occurrence of object instance AObject. If the object is not in the list, -1 is returned.

The performed search is linear, and not very efficient.

Index of Item in the list. Data object instance to search for. Find data associated with key Find searches (using the hash) for the data object associated with key AName and returns the data object instance associated with it. If the object is not found, Nil is returned. It uses the hash value of the key to perform the search. Object associated with AName or Nil if it does not exist. Key name to search for. Return index of named object. FindIndexOf returns the index of the key AName, or -1 if the key does not exist in the list. It uses the hash value to search for the key. Index of the key Key value to look for Find first element with given name and hash value FindWithHash searches for the object with key AName. It uses the provided hash value AHash to perform the search. If the object exists, the data object instance is returned, if not, the result is Nil. Object instance associated with key AName Key value to search for. Hash value of the key AName Rename a key Rename renames key AOldname to ANewName. The hash value is recomputed and the object is moved in the list to it's new position. If an object with ANewName already exists, an exception will be raised. New position in the list Key to rename New name of key Remove first occurrence of a object instance

Remove removes the first occurence of the object instance Item in the list, if it is present. The return value is the location of the removed object instance, or -1 if no object instance was removed.

If OwnsObjects is True, then the object itself is also freed from memory.

Position of object instance which was removed Object instance to remove from the list. Remove nil object instances from the list Pack removes all Nil objects from the list, and frees all unused memory. Return some statistics for the list.

ShowStatistics prints some information about the hash list to standard output. It prints the following values:

HashSize: Size of the hash table
HashMean: Mean hash value
HashStdDev: Standard deviation of hash values
ListSize: Size and capacity of the list
StringSize: Size and capacity of key strings

Call a procedure for each object in the list ForEachCall loops over the objects in the list and calls proc2call, passing it the object and arg. Callback procedure Additional argument passed to proc2call Capacity of the list. Capacity returns the current capacity of the list. The capacity is expanded as more elements are added to the list. If a good estimate of the number of elements that will be added to the list, the property can be set to a sufficiently large value to avoid reallocation of memory each time the list needs to grow. Count Items Current number of elements in the list. Count is the current number of elements in the list. Capacity Items Indexed array with object instances Items provides indexed access to the object instances, the index runs from 0 to Count-1. Specifying an invalid index will result in an exception. Capacity Count 0-based index Low-level hash list List exposes the low-level hash list. It should not be used directly. Search an instance of a certain class FindInstanceOf searches the list for an instance of class AClass. It starts searching at position AStartAt. If AExact is True, only instances of class AClass are considered. If AExact is False, then descendent classes of AClass are also taken into account when searching. If no instance is found, Nil is returned. First instance of AClass after position AStartAt Class to search for. Should the class match exactly, or also consider descendents Position in list to start search. Class of THTCustomNodeClass. THTCustomNodeClass was used by to decide which class should be created for elements in the list. Data node for pointer hashtable

THTDataNode is used by to store the hash items in. It simply holds the data pointer.

It should not be necessary to use THTDataNode directly, it's only for inner use by TFPDataHashTable

" Data pointer Pointer containing the user data associated with the hash value. Alias for THTDataNode THTNode is provided for backwards compatibility. " Data iterator method. TDataIteratorMethod is a callback prototype for the method. It is called for each data pointer in the hash list, passing the key (key) and data pointer (item) for each item in the list. If Continue is set to false, the iteration stops. Data pointer item Key associated with item Continue iterating or stop iteration Hash table for data pointers TFPDataHashTable is a descendent which stores simple data pointers together with the keys. In case the data associated with the keys are objects, it's better to use , or for string data, is more suitable. The data pointers are exposed with their keys through the Items property. Items Add a data pointer to the list. Add adds a data pointer (AItem) to the list with key AKey. If AKey already exists in the table, an exception is raised. Key to insert in the hash table Data pointer associated with AKey. Key-based access to the items in the table Items provides access to the items in the hash table using their key: the array index Index is the key. A key which is not present will result in an Nil pointer. Key with which to retrieve data pointer. Node type for TFPStringHashTable

THTStringNode is a descendent which holds the data in the hash table. It exposes a data string.

It should not be necessary to use THTStringNode directly, it's only for inner use by TFPStringHashTable

String data Data is the data of this has node. The data is a string, associated with the key. It is also exposed in Iterator callback type TStringIteratorMethod is the callback prototype for the Iterate method. It is called for each element in the hash table, with the string. If Continue is set to false, the iteration stops. String associated with key Key value Should iterate continue or stop ? Hash table for string data. TFPStringHashTable is a descendent which stores simple strings together with the keys. In case the data associated with the keys are objects, it's better to use , or for arbitrary pointer data, is more suitable. The strings are exposed with their keys through the Items property. Items Add a new string to the hash list Add adds a new string AItem to the hash list with key AKey. If a string with key Akey already exists in the hash table, an exception will be raised. Key value associated with aItem String data Key based access to the strings in the hash table Items provides access to the strings in the hash table using their key: the array index Index is the key. A key which is not present will result in an empty string. Key to retrieve string with. Node type for TFPObjectHashTable

THTObjectNode is a descendent which holds the data in the hash table. It exposes a data string.

It should not be necessary to use THTObjectNode directly, it's only for inner use by TFPObjectHashTable

Object instance Data is the object instance associated with the key value. It is exposed in Node type for owned objects. THTOwnedObjectNode is used instead of in case owns it's objects. When this object is destroyed, the associated data object is also destroyed. Destroys the node and the object. Destroy first frees the data object, and then only frees itself. iterate callback prototype. TObjectIteratorMethod is the iterator callback prototype. It is used to iterate over all items in the hash table, and is called with each key value (Key) and associated object (Item). If Continue is set to false, the iteration stops. Data object Key value Should the iteration continue or stop Hash table for object instances TFPStringHashTable is a descendent which stores object instances together with the keys. In case the data associated with the keys are strings themselves, it's better to use , or for arbitrary pointer data, is more suitable. The objects are exposed with their keys through the Items property. Create a new instance of TFPObjectHashTable Create creates a new instance of TFPObjectHashTable on the heap. It sets the OwnsObjects property to AOwnsObjects, and then calls the inherited Create. If AOwnsObjects is set to True, then the hash table owns the objects: whenever an object is removed from the list, it is automatically freed. If not enough memory is available on the heap, an exception may be raised. Does the hash table own the objects stored in it? Create a new hash table with given size and hash function

CreateWith sets the OwnsObjects property to AOwnsObjects, and then calls the inherited CreateWith. If AOwnsObjects is set to True, then the hash table owns the objects: whenever an object is removed from the list, it is automatically freed.

This constructor should be used when a table size and hash algorithm should be specified that differ from the default table size and hash algorithm.

If not enough memory is available on the heap, an exception may be raised. Hash table size Hash function to use Does the hash table own the objects stored in it? Add a new object to the hash table Add adds the object AItem to the hash table, and associates it with key aKey. If the key aKey is already in the hash table, an exception will be raised. key Associated with object Object to store Key-based access to the objects Items provides access to the objects in the hash table using their key: the array index Index is the key. A key which is not present will result in an Nil instance. Key to return object for Does the hash table own the objects ? OwnsObjects determines what happens with objects which are removed from the hash table: if True, then removing an object from the hash list will free the object. If False, the object is not freed. Note that way in which the object is removed is not relevant: be it Delete, Remove or Clear. Get next collision number GetNextCollision returns the next collision in hash item Index. This is the count of items with the same hash.means that the next it Index of hash item Get next collision number Index of hash item Record used in bucket list. TBucketItem is a record used for internal use in . It should not be necessary to use it directly. Item to associate data with Data associated with item Array of TBucketItem records Bucket record TBucket describes 1 bucket in the class. It is a container for records. It should never be used directly. Number of items in the bucket Items in this bucket Pointer to TBucket" type. Array of TBucket records. Callback for the ForEach call.

TBucketProc is the prototype for the call. It is the plain procedural form. The Continue parameter can be set to False to indicate that the Foreach call should stop the iteration.

For a procedure of object (a method) callback, see the prototype.

Extra info pointer passed to Foreach call. Item Data associated with item Set to false to stop iteration over items. Callback for the ForEach call.

TBucketProcObject is the prototype for the call. It is the method (procedure of object) form. The Continue parameter can be set to False to indicate that the Foreach call should stop the iteration.

For a plain procedural callback, see the prototype.

Item Data associated with item Set to false to stop iteration over items. Custom bucket list class

TCustomBucketList is an associative list using buckets for storage. It scales better than a regular TList list class, escpecially when an item must be searched in the list.

Since the list associates a data pointer with each item pointer, it follows that each item pointer must be unique, and can be added to the list only once.

The TCustomBucketList class does not determine the number of buckets or the bucket hash mechanism, this must be done by descendent classes such as . TCustomBucketList only takes care of storage and retrieval of items in the various buckets.

Because TCustomBucketList is an abstract class - it does not determine the number of buckets - one should never instantiate an instance of TCustomBucketList, but always use a descendent class such as .

Frees the bucketlist from memory Detsroy frees all storage for the buckets from memory. The items themselves are not freed from memory. Clear the list Clear clears the list. The items and their data themselves are not disposed of, this must be done separately. Clear only removes all references to the items from the list. None. Add an item to the list Add adds AItem with it's associated AData to the list and returns AData. If AItem is already in the list, an ElistError exception will be raised. The result is always AData Item to add to the list. Must uniquely identify AData. Data to be associated with AItem Assign one bucket list to another Assign is implemented by TCustomBucketList to copy the contents of another bucket list to the bucket list. It clears the contents prior to the copy operation. Source list to copy items from Check if an item exists in the list.

Exists searches the list and returns True if the AItem is already present in the list. If the item is not yet in the list, False is returne5Ad.

If the data pointer associated with AItem is also needed, then it is better to use Find.

True if the item exists in the list, False if not. Item to search for Find an item in the list Find searches for AItem in the list and returns the data pointer associated with it in AData if the item was found. In that case the return value is True. If AItem is not found in the list, False is returned. True if the item is present in the list. Item to search for in the list On return, contains the data pointer associated with AItem. Loop over all items.

Foreach loops over all items in the list and calls AProc, passing it in turn each item in the list.

AProc exists in 2 variants: one which is a simple procedure, and one which is a method. In the case of the simple procedure, the AInfo argument is passed as well in each call to AProc.

The loop stops when all items have been processed, or when the AContinue argument of AProc contains False on return.

The result of the function is True if all items were processed, or False if the loop was interrupted with a AContinue return of False.

None. True if all items were processed, False if the loop was stopped. Callback handler to call for each item in the list. Extra info to pass to the procedural variant of the method. Remove an item from the list. Remove removes AItem from the list, and returns the associated data pointer of the removed item. If the item was not in the list, then Nil is returned. Find Data pointer associated with AItem Item to remove from the list. Associative array for data pointers Data provides direct access to the Data pointers associated with the AItem pointers. If AItem is not in the list of pointers, an EListError exception will be raised. Item to retrieve data pointer from Enumerated type to indicate bucket list size TBucketListSizes is used to set the bucket list size: It specified the number of buckets created by . List with 2 buckets List with 4 buckets List with 8 buckets List with 16 buckets List with 32 buckets List with 64 buckets List with 128 buckets List with 256 buckets Default bucket list implementation.

TBucketList is a descendent of TCustomBucketList which allows to specify a bucket count which is a multiple of 2, up to 256 buckets. The size is passed to the constructor and cannot be changed in the lifetime of the bucket list instance.

The buckets for an item is determined by looking at the last bits of the item pointer: For 2 buckets, the last bit is examined, for 4 buckets, the last 2 bits are taken and so on. The algorithm takes into account the average granularity (4) of heap pointers.

Create a new TBucketList instance. Create instantiates a new bucketlist instance with a number of buckets determined by ABuckets. After creation, the number of buckets can no longer be changed. If not enough memory is available to create the instance, an exception may be raised. Number of buckets to create Bucket list using objects instead of pointers. TObjectBucketList is a class that redefines the associative Data array using TObject instead of Pointer. It also adds some overloaded versions of the Add and Remove calls using TObject instead of Pointer for the argument and result types. Add an object to the list Add adds AItem to the list and associated AData with it. The result is always AData Item to add to the list Data associated with AItem Remove an object from the list Remove removes the object AItem from the list. It returns the Data object which was associated with the item. If AItem was not in the list, then Nil is returned. Data item associated with AItem Object to remove from the list Associative array of data items Data provides associative access to the data in the list: it returns the data object associated with the AItem object. If the AItem object is not in the list, an EListError exception is raised. Object item to retrieve associated data object from Iterate over the pointers in the hash table Iterate iterates over all elements in the array, calling aMethod for each pointer, or until the method returns False in its continue parameter. It returns Nil if all elements were processed, or the pointer that was being processed when aMethod returned False in the Continue parameter. Nil or the pointer that caused the iteration to abort. Method to call for each pointer in the hash table. Iterate over the strings in the hash table Iterate iterates over all elements in the array, calling aMethod for each string, or until the method returns False in its continue parameter. It returns an empty string if all elements were processed, or the string that was being processed when aMethod returned False in the Continue parameter. Empty or the string that caused the iterate to abort. Method to call for each string in the hash table. Iterate over the objects in the hash table Iterate iterates over all elements in the array, calling aMethod for each object, or until the method returns False in its continue parameter. It returns Nil if all elements were processed, or the object that was being processed when aMethod returned False in the Continue parameter. Nil or the object that caused the iteration to be aborted. Method to call for each object in the hash table.