Clara-Doc - Method Reference
CTARR_IterNext
Description
Returns the next available item in the array within an iteration loop. The iteration loop is started by a call to CTARR_IterStart and CTARR_IterNext will return an array item at the current position in the iteration loop; the iterator keeps track of the current index value and CTARR_IterNext updates that current index value with each call.
When the iterator has reached the end of the array, a call to CTARR_IterNext returns a failure code, indicating that the iteration loop has reached its end.
When the iterator has reached the end of the array, a call to CTARR_IterNext returns a failure code, indicating that the iteration loop has reached its end.
Prototype
DCTARR_IterNext...
D PR 10I 0
D
D@This * Value
D@pBuffer * 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. |
@pBuffer
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a buffer where the array item will be copied. |
Return Values
| Symbolic Constant | Value | Description |
| CS_SUCCESS | 0 | The item was copied successfully. |
| CS_FAILURE | 1 | The item was not copied. This means we have reached the end of the array and no more items are available within the iteration loop. |
The CTARR class implements an iterator which allows the caller to navigate the array in sequential index order. An iteration loop is started with a call to CTARR_IterStart. Then, calling CTARR_IterNext successively will return array items in index order, moving up one item with each call until there are no more items in the array. When the CTARR_IterNext method returns CT_FAILURE, this indicates that the iteration has reached the end and no value is returned (This is similar to an index out of range conditoin).
This method is functionnaly similar to CTARR_Get except that no index is specified (since it is kept internally by the iterator). However, the same care should be taken when specifying the buffer that is to receive the array item. Make sure it is large enough to accomodate the item's size.
Examples
HDatEdit(*YMD)
*--------------------------------------------------------------
* Common Definitions
*--------------------------------------------------------------
/Include QINCSRC,CTBASE
DEntryProc Pr ExtProc('EXLST09')
DEntryProc PI
*-------------------------------------------------------------------------------
* Main
*-------------------------------------------------------------------------------
DArray S *
DBuffer S 32A
/Free
Array = CTARR_Constructor();
// Let's allocate an array of size 3
// And initialize each item with the string
// "HELLO"
Buffer = 'HELLO';
CTARR_Alloc(Array: 3: %Size(Buffer): %Addr(Buffer));
// Look at each item
CTARR_IterStart(Array);
Dow CTARR_IterNext(Array: %Addr(Buffer)) = CT_SUCCESS;
// Do something ...
EndDo;
// Let's assign values ....
Buffer = 'String - 1';
CTARR_Set(Array: %Addr(Buffer): 1);
Buffer = 'String - 2';
CTARR_Set(Array: %Addr(Buffer): 2);
Buffer = 'String - 3';
CTARR_Set(Array: %Addr(Buffer): 3);
// Look at each item
CTARR_IterStart(Array);
Dow CTARR_IterNext(Array: %Addr(Buffer)) = CT_SUCCESS;
// Do something ...
EndDo;
CTARR_Destructor(Array);
*InLr = *On;
Return;
/End-Free