Arrays in VectorScript. Nemetschek Vectorworks Language Guide

Arrays in VectorScript

4

An array in VectorScript is a collection of data values referenced by a single identifier. Arrays allow large amounts of data to be stored and manipulated during script execution.

The data values contained within an array are stored in a contiguous set of memory locations, and can be accessed either randomly or in sequential order. In VectorScript, you can access this data by means of an array index. An array index is an INTEGER value corresponding to a specific storage location within the array. VectorScript arrays are indexed (that is, an individual data value is retrieved from the array) by enclosing the index value in square brackets after the array name. For example, if my_data is an array, and i is an INTEGER variable, then my_data[i] is an element of the array.

VectorScript provides support for two types of arrays: static arrays (ARRAY), and dynamic arrays (DYNARRAY). This section explains the syntax and conventions for using arrays in your scripts.

••••••••••••••••••••••••••••••••

Static Arrays

Dynamic Arrays

Static Arrays

Static arrays (ARRAY) are declared using the same method as used for variables, except that a series of storage locations is allocated for the array values, rather than a single location typical of a variable. Static array declarations occur in the

VAR block along with other variables.

Static arrays come in one- and two-dimensional varieties. The general syntax for one-dimensional static arrays is:

<identifier> : ARRAY [ m..n ] OF <data type>;

In the array declaration, the term [m..n] indicates the dimension, or size, of the array. An array declared with a dimension of [1..10] will allocate ten contiguous storage locations in memory. Static arrays support any valid

fundamental data type, as well as the user-defined STRUCTURE type (see “Creating Structures” on page 31 for details).

To retrieve a value from an element of a one-dimensional array, the same bracket notation described earlier is used.

The array name should appear to the left of the brackets, and a non-negative INTEGER value representing the array index should appear within the brackets: j := values[3]; values[23] := 15.5; total := price[i] + tax;

An array index may be any constant non-negative INTEGER value or expression which resolves to such a value.

The following example illustrates the practical use of a one-dimensional array:

PROCEDURE Example_41;

VAR s:STRING; i:INTEGER;

22 | Chapter 4: Arrays in VectorScript words:ARRAY[1..10] OF STRING;

BEGIN words[1]:='VectorScript '; words[2]:='is '; words[3]:='a '; words[4]:='fine '; words[5]:='language.';

FOR i:=1 TO 5 DO s:=Concat(s,words[i]);

END;

Message(s);

Run(Example_41);

In the example, a ten element array of STRING is declared, and the script code begins with assignment of values to the elements of the array. In the assignments, constants are used to represent the array indices, but a variable or other identifier which evaluates to an INTEGER value could have been used in their place. Such an identifier is used later in the Concat() function call to reference array elements.

Two-dimensional static arrays extend the syntax of a one-dimensional array by adding an additional array index to the declaration:

<identifier> : ARRAY [ m..n,r..s ] OF <data type>;

In the declaration for the two-dimensional array, the first index value defines the number of “rows” in the array, while the second index defines the number of “columns.” In such a two-dimensional array, n x s contiguous storage locations will be allocated to hold data values (when m and r are 1).

Accessing an element in a two-dimensional array is not very different from a one-dimensional array: j := values[3,5]; values[23,1] := 15.5; total := price[i,j] + tax;

If we think of the two-dimensional array in terms of rows and columns, we would use two index values to indicate the row and column position of the array element to be indexed.

Dynamic Arrays

Dynamic arrays (DYNARRAY) in VectorScript are similar to static arrays, with the notable exception of how they are dimensioned, or sized. While static arrays are explicitly sized when they are declared in the VAR block of your script, the size of a dynamic array is declared during the actual execution of a script. Dynamic arrays can also be resized at any point during script execution to suit your data storage requirements. As with static arrays, dynamic arrays

support any valid fundamental data type, as well as the user-defined STRUCTURE type (see “Creating Structures” on page 31 for details).

Dynamic arrays can also be specified as one- or two-dimensional. The general syntax for a one-dimensional dynamic array is:

<identifier> : DYNARRAY [] OF <data type>;

Dynamic Arrays | 23

Note that, unlike static arrays, dynamic arrays do not include the size (dimension) of the array in the brackets. This size will be defined when your script is executed. The syntax for a two-dimensional dynamic array is very similar:

<identifier> : DYNARRAY [,] OF <data type>;

As with the one-dimensional dynamic array, note that the index dimensions are not specified in the declaration. The comma, however, is needed to indicate that the array will have two dimensions.

To dimension a dynamic array, VectorScript uses the ALLOCATE keyword (along with a reference to the array) to reserve sufficient space in memory for all the data values that will be stored in the array. ALLOCATE can be used to initially dimension the array prior to first use, or it can be used to re-dimension the array should more (or less) storage space be required. For instance, to allocate five storage locations to an array int_values storing INTEGER values, you could use the following call:

ALLOCATE int_values[1..5];

The range specified inside the brackets indicates the number of elements to be created and reserved for storage.

The following example illustrates practical use of a dynamic array within a script:

PROCEDURE Example_42;

