SCRIPTING: Programming: Advanced (Arrays, User-Defined Data Types, Advanced Programming Examples) [22909]

Advanced Programming methods use arrays and user defined data types. These are very powerful features, but understanding the basic and intermediate programming is essential before you can fully utilize the information in the Advanced Programming articles:

 

Arrays

It is often the case that multiple pieces of information need to be used as a single variable. The best way to handle this is through the use of an array. An array is a storage unit for many items of the same type. The storage unit is comprised of multiple items of one type, each being stored in their own index within the array. Think of it as a filing drawer that may contain many files in a specific order which all pertain to a single topic. The array would be the drawer while the individual files within would be the indices.

 

NOTE: These examples are designed to illustrate the syntax of E-Basic array declarations only, and are not intended to be implemented and generated.

 

Declaring Arrays
To work with an array, refer to the name of the array and the index. An array can be of any data type, but can only hold a single data type. Specifically, you can declare an array that holds strings and an array that holds integers, but you cannot declare a single array that holds both strings AND integers. However, if you need to store multiple data types in a single array, you may declare arrays of variant data type, which holds any kind of data. Be careful though; since variant data typically is more memory intensive than other data types, creating and using an arrays of variants can potentially create an overwhelming amount of overhead. Use this option wisely.

 

As with any variable, before using it, first declare and initialize it. The declaration of an array is similar to any other variable. The Dim statement is used, and the only significant difference is that the array declaration also takes a dimensions value.

 

Dim position_array ( ) As Integer

Fixed Arrays
The dimensions of fixed arrays cannot be adjusted at execution time. Once declared, a fixed array will always require the same amount of storage. Fixed arrays can be declared with the Dim statement by supplying explicit dimensions. The following example declares a fixed array of eleven strings (arrays are zero-based) see Using an Array Index below):
 

Dim a(10) As String

 

Fixed arrays can be used as members of user-defined data types. The following example shows a structure containing fixed-length arrays:

 

Type Foo

Rect(4) As Integer

Colors(10) As Integer

End Type

 

Only fixed arrays can appear within structures. Refer to Stage 7, Step 2: User-Defined Data Types (Page 153) for a discussion of user-defined types.

 

Dynamic Arrays
Dynamic arrays are declared without explicit dimensions, as shown below:

 

Public Ages() As Integer

 

Dynamic arrays can be resized at execution time using the ReDim statement:

 

ReDim Ages (100)

 

Dynamic arrays cannot be members of user-defined data types.

 

Using an Array Index
Items within an array are indexed beginning with zero. In other words, the first element within an array is located within index number 0. For instance, if an array is designed to hold 10 elements, the array should be dimensioned as in the following:

 

Dim arrResponses (9) As String

 

In the previous statement, the arrResponses array is dimensioned to hold 10 elements. Because array indices begin at 0, the “9” in the dimension statement indicates the largest legal index within the array, and the total number of elements that the array may contain is one greater than this number.
 
Addressing an Element within an Array
The individual elements within an array accessed or set simply by listing the array name, followed by subscript notation (i.e., the index number enclosed in parentheses) to refer to the appropriate index. The index of the array includes an integer value for each dimension of the array. For example, my _array(3) refers to, or identifies the value in the fourth slot in the array called my _array Data contained within an array may be used like any other variables:

Assign a value to an array element.

 

Dim a(9) As Integer

a(0) = 12

 

Assign a value stored in an array to another variable.

 

x = a(0)

 

Use the value of an array element in an expression:

 

x = 10 * a(0)

Assigning Data to Array Indices
When an array is declared using the Dim statement, the elements composing the array are not initialized. That is, the elements contain no valid information. Before accessing the array elements, they must be assigned meaningful values. Array elements are assigned values using an assignment expression (i.e., ArrayName(Index) = Expression).

 

Dim a(9) As Integer

a(0) = 12

 

The most efficient method of assigning values to an entire array at one time (e.g., to initialize an array to consecutive values) is to use a For…Next loop.

 

ReDim Preserve Ages (100)

 

Dynamic arrays cannot be members of user-defined data types.

 

Using an Array Index
Items within an array are indexed beginning with zero. In other words, the first element within an array is located within index number 0. For instance, if an array is designed to hold 10 elements, the array should be dimensioned as in the following:

'create an array with 1- indices, numbered 0 through 9

Dim a(9) As Integer

Dim x As Integer

