<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<package name="rtl">

<!--
  ====================================================================
    fgl
  ====================================================================
-->

<module name="fgl">
<short>Free Pascal Generic Lists</short>
<descr>
The <var>fgl</var> unit contains some basic list-related generic classes.
</descr>

<!-- constant Visibility: default -->
<element name="MaxListSize">
<short>Maximum amount of elements in a list</short>
<descr>
<var>MaxListSize</var> is the maximum number of elements a list can contain
before the memory runs out.
</descr>
<seealso>
<link id="TFPSList.Capacity"/>
</seealso>
</element>

<!-- class Visibility: default -->
<element name="EListError">
<short>Exception thrown when a list-related error occurs</short>
<descr>
<var>EListError</var> is the exception used in the <link id="TFPSList"/>
class to indicate errors such as a list index out of bounds, wrong capacity
etc.
</descr>
<seealso>
<link id="TFPSList.Capacity"/>
<link id="TFPSList.Exchange"/>
<link id="TFPSList.Items"/>
</seealso>
</element>

<!-- class Visibility: default -->
<element name="TFPSList">
<short>Basic list of memory blocks</short>
<descr>
<p>
<var>TFPSList</var> can be seen as the generalized equivalent of the classes unit <link id="classes.TFPList">TFPList</link> list.
It is used as a base class for the <link id="TFPGList"/>, <link id="TFPGMap"/>, <link id="TFPGObjectList"/>,  
<link id="TFPGInterfacedObjectList"/> and <link id="TFPGMapInterfacedObjectData"/> generic classes.
</p>
<p>
This list is not meant to be used directly, it is an auxiliary class for the actual generic list classes.
</p>
</descr>
<seealso>
<link id="classes.TFPList"/>
<link id="TFPGMap"/>
<link id="TFPGObjectList"/>
<link id="TFPGInterfacedObjectList"/>
<link id="TFPGMapInterfacedObjectData"/>
</seealso>
</element>

<!-- function type Visibility: default -->
<element name="TFPSListCompareFunc">
<short>Compare list items callback signature</short>
<descr>
<p>
<var>TFPSListCompareFunc</var> is used in the <link id="TFPSList.Sort"/>
method to compare 2 elements. The list passes 2 pointers to the actual items
to the compare function. The result of this function determines how the pointers will be sorted:
</p>
<ul>
<li>If the result of this function is negative, the first key (<var>key1</var>) is
assumed to be 'less' than the second key (<var>key2</var>) and will be moved before the second
in the list.</li>
<li>If the function result is positive, the first key (<var>key1</var>) pointer is assumed to
be 'greater than' the second key (<var>key2</var>)and will be moved after the second in the
list.</li>
<li>if the function result is zero, the keys are assumed to be 'equal'
and no moving will take place.</li>
</ul>
</descr>
<seealso>
<link id="TFPSList.Sort"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TFPSListCompareFunc.Result">
<short>Is <var>key1</var> less than <var>key2</var></short>
</element>

<!-- argument Visibility: default -->
<element name="TFPSListCompareFunc.Key1">
<short>First key value</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPSListCompareFunc.Key2">
<short>Second key value</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPSList.Create">
<short>Create a new instance of <var>TFPSList</var></short>
<descr>
<var>Create</var> creates a new instance of <var>TFPSList</var>, and
initializes the item size to <var>ItemSize</var>, which defaults to the size
of a pointer.
</descr>
<seealso>
<link id="TFPSList.ItemSize"/>
<link id="TFPSList.Destroy"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Create.AItemSize">
<short>Size of items in the list</short>
</element>

<!-- destructor Visibility: public -->
<element name="TFPSList.Destroy">
<short>Destroy the list instance.</short>
<descr>
<var>Destroy</var> clears and cleans up the list instance. Depending on the descendant,
this may also remove the items in the list from memory.
</descr>
<seealso>
<link id="TFPSList.Clear"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPSList.Add">
<short>Add a new item to the list</short>
<descr>
<p>
<var>Add</var> adds the item pointed to by <var>Item</var> to the list. 
It is not the pointer <var>Item</var> itself which is added to the list, but
rather the <link id="TFPSList.ItemSize"/> bytes of memory to which <var>Item</var> is
pointing.
</p>
<p>
The function returns the index of the newly added item.
</p>
</descr>
<errors>
If the maximum list size is reached, an <link id="EListError"/> is raised.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
<link id="TFPSList.Items"/>
<link id="TFPSList.Clear"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSList.Add.Result">
<short>The index at which the item was added.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Add.Item">
<short>Pointer to the item to be added.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Clear">
<short>Clear the list</short>
<descr>
<var>Clear</var> removes all the items in the list. Depending on the
descendent, the list items themselves may be cleared as well.
</descr>
<seealso>
<link id="TFPSList.Delete"/>
<link id="TFPSList.Items"/> 
<link id="TFPSList.Add"/> 
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Delete">
<short>Delete an item from the list</short>
<descr>
<var>Delete</var> deletes the item at position <var>Index</var> from the list. Depending on the
descendent, the list items itself may be cleared as well.
</descr> 
<errors>
If <var>Index</var> is out of bounds, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPSList.Clear"/>
<link id="TFPSList.Items"/> 
<link id="TFPSList.Add"/>   
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Delete.Index">
<short>Item to delete from the list/</short>
</element>

<!-- class procedure Visibility: public -->
<element name="TFPSList.Error">
<short>Raise an <var>EListError</var> exception.</short>
<descr>
<var>Error</var> is an auxiliary routine which raises an <link
id="EListError"/> exception formatted from <var>Msg</var> and
<var>Data</var>.
</descr>
<seealso>
<link id="EListError"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Error.Msg">
<short>Message (will be formatted with Data)</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Error.Data">
<short>Integer index</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Exchange">
<short>Exchange two items in the list</short>
<descr>
<var>Exchange</var> will exchange 2 items at positions <var>Index1</var> and <var>Index2</var> in the list. 
</descr>
<errors>
If <var>Index1</var> or <var>Index2</var> are out of bounds, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Exchange.Index1">
<short>First item</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Exchange.Index2">
<short>Second item</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSList.Expand">
<short>Expand the capacity of the list</short>
<descr>
<var>Expand</var> will expand the capacity of the list, and returns itself.
</descr>
<errors>
If the size will become larger than <link id="MaxListSize"/> an <link
id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="MaxListSize"/> 
<link id="TFPSList.Capacity"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSList.Expand.Result">
<short>Self</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Extract">
<short>delete an element from the list</short>
<descr>
<p>
<var>Extract</var> removes the item pointed to by <var>Item</var> from the list.
It returns a pointer to the actually removed item from the list. The item is
searched using <link id="TFPSList.IndexOf"/>. If the item is not found, nil is returned.
</p>
<p>
Some descendents own the items in the list. <var>Extract</var> will not
dispose of the item, as <link id="TFPSList.Delete"/> does.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
<link id="TFPSList.Add"/>
<link id="TFPSList.IndexOf"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Extract.Item">
<short>Pointer to item to extract</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Extract.ResultPtr">
<short>The actually removed item.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSList.IndexOf">
<short>Search an item in the list</short>
<descr>
<var>IndexOf</var> searches in the list for the item pointed to by
<var>Item</var>, and returns the position (0-based index) of the item in the list, or -1 if it
was not found. The items are compared using <link id="sysutils.CompareMem"/>,
so an exact memory layout match. 
</descr>
<errors>
</errors>
<seealso>
<link id="TFPSList.Extract"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSList.IndexOf.Result">
<short>Position in the list (0-based)</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.IndexOf.Item">
<short>Pointer to item to search for.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Insert">
<short>Insert a new item in the list.</short>
<descr>
<p>
<var>Insert</var> comes in 2 overloaded version. The version without <var>Item</var>
creates a slot for a new item at position <var>Index</var> in the list, and returns a pointer to the new slot. 
The slot will be of size <link id="TFPSList.ItemSize"/>. 
</p>
<p>
The version with <var>Item</var> argument will allocate a slot in the list at position
<var>Index</var> and will copy the item pointed to by <var>Item</var> to the
slot in the list. 
</p>
<p>
In both cases, <var>Index</var> must be 0-based. 
</p>
</descr>
<errors>
If <var>Index</var> is invalid, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPSList.Add"/>
<link id="TFPSList.Delete"/>
<link id="TFPSList.Extract"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Insert.Index">
<short>Index at which to insert the new item in the list</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Insert.Item">
<short>Item to insert in the list</short>
</element>