VAR i,j,numtxt : INTEGER; h : HANDLE; textStore: DYNARRAY[] OF STRING;

BEGIN numtxt:=Count(((T=Text) & (SEL=TRUE))); j:=1;

ALLOCATE textStore[1..numtxt]; h:=FSActLayer;

WHILE (h <> NIL) DO BEGIN

IF (GetType(h) = 10) THEN BEGIN textStore[j]:=GetText(h); j:=j+1;

END; h:=NextSObj(h);

END;

24 | Chapter 4: Arrays in VectorScript

ALLOCATE textStore[1..numtxt+2];

TextOrigin(2,2);

CreateText('New text 1'); numtxt:=numtxt+1; textStore[numtxt]:=GetText(LNewObj);

TextOrigin(2,4);

CreateText('New text 2'); numtxt:=numtxt+1; textStore[numtxt]:=GetText(LNewObj);

FOR i:=1 TO numtxt DO BEGIN

Message('Array element ',i,' contains ', textStore[i]);

Wait(1);

END;

END;

Run(Example_42);

In the example, a dynamic array is used to store the text of any selected strings that may be found in the selection set.

The script begins by declaring the dynamic array, textStore, along with several other variables. In the VAR block declaration, the dynamic array is specified, but no space is allocated at this point for storage.

The body of the script begins with storing the number of selected text objects found within the selection set in the variable numtxt. This value is then used with the ALLOCATE keyword:

ALLOCATE textStore[1..numtxt]; to initialize the amount of storage space in the dynamic array.

Next, the script processes the selected items, and when it encounters a text object, stores the text in an element of the array. Since the text objects within the selection set were counted, textStore is sized to provide sufficient storage within the array for the exact number of text strings that were found.

Once all the objects have been processed, the array can be redimensioned to allocate more or less space as needed. In the example, additional storage space is reserved with another call to ALLOCATE,

ALLOCATE textStore[1..numtxt+2]; and use the newly added storage locations to store the text created by the script. The script concludes by displaying the values currently stored within the textStore array.

Note that the existing data values stored in the array are preserved when the array is re-dimensioned. If an array is redimensioned to a larger size during execution of the script, VectorScript will preserve all the values currently in the array. VectorScript will also attempt to preserve as many data values as possible if an array is redimensioned to a smaller size. In the case of dimensioning to a smaller size, any values contained in locations beyond the newly defined boundaries of the array will be lost.

Dynamic Arrays | 25

••••••••••••••••••••••••••••••••

Performance Considerations with Dynamic Arrays

Vectors and Array Notation

Extended String Support with CHAR Arrays

Performing Standard STRING-Related Operations

Performance Considerations with Dynamic Arrays

Dynamic arrays require more “overhead” than comparable static arrays in order to allocate memory during script execution and to maintain array values. As a result, scripts using dynamic arrays may execute more slowly than scripts using static arrays.

It is highly recommended that you use static arrays wherever possible for the best possible script performance. If dynamic arrays are required in your scripts, avoid making frequent calls to ALLOCATE to reserve storage. Use

ALLOCATE only when absolutely necessary to change reserved storage during script execution, and avoid any use of

ALLOCATE inside of a loop or repetition statement (see “Repetition Statements” on page 47 for details on these

statement types).

Vectors and Array Notation

As mentioned earlier, you can create arrays of any fundamental data type, which includes the VECTOR type. Vectors support two methods of accessing the fields of the vector: array-style brackets and dot notation.

To access a vector field using array-style notation, you can append an additional set of brackets to the array reference, and specify the vectors' field index within the second set of brackets. For example, vec_field[5][2]; will access the second field (the y-component) of the vector in element 5 of the one-dimensional array vec_field.

Two-dimensional arrays can also use this notation; if vec_field2 is a two-dimensional array, then vec_field2[4,5][2]; will access the second field of the vector located in the fourth row and fifth column of the array.

To access a vector field using dot notation, simply append the dot (field access) operator and field identifier to the array reference you want to index. Using the previous example, vec_field[5].y; will perform the same operation, accessing the second field (the y-component) of the vector in element 5 of vec_field. Two dimensional arrays work in a similar fashion; the reference vec_field2[4,5].y; will access the y-component of the vector located in the fourth row and fifth column of vec_field2.

Extended String Support with CHAR Arrays

VectorScript also supports a specialized set of functionality when using arrays of the CHAR data type. This functionality with static or dynamic arrays of the CHAR type provides you with a means of handling extended strings up to 32,767 characters long within your scripts.

Arrays of type CHAR can be used in place of the STRING data type in certain operations within VectorScript. The following sections provide details on operations supporting CHAR arrays and STRINGs in VectorScript.

••••••••••••••••••••••••••••••••

Assignments Between STRING Values and CHAR Arrays

26 | Chapter 4: Arrays in VectorScript

Retrieving or Assigning Strings to Text Objects

Retrieving or Assigning Strings to Record Fields

Assignments Between STRING Values and CHAR Arrays

Both static CHAR arrays (ARRAY OF CHAR) and dynamic CHAR arrays (DYNARRAY OF CHAR) can be used in place of

