lazarus/docs/xml/lazutils/maps.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
Maps
====================================================================
-->
<module name="Maps">
<short>Implements a map for unique IDs to arbitrary data.</short>
<descr>
<p>
<file>maps.pp</file> 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.
</p>
<p>
Author: Marc Weustink
</p>
<p>
<file>maps.pp</file> is part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved externals references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="Math"/>
<element name="typinfo"/>
<element name="Laz_AVL_Tree"/>
<element name="FPCAdds"/>

<element name="TMapIdType">
<short>Identifies the data type used for map IDs.</short>
<descr>
<p>
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.
</p>
</descr>
<seealso>
<link id="TMapID">TMapID</link>
<link id="TBaseMap.Create">TBaseMap.Create</link>
</seealso>
</element>
<element name="TMapIdType.itu1">
<short>1 byte unsigned value (Byte).</short>
</element>
<element name="TMapIdType.its1">
<short>1 byte signed value (ShortInt).</short>
</element>
<element name="TMapIdType.itu2">
<short>2 byte unsigned value (Word).</short>
</element>
<element name="TMapIdType.its2">
<short>2 byte signed value (SmallInt).</short>
</element>
<element name="TMapIdType.itu4">
<short>4 byte unsigned value (LongWord).</short>
</element>
<element name="TMapIdType.its4">
<short>4 byte signed value (LongInt).</short>
</element>
<element name="TMapIdType.itu8">
<short>8 byte unsigned value (QWord).</short>
</element>
<element name="TMapIdType.its8">
<short>8 byte signed value (Int64).</short>
</element>
<element name="TMapIdType.itu16">
<short>16 byte unsigned value (Low and High QWords).</short>
</element>
<element name="TMapIdType.its16">
<short>16 byte signed value (Low QWord and High Int64).</short>
</element>
<element name="TMapIdType.itu32">
<short>32 byte unsigned value (4 QWord values).</short>
</element>
<element name="TMapIdType.its32">
<short>32 byte signed value (3 QWord values and Int64).</short>
</element>

<element name="itsPtrSize">
<short>
Constant that indicates the size of a signed Pointer in the map.
</short>
<descr>
<p>
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).
</p>
<p>
Use ituPtrSize to get the length of an unsigned Pointer in the map.
</p>
<remark>
Not used in the current implementation.
</remark>
</descr>
</element>

<element name="ituPtrSize">
<short>
Constant that indicates the size of an unsigned Pointer in the map.
</short>
<descr>
<p>
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).
</p>
<p>
Use itsPtrSize to get the length of a signed Pointer in the map.
</p>
<remark>
Not used in the current implementation.
</remark>
</descr>
</element>

<element name="PMapItem">
<short>Pointer to a TMapItem data type.</short>
<descr>
<p>
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.
</p>
</descr>
<seealso>
<link id="TMapItem">TMapItem</link>
<link id="TMapLink">TMapLink</link>
<link id="TBaseMap">TBaseMap</link>
</seealso>
</element>

<element name="PMapLink">
<short>Pointer to a TMapLink data type.</short>
<descr>
<p>
PMapLink is a Pointer to a TMapLink data type.
</p>
<remark>
Not used in the current implementation.
</remark>
</descr>
</element>

<element name="TMapLink">
<short>Record type used to build the linked list for items in the map.</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="TMapLink.Previous">
<short>Pointer to the previous item in the linked list for a map.</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="TMapLink.Next">
<short>Pointer to the Next item in the linked list for a map.</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="PMapID">
<short>Pointer to a TMapID type.</short>
<descr>
<p>
PMapID is a Pointer to a TMapID type.
</p>
</descr>
</element>

