Units
Classes, Interfaces, Objects
Types
Variables
Constants
Functions, Procedures
Identifiers

Class TExContainer

Unit

rjExContainers

Declaration

type TExContainer = class(TErrorObject)

Description

Containers in the rjExCont Library store data of any type starting from integers to strings, records, and object instances.

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:

Do not create instances of TExContainer, only use it to derive new types of containers compatible with TExContainer.

Hierarchy

TErrorObject

Fields

NameDescription
FCount See Count.
FItemSize See ItemSize.
FOnFreeItem See OnFreeItem.
FOnInitItem See OnInitItem.

Methods

Overview

constructor Create; virtual;
constructor CreateWithItemSize(const AItemSize: Integer);
destructor Destroy; override;
function IsEmpty: Boolean;
function IsNotEmpty: Boolean;
procedure SetItemSize(const NewItemSize: Integer); virtual;

Description

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.

Properties

Overview

Count: Integer;
ItemSize: Integer;
OnFreeItem: TExFreeItemProc;
OnInitItem: TExInitItemProc;

Description

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


rjExContainer Library Version 0.2.
Copyright Ralf Junker 2000-2001.
http://www.zeitungsjunge.de/delphi/.