Implements a map for unique IDs to arbitrary data.

maps.pp implements a map for unique IDs to arbitrary data. The ID-to-Data mapping is stored in an Average Level Binary Tree for fast indexing. The map also maintains a linked list between the ordered items for fast iteration through its elements. The ID can be signed or unsigned, with a size of 1, 2, 4, 8, 16 or 32 bytes. The data can be of any (constant) size.

Author: Marc Weustink

This file is part of the LazUtils package.

Identifies the data type used for map IDs.

TMapIdType is an enumeration type with values that identify the native data type used in map ID values. TMapIdType is used in TMapID and as an argument in the TBaseMap.Create method.

TMapID TBaseMap.Create
1 byte unsigned value (Byte).
1 byte signed value (ShortInt).
2 byte unsigned value (Word).
2 byte signed value (SmallInt).
4 byte unsigned value (LongWord).
4 byte signed value (LongInt).
8 byte unsigned value (QWord).
8 byte signed value (Int64).
16 byte unsigned value (Low and High QWords).
16 byte signed value (Low QWord and High Int64).
32 byte unsigned value (4 QWord values).
32 byte signed value (3 QWord values and Int64).
Constant that indicates the size of a signed Pointer in the map.

itsPtrSize is a constant TMapIdType data type that indicates the size used for a signed Pointer in the map. The definition is CPU-specific. For a 64-bit CPU, it is defined as its8 in TMapIdType (or Int64). For all other CPUs, it is defines as its4 in TMapIdType (or LongInt).

Use ituPtrSize to get the length of an unsigned Pointer in the map.

Not used in the current implementation.
Constant that indicates the size of an unsigned Pointer in the map.

ituPtrSize is a constant TMapIdType data type that indicates the size used for an unsigned Pointer in the map. The definition is CPU-specific. For a 64-bit CPU, it is defined as itu8 in TMapIdType (or QWord). For all other CPUs, it is defines as itu4 in TMapIdType (or LongWord).

Use itsPtrSize to get the length of a signed Pointer in the map.

Not used in the current implementation.
Pointer to a TMapItem data type.

PMapItem is a Pointer to a TMapItem data type. PMapItem is the type used to represent the first, last, previous, and next items in a linked list. PMapItem is used in TMapLink and TBaseMap.

TMapItem TMapLink TBaseMap
Pointer to a TMapLink data type.

PMapLink is a Pointer to a TMapLink data type.

Not used in the current implementation.
Record type used to build the linked list for items in the map.

TMapLink is a record type with members that contain Pointers to the Previous and Next items in the linked list for the map. TMapLink is used to implement TMapItem.

Pointer to the previous item in the linked list for a map.

Previous is a PMapItem type that contains a pointer to the previous item in the linked list for a map. Values in Previous and Next are used when TBaseMap adds an item to the map, and when TMapIterator acts upon items in the linked list.

Pointer to the Next item in the linked list for a map.

Next is a PMapItem type that contains a pointer to the Next item in the linked list for a map. Values in Previous and Next are used when TBaseMap adds an item to the map, and when TMapIterator acts upon items in the linked list.

Pointer to a TMapID type.

PMapID is a Pointer to a TMapID type.

Represents an ID in a map association.

TMapID is a record type used to provide access to the byte values in the ID for a map association. Members are provided in TMapID to represent each byte in the signed or unsigned value used in the ID.

Values in the TMapIdType enumeration indicate which members in the variable structure are needed for the ID value. In other words, assigning an unsigned Byte value to the ID yields access to the U1 member. Assigning a signed ShortInt value to ID, yields access to the S1 member. Et. al.

The implementation for 16- and 32-byte ID values is platform- or OS-specific, and takes into account the Endian byte order for the values.

TMapID is the type used for the ID member in TMapItem.

