Clara-Doc - Method Reference
CTARR_Constructor
Description
Creates a CTARR instance in memory. This method must be called in order to use an array. The constructor method is equivalent to the new operator in C++ and Java. The constructor method allocates an empty array in memory and returns its memory address to the caller. The caller can then call other array methods on that array.
Several arrays can be created by calling the constructor method several times. A new memory address will be returned to the caller. Beware however not to overwrite an existing array address, unless that array has been relesed by a previous call to the destructor method.
Since the constructor allocates memory for an array, that memory will remain allocated (that is unavailable for re-use) until the caller releases it. The proper way to release the memory allocated for an array is to call the destructor method (CTARR_Destructor) and passing it the memory address returned by the constructor. DO NOT deallocate the memory yourself (by calling DEALLOC on the memory address); this will very likely cause memory leaks since the array object will allocate other resources in memory during its lifetime. Those memory resources are hidden from the caller thus making it impossible for the caller to properly dispose of those resources.
Several arrays can be created by calling the constructor method several times. A new memory address will be returned to the caller. Beware however not to overwrite an existing array address, unless that array has been relesed by a previous call to the destructor method.
Since the constructor allocates memory for an array, that memory will remain allocated (that is unavailable for re-use) until the caller releases it. The proper way to release the memory allocated for an array is to call the destructor method (CTARR_Destructor) and passing it the memory address returned by the constructor. DO NOT deallocate the memory yourself (by calling DEALLOC on the memory address); this will very likely cause memory leaks since the array object will allocate other resources in memory during its lifetime. Those memory resources are hidden from the caller thus making it impossible for the caller to properly dispose of those resources.
Prototype
DCTARR_Constructor...
D PR *
Parameters
Return Values
The method returns the memory address of the array. This memory address must be held in a pointer variable. The pointer should ONLY be used as a parameter to CTARR methods. This pointer is used by CTARR methods to distinguish one array from another since several arrays may be created by a calling program.
To create an object, a special function called a constructor is provided by the class to create the object in memory. That memory will hold the object's data. For a program to use this memory, it's address must be returned to the program. However, the program does (should) not know the specific ways in which the object holds its data. That is why methods are provided to manipulate the data in consistent ways. Those methods however must know which memory object to operate on. This is why they must be called by passing the memory address returned by the constructor. In other words, the calling program should not use the pointer other than to pass it on to methods since only methods know how an object is implemented.
Notes
An object is an entity that occupies memory to hold data; a class is executable code that provides a set of operations to manipulate this data. There may be one or more of these objects in memory but the code that implements its operations is shared by all objects. To create an object, a special function called a constructor is provided by the class to create the object in memory. That memory will hold the object's data. For a program to use this memory, it's address must be returned to the program. However, the program does (should) not know the specific ways in which the object holds its data. That is why methods are provided to manipulate the data in consistent ways. Those methods however must know which memory object to operate on. This is why they must be called by passing the memory address returned by the constructor. In other words, the calling program should not use the pointer other than to pass it on to methods since only methods know how an object is implemented.