mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-05-01 14:43:51 +02:00
499 lines
15 KiB
XML
499 lines
15 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
|
|
Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus
|
|
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0
|
|
International public license.
|
|
|
|
https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
|
|
file://../../cc-by-sa-4-0.txt
|
|
|
|
Copyright (c) 1997-2024, 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>
|