Unsigned Byte value for the ID (1 Byte).
Signed ShortInt value for the ID (1 Byte) .
Unsigned Word value for the ID (2 Bytes).
Signed SmallInt value for the ID (2 Bytes).
Unsigned LongWord value for the ID (4 Bytes).
Signed LongInt value for the ID (4 Bytes).
Unsigned QWord value for the ID (8 Bytes).
Signed Int64 value for the ID (8 Bytes).
Unsigned QWords (Low and High) (16 Bytes) (with Endian byte order).
.
.
Signed QWord (Low) and Int64 (High) (16 Bytes) (with Endian byte order).
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
Signed QWords (LL, LH, HL) and signed Int64 (HH) (with Endian byte order).
Signed QWords (LL, LH, HL) and signed Int64 (HH) (with Endian byte order).
Signed QWords (LL, LH, HL) and signed Int64 (HH) (with Endian byte order).
Signed QWords (LL, LH, HL) and signed Int64 (HH) (with Endian byte order).
Represents the ID and order of items in the linked list for the map.

TMapItem is a packed record type with members that represent the ID in the map, and navigation for the linked list of items. Data for the map item is written immediately following the packed record structure

Provides navigation to the previous and next map items in the linked list.

Link is a TMapLink type which provides navigation to the previous and next map items in the linked list. Link contains Pointers to TMapItem instances that represent the order of access for items in the linked list.

Represents the ID for the map item.

ID is a TMapID type that represents the ID for the map item. ID provides members which allow access to the byte values in the unique identifier.

Exception raised when a modification is made to a locked Map.
Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited constructor using the exception message text: 'Map modification not allowed'.

Implements the base class for a map for unique IDs to arbitrary data.

Implements the base class that is a map for unique IDs to arbitrary data. The ID-to-Data mapping is stored in an Average Level Binary Tree for fast indexing. The map also maintains a linked list between the ordered items for fast iteration through its elements. The ID can be signed or unsigned, with a size of 1, 2, 4, 8, 16 or 32 bytes. The data can be of any (constant) size.

Use a descendant class, such as TMap, which includes methods to Add items and to read or write their arbitrary data values.

Author: Marc Weustink

TPersistent
Finds a node in the AVL Tree with the specified ID.
AVL Tree node with the specified item.
ID to locate in the AVL Tree.
Finds the data for the item with the specified ID.
Data stored in the AVL Tree for the specified ID.
ID to locate in the AVL Tree.
Frees the data for the specified AVL Tree node.
AVL Tree node to locate in the map.
Gets the relative order for the specified map items using their binary ID values.
-1, 0, or 1 as the relative order for the map items.
AVL Tree for the operation.
Map item to compare.
Map item to compare.
Adds the map iterator to the internal list.
Map iterator to add to the list.
Removes the map iterator from the internal list.
Map iterator to remove from the list.
Locks the Map when an iterator is added.

Calls InterLockedIncrement to increase the value in the internal member used to track the locking state.

Unlocks the Map when an iterator is removed.

Calls InterLockedDecrement to decrease the value in the internal member used to track the locking state.

Adds a map item with the specified ID and Data to the AVL Tree.

InternalAdd is a procedure used to add a map item with the specified ID and Data to the AVL Tree. InternalAdd raises an EListError exception if AId already exists in the internal AVL Tree, and no actions are performed in the method.

InternalAdd allocates and populates memory used for the TMapItem and its arbitrary data, and adds the new item to the internal AVL Tree. InternalAdd updates the pointers to the previous and next map items in the linked list.

Do not call InternalAdd directly. Use a descendant class, such as TMap, which implements the Add method.

Raises an EListError exception when a duplicate ID is found in the AVL Tree. Raised with the message in DUPLICATE_ID.

ID for the new map item.
Data for the new map item.
Gets the data stored in the specified map item.

InternalGetData is a Boolean function used to get the data stored in the specified map item. AItem is the map item examined in the method, and must contain a valid pointer. The return value is set to False, and no actions are performed in the method, when AItem contains Nil. The return value is True when a pointer has been assigned to AItem.

InternalGetData skips the ID value in AItem, and stores the Data for the map item in AData. The size arguments passed in the constructor are used when reading the ID and Data values. Please note that no validation is performed for the arbitrary byte values read into AData.

