Clara-Doc - Programmer Reference

Module: CTARR

Methods

MethodDescription
CTARR_AllocAllocates an array of a specified size with items of a specified size.
CTARR_ConstructorCreates a CTARR Instance.
CTARR_CountReturns the number of items in the array
CTARR_DestructorReturns the size of items held in the array.
CTARR_GetRetrieves an item from the array.
CTARR_ItemSizeReturns the size of items held in the array.
CTARR_IterNextRetrieves the next available item from the iteration loop.
CTARR_IterStartPrepares the array for iterating through its items.
CTARR_ReallocIncreases the existing array size by a specified number of items.
CTARR_SetSets the value of an array item at a specified index.



Description

Creating an array
Creating an array is a 2 step process. The first step is to create a CTARR instance. This is done by calling the constructor sub-procedure, namely the CTARR_Constructor sub-procedure. At this point, you have a CTARR instance or object but it contains no array as such. The next step is to allocate the array by specifying its size. This is done by calling the CTARR_Alloc sub-procedure and specifying the array size and the size of the items it will hold:

     DmyArray          S               *
     DmyItem           S             32A
     
      /Free
     
        myArray = CTARR_Constructor();
        
        CTARR_Alloc(myArray: 10: %Size(myItem): *Null);
        
        
        // ....
        
        
        CTARR_Destructor(myArray);
        
      /End-Free
      
Resizing a an array
Once you have created an array, you can resize it as needed. Resizing an existing array requires that some policy be in place to determine how existing items are handled. The CTARR class will copy existing items up to the new array size. For example, if an array has 10 elements and the array is resized to 5 elements, then only the first 5 elements will be kept in the new array. If however the new size is greater than the current array size, then all existing elements will be preserved and the new items will be initialised according to what is passed to the CTARR_Realloc sub-procedure.