<element name="TMapID">
<short>Represents an ID in a map association.</short>
<descr>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
TMapID is the type used for the ID member in TMapItem.
</p>
</descr>
</element>
<element name="TMapID.U1">
<short>
Unsigned Byte value for the ID (1 Byte).
</short>
</element>
<element name="TMapID.S1">
Signed ShortInt value for the ID (1 Byte)
<short>.
</short>
</element>
<element name="TMapID.U2">
<short>
Unsigned Word value for the ID (2 Bytes).
</short>
</element>
<element name="TMapID.S2">
<short>
Signed SmallInt value for the ID (2 Bytes).
</short>
</element>
<element name="TMapID.U4">
<short>
Unsigned LongWord value for the ID (4 Bytes).
</short>
</element>
<element name="TMapID.S4">
<short>
Signed LongInt value for the ID (4 Bytes).
</short>
</element>
<element name="TMapID.U8">
<short>
Unsigned QWord value for the ID (8 Bytes).
</short>
</element>
<element name="TMapID.S8">
<short>
Signed Int64 value for the ID (8 Bytes).
</short>
</element>
<element name="TMapID.U16H">
<short>
Unsigned QWords (Low and High) (16 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.U16L">
<short>.
</short>
</element>
<element name="TMapID.S16H">
<short>.
</short>
</element>
<element name="TMapID.S16L">
<short>
Signed QWord (Low) and Int64 (High) (16 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.U32HH">
<short>
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.U32HL">
<short>
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.U32LH">
<short>
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.U32LL">
<short>
Unsigned QWords (LL, LH, HL, HH) (32 Bytes) (with Endian byte order).
</short>
</element>
<element name="TMapID.S32HH">
<short>
Signed QWords (LL, LH, HL)  and signed Int64 (HH) (with Endian byte order).
</short>
</element>
<element name="TMapID.S32HL">
<short>
Signed QWords (LL, LH, HL)  and signed Int64 (HH) (with Endian byte order).
</short>
</element>
<element name="TMapID.S32LH">
<short>
Signed QWords (LL, LH, HL)  and signed Int64 (HH) (with Endian byte order).
</short>
</element>
<element name="TMapID.S32LL">
<short>
Signed QWords (LL, LH, HL)  and signed Int64 (HH) (with Endian byte order).
</short>
</element>

<element name="TMapItem">
<short>
Represents the ID and order of items in the linked list for the map.
</short>
<descr>
<p>
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
</p>
</descr>
</element>

<element name="TMapItem.Link">
<short>
Provides navigation to the previous and next map items in the linked list.
</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="TMapItem.ID">
<short>
Represents the ID for the map item.
</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="TLockedMapModifyException">
<short>Exception raised when a modification is made to a locked Map.</short>
<descr/>
<seealso>
<link id="TBaseMap"/>
</seealso>
</element>

<element name="TLockedMapModifyException.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance, and calls the 
inherited constructor using the exception message text: 'Map modification not 
allowed'.
</p>
</descr>
<seealso>
<link id="TBaseMap.Clear"/>
<link id="TBaseMap.Delete"/>
<link id="TBaseMap.Destroy"/>
<link id="TBaseMap.InternalAdd"/>
</seealso>
</element>

<element name="TBaseMap">
<short>
Implements the base class for a map for unique IDs to arbitrary data.
</short>
<descr>
<p>
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.
</p>
<p>
Use a descendant class, such as TMap, which includes methods to Add items and 
to read or write their arbitrary data values.
</p>
<p>
Author: Marc Weustink
</p>
</descr>
<seealso>
<link id="#rtl.classes.TPersistent">TPersistent</link>
</seealso>
</element>

<element name="TBaseMap.FTree"/>
<element name="TBaseMap.FIdType"/>
<element name="TBaseMap.FDataSize"/>
<element name="TBaseMap.FFirst"/>
<element name="TBaseMap.FLast"/>
<element name="TBaseMap.FIterators"/>
<element name="TBaseMap.FLocked"/>

<element name="TBaseMap.FindNode">
<short>Finds a node in the AVL Tree with the specified ID.</short>
</element>
<element name="TBaseMap.FindNode.Result">
<short>AVL Tree node with the specified item.</short>
</element>
<element name="TBaseMap.FindNode.AId">
<short>ID to locate in the AVL Tree.</short>
</element>

<element name="TBaseMap.FindItem">
<short>Finds the data for the item with the specified ID.</short>
</element>
<element name="TBaseMap.FindItem.Result">
<short>Data stored in the AVL Tree for the specified ID.</short>
</element>
<element name="TBaseMap.FindItem.AId">
<short>ID to locate in the AVL Tree.</short>
</element>

<element name="TBaseMap.FreeData">
<short>Frees the data for the specified AVL Tree node.</short>
</element>
<element name="TBaseMap.FreeData.ANode">
<short>AVL Tree node to locate in the map.</short>
</element>

<element name="TBaseMap.TreeCompareID">
<short>
Gets the relative order for the specified map items using their binary ID 
values.
</short>
</element>
<element name="TBaseMap.TreeCompareID.Result">
<short>-1, 0, or 1 as the relative order for the map items.</short>
</element>
<element name="TBaseMap.TreeCompareID.Sender">
<short>AVL Tree for the operation.</short>
</element>
<element name="TBaseMap.TreeCompareID.AItem1">
<short>Map item to compare.</short>
</element>
<element name="TBaseMap.TreeCompareID.AItem2">
<short>Map item to compare.</short>
</element>

<element name="TBaseMap.IteratorAdd">
<short>Adds the map iterator to the internal list.</short>
</element>
<element name="TBaseMap.IteratorAdd.AIterator">
<short>Map iterator to add to the list.</short>
</element>

<element name="TBaseMap.IteratorRemove">
<short>Removes the map iterator from the internal list.</short>
</element>
<element name="TBaseMap.IteratorRemove.AIterator">
<short>Map iterator to remove from the list.</short>
</element>

<element name="TBaseMap.LockMap">
<short>Locks the Map when an iterator is added.</short>
<descr>
<p>
Calls <var>InterLockedIncrement</var> to increase the value in the internal 
member used to track the locking state.
</p>
</descr>
<seealso>
<link id="TLockedMapIterator.AddToMap"/>
</seealso>
</element>

<element name="TBaseMap.UnLockMap">
<short>Unlocks the Map when an iterator is removed.</short>
<descr>
<p>
Calls <var>InterLockedDecrement</var> to decrease the value in the internal 
member used to track the locking state.
</p>
</descr>
<seealso>
<link id="TLockedMapIterator.RemoveFromMap"/>
</seealso>
</element>

<element name="TBaseMap.InternalAdd">
<short>
Adds a map item with the specified ID and Data to the AVL Tree.
</short>
<descr>
<p>
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.
</p>
<p>
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.
</p>
<p>
Do not call InternalAdd directly. Use a descendant class, such as TMap, which 
implements the Add method.
</p>
</descr>
<errors>
<p>
Raises an EListError exception when a duplicate ID is found in the AVL Tree. 
Raised with the message in DUPLICATE_ID.
</p>
</errors>
</element>
<element name="TBaseMap.InternalAdd.AId">
<short>ID for the new map item.</short>
</element>
<element name="TBaseMap.InternalAdd.AData">
<short>Data for the new map item.</short>
</element>

<element name="TBaseMap.InternalGetData">
<short>
Gets the data stored in the specified map item.
</short>
<descr>
<p>
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 <var>Nil</var>. The return value 
is <b>True</b> when a pointer has been assigned to AItem.
</p>
<p>
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.
</p>
<p>
Do not call InternalGetData directly. Use the public methods in the class, or 
a descendant class like TMap which implements the GetData method.
</p>
</descr>
<seealso>
<link id="#lazutils.maps.TMap.GetData">TMap.GetData</link>
</seealso>
</element>
<element name="TBaseMap.InternalGetData.Result">
<short><b>True</b> when the specified map item is a valid pointer.</short>
</element>
<element name="TBaseMap.InternalGetData.AItem">
<short>Map item to examine n the method.</short>
</element>
<element name="TBaseMap.InternalGetData.AData">
<short>Data stored in the specified map item.</short>
</element>

<element name="TBaseMap.InternalGetDataPtr">
<short>
Gets a Pointer to the data for the specified map item.
</short>
<descr>
<p>
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 <var>Nil</var> when AItem has not been 
assigned, and no actions are performed in the method.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TBaseMap.Delete"/>
<link id="#lazutils.maps.TMap.GetDataPtr">TMap.GetDataPtr</link>
</seealso>
</element>
<element name="TBaseMap.InternalGetDataPtr.Result">
<short>Pointer to the data for the specified map item.</short>
</element>
<element name="TBaseMap.InternalGetDataPtr.AItem">
<short>Map item examined in the method.</short>
</element>

<element name="TBaseMap.InternalGetId">
<short>
Get the ID value for the specified map item.
</short>
<descr>
<p>
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 <b>False</b> if AItem has not been assigned 
(contains <var>Nil</var>), and no actions are performed in the method.
</p>
<p>
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.
</p>
<p>
InternalGetID is used primarily in the implementation of TBaseMapIterator and 
descendant classes.
</p>
</descr>
</element>
<element name="TBaseMap.InternalGetId.Result">
<short><b>False</b> if the specified map item is not a valid Pointer.</short>
</element>
<element name="TBaseMap.InternalGetId.AItem">
<short>Map item examined in the method.</short>
</element>
<element name="TBaseMap.InternalGetId.AID">
<short>Value for the ID in the specified map item.</short>
</element>

<element name="TBaseMap.InternalSetData">
<short>Stores the data for the specified map item.</short>
<descr/>
</element>
<element name="TBaseMap.InternalSetData.Result">
<short/>
</element>
<element name="TBaseMap.InternalSetData.AItem">
<short/>
</element>
<element name="TBaseMap.InternalSetData.AData">
<short/>
</element>

<element name="TBaseMap.ReleaseData">
<short>Frees resources allocated for the data in the map item.</short>
<descr/>
</element>
<element name="TBaseMap.ReleaseData.ADataPtr">
<short/>
</element>

<element name="TBaseMap.Create">
<short>Constructor for the class instance.</short>
<descr/>
</element>
<element name="TBaseMap.Create.AIdType">
<short/>
</element>
<element name="TBaseMap.Create.ADataSize">
<short/>
</element>

<element name="TBaseMap.Clear">
<short>Clears all map items in the AVL Tree.</short>
<descr/>
</element>

<element name="TBaseMap.Count">
<short>Gets the number of map items in the AVL Tree.</short>
<descr/>
</element>
<element name="TBaseMap.Count.Result">
<short/>
</element>

<element name="TBaseMap.Delete">
<short>Deletes the specified map item from the AVL Tree.</short>
<descr/>
</element>
<element name="TBaseMap.Delete.Result">
<short/>
</element>
<element name="TBaseMap.Delete.AId">
<short/>
</element>

<element name="TBaseMap.Destroy">
<short>Destructor for the class instance.</short>
<descr/>
</element>

<element name="TBaseMapIterator">
<short>Specifies the interface used for map item iterators.</short>
<descr/>
</element>

<element name="TBaseMapIterator.FMap"/>
<element name="TBaseMapIterator.FCurrent"/>
<element name="TBaseMapIterator.FInValid"/>
<element name="TBaseMapIterator.FBOM"/>
<element name="TBaseMapIterator.FEOM"/>

<element name="TBaseMapIterator.MapDestroyed">
<short>Called when the map is destroyed.</short>
</element>

<element name="TBaseMapIterator.MapCleared">
<short>Called when the map is cleared.</short>
</element>

<element name="TBaseMapIterator.ItemRemove">
<short>Called when an Item is removed from the map.</short>
</element>
<element name="TBaseMapIterator.ItemRemove.AData">
<short>Pointer to the AVL Tree node for the item.</short>
</element>

<element name="TBaseMapIterator.AddToMap">
<short>Adds the class instance to the associated Map for the iterator.</short>
<descr/>
<seealso/>
</element>

<element name="TBaseMapIterator.RemoveFromMap">
<short>
Removes the class instance from the associated Map for the iterator.
</short>
<descr/>
<seealso/>
</element>

<element name="TBaseMapIterator.InternalCreate">
<short>
Initializes the iterator for specified the map.
</short>
<descr>
<p>
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:
</p>
<dl>
<dt>Current</dt>
<dd>Set to the first map item in the linked list</dd>
<dt>BOM</dt>
<dd>Set to <b>True</b> when Current is <var>Nil</var></dd>
<dt>EOM</dt>
<dd>Set to <b>True</b> when Current is <var>Nil</var></dd>
</dl>
<p>
InternalCreate is called from the Create method for the class instance.
</p>
</descr>
</element>
<element name="TBaseMapIterator.InternalCreate.AMap">
<short>Map for the iterator class instance.</short>
</element>

<element name="TBaseMapIterator.InternalLocate">
<short>
<b>True</b> when a matching map item is found.
</short>
<descr>
<p>
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 <b>True</b> when a matching map item is 
found.
</p>
<p>
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 <var>Nil</var>).
</p>
<p>
InternalLocate compares the map item in AId to the nodes in the AVL Tree for 
the map. The internal Invalid flag is set to <b>True</b> 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:
</p>
<dl>
<dt>BOM</dt>
<dd><b>True</b> when the item in Current is <var>Nil</var></dd>
<dt>EOM</dt>
<dd><b>True</b> when the item in Current is <var>Nil</var></dd>
<dt>Current</dt>
<dd>
Node in the AVL Tree where the item is stored, or the value from Last when 
the item is not found
</dd>
</dl>
<p>
Do not call InternalLocate directly. It is called from descendant classes 
which implement the Locate method.
</p>
</descr>
</element>
<element name="TBaseMapIterator.InternalLocate.Result">
<short><b>True</b> when the map item exists in the map.</short>
</element>
<element name="TBaseMapIterator.InternalLocate.AId">
<short>Map item to locate in the method.</short>
</element>

<element name="TBaseMapIterator.Validate">
<short>
Validates the AVL Tree and the Current item in the iterator.
</short>
<descr>
<p>
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 <var>Nil</var>, or the Invalid flag is set.
</p>
</descr>
<errors>
<dl>
<dt>EInvalidOperation</dt>
<dd>
Raised when Current is unassigned with the message 'No current item'.
</dd>
<dt>EInvalidOperation</dt>
<dd>
Raised when the Invalid flag is set with the message  'Current item removed'.
</dd>
</dl>
</errors>
</element>

<element name="TBaseMapIterator.ValidateMap">
<short>
Ensures that the map for the iterator is still valid.
</short>
<descr>
<p>
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 <var>Nil</var>).
</p>
</descr>
<errors>
<p>
EInvalidOperation is raised if the map class instance is unassigned (contains 
<var>Nil</var>). Raised with the message 'Map destroyed'.
</p>
</errors>
</element>