Dim i As Integer

For i = Lbound(a) To Ubound(a)

a(i) = x

x = x + 1

Next i

Arrays may also be multi-dimensional. Arrays containing more than one dimension are similar to a spreadsheet-like organization, with different dimensions handling different tables or lists of information. Multi-dimensional arrays are declared just like one-dimensional arrays, with commas separating the values specifying the size of each dimension in the array.

 

Dim multi_array(9,6,8) As Integer

 

The total number of elements held by a multi-dimensional array is equal to the product of the sizes of the individual dimensions. The example above would result in an array holding 630 elements (10 by 7 by 9).

 

User-Defined Data Types

E-Basic allows the user to define data types. A user-defined data type is declared using the Type statement, and the data items organized by the data type are listed within the Type statement. User-defined data types must be declared on the User tab of the User Script window; they cannot be declared on an In-Line object.

 

User-defined data types are very useful for organizing related data items of various types. For example, to draw and modify a grid in which some of the cells are drawn in color, it would be useful to keep track of an ID number for each cell, the color in which each cell is drawn, the location of the cell, and other possible information about each cell. The script below uses the Type statement to declare the CellInfo data type, organizing the data relevant to each cell in the grid.

 

Type CellInfo  ‘keep track of cell info
nID As Integer
nColorState As Integer	‘Is the cell a color or non-color nColor
As Long	‘Specific color used to draw the cell
nRow As Integer	‘Row in the grid where cell appears
nColumn As Integer	‘Column in the grid
End Type

 

Within the Type declaration of the CellInfo data type, variables are declared to organize the information pertaining to each cell (i.e., the cell ID, color of the cell, row, column, etc.). Once the data type has been declared, the Dim command is used to declare a new instance of the type. For example, the script below declares the CurrentCell variable as an instance of the CellInfo type (i.e., a single cell in the grid).

 

Dim CurrentCell As CellInfo

 

If the CurrentCell variable declaration is made on the user tab of the Script window, after the CellInfo type definition, then the CurrentCell variable becomes a global variable. Alternatively, if the variable declaration is made on an InLine object, then it is participant to the scope rules in SCRIPTING: Variable Declaration and Initialization [22878].

Like assigning values to object properties, the dot operator is used to assign values to the component variables of a user-defined type. Below, the CurrentCell variable is assigned values for the ID number, row, column, color state, and color components.

 

'Define cell info
CurrentCell.nID = 12
CurrentCell.nRow = 2
CurrentCell.nColumn = 3
CurrentCell.nColorState = 1	'1 = color, 0 = white
CurrentCell.nColor = CColor("Blue")

 

Recall that the assignment script can only occur on an InLine object; this script can NOT be placed on the User tab of the Script window.

 

Advanced Programming Examples

Contingent Branching
Launching a specific Procedure based on the participant’s response.

 

This example assumes a structure in which an input object named “participant” collects a response, and two separate List objects (List1 and List2) call separate Procedures.

 

'If the participant enters "1" run Procedure 1, otherwise run

'Procedure 2.

If participant.RESP = "1" Then

List1.Run

Else

List2.Run

End If

 

Arrays
Creating a single dimension array, assigning values, and accessing values for display.

 

Creating and assigning calues to a single dimension array

Dim WordList(4) As String

Dim i As Integer

WordList (0) = "Every"

WordList (1) = "Good"

WordList (2) = "Boy"

WordList (3) = "Does"

WordList (4) = "Fine"

For i = 0 To 4

MsgBox WordList(i)

Next i

Debugging
Using Debug.Print to verify logging accuracy an input object named “TextStimulus” which collects a response.

 

Evaluate the response collected by the TextStimulus object.

Send the response entered by the participant (RESP), the

correct response (CRESP), and the accuracy (ACC) to the

OUTPUT window separated by tabs. View using the DEBUG tab

in the OUTPUT window.

Debug.Print TextStimulus.RESP & "\t" TextStimulusStimDisplay.CRESP &_

"\t" & TextStimulus.ACC

 

The script above will send information to the Debug tab in the Output window as follows:

 

 

Next Article: SCRIPTING: Debugging [22913]
Previous Article: SCRIPTING: Programming: Intermediate (Variables, Writing Subroutines, Writing Functions) [22905]

 

See Also:

For further information on scripting using E-Basic, please refer to the E-Prime Command Reference (https://pstnet.com/ecr).