<!-- function result Visibility: public -->
<element name="TFPSList.Insert.Result">
<short>Newly allocated slot in the list</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Move">
<short> Moves an item from one position in the list to another. </short>  
<descr>
<p>
<var>Move</var> moves the item at position <var>CurIndex</var>
to position <var>NewIndex</var>. This is done by storing the value 
at position <var>CurIndex</var>, deleting the pointer at position
<var>CurIndex</var>, and reinserting the value at position
<var>NewIndex</var>
</p>
</descr>  
<errors>
If <var>CurIndex</var> or <var>Newindex</var> are not inside the valid
range of indices, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPSList.Exchange">Exchange</link>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Move.CurIndex">
<short>Item's current position in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Move.NewIndex">
<short>Items new position in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Assign">
<short>Copy one list to another</short>
<descr>
<var>Assign</var> clears the list and will add all items from <var>Obj</var> to the list. 
The items are copied one by one.
</descr>
<errors>
If the  <link id="TFPSList.ItemSize"/> differs for the two lists, an <link
id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPSList.Add"/> 
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Assign.Obj">
<short>Source list from which to copy items.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSList.Remove">
<short>Remove the item from the list </short>
<descr>
<p>
<var>Remove</var> searches <var>Item</var> in the list, and deletes it from
the list. It returns the index of the item that was removed, or -1 if it was
not found. Only the first match is removed.
</p>
<p>
If a descendent of <var>TFPSList</var> owns the object of the list, the item
is removed from memory. If this is not desired, then <link
id="TFPSList.Extract"/> must be used instead.
</p>
</descr>
<seealso>
<link id="TFPSList.Extract"/> 
<link id="TFPSList.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSList.Remove.Result">
<short>Index of removed item</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Remove.Item">
<short>Removed item</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Pack">
<short>Remove empty items from the list</short>
<descr>
<var>Pack</var> will remove all empty items from the list. An item is
considered to be empty if the memory location where the item is stored contains
only zero bytes.
</descr>
<seealso>
<link id="TFPSList.Clear"/>
<link id="TFPSList.Sort"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.Sort">
<short>Sort the list</short>
<descr>
<p>
<var>Sort></var> sorts the items in the list. Two pointers are compared
by passing them to the <var>Compare</var> function. The result of this
function determines how the pointers will be sorted:
</p>
<ul>
<li>If the result of this function is negative, the first item is
assumed to be 'less' than the second and will be moved before the second
item in the list.
</li>
<li>If the function result is positive, the first item is assumed to
be 'greater than' the second and will be moved after the second item in the 
list.
</li>
<li>if the function result is zero, the pointers are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
<p>  
The sort is done using a quicksort algorithm.
</p>
</descr>
<seealso>
<link id="TFPSListCompareFunc"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Sort.Compare">
<short>Function to compare 2 items in the list</short>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.Capacity">
<short>Current capacity of the list</short>
<descr>
<var>Capacity</var> is the current capacity (maximum amount of elements) of the list. 
The list capacity will expand automatically if an item is added and the capacity is reached
(i.e. <link id="TFPSList.Count"/> equals <var>capacity</var>. Expanding the
list is an expensive operation involving reallocation of memory and moving of list data in memory, 
so capacity can be set to a large amount to avoid frequent reallocations.
</descr>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPSList.Expand"/>
<link id="TFPSList.Items"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.Count">
<short>Current element count</short>
<descr>
<var>Count</var> is the current amount of elements in the list. It is
initially zero. A valid item index is always a value between zero and
<var>Count-1</var>.
</descr>
<seealso>
<link id="TFPSList.Items"/>
<link id="TFPSList.Capacity"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.Items">
<short>Items in the list</short>
<descr>
<p>
<var>Items</var> provides indexed access to the items in the list, the
returned pointers are not the actual list items, but pointers to the
elements in the list. The items can be get or set. 
</p>
<p>
When assigning to the <var>Items</var> property, the memory area
pointed to by the assigned pointer is copied to the list. 
Exactly <link id="TFPSList.ItemSize"/> bytes are copied.
</p>
<p>
The index <var>Index</var> is zero based, and has a maximum value of <link
id="TFPSList.Count">Count-1</link>.
</p>
</descr>
<errors>
If an invalid index is used, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPSList.ItemSize"/>
<link id="TFPSList.Count"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSList.Items.Index">
<short>Index of item to retrieve or set</short>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.ItemSize">
<short>Size of the items in the list</short>
<descr>
<var>ItemSize</var> is the memory size of the items in the list. It is specified in
the constructor and cannot be changed during the lifetime of the list.
</descr>
<seealso>
<link id="TFPSList.Create"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.List">
<short>Internal list pointer</short>
<descr>
<var>List</var> is a pointer to the memory area used for the items in the list.
It should not be manipulated.
</descr>
<seealso>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.First">
<short>Pointer to first non-empty item in the list</short>
<descr>
<p>
<var>First</var> returns the value of the first non-empty item in the list.
An item is considered empty if consists of <link id="TFPSList.ItemSize"/>
zero bytes.
</p>
<p>
If there are no non-empty items in the list, then <var>Nil</var> is returned.
</p>
</descr>
<seealso>
<link id="TFPSList.Last"/>
<link id="TFPSList.Pack"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSList.Last">
<short>Pointer to last non-empty item in the list</short>
<descr>
<p>
<var>Last</var> returns the value of the last non-empty item in the list. 
An item is considered empty if consists of <link id="TFPSList.ItemSize"/>   
zero bytes.
</p>
<p>If there are no non-empty items in the list, then <var>Nil</var> is
returned.
</p>
</descr> 
<seealso>
<link id="TFPSList.Last"/>
<link id="TFPSList.Pack"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="MaxGListSize">
<short>TFPGList maximum list size</short>
<descr>
<var>MaxGListSize</var> is the maximum number of elements in the <link
id="TFPGList"/> list.
</descr>
<seealso>
<link id="TFPGList"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGListEnumerator">
<short>Generic list enumerator</short>
<descr>
<p>
<var>TFPGListEnumerator</var> is a generic list enumerator. It is used in
the <link id="TFPGList"/> class to implement the enumerator for the list.
</p>
<p>
Normally there should be no need to instantiate or use this class directly.
</p>
</descr>
<seealso>
<link id="TFPGList"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGListEnumerator.T">
<short>Enumerator Type template</short>
<descr>
<var>T</var> is the type of the element returned by the enumerator.
</descr>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGListEnumerator.Create">
<short>Create a new list enumerator</short>
<descr>
<var>Create</var> is called by the list <var>AList</var> to initialize a new
enumerator. There should be no need to call this directly.
</descr>
<seealso>
<link id="TFPGList"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGListEnumerator.Create.AList">
<short>List to be enumerated</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGListEnumerator.MoveNext">
<short>Move to next element in the list</short>
<descr>
<var>MoveNext</var> moves to the next element in the list.
</descr>
<seealso>
<link id="TFPGListEnumerator.Current"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGListEnumerator.MoveNext.Result">
<short>True if the enumerator successfully selected the next element</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGListEnumerator.Current">
<short>Current enumerated element</short>
<descr>
<var>Current</var> returns the currently enumerated element. It is only valid
after <link id="TFPGListEnumerator.MoveNext"/> was called and returned
<var>True</var>.
</descr>
<seealso>
<link id="TFPGListEnumerator.MoveNext"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGList">
<short>Generic list</short>
<descr>
<var>TFPGList</var> can be used to specialize a list for any type <var>T</var>
that does not require reference counting (such as interfaced objects). It
will specialize to a list with the same methods as <link id="TFPSList"/> or <link
id="classes.TFPList"/>
</descr>
<seealso>
<link id="TFPSList"/> 
<link id="classes.TFPList"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGList.T">
<short>Type to specialize the list with</short>
</element>

<!-- function result Visibility: default -->
<element name="TFPGList.TCompareFunc.Result">
<short>Generic compare function for 2 elements in the list</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGList.TCompareFunc.Item1">
<short>Item 1 in comparison</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGList.TCompareFunc.Item2">
<short>Item 2 in comparison</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGList.TFPGListEnumeratorSpec.T">
<short>Enumerator for template type</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGList.Create">
<short>Instantiate a new list</short>
<descr>
<var>Create</var> instantiates a new list. It will simply call the inherited
constructor with the correct item size: <var>sizeof(T)</var>.
</descr>
</element>

<!-- function Visibility: public -->
<element name="TFPGList.Add">
<short>Add new item of type <var>T</var> to the list.</short>
<descr>
<var>Add</var> adds a new item <var>Item</var> of generic type <var>T</var>
to the list and returns the position at which the item was added.
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPGList.Extract"/>
<link id="TFPGList.Items"/>
<link id="TFPGList.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGList.Add.Result">
<short>Index at which item was added.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Add.Item">
<short>Item to add to the list.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGList.Extract">
<short>Extract an item from the list</short>
<descr>
<var>Extract</var> removes <var>Item</var> from the list and returns the
removed item, or an expression equivalent to <var>T(0)</var> if it was not found.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGList.Extract.Result">
<short>The extracted item</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Extract.Item">
<short>Item to extract</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGList.First">
<short>First non-empty item</short>
<descr>
<var>First</var> returns the first non-empty item, which means the first
item not equal to <var>T(0)</var>. If no such element is present,
<var>T(0)</var>. is returned.
</descr>
<seealso>
<link id="TFPSList.First"/>
<link id="TFPGList.Last"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGList.GetEnumerator">
<short>Return a list enumerator for <var>T</var>.</short>
<descr>
<var>GetEnumerator</var> returns an enumerator for the elements in the list.
It is a specialized version of <link id="TFPGListEnumerator"/>.
</descr>
<seealso>
<link id="TFPGListEnumerator"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGList.GetEnumerator.Result">
<short>A new enumerator</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGList.IndexOf">
<short>Index of item</short>
<descr>
<var>IndexOf</var> returns the index of <var>Item</var> in the list, or -1
if the item does not appear in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGList.Items"/>
<link id="TFPGList.Insert"/>
<link id="TFPSList.Add"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGList.IndexOf.Result">
<short>Index of <var>Item</var> in the list or -1 if it is not in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.IndexOf.Item">
<short>Item to search in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGList.Insert">
<short>Insert a new item in the list</short>
<descr>
<var>Insert</var> inserts a new <var>item</var> in the list at position
<var>Index</var>. The index is zero based and must be less than <link
id="TFPSList.Count">Count</link>.
</descr>
<errors>
If an invalid index is specified, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPGList.Items"/>
<link id="TFPGList.Insert"/>
<link id="TFPSList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Insert.Index">
<short>Position to insert <var>item</var> at</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Insert.Item">
<short>Item to insert in the list</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGList.Last">
<short>Last non-empty item</short>
<descr>
<var>Last</var> returns the last non-empty item, which means the last
item not equal to <var>T(0)</var>. If no such element is present,
<var>T(0)</var>. is returned.
</descr>
<seealso>
<link id="TFPGList.First"/>
<link id="TFPSList.Last"/>  
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGList.Assign">
<short>Copy elements from Source list</short>
<descr>
<var>Assign</var> clears the list and copies all items in <var>Source</var> to the list.
The source list must be of the same type as the destination list.
</descr>
<seealso>
<link id="TFPSList.Clear"/>
<link id="TFPGList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Assign.Source">
<short>Source list to copy items from.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGList.Remove">
<short>Remove an item from the list.</short>
<descr>
<var>Remove</var> removes the item <var>Item</var> from the list, and
returns the index of the removed item. If no item was removed, <var>-1</var> is
returned. Only the first item is removed.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGList.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGList.Remove.Result">
<short>Index of the removed item.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Remove.Item">
<short>Item to remove from the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGList.Sort">
<short>Sort the list</short>
<descr>
<p>
<var>Sort</var> sorts the elements in the list using the provided <var>Compare</var> function.
The list passes 2 items to the compare function. The result of this function determines how the
items will be sorted:
</p>
<ul>
<li>If the result of this function is negative, the first item (<var>Item1</var>) is
assumed to be 'less' than the second item (<var>Item2</var>) and will be moved before the second
in the list.
</li>
<li>If the function result is positive, the first item (<var>Item1</var>) is assumed to
be 'greater than' the second item (<var>Item2</var>)and will be moved after the second in the
list.
</li>
<li>if the function result is zero, the items are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Sort.Compare">
<short>Compare function for 2 items</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGList.Items">
<short>Indexed access to items in the list</short>
<descr>
<p>
<var>Items</var> provides indexed access to the items in the list. 
The items can be get or set.
</p>
<p>
The index <var>Index</var> is zero based, and has a maximum value of <link
id="TFPSList.Count">Count-1</link>.
</p>
</descr>
<errors>
If an invalid index is used, an <link id="EListError"/> exception is raised.
</errors> 
<seealso>
<link id="TFPSList.Count"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGList.Items.Index">
<short>Index of item to get or set</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGList.List">
<short>Internal list object</short>
<descr>
<var>List</var> is the internal list of items. It should not be used directly.
</descr>
<seealso>
<link id="TFPGList.Items"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGObjectList">
<short>Generic object list</short>
<descr>
<var>TFPGList</var> can be used to specialize a list for any class type <var>T</var>
that does not require reference counting (such as interfaced objects). 
It will specialize to a list with the same methods as <link id="TFPSList"/> or
<link id="classes.TFPList"/> or <var>TFPObjectList</var>
</descr>
<seealso>
<link id="TFPSList"/> 
<link id="classes.TFPList"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGObjectList.T">
<short>Class type to specialize the list with</short>
</element>

<!-- function result Visibility: default -->
<element name="TFPGObjectList.TCompareFunc.Result">
<short>Generic compare function for 2 objects in the list</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGObjectList.TCompareFunc.Item1">
<short>Item 1 in comparison</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGObjectList.TCompareFunc.Item2">
<short>Item 2 in comparison</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGObjectList.TFPGListEnumeratorSpec.T">
<short>Enumerator for template type</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGObjectList.Create">
<short>Instantiate a new object list.</short>
<descr>
<p>
<var>Create</var> instantiates a new object list. It will simply call the inherited
constructor with the correct item size and will initialize <link
id="TFPGObjectList.FreeObjects"/> with <var>FreeObjects</var>.
</p>
<p>
If <var>FreeObjects</var> is true, then the list owns the objects. Freeing
or clearing the list will remove all objects from memory by calling the
destructor. Deleting or removing an item from the list will also dispose of
the element.
</p>
</descr>
<seealso>
<link id="TFPGObjectList.FreeObjects"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Create.FreeObjects">
<short>When <var>True</var> the list owns the objects.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGObjectList.Add">
<short>Add new object of class <var>T</var> to the list.</short>
<descr>
<var>Add</var> adds a new item <var>Item</var> of class type <var>T</var>
to the list and returns the position at which the item was added.
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is
raised.
</errors>
<seealso>
<link id="TFPGObjectList.Extract"/>
<link id="TFPGObjectList.Items"/>
<link id="TFPGObjectList.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGObjectList.Add.Result">
<short>Index at which item was added.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Add.Item">
<short>Item to add to the list.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGObjectList.Extract">
<short>Extract an item from the list</short>
<descr>
<p>
<var>Extract</var> removes <var>Item</var> from the list and returns the
removed item, or <var>Nil</var> if it was not found.
</p>
<p>
The extracted object will not be destroyed even if the list owns the
objects.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGObjectList.Extract.Result">
<short>The actually removed item, or <var>Nil</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Extract.Item">
<short>The extracted item</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGObjectList.First">
<short>First non-nil item</short>
<descr>
<var>First</var> returns the first non-nil item.
If no such element is present, <var>Nil</var> is returned.
</descr>
<seealso>
<link id="TFPSList.First"/>
<link id="TFPGList.Last"/>
<link id="TFPSList.Pack"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGObjectList.GetEnumerator">
<short>Return a list enumerator for <var>T</var>.</short>
<descr>
<var>GetEnumerator</var> returns an enumerator for the elements in the list.
It is a specialized version of <link id="TFPGListEnumerator"/>.
</descr>
<seealso>
<link id="TFPGListEnumerator"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGObjectList.GetEnumerator.Result">
<short>A new enumerator</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGObjectList.IndexOf">
<short>Index of item</short>
<descr>
<var>IndexOf</var> returns the index of <var>Item</var> in the list, or -1
if the item does not appear in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGObjectList.Items"/>
<link id="TFPGObjectList.Insert"/>
<link id="TFPGObjectList.Add"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGObjectList.IndexOf.Result">
<short>Index of <var>Item</var> in the list or -1 if it is not in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.IndexOf.Item">
<short>Item to search in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGObjectList.Insert">
<short>Insert a new object in the list</short>
<descr>
<var>Insert</var> inserts a new object (<var>Item</var>) in the list at position
<var>Index</var>. The index is zero based and must be less than <link
id="TFPSList.Count">Count</link>.
</descr>
<errors>
If an invalid index is specified, an <link id="EListError"/> exception is
raised.
</errors>
<seealso>
<link id="TFPGList.Items"/>
<link id="TFPGList.Insert"/>
<link id="TFPSList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Insert.Index">
<short>Position to insert <var>Item</var> at</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Insert.Item">
<short>Object to insert in the list</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGObjectList.Last">
<short>Last non-<var>Nil</var> object</short>
<descr>
<var>Last</var> returns the last non-<var>Nil</var> object.
If no such element is present, <var>Nil</var>. is returned.
</descr>
<seealso>
<link id="TFPGObjectList.First"/>
<link id="TFPSList.Last"/>  
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGObjectList.Assign">
<short>Copy objects from Source list</short>
<descr>
<p>
<var>Assign</var> clears the list and copies all items in <var>Source</var>
to the list. The source list must be of the same type as the destination list.
</p>
<p>
Take care if both the list owns the objects (i.e. have <link id="TFPGObjectList.FreeObjects"/> set to
<var>True</var>), this may result to access violations.
</p>
</descr>
<seealso>
<link id="TFPSList.Clear"/>
<link id="TFPGObjectList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Assign.Source">
<short>Source list to copy items from.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGObjectList.Remove">
<short>Remove an object from the list.</short>
<descr>
<p>
<var>Remove</var> removes the object  <var>Item</var> from the list, and
returns the index of the removed item. If no item was removed, <var>-1</var>
is returned. Only the first object is removed. 
</p>
<p>
If the list owns the objects, (<link id="TFPGObjectList.FreeObjects"/> is set to <var>True</var>) then the object is freed.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGObjectList.IndexOf"/>
<link id="TFPSList.Delete"/>
<link id="TFPGObjectList.FreeObjects"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGObjectList.Remove.Result">
<short>Index of removed object, prior to removal.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Remove.Item">
<short>Object to remove from the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGObjectList.Sort">
<short>Sort the objects in the list</short>
<descr>
<p>
<var>Sort</var> sorts the elements in the list using the provided
<var>Compare</var> function.
The list passes 2 items to the compare function. The result of this function
determines how the
items will be sorted:
</p>
<ul>
<li>If the result of this function is negative, the first object (<var>Item1</var>) is
assumed to be 'less' than the second object (<var>Item2</var>) and will be
moved before the second
in the list.
</li>
<li>If the function result is positive, the first object (<var>Item1</var>) is
assumed to
be 'greater than' the second object (<var>Item2</var>)and will be moved after
the second in the
list.
</li>
<li>if the function result is zero, the objects are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<errors>
None.
</errors>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Sort.Compare">
<short>Compare function for 2 objects</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGObjectList.Items">
<short>Indexed access to objects in the list.</short>
<descr>
<p>
<var>Items</var> provides indexed access to the objects in the list. 
The objects can be get or set. 
</p>
<p>
The index <var>Index</var> is zero based, and has a maximum value of <link
id="TFPSList.Count">Count-1</link>.
</p>
<p>
If the list owns the objects, (<link id="TFPGObjectList.FreeObjects"/> is
set to <var>True</var>) then the previous object at position
<var>Index</var> is freed when setting the property.
</p>
</descr>
<errors>
If an invalid index is used, an <link id="EListError"/> exception is raised.
</errors> 
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGObjectList.FreeObjects"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGObjectList.Items.Index">
<short>Index of object to get or set</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGObjectList.List">
<short>Internal list pointer</short>
<descr>
<var>List</var> is the internal list of objects. It should not be used directly.
</descr>
<seealso>
<link id="TFPGObjectList.Items"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGObjectList.FreeObjects">
<short>Does the list own the objects or not?</short>
<descr>
<p>
<var>FreeObjects</var> indicates whether the list owns the objects or not.
If set to <var>True</var>, freeing or clearing the list will remove all 
objects from memory by calling the destructor. Deleting or removing an 
item from the list will also dispose of the element.
</p>
<p>
The initial value for this property is set in the constructor and is
<var>True</var> by default.
</p>
</descr>
<seealso>
<link id="TFPGObjectList.FreeObjects"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGInterfacedObjectList">
<short>Generic interfaced object list</short>
<descr>
<p>
<var>TFPGList</var> can be used to specialize a list for any class type <var>T</var>
that requires reference counting (all objects that implement <var>IInterface</var> or <var>IUnknown</var>)). 
It will specialize to a list with the same methods as <link id="TFPSList"/> or
<link id="classes.TFPList"/> or <var>TFPObjectList</var>
</p>
<p>
Classes that implement <var>IInterface</var> or <var>IUnknown</var> require
special care to maintain the reference count. The <var>TFPGInterfacedObjectList</var>
list provides the necessary functionality to deal with this. 
</p>
</descr>
<seealso>
<link id="TFPSList"/> 
<link id="classes.TFPList"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGInterfacedObjectList.T">
<short>Interfaced class type</short>
</element>