<element name="TBaseMapIterator.Current">
<short>
Current map item for the iterator.
</short>
<descr>
<p>
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.
</p>
</descr>
</element>

<element name="TBaseMapIterator.Destroy">
<short>Destructor for the class instance.</short>
<descr/>
</element>

<element name="TBaseMapIterator.First">
<short>Moves to the first item in the linked list.</short>
<descr/>
</element>

<element name="TBaseMapIterator.Next">
<short>Moves to the next item in the linked list.</short>
<descr/>
</element>

<element name="TBaseMapIterator.Previous">
<short>Moves to the previous item in the linked list.</short>
<descr/>
</element>

<element name="TBaseMapIterator.Last">
<short>Moves to the last item in the linked list.</short>
<descr/>
</element>

<element name="TBaseMapIterator.Valid">
<short>Indicates if the map for the iterator has been freed.</short>
<descr>
<p>
Valid is a Boolean function used to determine if the map for the iterator is 
still valid. The return value is <b>False</b> when the map class instance has 
been freed (contains <var>Nil</var>).
</p>
</descr>
</element>
<!-- function result Visibility: public -->
<element name="TBaseMapIterator.Valid.Result">
<short><b>False</b> when the map for the iterator has been freed.</short>
</element>

<element name="TBaseMapIterator.BOM">
<short>
<b>True</b> when the iterator is at the beginning of the linked list for the 
map.
</short>
<descr>
<p>
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 
<var>Nil</var>. The value in BOM is updated when navigation methods for the 
iterator are used, such as: First, Next, Previous, Last, and Locate.
</p>
</descr>
</element>

