TBLArray<T>

Generic array container.

Definition

type TBLArray<T> = record ... end;

Type Parameters

T:

Remarks

T must be of one of the following types:

A signed or unsigned 8-, 16-, 32- or 64-bit integer.
Enumerated types.
A 32- or 64-bit floating-point value (Single or Double).
An unmanaged record that does not contain any [weak] references. So the record cannot contain reference-counted values like Strings, Interfaces or dynamic arrays. Also, only small records of certain sizes (32 bytes or less) bytes are supported.

These conditions are checked with an assertion.

Nested Types

Name	Description
P	A pointer to type `T`.

Properties

Name	Description
Capacity	The capacity of the array (number of items).
Data	Pointer to the array data.
IsEmpty	Whether the array is empty.
Items	The items in the array.
Refs	References to the items in the array.
Size	The size of the array (number of items).

Constructors

Name	Description
Assign	Copy constructor.
Create
Finalize	Destroys the path.
Initialize	Creates a default constructed array.

Operators

Name	Description
Equal(TBLArray<T>, TBLArray<T>)	Returns True if two arrays are equal (have the same contents).
Equal(TBLArray<T>, Pointer)	Used to compare against `nil` (empty array).
NotEqual(TBLArray<T>, TBLArray<T>)	Returns True if two arrays are not equal (do not have the same contents).
NotEqual(TBLArray<T>, Pointer)	Used to compare against `nil` (empty array).

Methods

Name	Description
Append(T[])	Appends a number of items items passed in `AItems` to the array.
Append(T)	Appends `AItem` to the array.
AppendData(P, NativeInt)	Appends `AItems` to the array of length `ASize`.
AppendData(TBLArrayView<T>)	Appends items to the array of the given array `AView`.
Assign	Replaces the content of the array with the items passed in `AItems`.
AssignData(P, NativeInt)	Replaces the content of the array `AItems` of length `ASize`.
AssignData(TBLArrayView<T>)	Replaces the content of the array by items in the passed array `AView`.
AssignDeep	Copy assignment, but creates a deep copy of the `AOther` array instead of weak copy.
AssignExternalData	Assign an external buffer to the array, which would replace the existing content.
At	Returns the array item at the given `AIndex`.
Clear	Clears the content of the array.
Equals	Returns whether the content of this array and `AOther` matches.
First	Returns a reference to the first item.
IndexOf(T, NativeInt)	Returns the index at which a given `AItem` can be found in the array starting from `AFromIndex`, or -1 if not found.
IndexOf(T)	Returns the first index at which a given `AItem` can be found in the array, or -1 if not found.
Insert(NativeInt, T[])	Inserts a number of items passed in `AItems` at the given `AIndex`.
Insert(NativeInt, T)	Inserts `AItem` at the given `AIndex`.
InsertData(NativeInt, P, NativeInt)	Prepends `AItems` to the array of length `ASize` at the given `AIndex`.
InsertData(NativeInt, TBLArrayView<T>)	Inserts items to the array of the given array `AView` at the given `AIndex`.
InsertOp	Insert operation, the semantics is similar to `ModifyOp`, however, ASize items are inserted at the given `AIndex` instead of assigned or appended.
Last	Returns a reference to the last item.
LastIndexOf(T, NativeInt)	Returns the index at which a given `AItem` can be found in the array starting from `AFromIndex` and ending at 0, or -1 if not present.
LastIndexOf(T)	Returns the last index at which a given `AItem` can be found in the array, or -1 if not present.
MakeMutable	Makes the array mutable by possibly creating a deep copy of the data if it's either read-only or shared with another array. Returns a pointer to the beginning of mutable data in `dataOut`.
Modify	Similar to `ModifyOp`, but the items to assign/append to the array are given after the `AOp` argument.
ModifyOp	Modify operation is similar to `MakeMutable`, however, the `AOp` argument specifies the desired array operation, and `ASize` specified the number of items to assign or append. Returns a pointer to the first item to be either assigned or appended and it points to an uninitialized memory.
Prepend(T[])	Prepends a number of items passed in `AItems` to the array.
Prepend(T)	Prepends `AItem` to the array.
PrependData(P, NativeInt)	Prepends `AItems` to the array of length `ASize`.
PrependData(TBLArrayView<T>)	Prepends items to the array of the given array `AView`.
RefAt	Returns a reference to the array item at the given `AIndex`.
Remove(TBLRange)	Removes `ARange` of items.
Remove(NativeInt)	Removes an item at the given `Andex`.
Replace	Replaces an item at the given `AIndex` by `AItem`.
ReplaceData(TBLRange, P, NativeInt)	Replaces the given `ARange` of items by `AItems` of length `ASize`.
ReplaceData(TBLRange, TBLArrayView<T>)	Replaces the given `ARange` of items by the given array `AView`.
Reserve	Reserves the array capacity to hold at least `AMinCapacity` items.
Reset	Resets the array into a default constructed state by clearing its content and releasing its memory.
Resize	Resizes the array to `ASize` items.
Shrink	Shrinks the capacity of the array to fit its length.
Swap	Swaps the content of this array with the `AOther` array.
ToArray	Converts this array to a Delphi `TArray
Truncate	Truncates the length of the array to maximum `AMaxSize` items.
View	Returns the array data as `TBLArrayView

