Release 4.0

Datatype array

An array in ChaosPro is an ordered set of values (0 based) that you refer to with a name and an index, eventually more than one index, if using a multidimensional array. Each element in an array is a number of a specific datatype.

There are two types of arrays in ChaosPro:

• Static arrays: This type of array has a fixed number of dimensions and each dimension is fix: You specify the different array dimensions (number and size) on declaring the array. During runtime you cannot change the array dimension. The advantage is that this type of array allows more optimizations. Because ChaosPro knows the dimensions it can optimize the code. Additionally the multi pass compiler in ChaosPro detects constant elements in the array and performs additional optimizations.
• Dynamic arrays: On declaring the array you only specify the number of dimensions. During runtime you assign a storage area for the array by using the array function, specifying the different dimension values as parameters to this function. You can reallocate a different storage area as often as you like and thus redimension the array during runtime.

On declaring the array you have to specify at least the dimension and the datatype of the elements in the array.

For example, you could have a one-dimensional array called aDist that contains the absolute distance of z to some static (complex) point. You work with it using "aDist[0]=cabs(z-sPoint);" or "d=aDist[i-3];"

First of all, you have to define an array: Arrays can be defined only on class level, not on function level. This restriction is due to performance reasons: This way ChaosPro doesn't have to bother with freeing the array memory, it's sufficient to free it at the end of the fractal calculation. Always keep in mind: Allocating and freeing array memory lasts very long! It needs about 1/2000 of a second (on my computer), which does not seem to be much. But if you allocate an array in the init section of a fractal and calculate the fractal at a size of 320x200, then this means that 320x200=64000 array allocations are carried out, thus needing 32 seconds!

An array is declared using one of the following syntax:

• static array: <datatype> <ident>[dimension1,dimension2,...,dimension n]
  Example: complex aDist[4,6]; // defines two-dimensional complex array aDist with dimensions 4 and 6
• dynamic array: array <ident>[dimension] of <datatype>
  Example: array aDist[2] of complex; // defines two dimensional complex array
aDist = array(4,6); // assigns storage area to the array, so that the first dimension is 4, the second one 6.

Examples:

array d[2] of quaternion;

d[4]=6;        // syntax error: dimension of array is 2!
d[3,4]=8;      // OK: dimension of array is 2, it's allowed to assign a real number to a quaternion number!
x=sin(d[5,6]); // error: Function sin() cannot be applied to quaternion numbers

So you can see, declaring an array allows ChaosPro to do all necessary syntax checks.

complex dArray[10,20,30];

This statement defines a static array: Each element in the array has the datatype complex. The array has three dimensions, you cannot redimension it during runtime. Each array dimension needs to be a constant value, so you can use the value of a parameter for each array dimension.

parameter int iSizeX,iSizeY,iSizeZ;
complex dArray[iSizeX,iSizeY,iSizeZ];


This code will work because parameters are treated as constants. But please note that ChaosPro will produce an error if you later on write to a parameter!

ChaosPro does no bounds checking or any other checks! So it's your responsibility to ensure that you do not write to uninitialized arrays or write beyond the limits of the array! ChaosPro will most likely crash! If you write beyond the limits of the array then there may be program code. The fractal calculation could behave almost "normal", but perhaps the program code which was overwritten contained the routine for saving a fractal image. And as soon as you then save an image, (perhaps hours after having used an array), ChaosPro can crash!

After having declared the array you can allocate a "storage area" for the elements of the array. You do this by using the "array" function: This function first checks whether there has already been assigned a storage area for the array. If yes, it will free the old storage area, all values in this (old) area are lost! After that the array function will allocate and assign the new storage area.

Example:

// assume the array d has been declared as array d[2] of complex;
d = array(10,20); // allocates storage area
                  // 10*20 elements can be stored in this array:
                  // d[0,0]...d[9,19]
d = array(10,20,30); // Syntax Error: array dimension is 2, you cannot specify three dimensions!

dim1=15;
dim2=25;
d = array(dim1,dim2);	// The parameters of the array function need not be constants, they can be variables as well.
                      // So this statement would allocate an array with 15*25 elements.

• bool, then the array needs 64000 * 4 bytes, thus 320 000 bytes = about 320KB
• int, then the array needs 64000 * 4 bytes, thus 320 000 bytes = about 320KB
• float, then the array needs 64000 * 4 bytes, thus 320 000 bytes = about 320KB
• double, then the array needs 64000 * 8 bytes, thus 640 000 bytes = about 640KB (ought to be enough for everybody (tm))
• real, then the array needs 64000 * 16 bytes, thus 1 280 000 bytes = about 1.3 MB
• complex, then the array needs 64000 * 16 bytes (array with datatype complex uses double values to store its two parts), thus 1 280 000 bytes = about 1.3 MB
• quaternion, then the array needs 64000 * 32 bytes (array with datatype quatenion uses double values to store its four parts), thus 2 560 000 bytes = about 2.6 MB

• There are two kinds of arrays: Static and dynamic. Use static arrays for more speed!
• You have to declare a static array using <datatype> <ident>[dimension1,dimension2, ..., dimension n]
• You have to declare a dynamic array using array <ident>[dimension] of <datatype>
• For dynamic arrays only: You have to allocate a storage area for the array using the array function: <ident> = array(<dim1>,<dim2>,...,<dimn>);
• When allocating a new storage area, the old storage area gets free'd, values are NOT preserved!
• A new storage area from the array function is not initialized in any way, the values in it are random!
• No bounds checking is done!