<element name="TBaseMapIterator.EOM">
<short>
<b>True</b> when the iterator is at the end of the linked list for the map.
</short>
<descr/>
</element>

<element name="TMap">
<short>
Implements a map for unique IDs to arbitrary data.
</short>
<descr>
<p>
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.
</p>
<p>
TMap extends the ancestor class to include public methods which Add map 
items, and read or write their arbitrary data values.
</p>
<p>
Author: Marc Weustink
</p>
</descr>
</element>

<element name="TMap.Add">
<short>
Adds a map item with the specified ID and Data values.
</short>
<descr/>
</element>
<element name="TMap.Add.AId">
<short>Map item to add in the method.</short>
</element>
<element name="TMap.Add.AData">
<short>Data for the map item to add in the method.</short>
</element>

<element name="TMap.HasId">
<short>
Checks for the specified ID is in the AVL Tree for the map.
</short>
<descr>
<p>
<var>HasId</var> is a <var>Boolean</var> 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 <b>True</b> when 
FindNode returns a value other than <var>Nil</var>.
</p>
</descr>
</element>
<element name="TMap.HasId.Result">
<short>
<b>True</b> when the AVL Tree contains a node for the specified map item.
</short>
</element>
<element name="TMap.HasId.AID">
<short>Map item to locate in the AVL Tree.</short>
</element>

