Clara-Doc - Method Reference
CTARR_Realloc
Description
This method resizes an array. Unlike the CTARR_Alloc method, existing items will be kept up to the number of items that will fit in the new size. If the new size is larger than the existing size, then all existing items will be kept intact. If however, the new size is smaller than the size of the existing array, then only items from index 1 to the new size will be kept. The remaining items will be lost.
Since the array may contain data of any type and of any size, initialization cannot be automated by the class. You can provide the initialization data that each additional item will assume when re-allocating the array. However, unlike the CTARR_Alloc method, initialization occurs only on additional items, not existing items. For example, if an array contains 5 items and is re-allocated to 10 items, then only the last 5 items will be initilized with the initialization data.
Also, unlike the CTARR_Alloc method, the item size is not specified; the item size will remain the same as it was. Note however that if the array is empty (perhaps because the CTARR_Alloc method was never called on it), then the items will be of size zero.
Since the array may contain data of any type and of any size, initialization cannot be automated by the class. You can provide the initialization data that each additional item will assume when re-allocating the array. However, unlike the CTARR_Alloc method, initialization occurs only on additional items, not existing items. For example, if an array contains 5 items and is re-allocated to 10 items, then only the last 5 items will be initilized with the initialization data.
Also, unlike the CTARR_Alloc method, the item size is not specified; the item size will remain the same as it was. Note however that if the array is empty (perhaps because the CTARR_Alloc method was never called on it), then the items will be of size zero.
Prototype
DCTARR_Realloc...
D PR 10I 0
D
D@This * Value
D@NumItems 10I 0 Value
D@InitData * Value
Parameters
@This
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of an array instance. This pointer MUST be obtained through a call to CTARR_Constructor. |
@NumItems
| Type | 10I 0 |
| Passing Mode | Value |
| Description | The number of items the array is to contain. |
@InitData
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a data buffer that holds the data to be copied to each array item. Make sure the buffer is at least the same size as the @ItemSize parameter passed to the CTARR_Alloc method or else, garbage will be copied to every array item. |
Return Values
| Symbolic Constant | Value | Description |
| CS_SUCCESS | 0 | The array was re-allocated successfully. |
| CS_FAILURE | 1 | The array could not be re-allocated. |
Notes
Initializing an array during re-allocation
The third parameter to the CTARR_Realloc method points to a buffer that will be copied to every item in the newly allocated array. This is provided because the CTARR class does not keep type information on the items its objects hold. The initialization data is optional and you can specify *Null if you do not whish to set items to a particualr value; the data held in the items however will be undefined and may be incompatible with the actual data intended for the items (such as character data in numeric fields). Zero size arrays and zero size items
It is possible to re-allocate an array to zero items. It is also possible to allocate an array with items of size zero. All methods will behave consistently under those conditions, regardless if a zero size array or an array with items of zero size makes sense (it might have unforseen applications so it is supported).