type TExContainer = class(
TErrorObject
)
For a general term, we will call the container's data Items. Items are made up of one or more Elements. As such, they resemble Pascal records with one or more elements or simply one of the basic Pascal types like Integer, Cardinal, AnsiString and so on.
TExContainer is the most abstract base class in the rjExContainers Library. As such, it has no knowledge of the structure of the Items it stores. However, it provides three key properties to let the container know about how to perform basic operations on each Item:
ItemSize
: Size in bytes of one Item in the container. Related method: CreateWithItemSize
. OnInitItem
: Procedure called each time an Item needs to be initialized. OnFreeItem
: Procedure called each time an Item needs to be freed / finalized. Do not create instances of TExContainer, only use it to derive new types of containers compatible with TExContainer.
TErrorObject
Name | Description |
---|---|
FCount | See Count . |
FItemSize | See ItemSize . |
FOnFreeItem | See OnFreeItem . |
FOnInitItem | See OnInitItem . |
constructor Create; virtual; |
constructor CreateWithItemSize(const AItemSize: Integer); |
Constructs a container and sets its ItemSize
to AItemSize
.
Use the CreateWithItemSize
contructor to create a container and at the same time set its ItemSize
to a value greater than its default ItemSize
.
CreateWithItemSize
is an easy way of creating container descendants "on the fly". It tells the container to allocate additional memory for its Items to store extra information. New Elements must always be added after the container's default elements.
Care must be taken not to interfere with the memory de/allocation of the default Elements. You may set OnInitItem
and OnFreeItem
to the appropriate procedures to automate this task.
destructor Destroy; override; |
Destroys an instance of TExContainer
.
function IsEmpty: Boolean; |
Returns True if the container is empty, i.e. does not contain any Items.
function IsNotEmpty: Boolean; |
Returns True if the container is not empty, i.e. contains at least one or more Items.
procedure SetItemSize(const NewItemSize: Integer); virtual; |
Sets the ItemSize
.
Count: Integer; |
ItemSize: Integer; |
OnFreeItem: TExFreeItemProc; |
OnInitItem: TExInitItemProc; |
Count: Integer; |
Indicates the number of items in the container. Use Count
when iterating over all the items in the container. Count
is read only in TExContainer
, but descendend classes might introcuce methods to set the number of items by writing to Count
.
ItemSize: Integer; |
The size in bytes of each Item stored in the container. Applications can set ItemSize
only if the container is empty (Count
= 0), and only to a size equal or greater than the current ItemSize
. This is a precaution to prevent memory corruption.
Another way of setting ItemSize
is by passing a value to the CreateWithItemSize
constructor. Descendant classes best do so by overriding the Create
method and setting it there.
ItemSize
should generally be computed by applying the compiler's SizeOf
operator to the Item type. For example, if the Items are Integers, call CreateWithItemSize
(SizeOf(Integer))
. Whenever a new Item is inserted, the container allocates ItemSize
bytes of heap memory for that Item.
OnFreeItem: TExFreeItemProc; |
OnFreeItem
is a procedural variable of the type TExFreeItemProc
. It will be called each time an Item is deleted or the container is cleared or destroyed and the Items are to be destroyed as well. The OnFreeItem
procedure must free / finalize one single Item, and will be called once for each Item in the container.
Two parameters are passed into the procedure: A reference to the calling container and an untyped Pointer. This pointer must be typecast to the appropriate Item type in the procedure in order to successfully free the Item.
There is generally no need to assign OnFreeItem
if none of the Item's Elements are dynamically allocated. Dynamically allocated Elements include long strings (AnsiString, WideString) and Dynamic Arrays. The procedure assigned to OnFreeItem
must properly free those dynamic elements in order to avoid memory leaks. It can also be used to free objects of an object-owner container (as in TObjectOwnerVector
).
See also: OnInitItem
OnInitItem: TExInitItemProc; |
OnInitItem
is a procedural variable of the type TExInitItemProc
. This procedure will be called each time a new Item will be inserted into the container and needs to be initialized. The OnInitItem
procedure must initialize one single Item, and will be called once for each Item in the container.
Two parameters are passed into the procedure: A reference to the calling container and an untyped Pointer. This pointer must be typecast to the appropriate Item type in the procedure in order to successfully initialize the Item.
There is generally no need to assign OnInitItem
if none of the Item's Elements are dynamically allocated. Dynamically allocated Elements include long strings (AnsiString, WideString) and Dynamic Arrays, which must all be initalized with zeros. The procedure assigned to OnInitItem
must properly initialize those dynamic elements in order to avoid wrong memory allocations. It can also be used, for example, to create objects of object containers.
See also: OnFreeItem