<!-- function result Visibility: default -->
<element name="TFPGInterfacedObjectList.TCompareFunc.Result">
<short>Generic compare function for 2 objects in the list</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGInterfacedObjectList.TCompareFunc.Item1">
<short>Object 1 in comparison</short>
</element>

<!-- argument Visibility: default -->
<element name="TFPGInterfacedObjectList.TCompareFunc.Item2">
<short>Object 2 in comparison</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGInterfacedObjectList.TFPGListEnumeratorSpec.T">
<short>Enumerator for template type</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGInterfacedObjectList.Create">
<short>Instantiate a new interfaced object list.</short>
<descr>
<p>
<var>Create</var> instantiates a new object list. It will simply call the
inherited constructor with the correct item size.
</p>
</descr>
<seealso>
<link id="TFPSList.Destroy"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGInterfacedObjectList.Add">
<short>Add new object of class <var>T</var> to the list.</short>
<descr>
<var>Add</var> adds a new item <var>Item</var> of class type <var>T</var>
to the list and returns the position at which the item was added. Add will
increase the reference count of the object.
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is
raised.
</errors>
<seealso>
<link id="TFPGInterfacedObjectList.Extract"/>
<link id="TFPGInterfacedObjectList.Items"/>
<link id="TFPGInterfacedObjectList.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGInterfacedObjectList.Add.Result">
<short>Index at which the object was added.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Add.Item">
<short>Interfaced object to add to the list.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGInterfacedObjectList.Extract">
<short>Extract an item from the list</short>
<descr>
<p>
<var>Extract</var> removes <var>Item</var> from the list and returns the
removed item, or <var>Nil</var> if it was not found.
</p>
<p>
The extracted object will not be destroyed.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGInterfacedObjectList.Extract.Result">
<short>The actually removed object, or <var>Nil</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Extract.Item">
<short>The extracted object</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGInterfacedObjectList.First">
<short>First non-nil object</short>
<descr>
<var>First</var> returns the first non-nil object.
If no such element is present, <var>Nil</var> is returned.
</descr>
<seealso>
<link id="TFPSList.First"/>
<link id="TFPGInterfacedObjectList.Last"/>
<link id="TFPSList.Pack"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGInterfacedObjectList.GetEnumerator">
<short>Return a list enumerator for <var>T</var></short>
<descr>
<var>GetEnumerator</var> returns an enumerator for the elements in the list.
It is a specialized version of <link id="TFPGListEnumerator"/>.
</descr>
<seealso>
<link id="TFPGListEnumerator"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGInterfacedObjectList.GetEnumerator.Result">
<short>A new enumerator</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGInterfacedObjectList.IndexOf">
<short>Index of object</short>
<descr>
<var>IndexOf</var> returns the index of <var>Item</var> in the list, or -1
if the object does not appear in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGInterfacedObjectList.Items"/>
<link id="TFPGInterfacedObjectList.Insert"/>
<link id="TFPGInterfacedObjectList.Add"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGInterfacedObjectList.IndexOf.Result">
<short>Index of <var>Item</var> in the list or -1 if it is not in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.IndexOf.Item">
<short>Item to search in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGInterfacedObjectList.Insert">
<short>Insert a new object in the list</short>
<descr>
<var>Insert</var> inserts a new object (<var>Item</var>) in the list at
position
<var>Index</var>. The index is zero based and must be less than <link
id="TFPSList.Count">Count</link>.
</descr>
<errors>
If an invalid index is specified, an <link id="EListError"/> exception is
raised.
</errors>
<seealso>
<link id="TFPGInterfacedObjectList.Items"/>
<link id="TFPGInterfacedObjectList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Insert.Index">
<short>Position to insert <var>Item</var> at</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Insert.Item">
<short>Interfaced Object to insert in the list</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGInterfacedObjectList.Last">
<short>Last non-<var>Nil</var> object</short>
<descr>
<var>Last</var> returns the last non-<var>Nil</var> object.
If no such element is present, <var>Nil</var> is returned.
</descr>
<seealso>
<link id="TFPGInterfacedObjectList.First"/>
<link id="TFPSList.Last"/>  
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGInterfacedObjectList.Assign">
<short>Copy objects from Source list</short>
<descr>
<p>
<var>Assign</var> clears the list and copies all items in <var>Source</var>
to the list. The source list must be of the same type as the destination list.
</p>
</descr>
<seealso>
<link id="TFPSList.Clear"/>
<link id="TFPGObjectList.Add"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Assign.Source">
<short>Source list to copy items from.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGInterfacedObjectList.Remove">
<short>Remove an object from the list.</short>
<descr>
<p>
<var>Remove</var> removes the object  <var>Item</var> from the list, and
returns the index of the removed item. If no item was removed, <var>-1</var>
is returned. Only the first object is removed. 
</p>
<p>
Removing an object from the list may cause the object to be freed.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGInterfacedObjectList.IndexOf"/>
<link id="TFPSList.Delete"/>
<link id="TFPGInterfacedObjectList.FreeObjects"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGInterfacedObjectList.Remove.Result">
<short>Index of removed object, prior to removal.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Remove.Item">
<short>Object to remove from the list</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGInterfacedObjectList.Sort">
<short>Sort the objects in the list</short>
<descr>
<p>
<var>Sort</var> sorts the elements in the list using the provided
<var>Compare</var> function. The list passes 2 items to the compare function. 
The result of this function determines how the items will be sorted:
</p>
<ul>
<li>If the result of this function is negative, the first object (<var>Item1</var>) is
assumed to be 'less' than the second object (<var>Item2</var>) and will be moved before the second in the list.
</li>
<li>If the function result is positive, the first object (<var>Item1</var>) is assumed to
be 'greater than' the second object (<var>Item2</var>)and will be moved after the second in the list.
</li>
<li>if the function result is zero, the objects are assumed to be 'equal' and no moving will take place.
</li>
</ul>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Sorted"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Sort.Compare">
<short>Compare function for 2 objects</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGInterfacedObjectList.Items">
<short>Indexed access to objects in the list.</short>
<descr>
<p>
<var>Items</var> provides indexed access to the objects in the list. 
The objects can be get or set. 
</p>
<p>
The index <var>Index</var> is zero based, and has a maximum value of <link
id="TFPSList.Count">Count-1</link>.
</p>
<p>
The previous object at position <var>Index</var> may be freed when setting the
property, depending on its reference count.
</p>
</descr>
<errors>
If an invalid index is used, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPSList.Count"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGInterfacedObjectList.Items.Index">
<short>Index of object to get or set</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGInterfacedObjectList.List">
<short>Internal list pointer</short>
<descr>
<var>List</var> is the internal list of objects. It should not be used directly.
</descr>
<seealso>
<link id="TFPGInterfacedObjectList.Items"/>
</seealso>
</element>