Property Descriptions

Capacity

The capacity of the array (number of items).

property Capacity: NativeInt read GetCapacity

Type: NativeInt

Data

Pointer to the array data.

property Data: P read GetData

Type: P

IsEmpty

Whether the array is empty.

property IsEmpty: Boolean read GetIsEmpty

Type: Boolean

Items

The items in the array.

property Items[const AIndex: NativeInt]: T read GetItem write SetItem; default

Type: T

Remarks

This is the same as calling At(AIndex). The index must be valid, which means it has to be less than the array length. Accessing items out of range is undefined behavior that would be caught by assertions in debug builds.

Refs

References to the items in the array.

property Refs[const AIndex: NativeInt]: P read GetRef

Type: P

Remarks

This is the same as calling RefAt(AIndex).

Size

The size of the array (number of items).

property Size: NativeInt read GetSize

Type: NativeInt

Constructor Descriptions

`Assign`

Copy constructor.

Creates a weak-copy of the ASrc array by increasing it's internal reference counter. This array and ASrc would point to the same data and would be otherwise identical. Any change to ASrc would also affect this array.

constructor Assign(var ADest: TBLArray<T>; const ASrc: TBLArray<T>); inline

Parameters

ADest: TBLArray<T>

ASrc: TBLArray<T>

Exceptions

EBlend2DError: Raised on failure.

`Create`

class constructor Create

`Finalize`

Destroys the path.

destructor Finalize(var ADest: TBLArray<T>)

Parameters

ADest: TBLArray<T>

Exceptions

EBlend2DError: Raised on failure.

`Initialize`

Creates a default constructed array.

constructor Initialize(out ADest: TBLArray<T>)

Parameters

ADest: TBLArray<T>

Exceptions

EBlend2DError: Raised on failure.

Operator Descriptions

Equal(TBLArray, TBLArray)

Returns True if two arrays are equal (have the same contents).

class operator Equal(const ALeft, ARight: TBLArray<T>): Boolean; inline; static

Parameters

ALeft: TBLArray<T>

ARight: TBLArray<T>

Returns

Boolean

Equal(TBLArray, Pointer)

Used to compare against nil (empty array).

