4.42 HLA Standard Library Array Support

The HLA Standard Library provides an array module that helps reduce the effort needed to support static and dynamic arrays in your program. The arrays.hhf library module provides code to declare and allocate dynamic arrays, compute the index into an array, copy arrays, perform row reductions, transpose arrays, and more. This section will explore some of the more useful features the arrays module provides.

One of the more interesting features of the HLA Standard Library arrays module is that most of the array manipulation procedures support both statically allocated and dynamically allocated arrays. In fact, the HLA array procedures can automatically figure out if an array is static or dynamic and generate the appropriate code for that array. There is one catch, however. In order for HLA to be able to differentiate statically and dynamically allocated arrays, you must use the dynamic array declarations found in the arrays package. This won't be a problem because HLA's dynamic array facilities are powerful and very easy to use.

To declare a dynamic array with the HLA arrays package, you use a variable declaration like the following:

 variableName: array.dArray( elementType, Arity );

The elementType parameter is a regular HLA data type identifier (e.g., int32 or some type identifier you've defined in the type section). The Arity parameter is a constant that specifies the number of dimensions for the array ("arity" is the formal name for "number of dimensions"). Note that you do not specify the bounds of each dimension in this declaration. Storage allocation occurs later, at runtime. The following is an example of a declaration for a dynamically allocated two-dimensional matrix:

 ScreenBuffer: array.dArray( char, 2 );

The array.dArray data type is actually an HLA macro that expands the above to the following:

 ScreenBuffer:      record                dataPtr: dword;                dopeVector: uns32[ 2 ];                elementType: char;      endrecord;

The dataPtr field will hold the base address of the array once the program allocates storage for it. The dopeVector array has one element for each array dimension (the macro uses the second parameter of the array.dArray type as the number of elements for the dopeVector array). The elementType field is a single object that has the same type as an element of the dynamic array.

After you declare a dynamic array, you must initialize the dynamic array object before attempting to use the array. The HLA Standard Library array.daAlloc routine handles this task for you. This routine uses the following syntax:

      array.daAlloc( arrayName, comma_separated_list_of_array_bounds );

To allocate storage for the ScreenBuffer variable in the previous example you could use a call like the following:

      array.daAlloc( ScreenBuffer, 20, 40 );

This call will allocate storage for a 20x40 array of characters. It will store the base address of the array into the ScreenBuffer.dataPtr field. It will also initialize ScreenBuffer.dopeVector[0] with 20 and ScreenBuffer.dopeVector[1*4] with 40. To access elements of the ScreenBuffer array you can use the techniques of the previous section, or you could use the array.index function.

The array.index function automatically computes the address of an array element for you. This function uses the following call syntax:

 array.index( reg32, arrayName, comma_separated_list_of_index_values );

The first parameter must be a 32-bit register. The array.index function will store the address of the specified array element in this register. The second array.index parameter must be the name of an array; this can be either a statically allocated array or an array you've declared with array.dArray and allocated dynamically with array.daAlloc. Following the array name parameter is a list of one or more array indices. The number of array indices must match the arity of the array. These array indices can be constants, double word memory variables, or registers (however, you must not specify the same register that appears in the first parameter as one of the array indices). Upon return from this function, you may access the specified array element using the register indirect addressing mode and the register appearing as the first parameter.

One last routine you'll want to know about when manipulating HLA dynamic arrays is the array.daFree routine. This procedure expects a single parameter that is the name of an HLA dynamic array. Calling array.daFree will free the storage associated with the dynamic array. The following code fragment is a rewrite of the example from the previous section using HLA dynamic arrays:

 var      da:   array.dArray( uns32, 2 );      Bnd1: uns32;      Bnd2: uns32;           .           .           .      // Get the array bounds from the user:      stdout.put( "Enter the bounds for dimension #1: ");      stdin.get( Bnd1 );      stdout.put( "Enter the bounds for dimension #2: ");      stdin.get( Bnd2 );      // Allocate storage for the array:      array.daAlloc( da, Bnd1, Bnd2 );      // Initialize the array:      mov( 0, edx );      for( mov( 0, ebx ); ebx < Bnd1; inc( ebx )) do           for( mov( 0, ecx ); ecx < Bnd2; inc( ecx )) do                // Initialize the current array element with edx.                // Use array.index to compute the address of the array element.                array.index( edi, da, ebx, ecx );                mov( edx, [edi] );                inc( edx );           endfor;      endfor;

Another extremely useful library module is the array.cpy routine. This procedure will copy the data from one array to another. The calling syntax is:

 array.cpy( sourceArrayName, destArrayName );

The source and destination arrays can be static or dynamic arrays. The array.cpy automatically adjusts and emits the proper code for each combination of parameters. With most of the array manipulation procedures in the HLA Standard Library, you pay a small performance penalty for the convenience of these library modules. Not so with array.cpy. This procedure is very, very fast — much faster than writing a loop to copy the data element by element.