<!-- class Visibility: default -->
<element name="TFPSMap">
<short>Basic map object, used in generic maps</short>
<descr>
<p>
<var>TFPSMap</var> can be used to create a map for any type <var>T</var>
that does not require reference counting (such as interfaced objects). 
It will specialize to a map which is a generalized list with an arbitrary
type as the list index (called the key). 
</p>
<p>
This class should normally not be used directly, instead use one of the generic map
objects such as <link id="TFPGMap"/>.
</p>
</descr>
<seealso>
<link id="TFPGMap"/>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TFPSMap.Create">
<short>Create a new map with given key and data size.</short>
<descr>
<var>Create</var> instantiates a new <var>TFPSMap</var> instance and
initializes <link id="TFPSMap.KeySize"/> and <link id="TFPSMap.DataSize"/>
with <var>AKeySize</var> and <var>ADataSize</var>, respectively. 
It also initializes the <link id="TFPSMap.OnDataPtrCompare"/>  and <link
id="TFPSMap.OnKeyPtrCompare"/> properties to functions that compare memory
blocks.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSMap.Destroy"/>
<link id="TFPSMap.KeySize"/>
<link id="TFPSMap.DataSize"/>
<link id="TFPSMap.OnDataPtrCompare"/>
<link id="TFPSMap.OnKeyPtrCompare"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Create.AKeySize">
<short>Size for map keys</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Create.ADataSize">
<short>Size for map data</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.Add">
<short>Add a key, value pair to the map.</short>
<descr>
<var>Add</var> adds the memory pointed to by <var>AData</var> to the map using
the memory pointed to by <var>AKey</var> as the key. If no data is
specified, it allocates a slot for <var>AKey</var> and returns a pointer to
that slot.
</descr>
<errors>
If the maximum amount of values is reached, <var>Add</var> will raise an
<link id="EListError"/> exception.
</errors>
<seealso>
<link id="TFPSMap.Insert"/>
<link id="TFPSMap.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.Add.Result">
<short>Slot in the list for the key and data.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Add.AKey">
<short>Pointer to key to add to list</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Add.AData">
<short>Pointer to data to add to list</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.Find">
<short>Find data using the associated key</short>
<descr>
<p>
<var>Find</var> searches for the first key less than or equal to <var>AKey</var> and
returns its index in the list in <var>Index</var>. It returns <var>True</var> if an exact match for the key was found.
It returns <var>False</var> if the key was not found, and <var>Index</var> is then set to <var>-1</var>
</p>
<p>
This function performs a binary search using the key comparing function
specified in  <link id="TFPSMap.OnKeyPtrCompare">OnKeyPtrCompare</link>.
</p>
</descr>
<errors>
if <var>OnKeyPtrCompare</var> is not set, an access violation will occur.
</errors>
<seealso>
<link id="TFPSMap.OnKeyPtrCompare"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.Find.Result">
<short>True if an exact match was found</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Find.AKey">
<short>Key to search for</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Find.Index">
<short>Index of first key smaller than <var>Akey</var></short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.IndexOf">
<short>Index of key pointed to by <var>AKey</var></short>
<descr>
<p>
<var>IndexOf</var> returns the index of the element with a key pointed to by
<var>AKey</var>. It returns -1 if the key was not found.
</p>
<p>
If the list is sorted, then a binary search is performed, otherwise a linear search is used to find the key.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSMap.Find"/>
<link id="TFPSMap.IndexOfData"/>
<link id="TFPSMap.Keys"/>
<link id="TFPSMap.Data"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.IndexOf.Result">
<short>Index of <var>AKey</var> or -1 if <var>AKey</var> was not found.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.IndexOf.AKey">
<short>key to search for</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.IndexOfData">
<short>Index of data item <var>AData</var></short>
<descr>
<var>IndexOfData</var> returns the index of the element with data pointed to
by <var>AData</var>. It returns -1 if the data item was not found.
The search is always performed using a linear search.
</descr>
<seealso>
<link id="TFPSMap.Find"/>
<link id="TFPSMap.IndexOf"/>
<link id="TFPSMap.Keys"/>
<link id="TFPSMap.Data"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.IndexOfData.Result">
<short>Index of <var>AData</var> in the <var>Data</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.IndexOfData.AData">
<short>Data item to search for.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.Insert">
<short>Insert a new slot for key and associated data item in the list</short>
<descr>
<var>Insert</var> will allocate a new slot in the list. It returns a pointer
to the new slot. If <var>Akey</var> and <var>AData</var> are given, then
they will point to the positions in the slot for the key and data items.
</descr>
<errors>
If the maximum amount of values is reached or an invalid index is specified, 
<var>Insert</var> will raise an <link id="EListError"/> exception.
</errors>
<seealso>
<link id="TFPSMap.Add"/>
<link id="TFPSMap.InsertKey"/>
<link id="TFPSMap.InsertKeyData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.Insert.Result">
<short>Slot to add data to</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Insert.Index">
<short>Index to insert new key, value pair</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Insert.AKey">
<short>Pointer to location for key value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Insert.AData">
<short>Pointer to location for data value</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSMap.InsertKey">
<short>Insert a key  in the list</short>
<descr>
<var>InsertKey</var> will allocate a new slot in the list for a key value as
pointed to by <var>AKey</var>, and copy the key pointed to by <var>AKey</var> to the slot.
</descr> 
<errors> 
If the maximum amount of values is reached or an invalid index is specified, 
<var>InsertKey</var> will raise an <link id="EListError"/> exception.
</errors>
<seealso>
<link id="TFPSMap.Add"/>
<link id="TFPSMap.Insert"/>
<link id="TFPSMap.InsertKeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.InsertKey.Index">
<short>Index at which position key must be inserted</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.InsertKey.AKey">
<short>Pointer to Key value to insert</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSMap.InsertKeyData">
<short>Insert a key and associated in the list</short>
<descr>
<var>InsertKeyData</var> will allocate a new slot in the list for a key value as
pointed to by <var>AKey</var>, and copy the key  pointed to by
<var>AKey</var> as well as the data pointed to by <var>AData</var> to the
newly allocated slot. 
</descr> 
<errors>
If the maximum amount of values is reached or an invalid index is specified,
<var>InsertKeyData</var> will raise an <link id="EListError"/> exception.
</errors>
<seealso>
<link id="TFPSMap.Add"/>
<link id="TFPSMap.Insert"/>
<link id="TFPSMap.InsertKey"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.InsertKeyData.Index">
<short>Index at which to insert key and value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.InsertKeyData.AKey">
<short>Pointer to key value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.InsertKeyData.AData">
<short>Pointer to data value</short>
</element>