<element name="TMap.GetData">
<short>
Gets the Data for the map item with the specified ID.
</short>
<descr/>
</element>
<element name="TMap.GetData.Result" link="#lazutils.maps.TBaseMap.InternalGetData.Result">
<short/>
</element>
<element name="TMap.GetData.AId" link="#lazutils.maps.TBaseMap.InternalGetData.AId">
<short/>
</element>
<element name="TMap.GetData.AData" link="#lazutils.maps.TBaseMap.InternalGetData.AId">
<short/>
</element>

<element name="TMap.GetDataPtr">
<short>Gets a Pointer to the data for the specified map item.</short>
<descr/>
</element>
<element name="TMap.GetDataPtr.Result" link="#lazutils.maps.TBaseMap.InternalGetDataPtr.Result">
<short/>
</element>
<element name="TMap.GetDataPtr.AId" link="#lazutils.maps.TBaseMap.InternalGetDataPtr.AId">
<short/>
</element>

<element name="TMap.SetData">
<short>Stores the data for the specified map item.</short>
<descr/>
</element>
<element name="TMap.SetData.Result" link="#lazutils.maps.TBaseMap.InternalSetData.Result">
<short/>
</element>
<element name="TMap.SetData.AId" link="#lazutils.maps.TBaseMap.InternalSetData.AId">
<short/>
</element>
<element name="TMap.SetData.AData" link="#lazutils.maps.TBaseMap.InternalSetData.AData">
<short/>
</element>

