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

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

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

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

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
ExtendedStrings
====================================================================
-->
<module name="ExtendedStrings">
<short>
Implements an extended string list that allows its Objects property to hold 
records.
</short>
<descr>
<p>
<file>extendedstrings.pas</file> implements <var>TExtendedStrings</var>, 
which is a <var>TStringList</var> that allows its <var>Objects</var> property 
to hold any type of record.
</p>
<p>
<file>extendedstrings.pas</file> is part of the <file>LazUtils</file> package.
</p>
<p>
Author: Mattias Gaertner
</p>
</descr>

<!-- unresolved references -->
<element name="Classes"/>
<element name="SysUtils"/>

<!-- enumeration type Visibility: default -->
<element name="TExtStringsOption">
<short>
Defines actions needed when creating or freeing records in 
TExtendedStringList.
</short>
<descr>
<p>
<var>TExtStringsOption</var> is an enumeration type with values that define 
actions needed when creating or freeing records in TExtendedStringList. 
Values from TExtStringsOption are stored in the <var>TExtStringsOptions</var> 
type.
</p>
</descr>
<seealso>
<link id="TExtStringsOption"/>
<link id="TExtStringsOptions"/>
</seealso>
</element>
<element name="TExtStringsOption.esoClearRecordsOnCreate">
<short>Memory allocated to a new record is cleared (filled with #0).</short>
</element>
<element name="TExtStringsOption.esoFreeObjectsOnDelete">
<short>Objects call their free method before they are deleted.</short>
</element>

<element name="TExtStringsOptions">
<short>
Stores TExtStringsOption values.
</short>
<descr>
<p>
<var>TExtStringsOptions</var> is a set type used to store 
<var>TExtStringsOption</var> values. TExtStringsOptions is the type used for 
the <var>TExtendedStringList.Options</var> property.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.Options"/>
</seealso>
</element>

<element name="TExtendedStringList">
<short>
Implements a string list that allows Records in its Objects property.
</short>
<descr>
<p>
<var>TExtendedStringList</var> is a <var>TStringList</var> descendant that 
provides support for using records in the class. The <var>Records</var> 
property allows access to records stored in the class. TExtendedStringList 
provides overridden methods to maintain values in the <var>Objects</var> 
property. New properties and methods are included to perform actions needed 
when adding or freeing Records stored in the Objects property.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>

<!-- private members -->
<element name="TExtendedStringList.FOptions"/>
<element name="TExtendedStringList.FRecordSize"/>

<element name="TExtendedStringList.GetRecords"/>
<element name="TExtendedStringList.GetRecords.Result"/>
<element name="TExtendedStringList.GetRecords.Index"/>

<element name="TExtendedStringList.SetOptions"/>
<element name="TExtendedStringList.SetOptions.AValue"/>

<element name="TExtendedStringList.SetRecords"/>
<element name="TExtendedStringList.SetRecords.Index"/>
<element name="TExtendedStringList.SetRecords.AValue"/>

<element name="TExtendedStringList.SetRecordSize"/>
<element name="TExtendedStringList.SetRecordSize.AValue"/>

<element name="TExtendedStringList.DoResizeRecord"/>
<element name="TExtendedStringList.DoResizeRecord.Index"/>
<element name="TExtendedStringList.DoResizeRecord.OldSize"/>
<element name="TExtendedStringList.DoResizeRecord.NewSize"/>

<!-- protected -->
<element name="TExtendedStringList.ResizeRecord">
<short>
Changes the memory allocation size for the specified record.
</short>
<descr>
<p>
<var>ResizeRecord</var> is a procedure used to change the memory allocation 
size for the specified record. ResizeRecord calls <var>ReAllocMem</var> to 
change the allocated memory size to the value in <var>NewSize</var>. 
ResizeRecord is called when the value in the <var>RecordSize</var> property 
is changed.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.RecordSize"/>
</seealso>
</element>
<element name="TExtendedStringList.ResizeRecord.ARecord">
<short>Pointer to the record.</short>
</element>
<element name="TExtendedStringList.ResizeRecord.Index">
<short>Ordinal position for the specified record.</short>
</element>
<element name="TExtendedStringList.ResizeRecord.OldSize">
<short>Previous memory allocation size.</short>
</element>
<element name="TExtendedStringList.ResizeRecord.NewSize">
<short>New memory allocation size.</short>
</element>

<element name="TExtendedStringList.GetObject">
<short>
Re-implements the read access specifier for the Objects property.
</short>
<descr>
<p>
<var>GetObject</var> is an overridden TObject function which re-implements 
the read access specifier for the Objects property. GetObject calls the 
inherited method to retrieve the value at the position in Index. GetObject 
ensures that the return value is cast to a TObject instance when assigned, or 
<var>Nil</var> when unassigned.
</p>
<p>
GetObject and PutObject are called directly (as opposed to using the Objects 
property) in methods which maintain values in Records.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>
<element name="TExtendedStringList.GetObject.Result">
<short>TObject stored at the specified position.</short>
</element>
<element name="TExtendedStringList.GetObject.Index">
<short>Ordinal position for the requested value.</short>
</element>

<element name="TExtendedStringList.PutObject">
<short>
Reimplements the write access specifier for the Objects property.
</short>
<descr>
<p>
<var>PutObject</var> is an overridden procedure which reimplements the write 
access specifier for the Objects property. PutObject uses a pointer to the 
value in Records stored at the position in Index. If a record has not been 
stored at the position, CreateRecord is called to allocate and initialize the 
memory for the record. The value in AnObject is stored in Records at the 
position in Index.
</p>
<p>
GetObject and PutObject are called directly (as opposed to using the Objects 
property) in methods which maintain values in Records.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>
<element name="TExtendedStringList.PutObject.Index">
<short>Ordinal position for value.</short>
</element>
<element name="TExtendedStringList.PutObject.AnObject">
<short>Object to store at the specified position.</short>
</element>

<!-- public -->
<element name="TExtendedStringList.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the overloaded constructor for the class instance. 
Create calls the inherited constructor, and sets the default values 
in the following properties:
</p>
<dl>
<dt>Options</dt>
<dd>Set to <var>[ esoClearRecordsOnCreate ]</var>.</dd>
<dt>RecordSize</dt>
<dd>Set to the value in the <var>InitialRecordSize</var> argument.</dd>
</dl>
<p>
Use RecordSize to change the memory allocation size for Records in the class.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList">TStringList</link>
</seealso>
</element>
<element name="TExtendedStringList.Create.InitialRecordSize">
<short>Memory size allocated for records.</short>
</element>

<element name="TExtendedStringList.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy calls FreeAllRecords to release memory allocated for entries in the 
Records property. Destroy calls the inherited destructor.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList.Destroy">TStringList.Destroy</link>
</seealso>
</element>

<element name="TExtendedStringList.Clear">
<short>
Removes items stored in the string list.
</short>
<descr>
<p>
<var>Clear</var> is an overridden procedure used to remove items stored in 
the string list. Clear calls FreeAllRecords to release memory allocated for 
items in the Records property. Clear calls the inherited Clear method.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList.Clear">TStringList.Clear</link>
</seealso>
</element>

<element name="TExtendedStringList.Delete">
<short>
Deletes the item at the specified position.
</short>
<descr>
<p>
<var>Delete</var> is an overridden procedure used to delete the item at the 
specified position in the string list. Delete ensures that memory allocated 
in Records is freed by calling FreeRecord using the position in Index. Delete 
calls the inherited Delete method.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStringList.Delete">TStringList.Delete</link>
</seealso>
</element>
<element name="TExtendedStringList.Delete.Index">
<short>Ordinal position for the item.</short>
</element>

<element name="TExtendedStringList.CreateRecord">
<short>
Allocates memory for a new record instance.
</short>
<descr>
<p>
<var>CreateRecord</var> is a procedure used to allocate (and optionally 
initialize) memory for a new value in the Records property. CreateRecord 
calls GetMem to allocate the memory size specified in the RecordSize 
property. When Options includes the value <var>esoClearRecordsOnCreate</var>, 
the allocated memory is filled with the character value <var>#0</var>. 
CreateRecord calls the inherited PutObject method to store the new record.
</p>
<p>
CreateRecord is called when reading a value in the Records property, and when 
writing a value to the Objects property.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.RecordSize"/>
<link id="TExtendedStringList.Options"/>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>
<element name="TExtendedStringList.CreateRecord.Index">
<short>Ordinal position for the record.</short>
</element>

<element name="TExtendedStringList.FreeRecord">
<short>
Frees memory allocated for the record at the specified position.
</short>
<descr>
<p>
<var>FreeRecord</var> is a procedure used to free memory allocated for the 
record at the specified position. FreeRecord calls the inherited GetObject 
method to get the value stored in the Objects property. If a record has been 
allocated, and Options contains the value esoFreeObjectsOnDelete, the object 
instance in Objects is freed. FreeRecord calls FreeMem to release memory 
allocated for the record, and calls the inherited PutObject method to store 
the <var>Nil</var>'d object reference.
</p>
<p>
FreeRecord is called when writing a new value in the Records property, and in 
methods like FreeAllRecords and Delete.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.RecordSize"/>
<link id="TExtendedStringList.Options"/>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>
<element name="TExtendedStringList.FreeRecord.Index">
<short>Ordinal position for the record.</short>
</element>

<element name="TExtendedStringList.FreeAllRecords">
<short>
Frees memory allocated for all Records in the class.
</short>
<descr>
<p>
<var>FreeAllRecords</var> is a procedure used to free memory allocated for 
the Records in the class. FreeAllRecords iterates over the items in the 
string list, and calls the FreeRecord method to free memory allocated for 
each item.
</p>
<p>
FreeAllRecords is called in the Clear method, and in the destructor for the 
class.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.Records"/>
<link id="TExtendedStringList.Clear"/>
</seealso>
</element>

<element name="TExtendedStringList.RecordAllocated">
<short>
Determines if memory has been allocated for the specified record.
</short>
<descr>
<p>
<var>RecordAllocated</var> is a Boolean function which determines if memory 
has been allocated for the record at the specified position. The return value 
is <b>True</b> if the item at the Index position in Objects contains a value 
other than <var>Nil</var>.
</p>
<p>
RecordAllocated is called when reading a value for the Records property.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.Records"/>
</seealso>
</element>
<element name="TExtendedStringList.RecordAllocated.Result">
<short><b>True</b> if memory has been allocated for the record.</short>
</element>
<element name="TExtendedStringList.RecordAllocated.Index">
<short>Ordinal position for the record.</short>
</element>

<element name="TExtendedStringList.Records">
<short>
Provides indexed access to records in the string list.
</short>
<descr>
<p>
<var>Records</var> an indexed Pointer property that provides access to 
records stored in the string list. Index is the ordinal position in the list 
for the desired record.
</p>
<p>
Reading a value in Records causes a record to be created using CreateRecord 
if one has not already been allocated. The record pointer is retrieved by 
calling the inherited GetObject method.
</p>
<p>
Writing a new value in Records causes a previous record value to be freed by 
calling FreeRecord. The inherited PutObject method is called to store the 
value in AValue as a TObject reference in the Objects property.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.RecordSize"/>
<link id="TExtendedStringList.Options"/>
<link id="TExtendedStringList.FreeRecord"/>
<link id="TExtendedStringList.FreeAllRecords"/>
<link id="TExtendedStringList.Clear"/>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>
<element name="TExtendedStringList.Records.Index">
<short>Ordinal position for the record.</short>
</element>

<element name="TExtendedStringList.RecordSize">
<short>
Memory allocation size for Records in the class.
</short>
<descr>
<p>
<var>RecordSize</var> is an Integer property that specifies the memory 
allocation size for Records in the class. The initial value for the property 
is set to the argument passed in the constructor. Setting a new value for the 
property causes the allocated memory size for any existing Records to be 
changed to the new value.
</p>
<p>
RecordSize is used in the CreateRecord method and indicates the initial size 
for the block of memory allocated for the record instance using GetMem.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.Records"/>
<link id="TExtendedStringList.CreateRecord"/>
<link id="TExtendedStringList.Options"/>
</seealso>
</element>

<element name="TExtendedStringList.Options">
<short>
Contains record options enabled in the class.
</short>
<descr>
<p>
<var>Options</var> is a <var>TExtStringsOptions</var> property that contains 
the record options enabled for the class. Options can contains values from 
the <var>TExtStringsOption</var> enumeration, including:
</p>
<dl>
<dt><var>esoClearRecordsOnCreate</var></dt>
<dd>
Memory allocated to a new record is cleared (filled with <var>#0</var>)
</dd>
<dt><var>esoFreeObjectsOnDelete</var></dt>
<dd>
Objects call their free method before they are deleted
</dd>
</dl>
<p>
The default value for the property is <var>[ esoClearRecordsOnCreate ]</var> 
as set in the constructor for the class.
</p>
</descr>
<seealso>
<link id="TExtendedStringList.CreateRecord"/>
<link id="TExtendedStringList.FreeRecord"/>
<link id="TExtendedStringList.Create"/>
<link id="TExtStringsOptions"/>
<link id="TExtStringsOption"/>
</seealso>
</element>

</module>
<!-- ExtendedStrings -->

</package>
</fpdoc-descriptions>