<!-- function Visibility: public -->
<element name="TFPSMap.Remove">
<short>Remove a key/value pair from the map.</short>
<descr>
<var>Remove</var> removes the key/value pair pointing to by <var>AKey</var> from the map.
It returns the index of <var>Akey</var> prior to removal from the list. 
If <var>AKey</var> was not found, -1 is returned.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSList.Delete"/>
<link id="TFPSMap.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPSMap.Remove.Result">
<short>Index of <var>AKey</var> prior to removal, or -1 if not found.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Remove.AKey">
<short>Key to remove from the map.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSMap.Sort">
<short>Sort the list according to key</short>
<descr>
<var>Sort</var> sorts the list according to the key value, using the
compare function provided in <link id="TFPSMap.OnKeyPtrCompare"/>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPSMap.OnKeyPtrCompare"/>
<link id="TFPSMap.OnDataPtrCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.Duplicates">
<short>What to do with duplicate key values</short>
<descr>
<p>
<var>Duplicates</var> can be set to determine what to do with duplicate key
values in the map:
</p>
<dl>
<dt>dupIgnore</dt><dd><printshort id="types.TDuplicates.dupIgnore"/></dd>
<dt>dupAccept</dt><dd><printshort id="types.TDuplicates.dupAccept"/></dd>
<dt>dupError</dt><dd><printshort id="types.TDuplicates.dupError"/></dd>
</dl>
<p>
The value is ignored if <link id="TFPSMap.Sorted">Sorted</link> is <var>False</var>.
</p>
</descr>
<seealso>
<link id="TFPSMap.Sorted"/>
<link id="types.TDuplicates"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.KeySize">
<short>Size (in bytes) for the key</short>
<descr>
<var>KeySize</var> is the size (in bytes) for the keys in the map. 
This size is initialized during list construction and defaults to the size
of a pointer.
</descr>
<seealso>
<link id="TFPSMap.Create"/>
<link id="TFPSMap.DataSize"/>
<link id="TFPSMap.Keys"/>
<link id="TFPSMap.KeyData"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.DataSize">
<short>Size (in bytes) for the data associated with keys</short>
<descr>
<var>DataSize</var> is the size (in bytes) for the data in the map.
This size is initialized during list construction and defaults to the size
of a pointer.
</descr>  
<seealso> 
<link id="TFPSMap.Create"/>
<link id="TFPSMap.KeySize"/>
<link id="TFPSMap.Keys"/>    
<link id="TFPSMap.KeyData"/>
<link id="TFPSMap.Data"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.Keys">
<short>Indexed access to the locations of all keys</short>
<descr>
<var>Keys</var> provides indexed access to all keys. It does not return  the
key, but returns a pointer to the key value. When setting the <var>Keys</var>
property, a pointer to the key value must be set, and the key value is copied from the
pointer.
</descr>
<seealso>
<link id="TFPSMap.KeySize"/>
<link id="TFPSMap.KeyData"/>
<link id="TFPSMap.Data"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Keys.Index">
<short>Index of key location to get or set</short>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.Data">
<short>Indexed access to the locations of all data items</short>
<descr>
<var>Data</var> provides indexed access to all data. It does not return the
actual data, but returns a pointer to the data. When setting the
<var>Data</var> property, a pointer to the data value must be set, and the
data value is copied from the pointer.
</descr>
<seealso>
<link id="TFPSMap.DataSize"/>
<link id="TFPSMap.KeyData"/>
<link id="TFPSMap.Keys"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.Data.Index">
<short>Index of data location to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.KeyData">
<short>Access to data locations using key</short>
<descr>
<var>KeyData</var> provides access to the data items, using their key value (as pointed to by <var>AKey</var>) as an index.
When reading a non-existent key value, <var>Nil</var> is returned.
If the key is found, a pointer to the associated data's location is returned. 
When writing, the key pointed to by <var>Key</var> is added if it was not
present, and the data data is copied from the written pointer.
</descr>
<seealso>
<link id="TFPSMap.DataSize"/>
<link id="TFPSMap.KeyData"/>
<link id="TFPSMap.Data"/>
<link id="TFPSMap.Keys"/>   
<link id="TFPSMap.KeySize"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPSMap.KeyData.Key">
<short>Pointer to key data to use</short>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.Sorted">
<short>Is the map permanently sorted on key ?</short>
<descr>
<var>Sorted</var> can be set to true to keep the map permanently sorted on key value.
The sorting happens using <link id="TFPSMap.OnKeyPtrCompare"/>.
</descr>
<seealso>
<link id="TFPSMap.OnKeyPtrCompare"/>
<link id="TFPSMap.Sort"/>
<link id="TFPSMap.Duplicates"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.OnPtrCompare">
<short>Alias for <var>OnKeyPtrCompare</var></short>
<descr>
<var>OnPtrCompare</var> is a deprecated alias for <link
id="TFPSMap.OnKeyPtrCompare">OnKeyPtrCompare</link>.
</descr>
<seealso>
<link id="TFPSMap.OnKeyPtrCompare"/>
<link id="TFPSMap.OnDataPtrCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.OnKeyPtrCompare">
<short>Callback to compare 2 keys</short>
<descr>
<p>
<var>OnKeyPtrCompare</var> is used to compare the values of 2 keys. By
default it simply compares the byte values of the key memory block. It can be
set to any function that performs another comparison. (e.g. a function that
treats the memory blocks  as a string pointer and compare the actual strings).
</p>
<p>
This function is used to sort the list or find a key.
</p>
</descr>
<seealso>
<link id="TFPSListCompareFunc"/>
<link id="TFPSMap.OnDataPtrCompare"/>
<link id="TFPSMap.Sort"/>
<link id="TFPSMap.Find"/>
<link id="TFPSMap.IndexOf"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPSMap.OnDataPtrCompare">
<short>Callback to compare 2 data items</short>
<descr>
<p>
<var>OnKeyPtrCompare</var> is used to compare the values of 2 keys. By
default it simply compares the byte values of the key memory block. It can
be set to any function that performs another comparison. (e.g. a function that  
treats the memory blocks  as a string pointer and compare the actual strings).
</p>
<p> 
This function is used to find a data item (<link id="TFPSMap.IndexOfData">IndexOf</link>).
</p>
</descr>
<seealso>
<link id="TFPSListCompareFunc"/>
<link id="TFPSMap.OnKeyPtrCompare"/>
<link id="TFPSMap.IndexOfData"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGMap">
<short>Generic map</short>
<descr>
<var>TFPGMap</var> is a generic map class. It can be used to specialize a map for any key type and data
type that do not require manual reference counting: For reference counted interface objects, <link id="TFPGMapInterfacedObjectData"/> must be used.
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMap.TKey">
<short>Map Key type</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMap.TData">
<short>Map data type</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGMap.Create">
<short>Create a new instance of the map</short>
<descr>
<var>Create</var> instantiates a new map. It mainly initializes the
<link id="TFPSMap"/> parent with the sized of the key and data.
</descr>
<seealso>
<link id="TFPSMap.Create"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.Add">
<short>Add a key and value to the map</short>
<descr>
<var>Add</var> adds a new key <var>AKey</var> of generic type <var>TKey</var>
with data value <var>AData</var> to the list and returns the position at which 
the key was added. 
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is raised.
If <link id="TFPSMap.Duplicates">Duplicates</link> is set to <var>dupError</var>
and a duplicate key is added, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPGMap.Keys"/>
<link id="TFPGMap.IndexOf"/>
<link id="TFPGMap.KeyData"/>
<link id="TFPGMap.Data"/>
<link id="TFPSMap.Duplicates"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMap.Add.Result">
<short>Index of the new key</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Add.AKey">
<short>Key value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Add.AData">
<short>Data item</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.Find">
<short>Find item based on key</short>
<descr>
<p>
<var>Find</var> will search the key equal to <var>AKey</var> and return its index in <var>AIndex</var>. 
The return value of the function is <var>True</var> if an exact match for <var>AKey</var> is found, <var>False</var> otherwise.
</p>
<p>
The behaviour of Find is undefined if the map is not sorted. 
For unsorted maps, use <link id="TFPGMap.IndexOf">IndexOf</link> instead.
</p>
</descr>
<seealso>
<link id="TFPGMap.IndexOf"/>
<link id="TFPGMap.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMap.Find.Result">
<short>True if an exact match for <var>AKey</var> was found.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Find.AKey">
<short>Key to search for.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Find.Index">
<short>Index of found key</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.IndexOf">
<short>Find index of a key in the list.</short>
<descr>
<var>IndexOf</var> returns the index of <var>AKey</var> in the list, or -1
if the key was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.Find"/>
<link id="TFPGMap.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMap.IndexOf.Result">
<short>Index of <var>AKey</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.IndexOf.AKey">
<short>Key value to search.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.IndexOfData">
<short>Find index of data value in the list.</short>
<descr>
<var>IndexOfData</var> returns the index of <var>AData</var> in the list, or -1
if the data was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.Find"/>
<link id="TFPGMap.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMap.IndexOfData.Result">
<short>Index of <var>AData</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.IndexOfData.AData">
<short>Data value to search</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMap.InsertKey">
<short>Insert a new key in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> at position <var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMap.InsertKeyData"/>
<link id="TFPGMap.Add"/>
<link id="TFPSMap.Delete"/>
<link id="TFPSMap.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.InsertKey.Index">
<short>Index at which to insert <var>AKey</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.InsertKey.AKey">
<short>Key to insert in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMap.InsertKeyData">
<short>Insert a new key with associated data in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> with associated data
<var>AData</var> at position <var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMap.InsertKey"/>
<link id="TFPGMap.Add"/>
<link id="TFPSMap.Delete"/>
<link id="TFPGMap.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.InsertKeyData.Index">
<short>Index at which to insert <var>AKey</var> and <var>AData</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.InsertKeyData.AKey">
<short>Key to insert in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.InsertKeyData.AData">
<short>Data to associate with <var>AKey</var></short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.Remove">
<short>Remove a key from the list</short>
<descr>
<var>Remove</var> removes the key <var>AKey</var> from the list, together
with its associated data. The function returns the index of <var>AKey</var>
prior to removal from the list, or -1 if <var>AKey</var> was not present in
the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.InsertKey"/>
<link id="TFPGMap.InsertKeyData"/>
<link id="TFPGMap.Add"/>
<link id="TFPSMap.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMap.Remove.Result">
<short>Index of <var>AKey</var> prior to removal.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Remove.AKey">
<short>Key to remove from the list.</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.Keys">
<short>Indexed access to the keys in the list.</short>
<descr>
<var>Keys</var> provides indexed access to the key values in the list. 
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Key values can always be read, but can only be written if the list is unsorted.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link id="EListError"/> exception will be
raised. The same exception is raised if a key is written and the list is sorted.
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMap.Data"/>
<link id="TFPGMap.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Keys.Index">
<short>Index of key value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.Data">
<short>Indexed access to the data in the list</short>
<descr>
<var>Data</var> provides indexed access to the data values in the list.
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Data can always be read or written.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link
id="EListError"/> exception will be raised.                      
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMap.Keys"/>  
<link id="TFPGMap.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.Data.Index">
<short>Index of data value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.KeyData">
<short>Access to data based on key</short>
<descr>
<var>KeyData</var> allows access to the data based on the key value
<var>AKey</var>. The data can be read and written. When writing, writing
using an existing key will overwrite the current data. If it does not exist
yet, it will be created. When reading, if the key is not present, an
<link id="EListError"/> will be raised.
</descr>
<errors>
If the key does not exist, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPSList.Count"/> 
<link id="TFPGMap.Keys"/>   
<link id="TFPGMap.Data"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMap.KeyData.AKey">
<short>Key associated with data value to read or write</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.OnCompare">
<short>Alias for <var>OnKeyCompare</var></short>
<descr>
<var>OnCompare</var> is a deprecated property, use <link id="TFPGMap.OnKeyCompare"/> instead.
</descr>
<seealso>
<link id="TFPGMap.OnKeyCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.OnKeyCompare">
<short>Compare function for key values.</short>
<descr>
<p>
<var>OnKeyCompare</var> can be set to a function that compares key values.
The default value for this event is a function that compares keys based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first key (<var>key1</var>) is
assumed to be 'less' than the second key (<var>key2</var>) and will be moved
before the second in the list.
</li>
<li>If the function result is positive, the first key (<var>key1</var>)
pointer is assumed to be 'greater than' the second key (<var>key2</var>)and will be moved after
the second in the list.
</li>
<li>if the function result is zero, the keys are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMap.OnDataCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMap.OnDataCompare">
<short>Compare function for data values.</short>
<descr>
<p>
<var>OnDataCompare</var> can be set to a function that compares data values.
The default value for this event is a function that compares data based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first data item (<var>Data1</var>) is
assumed to be 'less' than the second data item (<var>Data2</var>) and will be moved
before the second in the list.
</li>
<li>If the function result is positive, the first data item (<var>Data1</var>)
pointer is assumed to be 'greater than' the second data item (<var>Data2</var>)and will be moved after
the second in the list.
</li>
<li>if the function result is zero, the data items are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMap.OnKeyCompare"/>
</seealso>
</element>