<element name="TMapIterator">
<short>Implements an iterator for items in a map.</short>
<descr>
<p>
<var>TMapIterator</var> is a <var>TBaseMapIterator</var> 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.
</p>
</descr>
<seealso>
<link id="TBaseMapIterator"/>
</seealso>
</element>

<element name="TMapIterator.Create">
<short>Constructor for the class instance.</short>
<seealso>
<link id="TBaseMapIterator.InternalCreate"/>
</seealso>
<descr/>
</element>
<element name="TMapIterator.Create.AMap">
<short>Map with IDs and Data for the iterator.</short>
</element>

<element name="TMapIterator.DataPtr">
<short>Gets the Pointer to the Data in a map item.</short>
<descr/>
<seealso>
<link id="TBaseMap.InternalGetDataPtr"/>
</seealso>
</element>
<element name="TMapIterator.DataPtr.Result" link="#lazutils.maps.TBaseMap.InternalGetDataPtr.Result">
<short/>
</element>

<element name="TMapIterator.GetData">
<short>Gets the Data for a map item.</short>
<seealso>
<link id="TBaseMap.InternalGetData"/>
</seealso>
<descr/>
</element>
<element name="TMapIterator.GetData.AData" link="#lazutils.maps.TBaseMap.InternalGetData,AData">
<short>Data for the map item.</short>
</element>

