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

Class TExVector

Unit

rjExVectors

Declaration

type TExVector = class(TExContainer)

Description

Base class to maintain an array-based vector of Items. The Items are referenced by a zero-based index number. The container's vector automatically expands when required to insert new Items.

Containers based on TExVector are very similar to Delphi's TList or TStringList, except that they are more flexible, fully extendable and can store Items of very different flavors.

The following containers included in rjExContainer Library are descendants of TExVector:

Hierarchy

TExContainer > TErrorObject

Fields

NameDescription
FVector Pointer to the vector's memory.

Methods

Overview

destructor Destroy; override;
procedure AdjustCapacity(const NewCount: Integer);
procedure Clear; virtual;
procedure DeleteAt(const Index: Integer);
procedure DeleteFirst;
procedure DeleteLast;
procedure Exchange(const Index1, Index2: Integer);
procedure ExchangeItems(const Item1, Item2: Pointer);
function ExistAll(const PItems: array of Pointer; const Same: TExSameItemsFunc): Boolean;
function ExistAny(const PItems: array of Pointer; const Same: TExSameItemsFunc): Boolean;
function Exists(const PItem: Pointer; const Same: TExSameItemsFunc): Boolean;
function ExistsBack(const PItem: Pointer; const Same: TExSameItemsFunc): Boolean;
function Find(const PItem: Pointer; const Compare: TExCompareItemsFunc; out Index: Integer): Boolean;
function FindDesc(const PItem: Pointer; const Compare: TExCompareItemsFunc; out Index: Integer): Boolean;
function GetPFirstItem: Pointer;
function GetPItemAt(const Index: Integer): Pointer;
function GetPLastItem: Pointer;
function IndexBackOf(const PItem: Pointer; const Same: TExSameItemsFunc): Integer;
function IndexOf(const PItem: Pointer; const Same: TExSameItemsFunc): Integer;
function InsertItemAt(const Index: Integer): Pointer;
function InsertItemFirst: Pointer;
function InsertItemLast: Pointer;
procedure Iterate(const Action: TExIterateProc; const ExtraData: Pointer; const Index: Integer = 0; Count: Integer = 0);
function LoadFromFile(const FileName: AnsiString): Boolean;
function LoadFromStream(const Stream: TStream): Boolean; virtual;
procedure Move(const CurrentIndex, NewIndex: Integer);
function PItemBackOf(const PItem: Pointer; const Same: TExSameItemsFunc): Pointer;
function PItemOf(const PItem: Pointer; const Same: TExSameItemsFunc): Pointer;
procedure RemoveAll(const Item: Pointer; const Same: TExSameItemsFunc);
procedure SaveToFile(const FileName: AnsiString);
procedure SaveToStream(const Stream: TStream); virtual;
procedure SetCount(const NewCount: Integer);
procedure SetCountNoInit(const NewCount: Integer);
procedure Sort(const Compare: TExCompareItemsFunc);
procedure SortDesc(const Compare: TExCompareItemsFunc);

Description

destructor Destroy; override;

Destroys an instance of TExVector. Do not call Destroy directly in an application. Instead, call Free. Free verifies that the Destroy object is not already freed and only then calls Destroy.

If OnFreeItem is assigend, it will be called to free / finalize each Item in the vector. Then Destroy frees the memory allocated to hold the Items before calling the inherited destructor.

procedure AdjustCapacity(const NewCount: Integer);

Ensures that enough memory is allocated to FVector in order to hold NewCount bytes.

procedure Clear; virtual;

Deletes all Items from a vector container.

If OnFreeItem is assigned, it will be called for each Item starting with the first (Index equal to zero) and all Items will be freed / finalized accordingly.

procedure DeleteAt(const Index: Integer);

Removes the Item specified by the Index parameter.

Call DeleteAt to remove a single Item from the vector. If the OnFreeItem procedure is assigned, it will be called for the Item and the Item will be freed / finalized accordingly. Index gives the position of the Item, where 0 is the first Item, 1 is the second Item, and so on.

Index must be in the range zero to Count-1. An exception will be raised if Index is outside of this range and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

See also: DeleteFirst, DeleteLast.

procedure DeleteFirst;

Removes the first Item in the container.

Call DeleteFirst to remove the first Item from the container. If the OnFreeItem procedure is assigned, it will be called for the Item and the Item will be freed / finalized accordingly. DeleteFirst corresponds to a call of DeleteAt[Count-1].

The container must not be empty, i.e. Count must not be zero. An exception will be raised the container is empty and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

See also: DeleteAt, DeleteLast.

procedure DeleteLast;

Removes the last Item in the container.

Call DeleteLast to remove the last Item from the container. If the OnFreeItem procedure is assigned, it will be called for the Item and the Item will be freed / finalized accordingly. DeleteFirst corresponds to a call of DeleteAt[Count-1].

The container must not be empty, i.e. Count must not be zero. An exception will be raised the container is empty and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

See also: DeleteAt, DeleteFirst.

procedure Exchange(const Index1, Index2: Integer);

 

procedure ExchangeItems(const Item1, Item2: Pointer);

Exchanges the memory of the two Items pointed to by Item1 and Item2. No rangechecking will be performed, so both Item1 and Item2 must not be nil and must be valid in terms of pointing to two different Items in the vector.

Applications should not use this protected method. Descendant classes, however, may use it after making sure the above conditions are met.

function ExistAll(const PItems: array of Pointer; const Same: TExSameItemsFunc): Boolean;

 