<!-- generic class Visibility: default -->
<element name="TFPGMapInterfacedObjectData">
<short>Generic map for reference counted objects</short>
<descr>
<p>
<var>TFPGInterfacedObjectMap</var> is a generic map class. It can be used to specialize a map for any key
type, with associated data type that requires manual reference counting: any type which implements <var>IInterface</var>. 
For non-reference counted objects, <link id="TFPGMap"/> should be used.
</p>
<p>
This map class is entirely equivalent to <link id="TFPGMap"/>, but operates on
data items that require additional reference counting code on the data.
</p>
</descr>
<seealso>
<link id="TFPGMap"/> 
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMapInterfacedObjectData.TKey">
<short>Map Key type</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMapInterfacedObjectData.TData">
<short>Map data type, any type which implements <var>IInterface</var></short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Create">
<short>Create a new instance of the map</short>
<descr>
<var>Create</var> instantiates a new map. It mainly initializes the
<link id="TFPSMap"/> parent with the sized of the key and data.
</descr>
<seealso>
<link id="TFPSMap.Create"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Add">
<short>Add a key and value to the map</short>
<descr>
<var>Add</var> adds a new key <var>AKey</var> of generic type
<var>TKey</var>
with data value <var>AData</var> to the list and returns the position at
which 
the key was added. 
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is
raised.
If <link id="TFPSMap.Duplicates">Duplicates</link> is set to
<var>dupError</var>
and a duplicate key is added, an <link id="EListError"/> exception is
raised.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.Keys"/>
<link id="TFPGMapInterfacedObjectData.IndexOf"/>
<link id="TFPGMapInterfacedObjectData.KeyData"/>
<link id="TFPGMapInterfacedObjectData.Data"/>
<link id="TFPS.Duplicates"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Add.Result">
<short>Index of the new key</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Add.AKey">
<short>Key value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Add.AData">
<short>Data item</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Find">
<short>Find item based on key</short>
<descr>
<var>Find</var> will search the first key smaller than or equal
to <var>AKey</var> and return its index in <var>AIndex</var>. If the key was
not found then -1 is returned. The return value of the function is
<var>True</var> if an exact match for <var>AKey</var> is found,
<var>False</var> otherwise.
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData.IndexOf"/>
<link id="TFPGMapInterfacedObjectData.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Find.Result">
<short>True if an exact match for <var>AKey</var> was found.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Find.AKey">
<short>Key to search for</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Find.Index">
<short>Index of found key</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOf">
<short>Find index of a key in the list.</short>
<descr>
<var>IndexOf</var> returns the index of <var>AKey</var> in the list, or -1
if the key was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.Find"/>
<link id="TFPGMapInterfacedObjectData.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOf.Result">
<short>Index of <var>AKey</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOf.AKey">
<short>Key value to search.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOfData">
<short>Find index of data value in the list.</short>
<descr>
<var>IndexOfData</var> returns the index of <var>AData</var> in the list, or
-1
if the data was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.Find"/>
<link id="TFPGMapInterfacedObjectData.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOfData.Result">
<short>Index of <var>AData</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.IndexOfData.AData">
<short>Data value to search</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKey">
<short>Insert a new key in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> at position
<var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.InsertKeyData"/>
<link id="TFPGMapInterfacedObjectData.Add"/>
<link id="TFPSMapInterfacedObjectData.Delete"/>
<link id="TFPSMapInterfacedObjectData.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKey.Index">
<short>Index at which to insert <var>AKey</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKey.AKey">
<short>Key to insert in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKeyData">
<short>Insert a new key with associated data in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> with associated data
<var>AData</var> at position <var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.InsertKey"/>
<link id="TFPGMapInterfacedObjectData.Add"/>
<link id="TFPSMapInterfacedObjectData.Delete"/>
<link id="TFPGMapInterfacedObjectData.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKeyData.Index">
<short>Index at which to insert <var>AKey</var> and <var>AData</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKeyData.AKey">
<short>Key to insert in the list</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.InsertKeyData.AData">
<short>Data to associate with <var>AKey</var></short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Remove">
<short>Remove a key from the list</short>
<descr>
<var>Remove</var> removes the key <var>AKey</var> from the list, together
with its associated data. The function returns the index of <var>AKey</var>
prior to removal from the list, or -1 if <var>AKey</var> was not present in
the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.InsertKey"/>
<link id="TFPGMap.InsertKeyData"/>
<link id="TFPGMap.Add"/>
<link id="TFPGMapInterfacedObjectData.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Remove.Result">
<short>Index of <var>AKey</var> prior to removal</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Remove.AKey">
<short>Key to remove from the list</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Keys">
<short>Indexed access to the keys in the list.</short>
<descr>
<var>Keys</var> provides indexed access to the key values in the list. 
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Key values can always be read, but can only be written if the list is
unsorted.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link
id="EListError"/> exception will be
raised. The same exception is raised if a key is written and the list is
sorted.
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMapInterfacedObjectData.Data"/>
<link id="TFPGMapInterfacedObjectData.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Keys.Index">
<short>Index of key value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Data">
<short>Indexed access to the data in the list</short>
<descr>
<var>Data</var> provides indexed access to the data values in the list.
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Data can always be read or written.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link
id="EListError"/> exception will be raised.                      
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMapInterfacedObjectData.Keys"/>  
<link id="TFPGMapInterfacedObjectData.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.Data.Index">
<short>Index of data value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.KeyData">
<short>Access to data based on key</short>
<descr>
<var>KeyData</var> allows access to the data based on the key value
<var>AKey</var>. The data can be read and written. When writing, writing
using an existing key will overwrite the current data. If it does not exist
yet, it will be created. When reading, if the key is not present, an
<link id="EListError"/> will be raised.
</descr>
<errors>
If the key does not exist, an <link id="EListError"/> exception will be
raised.
</errors>
<seealso>
<link id="TFPSList.Count"/> 
<link id="TFPGMapInterfacedObjectData.Keys"/>   
<link id="TFPGMapInterfacedObjectData.Data"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapInterfacedObjectData.KeyData.AKey">
<short>Key associated with data value to read or write</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.OnCompare">
<short>Alias for <var>OnKeyCompare</var></short>
<descr>
<var>OnCompare</var> is a deprecated property, use <link id="TFPGMapInterfacedObjectData.OnKeyCompare"/> instead.
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData.OnKeyCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.OnKeyCompare">
<short>Compare function for key values.</short>
<descr>
<p>
<var>OnKeyCompare</var> can be set to a function that compares key values.
The default value for this event is a function that compares keys based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first key
(<var>key1</var>) is
assumed to be 'less' than the second key (<var>key2</var>) and will be moved
before the second in the list.
</li>
<li>If the function result is positive, the first key (<var>key1</var>)
pointer is assumed to be 'greater than' the second key (<var>key2</var>)and
will be moved after
the second in the list.
</li>
<li>if the function result is zero, the keys are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData.OnDataCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapInterfacedObjectData.OnDataCompare">
<short>Compare function for data values.</short>
<descr>
<p>
<var>OnDataCompare</var> can be set to a function that compares data values.
The default value for this event is a function that compares data based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first data item
(<var>Data1</var>) is
assumed to be 'less' than the second data item (<var>Data2</var>) and will
be moved
before the second in the list.
</li>
<li>If the function result is positive, the first data item
(<var>Data1</var>)
pointer is assumed to be 'greater than' the second data item
(<var>Data2</var>)and will be moved after
the second in the list.
</li>
<li>if the function result is zero, the data items are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData.OnKeyCompare"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGMap.TryGetData">
<short>Find data or return default</short>
<descr>
<var>TryGetData</var> will search the map for <var>AKey</var> and return
<var>True</var> or <var>False</var> depending on whether the value with the
given key was found. If the key was found, the associated value is returned
in <var>AData</var>, if it is not found a default value (using
<var>Default</var>) is returned.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.Find"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMap.AddOrSetData">
<short>Add data with given or set value if the key already exists.</short>
<descr>
<var>AddOrSetData</var> will check if key <var>AKey</var> already exists. if
yes, the value associated with it will be replaced with <var>AData</var>. If
the key does not yet exist, it will be added with value <var>AData</var>.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMap.TryGetData"/>
<link id="TFPGMap.Add"/>
<link id="TFPGMap.Find"/>
</seealso>
</element>

