Implements an extended string list that allows its Objects property to hold records.

extendedstrings.pas implements TExtendedStrings, which is a TStringList that allows its Objects property to hold any type of record.

This file is part of the LazUtils package.

Author: Mattias Gaertner

Defines actions needed when creating or freeing records in TExtendedStringList.

TExtStringsOption is an enumeration type with values that define actions needed when creating or freeing records in TExtendedStringList. Values from TExtStringsOption are stored in the TExtStringsOptions type.

Memory allocated to a new record is cleared (filled with #0).
Objects call their free method before they are deleted.
Stores TExtStringsOption values.

TExtStringsOptions is a set type used to store TExtStringsOption values. TExtStringsOptions is the type used for the TExtendedStringList.Options property.

Implements a string list that allows Records in its Objects property.

TExtendedStringList is a TStringList descendant that provides support for using records in the class. The Records property allows access to records stored in the class. TExtendedStringList provides overridden methods to maintain values in the Objects property. New properties and methods are included to control actions needed when adding or freeing Records stored in the Objects property.

TStringList
Changes the memory allocation size for the specified record.

ResizeRecord is a procedure used to change the memory allocation size for the specified record. ResizeRecord calls ReAllocMem to change the allocated memory size to the value in NewSize. ResizeRecord is called when the value in the RecordSize property is changed.

Pointer to the record.
Ordinal position for the specified record.
Previous memory allocation size.
New memory allocation size.
Re-implements the read access specifier for the Objects property.

GetObject 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 Nil when unassigned.

GetObject and PutObject are called directly (as opposed to using the Objects property) in methods which maintain values in Records.

TObject stored at the specified position.
Ordinal position for the requested value.
Reimplements the write access specifier for Objects.

PutObject 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.

GetObject and PutObject are called directly (as opposed to using the Objects property) in methods which maintain values in Records.

Ordinal position for value.
Object to store at the specified position.
Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor, and sets the default values in the following properties:

Options
  Set to [ esoClearRecordsOnCreate ]
RecordSize
  Set to the value in the InitialRecordSize argument

Use RecordSize to change the memory allocation size for Records in the class.

Memory size allocated for records.
Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy calls FreeAllRecords to release memory allocated for entries in the Records property. Destroy calls the inherited destructor.

Removes items stored in the string list.

Clear 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.

Deletes the item at the specified position.

Delete 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.

Ordinal position for the item.
Allocates memory for a new record instance.

CreateRecord 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 esoClearRecordsOnCreate, the allocated memory is filled with the character value #0. CreateRecord calls the inherited PutObject method to store the new record.

CreateRecord is called when reading a value in the Records property, and when writing a value to the Objects property.

Ordinal position for the record.
Frees memory allocated for the record at the specified position.

FreeRecord 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 Nil'd object reference.

FreeRecord is called when writing a new value in the Records property, and in methods like FreeAllRecords and Delete.

Ordinal position for the record.
Frees memory allocated for all Records in the class.

FreeAllRecords 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.

FreeAllRecords is called in the Clear method, and in the destructor for the class.

Determines if memory has been allocated for the specified record.

RecordAllocated is a Boolean function which determines if memory has been allocated for the record at the specified position. The return value is True if the item at the Index position in Objects contains a value other than Nil.

RecordAllocated is called when reading a value for the Records property.

True if memory has been allocated for the record.
Ordinal position for the record.
Provides indexed access to records in the string list.

Records 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.

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.

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.

Ordinal position for the record.
Memory allocation size for Records in the class.

RecordSize 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.

Contains record options enabled in the class.

Options is a TExtStringsOptions property that contains the record options enabled for the class. Options can contains values from the TExtStringsOption enumeration, including:

esoClearRecordsOnCreate
  Memory allocated to a new record is cleared (filled with #0)
esoFreeObjectsOnDelete
  Objects call their free method before they are deleted

The default value for the property is [ esoClearRecordsOnCreate ] as set in the constructor for the class.