<element name="TMapIterator.GetID">
<short>Gets the ID for a map item.</short>
<descr/>
<seealso>
<link id="TBaseMap.InternalGetID"/>
</seealso>
</element>
<element name="TMapIterator.GetID.AID" link="#lazutils.maps.TBaseMap.InternalGetID.AID">
<short/>
</element>

<element name="TMapIterator.Locate">
<short>Locates a map item with the specified ID.</short>
<descr/>
<seealso>
<link id="TBaseMapIterator.InternalLocate"/>
</seealso>
</element>
<element name="TMapIterator.Locate.Result" link="#lazutils.maps.TBaseMapIterator.InternalLocate.Result">
<short/>
</element>
<element name="TMapIterator.Locate.AId" link="#lazutils.maps.TBaseMapIterator.InternalLocate.AId">
<short/>
</element>

<element name="TMapIterator.SetData">
<short>Sets the Data for a map item.</short>
<descr/>
<seealso>
<link id="TBaseMap.InternalSetData"/>
</seealso>
</element>
<element name="TMapIterator.SetData.AData" link="#lazutils.maps.TBaseMap.InternalSetData.AData">
<short/>
</element>

<element name="TLockedMapIterator">
<short>
Implements a map iterator with thread-safe locking in the associated map.
</short>
<descr>
<p>
<var>TLockedMapIterator</var> is a <var>TMapIterator</var> descendant which 
allows iteration of a map in multiple threads. The associated map will be 
locked prior to adding or removing entries.
</p>
</descr>
<seealso/>
</element>

<element name="TLockedMapIterator.AddToMap">
<short/>
<descr/>
<seealso/>
</element>

<element name="TLockedMapIterator.RemoveFromMap">
<short/>
<descr/>
<seealso/>
</element>

<element name="TTypedMap">
<short>
Implements a map with support for reference counted Type Information in the 
Data.
</short>
<descr>
<p>
TTypedMap is a TBaseMap map descendant that implements a map with support for 
reference counted Type Information in the Data for map items.
</p>
</descr>
<seealso>
<link id="TBaseMap"/>
</seealso>
</element>

<element name="TTypedMap.FTypeInfo"/>

<element name="TTypedMap.InternalSetData" link="#lazutils.maps.TBaseMap.InternalSetData">
<short/>
<descr/>
</element>
<element name="TTypedMap.InternalSetData.Result">
<short/>
</element>
<element name="TTypedMap.InternalSetData.AItem">
<short/>
</element>
<element name="TTypedMap.InternalSetData.AData">
<short/>
</element>

<element name="TTypedMap.ReleaseData" link="#lazutils.maps.TBaseMap.ReleaseData">
<short/>
<descr/>
</element>
<element name="TTypedMap.ReleaseData.ADataPtr">
<short/>
</element>