<!--
  ********************************************************************
    #rtl.fgl.TFPGMapObject
  ********************************************************************
-->

<!-- generic class Visibility: default -->
<element name="TFPGMapObject">
<short>Generic map</short>
<descr>
<var>TFPGMapObject</var> is a generic map class. It can be used to specialize a map for object types, 
but not objects with automated reference counting: For reference counted interface objects, 
<link id="TFPGMapInterfacedObjectData"/> must be used.
</descr>
<seealso>
<link id="TFPGMapInterfacedObjectData"/>
</seealso>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMapObject.TKey">
<short>Map Key type</short>
</element>

<!-- generic element Visibility: default -->
<element name="TFPGMapObject.TData">
<short>Map data type. This must be a <var>TObject</var> descendent</short>
</element>

<!-- constructor Visibility: public -->
<element name="TFPGMapObject.Create">
<short>Create a new instance of the map</short>
<descr>
<var>Create</var> instantiates a new map. It mainly initializes the
<link id="TFPSMap"/> parent with the sized of the key and data.
</descr>
<seealso>
<link id="TFPSMap.Create"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.Add">
<short>Add a key and value to the map</short>
<descr>
<var>Add</var> adds a new key <var>AKey</var> of generic type <var>TKey</var>
with data object <var>AData</var> to the list and returns the position at which 
the key was added. 
</descr>
<errors>
If the item could not be added, an <link id="EListError"/> exception is raised.
If <link id="TFPSMap.Duplicates">Duplicates</link> is set to <var>dupError</var>
and a duplicate key is added, an <link id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TFPGMapObject.Keys"/>
<link id="TFPGMapObject.IndexOf"/>
<link id="TFPGMapObject.KeyData"/>
<link id="TFPGMapObject.Data"/>
<link id="TFPSMap.Duplicates"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapObject.Add.Result">
<short>Index of the new key</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Add.AKey">
<short>Key value</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Add.AData">
<short>Data item</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.Find">
<short>Find item based on key</short>
<descr>
<var>Find</var> will search the first key smaller than or equal
to <var>AKey</var> and return its index in <var>AIndex</var>. If the key was
not found then -1 is returned. The return value of the function is
<var>True</var> if an exact match for <var>AKey</var> is found,
<var>False</var> otherwise.
</descr>
<seealso>
<link id="TFPGMapObject.IndexOf"/>
<link id="TFPGMapObject.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapObject.Find.Result">
<short>True if an exact match for <var>AKey</var> was found.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Find.AKey">
<short>Key to search for.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Find.Index">
<short>Index of found key</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.IndexOf">
<short>Find index of a key in the list.</short>
<descr>
<var>IndexOf</var> returns the index of <var>AKey</var> in the list, or -1
if the key was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapObject.Find"/>
<link id="TFPGMapObject.IndexOfData"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapObject.IndexOf.Result">
<short>Index of <var>AKey</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.IndexOf.AKey">
<short>Key value to search.</short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.IndexOfData">
<short>Find index of data value in the list.</short>
<descr>
<var>IndexOfData</var> returns the index of object <var>AData</var> in the list, or -1
if the data was not found in the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapObject.Find"/>
<link id="TFPGMapObject.IndexOf"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapObject.IndexOfData.Result">
<short>Index of <var>AData</var> in the list, -1 if not present.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.IndexOfData.AData">
<short>Data value to search</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapObject.InsertKey">
<short>Insert a new key in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> at position <var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMapObject.InsertKeyData"/>
<link id="TFPGMapObject.Add"/>
<link id="TFPSMap.Delete"/>
<link id="TFPSMap.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.InsertKey.Index">
<short>Index at which to insert <var>AKey</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.InsertKey.AKey">
<short>Key to insert in the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapObject.InsertKeyData">
<short>Insert a new key with associated data in the list</short>
<descr>
<var>InsertKey</var> inserts key <var>AKey</var> with associated data
<var>AData</var> at position <var>Index</var> in the list.
It is not allowed to insert a key in a sorted list.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], or the list is
sorted, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPGMapObject.InsertKey"/>
<link id="TFPGMapObject.Add"/>
<link id="TFPSMap.Delete"/>
<link id="TFPGMapObject.Remove"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.InsertKeyData.Index">
<short>Index at which to insert <var>AKey</var> and <var>AData</var></short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.InsertKeyData.AKey">
<short>Key to insert in the list.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.InsertKeyData.AData">
<short>Data to associate with <var>AKey</var></short>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.Remove">
<short>Remove a key from the list</short>
<descr>
<var>Remove</var> removes the key <var>AKey</var> from the list, together
with its associated data. The function returns the index of <var>AKey</var>
prior to removal from the list, or -1 if <var>AKey</var> was not present in
the list.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapObject.InsertKey"/>
<link id="TFPGMapObject.InsertKeyData"/>
<link id="TFPGMapObject.Add"/>
<link id="TFPSMap.Delete"/>
</seealso>
</element>