function ExistAny(const PItems: array of Pointer; const Same: TExSameItemsFunc): Boolean;

 

function Exists(const PItem: Pointer; const Same: TExSameItemsFunc): Boolean;

 

function ExistsBack(const PItem: Pointer; const Same: TExSameItemsFunc): Boolean;

 

function Find(const PItem: Pointer; const Compare: TExCompareItemsFunc; out Index: Integer): Boolean;

 

function FindDesc(const PItem: Pointer; const Compare: TExCompareItemsFunc; out Index: Integer): Boolean;

 

function GetPFirstItem: Pointer;

 

function GetPItemAt(const Index: Integer): Pointer;

 

function GetPLastItem: Pointer;

 

function IndexBackOf(const PItem: Pointer; const Same: TExSameItemsFunc): Integer;

 

function IndexOf(const PItem: Pointer; const Same: TExSameItemsFunc): Integer;

 

function InsertItemAt(const Index: Integer): Pointer;

 

function InsertItemFirst: Pointer;

Inserts a new Item at the beginning of the the container.

If OnFreeItem is assigned, it will be called to initialize the new Item's memory.

InsertItemFirst returns a pointer to the memory of the new Item. As long as applications not insert additional Items to the vector, they may use this pointer to write directly to the Item's memory. Inserting additional Items (i.e. using InsertItemFirst or InsertItemAt), may cause the vector's memory to be reallocated and the result pointer to be invalid. To retreive a particular Item after memory reallocation, use the ItemAt property.

function InsertItemLast: Pointer;

Inserts a new Item at the end of the the container.

If OnFreeItem is assigned, it will be called to initialize the new Item's memory.

InsertItemLast returns a pointer to the memory of the new Item. As long as applications not insert additional Items to the vector, they may use this pointer to write directly to the Item's memory. Inserting additional Items (i.e. using InsertItemLast or InsertItemAt), may cause the vector's memory to be reallocated and the result pointer to be invalid. To retreive a particular Item after memory reallocation, use the ItemAt property.

procedure Iterate(const Action: TExIterateProc; const ExtraData: Pointer; const Index: Integer = 0; Count: Integer = 0);

 

function LoadFromFile(const FileName: AnsiString): Boolean;

Fills the container with Items from the file specified by FileName. Note: LoadFromFile uses the InsertItemLast method to insert the Items that are read from the file.

function LoadFromStream(const Stream: TStream): Boolean; virtual;

 

procedure Move(const CurrentIndex, NewIndex: Integer);

Changes the position of an Item in the container.

Use Move to move the Item at position CurrentIndex so that it occupies the position NewIndex. The positions are specified as 0-based indexes. For example, the following line of code moves the item in the first position to the last position.

MyVectorObject.Move(0, MyVectorObject.Count - 1);

All Elements associated with an Item will remain associated with the Item in its new position.

function PItemBackOf(const PItem: Pointer; const Same: TExSameItemsFunc): Pointer;

 

function PItemOf(const PItem: Pointer; const Same: TExSameItemsFunc): Pointer;

 

procedure RemoveAll(const Item: Pointer; const Same: TExSameItemsFunc);

 

procedure SaveToFile(const FileName: AnsiString);

Saves the Items in the container to the specified file.

procedure SaveToStream(const Stream: TStream); virtual;

 

procedure SetCount(const NewCount: Integer);

Internal protocted method to set the number of Items in the vector to NewCount.

All new or removed Items will be initialized / freed if OnInitItem or OnFreeItem are assigned. If NewCount is greater than Count, OnInitItem will be called for each newly allocated Item. If NewCount is less than Count, OnFreeItem will be called for each Item to be removed from the vector.

See also:SetCountNoInit.

procedure SetCountNoInit(const NewCount: Integer);

Internal protected method to set the number of Items in the vector to NewCount.

Caution: Items will NOT be initialized / freed, even if OnInitItem or OnFreeItem are assigned. This is intended to be a time-saver if the next operation would immediately overwrite all newly allocated Items. However, particular care must be taken not to call SetCountNoInit with NewCount less than Count, when dynamic Items like AnsiStrings must be freed.

See also: SetCount.

procedure Sort(const Compare: TExCompareItemsFunc);

Sorts the vector in ascending order based on the Compare function.

procedure SortDesc(const Compare: TExCompareItemsFunc);

Sorts the vector in descending order based on the Compare function.

Properties

Overview

Count: Integer;
PFirstItem: Pointer;
PItemAt[const Index: Integer]: Pointer;
PLastItem: Pointer;
Vector: Pointer;

Description

Count: Integer;

Indicates the number of Items in the vector.

Read Count when iterating over all the Items in the vector, or when trying to locate the position of an Item relative to the last Item in the vector.

Write Count to set the number of Items in the container. New Items will be inserted / excess Items cut off at the end of the Vector.

PFirstItem: Pointer;

Returns a pointer to the first Item in the vector.

The container must not be empty, i.e. Count must not be zero. An exception will be raised the container is empty and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

PItemAt[const Index: Integer]: Pointer;

Returns a pointer to the Item at the specified Index's position in the vector.

Index must be in the range zero to Count-1. An exception will be raised if Index is outside of this range and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

PLastItem: Pointer;

Returns a pointer to the last Item in the vector.

The container must not be empty, i.e. Count must not be zero. An exception will be raised the container is empty and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

Vector: Pointer;

Pointer to access the memory holding the vector's Items.


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