STRING values when assigning to or retrieving from a STRING variable.

When using either static or dynamic CHAR arrays to assign a value to a STRING variable, if the array length exceeds

255 characters, the first 255 characters will be copied into the string variable, and the remaining characters in the array will be dropped. Values of less than 255 characters will be completely copied into the STRING variable.

Assigning values from a STRING variable or constant to a static CHAR array works in a similar fashion. If the CHAR array has a length less than the length of the STRING value to be assigned, the value will be truncated to fit the array.

For instance:

PROCEDURE Example_43;

VAR

Part_name: STRING;

NameArray: ARRAY[1..16] OF CHAR;

BEGIN part_name:= 'Acme Left-handed Smoke Shifter';

NameArray:=part_name;

END;

Run(Example_43);

In the example, the STRING value assigned to the variable part_name would be truncated to

Acme Left-handed when assigned to the array. When using static CHAR arrays to handle STRING values, be sure to declare the size of the array to accommodate the longest STRING value expected to be stored within the array.

In contrast to static CHAR arrays, dynamic CHAR arrays will automatically size to the length of the STRING value being assigned to the array. For example:

PROCEDURE Example_44;

VAR sampleString: STRING; mytext: DYNARRAY[] OF CHAR;

BEGIN sampleString:= 'VectorScript now handles lots of text'; mytext:= sampleString;

Dynamic Arrays | 27

END;

Run(Example_44);

If the array mytext was declared but not previously used, the assignment would size the array length to 36, and the array would contain the string

VectorScript now handles lots of text

If mytext had been previously assigned a value, the assignment would resize the array to a length of 36 and assign the STRING value to the array. The values previously held in the array would be lost.

Retrieving or Assigning Strings to Text Objects

VectorScript allows STRING values greater than 255 characters long in text objects to be set or retrieved via CHAR arrays. The VectorScript API functions GetText() and SetText() support the use of a CHAR array in place of a

STRING value.

To set or retrieve the text string, use the name of the CHAR array (without brackets) in place of the STRING parameter or variable. For example:

PROCEDURE Example_45;

VAR h : HANDLE; theText : STRING; textArray : DYNARRAY[] OF CHAR;

BEGIN h:=FSActLayer; theText:= GetText(h);

CreateText(theText);

END;

Run(Example_45);

In the example, you would be limited to returning the first 255 characters of the text string. By using a dynamic array:

PROCEDURE Example_45;

VAR h : HANDLE; theText : STRING; textArray : DYNARRAY[] OF CHAR;

BEGIN h:=FSActLayer; textArray:= GetText(h);

CreateText(textArray);

28 | Chapter 4: Arrays in VectorScript

END;

Run(Example_45);

You can retrieve the entire text string and store it in the dynamic array. The entire text string can then be used in other operations.

Retrieving or Assigning Strings to Record Fields

VectorScript also allows you to set and retrieve STRING values greater than 255 characters long contained in record fields via the use of CHAR arrays. The VectorScript API functions GetRField() and SetRField() support the use of a CHAR array in place of a STRING value.

To set or retrieve the record field string, use the name of the CHAR array (without brackets) in place of the STRING parameter or variable. For example:

PROCEDURE Example_46;

VAR theText : STRING; longtext : ARRAY[1..512] OF CHAR;

BEGIN theText:= GetRField(FSActLayer,'Boring Info','Boring Notes');

CreateText(theText);

END;

Run(Example_46);

In the example, using a STRING variable would be limited to retrieving only the first 255 characters of the text string stored within the field. By using a CHAR array:

PROCEDURE Example_46;

VAR theText : STRING; longtext : ARRAY[1..512] OF CHAR;

BEGIN longtext:= GetRField(FSActLayer,'Boring Info','Boring Notes');

CreateText(textArray);

END;

Run(Example_46);

In the example, up to 512 characters of text from the field can be retrieved and stored in the array. Alternately, the dynamic array could be sized to support whatever amount of text might be found in the record field (up to 32K of text).

Dynamic Arrays | 29

Performing Standard STRING-Related Operations

VectorScript also provides support in its string API for handling the extended strings in CHAR arrays. Operations such as obtaining string length, substring position, and string concatenation can be performed on CHAR arrays just as they can on STRING values.

To use CHAR arrays with string API functions, just use the CHAR array in place of a STRING variable for a given function parameter or return value. For example:

PROCEDURE Example_47;

VAR s : STRING; textArray :ARRAY [1..32] OF CHAR;

BEGIN textArray:= 'A VectorScript text string'; s:= Copy(textArray,3,12);

END;

Run(Example_47);

In the example, a CHAR array is used in place of a STRING as the source value for the Copy() function. The result of the Copy() operation is then assigned to a STRING variable. String API function calls support both static and dynamic CHAR arrays.

The following VectorScript API functions have CHAR array support.

• Len()

• UprString()

• Pos()

• GetText()

• Concat()

• SetText()

• Copy()

• GetRField()

• Delete()

• SetRField()

• Insert()

• CreateText()

30 | Chapter 4: Arrays in VectorScript