class operator Equal(const ALeft: TBLArray<T>; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TBLArray<T>

ARight: Pointer

Returns

Boolean

NotEqual(TBLArray, TBLArray)

Returns True if two arrays are not equal (do not have the same contents).

class operator NotEqual(const ALeft, ARight: TBLArray<T>): Boolean; inline; static

Parameters

ALeft: TBLArray<T>

ARight: TBLArray<T>

Returns

Boolean

NotEqual(TBLArray, Pointer)

Used to compare against nil (empty array).

class operator NotEqual(const ALeft: TBLArray<T>; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TBLArray<T>

ARight: Pointer

Returns

Boolean

Method Descriptions

Append(T[])

Appends a number of items items passed in AItems to the array.

procedure Append(const AItems: array of T); overload

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: array of T

Remarks

The data in AItems cannot point to the same data that the array holds as the function that prepares the append operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

Append(T)

Appends AItem to the array.

procedure Append(const AItem: T); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItem: T

AppendData(P, NativeInt)

Appends AItems to the array of length ASize.

procedure AppendData(const AItems: P; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: P

ASize: NativeInt

Remarks

The implementation guarantees that a AItems pointing to the array data itself would work.

AppendData(TBLArrayView<T>)

Appends items to the array of the given array AView.

procedure AppendData(const AView: TBLArrayView<T>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AView: TBLArrayView<T>

Remarks

The implementation guarantees that a AView pointing to the array data itself would work.

Assign(T[])

Replaces the content of the array with the items passed in AItems.

procedure Assign(const AItems: array of T)

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: array of T

AssignData(P, NativeInt)

Replaces the content of the array AItems of length ASize.

procedure AssignData(const AItems: P; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: P

ASize: NativeInt

Remarks

The implementation can handle items pointing to the array's data as well, so it's possible to create a slice of the array if required.

AssignData(TBLArrayView<T>)

Replaces the content of the array by items in the passed array AView.

procedure AssignData(const AView: TBLArrayView<T>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AView: TBLArrayView<T>

Remarks

The implementation can handle AView pointing to the array's data as well, so it's possible to create a slice of the array if required.

AssignDeep(TBLArray<T>)

Copy assignment, but creates a deep copy of the AOther array instead of weak copy.

procedure AssignDeep(const AOther: TBLArray<T>); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AOther: TBLArray<T>

AssignExternalData(P, NativeInt, NativeInt, TBLDataAccessFlags, TBLDestroyExternalDataFunc, Pointer)

Assign an external buffer to the array, which would replace the existing content. External data buffer to use (cannot be nil).Size of the data buffer in items.Capacity of the buffer, cannot be zero or smaller than ASize.Flags that describe whether the data is read-only or read-write.(Optional) function that would be called when the array is destroyed (can be nil if you don't need it).(Optional) user data passed to ADestroyFunc.

procedure AssignExternalData(const AData: P; const ASize, ACapacity: NativeInt; const AAccessFlags: TBLDataAccessFlags; const ADestroyFunc: TBLDestroyExternalDataFunc = nil; const AUserData: Pointer = nil); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AData: P

ASize: NativeInt

ACapacity: NativeInt

AAccessFlags: TBLDataAccessFlags

ADestroyFunc: TBLDestroyExternalDataFunc = nil

AUserData: Pointer = nil

At(NativeInt)

Returns the array item at the given AIndex.

function At(const AIndex: NativeInt): T; inline

Parameters

AIndex: NativeInt

Returns

T

Remarks

The index must be valid, which means it has to be less than the array length. Accessing items out of range is undefined behavior that would be caught by assertions in debug builds.

Clear

Clears the content of the array.

procedure Clear; inline

Exceptions

EBlend2DError: Raised on failure.

Remarks

If the array uses a dynamically allocated memory and the instance is mutable the memory won't be released, it will be reused instead. Consider using Reset if you want to release the memory in such case instead.

Equals(TBLArray<T>)

Returns whether the content of this array and AOther matches.

function Equals(const AOther: TBLArray<T>): Boolean; inline

Parameters

AOther: TBLArray<T>

Returns

Boolean

First

Returns a reference to the first item.

function First: P; inline

Returns

P

Remarks

The array must have at least one item otherwise calling First would point to the end of the array, which is not initialized, and such reference would be invalid. Debug builds would catch this condition with an assertion.

IndexOf(T, NativeInt)

Returns the index at which a given AItem can be found in the array starting from AFromIndex, or -1 if not found.

function IndexOf(const AItem: T; const AFromIndex: NativeInt): NativeInt; overload

Parameters

AItem: T

AFromIndex: NativeInt

Returns

NativeInt

IndexOf(T)

Returns the first index at which a given AItem can be found in the array, or -1 if not found.

function IndexOf(const AItem: T): NativeInt; overload; inline

Parameters

AItem: T

Returns

NativeInt

Insert(NativeInt, T[])

Inserts a number of items passed in AItems at the given AIndex.

procedure Insert(const AIndex: NativeInt; const AItems: array of T); overload

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

AItems: array of T

Remarks

The data in AItems cannot point to the same data that the array holds as the function that prepares the insert operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

Insert(NativeInt, T)

Inserts AItem at the given AIndex.

procedure Insert(const AIndex: NativeInt; const AItem: T); overload

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

AItem: T

InsertData(NativeInt, P, NativeInt)

Prepends AItems to the array of length ASize at the given AIndex.

procedure InsertData(const AIndex: NativeInt; const AItems: P; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

AItems: P

ASize: NativeInt

Remarks

The implementation guarantees that a AItems pointing to the array data itself would work.

InsertData(NativeInt, TBLArrayView<T>)

Inserts items to the array of the given array AView at the given AIndex.

procedure InsertData(const AIndex: NativeInt; const AView: TBLArrayView<T>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

AView: TBLArrayView<T>

Remarks

The implementation guarantees that a AView pointing to the array data itself would work.

InsertOp(NativeInt, NativeInt)

Insert operation, the semantics is similar to ModifyOp, however, ASize items are inserted at the given AIndex instead of assigned or appended.

The caller is responsible for initializing the returned data.

function InsertOp(const AIndex, ASize: NativeInt): P; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

ASize: NativeInt

Returns

P

Last

Returns a reference to the last item.

function Last: P; inline

Returns

P

Remarks

The array must have at least one item otherwise calling Last would point to the end of the array, which is not initialized, and such reference would be invalid. Debug builds would catch this condition with an assertion.

LastIndexOf(T, NativeInt)

Returns the index at which a given AItem can be found in the array starting from AFromIndex and ending at 0, or -1 if not present.

function LastIndexOf(const AItem: T; const AFromIndex: NativeInt): NativeInt; overload

Parameters

AItem: T

AFromIndex: NativeInt

Returns

NativeInt

LastIndexOf(T)

Returns the last index at which a given AItem can be found in the array, or -1 if not present.

function LastIndexOf(const AItem: T): NativeInt; overload; inline

Parameters

AItem: T

Returns

NativeInt

MakeMutable

Makes the array mutable by possibly creating a deep copy of the data if it's either read-only or shared with another array. Returns a pointer to the beginning of mutable data in dataOut.

  var A: TBLArray&lt;Byte>;
  A.Append([0, 1, 2, 3, 4, 5, 6, 7]);

  var Data := A.MakeMutable;

  // Data is a mutable pointer to array content of 8 items.
  Data[0] = 100;

  // Calling array member functions could invalidate Data.
  A.Append(9); // You shouldn't use Data afterwards.

function MakeMutable: P; inline

Exceptions

EBlend2DError: Raised on failure.

Returns

P

Modify(TBLModifyOp, T[])

Similar to ModifyOp, but the items to assign/append to the array are given after the AOp argument.

procedure Modify(const AOp: TBLModifyOp; const AItems: array of T)

Exceptions

EBlend2DError: Raised on failure.

Parameters

AOp: TBLModifyOp

AItems: array of T

ModifyOp(TBLModifyOp, NativeInt)

Modify operation is similar to MakeMutable, however, the AOp argument specifies the desired array operation, and ASize specified the number of items to assign or append. Returns a pointer to the first item to be either assigned or appended and it points to an uninitialized memory.

Please note that assignments mean to wipe out the whole array content and to set the length of the array to ASize. The caller is responsible for initializing the returned data.

function ModifyOp(const AOp: TBLModifyOp; const ASize: NativeInt): P; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AOp: TBLModifyOp

ASize: NativeInt

Returns

P

Prepend(T[])

Prepends a number of items passed in AItems to the array.

procedure Prepend(const AItems: array of T); overload

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: array of T

Remarks

The data in AItems cannot point to the same data that the array holds as the function that prepares the prepend operation has no way to know about the source (it only makes space for new data). It's an undefined behavior in such case.

Prepend(T)

Prepends AItem to the array.

procedure Prepend(const AItem: T); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItem: T

PrependData(P, NativeInt)

Prepends AItems to the array of length ASize.

procedure PrependData(const AItems: P; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AItems: P

ASize: NativeInt

Remarks

The implementation guarantees that a AItems pointing to the array data itself would work.

PrependData(TBLArrayView<T>)

Prepends items to the array of the given array AView.

procedure PrependData(const AView: TBLArrayView<T>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AView: TBLArrayView<T>

Remarks

The implementation guarantees that a AView pointing to the array data itself would work.

RefAt(NativeInt)

Returns a reference to the array item at the given AIndex.

function RefAt(const AIndex: NativeInt): P; inline

Parameters

AIndex: NativeInt

Returns

P

Remarks

The index must be valid, which means it has to be less than the array length. Accessing items out of range is undefined behavior that would be caught by assertions in debug builds.

Remove(TBLRange)

Removes ARange of items.

procedure Remove(const ARange: TBLRange); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ARange: TBLRange

Remove(NativeInt)

Removes an item at the given Andex.

procedure Remove(const AIndex: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

Replace(NativeInt, T)

Replaces an item at the given AIndex by AItem.

procedure Replace(const AIndex: NativeInt; const AItem: T); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AIndex: NativeInt

AItem: T

ReplaceData(TBLRange, P, NativeInt)

Replaces the given ARange of items by AItems of length ASize.

procedure ReplaceData(const ARange: TBLRange; const AItems: P; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ARange: TBLRange

AItems: P

ASize: NativeInt

ReplaceData(TBLRange, TBLArrayView<T>)

Replaces the given ARange of items by the given array AView.

procedure ReplaceData(const ARange: TBLRange; const AView: TBLArrayView<T>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ARange: TBLRange

AView: TBLArrayView<T>

Reserve(NativeInt)

Reserves the array capacity to hold at least AMinCapacity items.

procedure Reserve(const AMinCapacity: NativeInt); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AMinCapacity: NativeInt

Reset

Resets the array into a default constructed state by clearing its content and releasing its memory.

procedure Reset; inline

Exceptions

EBlend2DError: Raised on failure.

Resize(NativeInt, T)

Resizes the array to ASize items.

If ASize is greater than the array length then all new items will be initialized by AFill item.

procedure Resize(const ASize: NativeInt; const AFill: T); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ASize: NativeInt

AFill: T

Shrink

Shrinks the capacity of the array to fit its length.

Some array operations like Append may grow the array more than necessary to make it faster when such manipulation operations are called consecutively. When you are done with modifications and you know the lifetime of the array won't be short you can use Shrink to fit its memory requirements to the number of items it stores, which could optimize the application's memory requirements.

procedure Shrink; inline

Exceptions

EBlend2DError: Raised on failure.

Swap(TBLArray<T>)

Swaps the content of this array with the AOther array.

procedure Swap(var AOther: TBLArray<T>); inline

Parameters

AOther: TBLArray<T>

ToArray

Converts this array to a Delphi TArray<t>.

function ToArray: TArray<T>

Returns

TArray<T>

Truncate(NativeInt)

Truncates the length of the array to maximum AMaxSize items.

If the length of the array is less than AMaxSize then truncation does nothing.

procedure Truncate(const AMaxSize: NativeInt); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AMaxSize: NativeInt

View

Returns the array data as TBLArrayView<t>.

function View: TBLArrayView<T>; inline

Returns

TBLArrayView<T>