<!-- function result Visibility: public -->
<element name="TFPGMapObject.Remove.Result">
<short>Index of <var>AKey</var> prior to removal.</short>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Remove.AKey">
<short>Key to remove from the list.</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.Keys">
<short>Indexed access to the keys in the list.</short>
<descr>
<var>Keys</var> provides indexed access to the key values in the list. 
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Key values can always be read, but can only be written if the list is unsorted.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link id="EListError"/> exception will be
raised. The same exception is raised if a key is written and the list is sorted.
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMapObject.Data"/>
<link id="TFPGMapObject.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Keys.Index">
<short>Index of key value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.Data">
<short>Indexed access to the data in the list</short>
<descr>
<var>Data</var> provides indexed access to the data values in the list.
Valid values for <var>Index</var> are in the range <var>[0..Count-1]</var>.
Data can always be read or written.
</descr>
<errors>
If the index <var>AIndex</var> is out of range [0..Count-1], an <link
id="EListError"/> exception will be raised.                      
</errors>
<seealso>
<link id="TFPSList.Count"/>
<link id="TFPGMapObject.Keys"/>  
<link id="TFPGMapObject.KeyData"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.Data.Index">
<short>Index of data value to retrieve</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.KeyData">
<short>Access to data based on key</short>
<descr>
<var>KeyData</var> allows access to the data based on the key value
<var>AKey</var>. The data can be read and written. When writing, writing
using an existing key will overwrite the current data. If it does not exist
yet, it will be created. When reading, if the key is not present, an
<link id="EListError"/> will be raised.
</descr>
<errors>
If the key does not exist, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPSList.Count"/> 
<link id="TFPGMapObject.Keys"/>   
<link id="TFPGMapObject.Data"/>
</seealso>
</element>

<!-- argument Visibility: public -->
<element name="TFPGMapObject.KeyData.AKey">
<short>Key associated with data value to read or write</short>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.OnCompare">
<short>Alias for <var>OnKeyCompare</var></short>
<descr>
<var>OnCompare</var> is a deprecated property, use <link id="TFPGMapObject.OnKeyCompare"/> instead.
</descr>
<seealso>
<link id="TFPGMapObject.OnKeyCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.OnKeyCompare">
<short>Compare function for key values.</short>
<descr>
<p>
<var>OnKeyCompare</var> can be set to a function that compares key values.
The default value for this event is a function that compares keys based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first key (<var>key1</var>) is
assumed to be 'less' than the second key (<var>key2</var>) and will be moved
before the second in the list.
</li>
<li>If the function result is positive, the first key (<var>key1</var>)
pointer is assumed to be 'greater than' the second key (<var>key2</var>)and will be moved after
the second in the list.
</li>
<li>if the function result is zero, the keys are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMapObject.OnDataCompare"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TFPGMapObject.OnDataCompare">
<short>Compare function for data values.</short>
<descr>
<p>
<var>OnDataCompare</var> can be set to a function that compares data values.
The default value for this event is a function that compares data based on a
byte-by-byte comparison of the memory block.
The function must have the following semantics:
</p>
<ul>
<li>If the result of this function is negative, the first data item (<var>Data1</var>) is
assumed to be 'less' than the second data item (<var>Data2</var>) and will be moved
before the second in the list.
</li>
<li>If the function result is positive, the first data item (<var>Data1</var>)
pointer is assumed to be 'greater than' the second data item (<var>Data2</var>)and will be moved after
the second in the list.
</li>
<li>if the function result is zero, the data items are assumed to be 'equal'
and no moving will take place.
</li>
</ul>
</descr>
<seealso>
<link id="TFPGMapObject.OnKeyCompare"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TFPGMapObject.TryGetData">
<short>Find data or return default</short>
<descr>
<var>TryGetData</var> will search the map for <var>AKey</var> and return
<var>True</var> or <var>False</var> depending on whether the value with the
given key was found. If the key was found, the associated value is returned
in <var>AData</var>, if it is not found a default value (using
<var>Default</var>) is returned.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapObject.Find"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapObject.AddOrSetData">
<short>Add data with given or set value if the key already exists.</short>
<descr>
<var>AddOrSetData</var> will check if key <var>AKey</var> already exists. if
yes, the value associated with it will be replaced with <var>AData</var>. If
the key does not yet exist, it will be added with value <var>AData</var>.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapObject.TryGetData"/>
<link id="TFPGMapObject.Add"/>
<link id="TFPGMapObject.Find"/>
</seealso>
</element>


<!-- function Visibility: public -->
<element name="TFPGMapInterfacedObjectData.TryGetData">
<short>Find data or return default</short>
<descr>
<var>TryGetData</var> will search the map for <var>AKey</var> and return
<var>True</var> or <var>False</var> depending on whether the value with the
given key was found. If the key was found, the associated value is returned
in <var>AData</var>, if it is not found a default value (using
<var>Default</var>) is returned.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.Find"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGMapInterfacedObjectData.AddOrSetData">
<short>Add data with given or set value if the key already exists.</short>
<descr>
<var>AddOrSetData</var> will check if key <var>AKey</var> already exists. if
yes, the value associated with it will be replaced with <var>AData</var>. If
the key does not yet exist, it will be added with value <var>AData</var>.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TFPGMapInterfacedObjectData.TryGetData"/>
<link id="TFPGMapInterfacedObjectData.Add"/>
<link id="TFPGMapInterfacedObjectData.Find"/>
</seealso>
</element>

<!-- uses unit Visibility: default -->
<element name="types">
<short>Several base types</short>
</element>

<!-- uses unit Visibility: default -->
<element name="sysutils">
<short>Exceptions and other auxiliary routines</short>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.DeleteRange">
<short>Delete a range of elements</short>
<descr>
<var>DeleteRange</var> deletes elements from <var>IndexFrom</var> till <var>IndexTo</var>. Both indexes are zero based, and 
<var>IndexTo</var> must be bigger than <var>IndexFrom</var>. 
Using this method results in less moving of data in memory, 
and as such is more effective than deleting the elements one by one using <link id="TFPSList.Delete"/>.
</descr>
<errors>
If invalid indexes are specified, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="EListError"/>
<link id="TFPSList.Delete"/>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TFPSList.AddList">
<short>Adds the elements from another list</short>
<descr>
<var>AddList</var> adds all the elements from list <var>Obj</var> to the current list. A check is done that the 2 lists have the same element size.
</descr>
<errors>
If the lists have different element size, an <link id="EListError"/> exception will be raised.
</errors>
<seealso>
<link id="TFPSList.Add"/>
<link id="EListError"/>
</seealso>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGListEnumerator.T">
<short>List enumerator type</short>
<descr>
<var>T</var> is the type of element in the enumerator
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGList.T">
<short>List element type</short>
<descr>
<var>T</var> is the type of element in the list
</descr>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGList.AddList">
<short>Adds the elements from another list</short>
<descr>
<var>AddList</var> adds all the elements from list <var>Source</var> to the current list. 
</descr>
<seealso>
<link id="TFPGList.Add"/>
<link id="TFPSList.AddList"/>
<link id="TFPGObjectList.AddList"/>
</seealso>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGObjectList.T">
<short>Object list element type</short>
<descr>
<var>T</var> is the type of element in the list.
</descr>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGObjectList.AddList">
<short>Adds the elements from another list</short>
<descr>
<var>AddList</var> adds all the elements from list <var>Source</var> to the current list. 
</descr>
<seealso>
<link id="TFPGList.AddList"/>
<link id="TFPSList.AddList"/>
<link id="TFPGObjectList.Add"/>
</seealso>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGInterfacedObjectList.T">
<short>Interfaced object list element type</short>
<descr>
<var>AddList</var> adds all the elements from list <var>Source</var> to the current list.
</descr>
</element>

<!-- procedure Visibility: public -->
<element name="TFPGInterfacedObjectList.AddList">
<short>Adds the elements from another list</short>
<descr>
<var>AddList</var> adds all the elements from list <var>Source</var> to the current list. 
</descr>
<seealso>
<link id="TFPGList.AddList"/>
<link id="TFPSList.AddList"/>
<link id="TFPGObjectList.AddList"/>
<link id="TFPGInterfacedObjectList.Add"/>
</seealso>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMap.TKey">
<short>Key type</short>
<descr>
<var>TKey</var> is the map key type.
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMap.TData">
<short>Data type</short>
<descr>
<var>TData</var> is the map data element type.
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMapObject.TKey">
<short>Key type</short>
<descr>
<var>TKey</var> is the map key type.
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMapObject.TData">
<short>Data type</short>
<descr>
<var>TData</var> is the map data type. It must be a descendent of <var>TObject</var>
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMapInterfacedObjectData.TKey">
<short>Key type</short>
<descr>
<var>TKey</var> is the map key type.
</descr>
</element>

<!-- generic type Visibility: default -->
<element name="TFPGMapInterfacedObjectData.TData">
<short>Data type</short>
<descr>
<var>TData</var> is the map data type. It must be a descendent of <var>TInterfacedObject</var>
</descr>
</element>

</module> <!-- fgl -->

</package>
</fpdoc-descriptions>