type TExVector = class(
TExContainer
)
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
:
TAnsiStringVector
TAnsiStringObjectVector
TAnsiStringObjectOwnerVector
TAnsiStringIntegerVector
TAnsiStringCardinalVector
TIntegerVector
TCardinalVector
TObjectVector
TAnsiString2Vector
TAnsiString2CardinalVector
TExContainer
> TErrorObject
Name | Description |
---|---|
FVector | Pointer to the vector's memory. |
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.
Count: Integer; |
PFirstItem: Pointer; |
PItemAt[const Index: Integer]: Pointer; |
PLastItem: Pointer; |
Vector: Pointer; |
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.