Do not call InternalGetData directly. Use the public methods in the class, or a descendant class like TMap which implements the GetData method.

TMap.GetData
True when the specified map item is a valid pointer.
Map item to examine n the method.
Data stored in the specified map item.
Gets a Pointer to the data for the specified map item.

InternalGetDataPtr is a function used to get a Pointer to the data for the specified map item. AItem is a Pointer to the map item examined in the method. The return value is set to Nil when AItem has not been assigned, and no actions are performed in the method.

InternalGetDataPtr sets the Pointer in the return value to the position in AItem immediately after the ID value. InternalGetDataPtr is used in the implementation of methods like Delete and FreeData.

Do not call InternalGetDataPtr directly. Use one of the public methods in the class, or a descendant class like TMap which implements the GetDataPtr method.

TMap.GetDataPtr
Pointer to the data for the specified map item.
Map item examined in the method.
Get the ID value for the specified map item.

InternalGetId is a Boolean function used to get the ID value for the specified map item. AItem is a Pointer to the map item examined in the method. The return value is False if AItem has not been assigned (contains Nil), and no actions are performed in the method.

InternalGetId stores the ID value from AItem in the AID parameter. The number of bytes used for the ID is specified using a TMapIdType value in the constructor for the class.

InternalGetID is used primarily in the implementation of TBaseMapIterator and descendant classes.

False if the specified map item is not a valid Pointer.
Map item examined in the method.
Value for the ID in the specified map item.
Stores the data for the specified map item.
Frees resources allocated for the data in the map item.
Constructor for the class instance.
Clears all map items in the AVL Tree.
Gets the number of map items in the AVL Tree.
Deletes the specified map item from the AVL Tree.
Destructor for the class instance.
Specifies the interface used for map item iterators.
Called when the map is destroyed.
Called when the map is cleared.
Called when an Item is removed from the map.
Pointer to the AVL Tree node for the item.
Adds the class instance to the associated Map for the iterator.
Removes the class instance from the associated Map for the iterator.
Initializes the iterator for specified the map.

InternalCreate is a procedure used to initialize the iterator for specified the map. InternalCreate calls the inherited Create method to create the class instance, and sets values needed for internal members in the class. The following properties are updated in the iterator:

Current
  Set to the first map item in the linked list
BOM
  Set to True when Current is Nil
EOM
  Set to True when Current is Nil

InternalCreate is called from the Create method for the class instance.

Map for the iterator class instance.
True when a matching map item is found.

InternalLocate is a Boolean function used to locate the specified map item in the AVL Tree for the map. AID contains a pointer to the map item and its ID and Data values. The return value is True when a matching map item is found.

InternalLocate calls ValidateMap to ensure that the map is still valid for the iterator. An EInvalidOperation is raised in ValidateMap if the structure is not assigned (contains Nil).

InternalLocate compares the map item in AId to the nodes in the AVL Tree for the map. The internal Invalid flag is set to True if a map item in the linked list has been removed, or when the map has been freed. The values in the following properties are updated to reflect the position and state for the iterator:

BOM
  True when the item in Current is Nil
EOM
  True when the item in Current is Nil
Current
  Node in the AVL Tree where the item is stored, or the value from Last when the item is not found

Do not call InternalLocate directly. It is called from descendant classes which implement the Locate method.

True when the map item exists in the map.
Map item to locate in the method.
Validates the AVL Tree and the Current item in the iterator.

Validate is a procedure used to validate the nodes in the AVL tree for the map, and the Current item for the iterator. Validate calls ValidateMap to check the nodes in the AVL Tree. It updates the values in Current and Invalid as the nodes are processed. Validate raises an EInvalidOperation exception if the value in Current is Nil, or the Invalid flag is set.

EInvalidOperation
  Raised when Current is unassigned with the message 'No current item'.
EInvalidOperation
  Raised when the Invalid flag is set with the message 'Current item removed'.

Ensures that the map for the iterator is still valid.

ValidateMap is a procedure used to ensure that the map class for the iterator is still valid. An EInvalidOperation exception is raised if the class instance is unassigned (contains Nil).