<element name="TTypedMap.Add" link="#lazutils.maps.TMap.Add">
<short/>
<descr/>
</element>
<element name="TTypedMap.Add.AId">
<short/>
</element>
<element name="TTypedMap.Add.AData">
<short/>
</element>

<element name="TTypedMap.Create">
<short>Constructor for the class instance.</short>
<descr/>
</element>
<element name="TTypedMap.Create.AIdType">
<short/>
</element>
<element name="TTypedMap.Create.ATypeInfo">
<short/>
</element>

<element name="TTypedMap.Destroy" link="#lazutils.maps.TBaseMap.Destroy">
<short>Destructor for the class instance.</short>
<descr/>
</element>

<element name="TTypedMap.HasId" link="#lazutils.maps.TMap.HasId">
<short/>
<descr/>
</element>
<element name="TTypedMap.HasId.Result">
<short/>
</element>
<element name="TTypedMap.HasId.AID">
<short/>
</element>

<element name="TTypedMap.GetData" link="#lazutils.maps.TMap.GetData">
<short>Gets the Data for the specified map item.</short>
<descr/>
</element>
<element name="TTypedMap.GetData.Result">
<short/>
</element>
<element name="TTypedMap.GetData.AId">
<short/>
</element>
<element name="TTypedMap.GetData.AData">
<short/>
</element>

<element name="TTypedMap.GetDataPtr" link="#lazutils.maps.TMap.GetDataPtr">
<short>Gets a Pointer to the Data for the specified map item.</short>
<descr/>
</element>
<element name="TTypedMap.GetDataPtr.Result">
<short/>
</element>
<element name="TTypedMap.GetDataPtr.AId">
<short/>
</element>

<element name="TTypedMap.SetData" link="#lazutils.maps.TMap.SetData">
<short>Stores the Data for the specified map item.</short>
<descr/>
</element>
<element name="TTypedMap.SetData.Result">
<short/>
</element>
<element name="TTypedMap.SetData.AId">
<short/>
</element>
<element name="TTypedMap.SetData.AData">
<short/>
</element>

<element name="TTypedMapIterator">
<short>Implements an iterator for items in a map.</short>
<descr>
<p>
<var>TTypedMapIterator</var> is a <var>TMapIterator</var> 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.
</p>
</descr>
<seealso>
<link id="TMapIterator"/>
</seealso>
</element>

<element name="TTypedMapIterator.Create">
<short>Constructor for the class instance.</short>
<descr/>
</element>
<element name="TTypedMapIterator.Create.AMap">
<short/>
</element>

<element name="TTypedMapIterator.GetData">
<short>Gets the Data for the map item.</short>
<descr/>
</element>
<element name="TTypedMapIterator.GetData.AData">
<short/>
</element>

<element name="TTypedMapIterator.GetID">
<short>Gets the ID for the map item.</short>
<descr/>
</element>
<element name="TTypedMapIterator.GetID.AID">
<short/>
</element>

<element name="TTypedMapIterator.Locate">
<short>Locates a map item with the specified ID.</short>
<descr/>
</element>
<element name="TTypedMapIterator.Locate.Result">
<short/>
</element>
<element name="TTypedMapIterator.Locate.AId">
<short/>
</element>

<element name="TTypedMapIterator.SetData">
<short>Stores the Data for the map item.</short>
<descr/>
</element>
<element name="TTypedMapIterator.SetData.AData">
<short/>
</element>

<!-- function Visibility: default -->
<element name="MapReport">
<short>Gets information about the AVL Tree in the specified map.</short>
<descr>
<p>
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.
</p>
</descr>
</element>
<element name="MapReport.Result">
<short>String with the multi-line information about the AVL Tree.</short>
</element>
<element name="MapReport.AMap">
<short>Map class to examine in the routine.</short>
</element>

</module>
<!-- Maps -->
</package>
</fpdoc-descriptions>