EInvalidOperation is raised if the map class instance is unassigned (contains Nil). Raised with the message 'Map destroyed'.

Current map item for the iterator.

Current is a read-only PMapItem property that contains a Pointer to the current map item for the iterator. The value in Current is updated in navigation methods for the iterator, such as: First, Next, Previous, Last, and Locate. The value in Current may also be updated in methods like Validate and ValidateMap.

Destructor for the class instance.
Moves to the first item in the linked list.
Moves to the next item in the linked list.
Moves to the previous item in the linked list.
Moves to the last item in the linked list.
Indicates if the map for the iterator has been freed.

Valid is a Boolean function used to determine if the map for the iterator is still valid. The return value is False when the map class instance has been freed (contains Nil).

False when the map for the iterator has been freed.
True when the iterator is at the beginning of the linked list for the map.

BOM is a read-only Boolean property that indicates if the iterator is at the beginning of the linked list for the map, or the value in Current is Nil. The value in BOM is updated when navigation methods for the iterator are used, such as: First, Next, Previous, Last, and Locate.

True when the iterator is at the end of the linked list for the map.
Implements a map for unique IDs to arbitrary data.

Implements a map for unique IDs to arbitrary data. The ID-to-Data mapping is stored in an Average Level Binary Tree for fast indexing. The map also maintains a linked list between the ordered items for fast iteration through its elements. The ID can be signed or unsigned, with a size of 1, 2, 4, 8, 16 or 32 bytes. The data can be of any (constant) size.

TMap extends the ancestor class to include public methods which Add map items, and read or write their arbitrary data values.

Author: Marc Weustink

Adds a map item with the specified ID and Data values.
Map item to add in the method.
Data for the map item to add in the method.
Checks for the specified ID is in the AVL Tree for the map.

HasId is a Boolean function used to locate the specified map item in the AVL Tree for the map. HasId calls the FindNode method to located the value in AId. The return value is True when FindNode returns a value other than Nil.

True when the AVL Tree contains a node for the specified map item.
Map item to locate in the AVL Tree.
Gets the Data for the map item with the specified ID.
Gets a Pointer to the data for the specified map item.
Stores the data for the specified map item.
Implements an iterator for items in a map.

TMapIterator is a TBaseMapIterator descendant that implements an iterator for items in a map. TMapIterator provides methods to initialize the iterator for a map. It also provides methods to read the IDs for map items, and to read and write the Data in map items. TMapIterator also provides an implementation of the Locate method.

Constructor for the class instance.
Map with IDs and Data for the iterator.
Gets the Pointer to the Data in a map item.
Gets the Data for a map item.
Data for the map item.
Gets the ID for a map item.
Locates a map item with the specified ID.
Sets the Data for a map item.
Implements a map iterator with thread-safe locking in the associated map.

TLockedMapIterator is a TMapIterator descendant which allows iteration of a map in multiple threads. The associated map will be locked prior to adding or removing entries.

Implements a map with support for reference counted Type Information in the Data.

TTypedMap is a TBaseMap map descendant that implements a map with support for reference counted Type Information in the Data for map items.

Constructor for the class instance.
Destructor for the class instance.
Gets the Data for the specified map item.
Gets a Pointer to the Data for the specified map item.
Stores the Data for the specified map item.
Implements an iterator for items in a map.

TTypedMapIterator is a TMapIterator descendant that implements an iterator for map items with reference counted Type Information in their Data. TTypedMapIterator provides methods to initialize the iterator for a map. It also provides methods to read the IDs for map items, and to read and write the Data in map items. TTypedMapIterator also provides an implementation of the Locate method.

Constructor for the class instance.
Gets the Data for the map item.
Gets the ID for the map item.
Locates a map item with the specified ID.
Stores the Data for the map item.
Gets information about the AVL Tree in the specified map.

MapReport is a String function used to get information about the AVL Tree in the specified map. The return value contains information about the order of nodes in the AVL Tree, and the pointers used in the structure. It is intended for use as a diagnostic tool.

String with the multi-line information about the AVL Tree.
Map class to examine in the routine.