Arrays

Arrays are sequences of numeric variables or of string variables (each is an element of the array), in which each element is identified by number. The first element is element number 1 (not element number 0, as in C language). Arrays are the easiest way to write code in which the variable affected varies depending on a counting number.

A BASIC program creates an array with the DIM statement discussed below. Certain BASIC statements that return multiple values can create arrays to hold the values. Others require that the array already exist.

When you create a string array, elements that are not yet assigned a value have the value of the empty string. When you create a numeric array, elements that are not yet assigned a value have the value of 0.

Syntax

The name of an array can be the name of a numeric variable (such as A), in which every element is a numeric value; or a string variable (such as A\$), in which every element is a string value.

The simplest array is an array of one dimension (a vector or linear array). If the variable A is a linear array of ten elements, its elements are referenced as A through A. The number inside the brackets is called the index and specifies the array element to be used. The index does not have to be a numeric constant, but can be any numeric expression. The expression A[I] operates on a different element depending on the value of I.

A two-dimensional array (a matrix) can be imagined as a table. All references to this array have two indexes. The first might be the row in the table and the second might be the column. So B[3, 5] might represent information in the table's third row, fifth column.

Segments

You can specify a segment of a one-dimensional array using this same syntax. The first index is the element at which to start, and the second index is the number of elements in the segment. So A[3, 5] means an array segment containing A, A, A, A, and A. Omitting the first index (such as A[, 5]) assumes 1, which starts at element 1 of the array. Omitting the second index (such as A[4, ]) continues to the end of the array. Therefore, omitting both (such as A[,] denotes the entire array. The syntax A[] also denotes the entire array.

Wherever this chapter specifies a vector or presents a variable whose name ends with _vec, it can be either an entire one-dimensional array, or a segment using the two-index syntax shown above.

The segment syntax doesn't apply to all arrays, only those DIM creates with a single dimension, when the program refers to them with two indexes instead of one. For example, if you create a matrix, there is no built-in syntax with which to specify a sub-matrix of it, though you can create a second matrix and copy entries to build such a sub-matrix.

Implementation

When an RFO-BASIC! program creates an array, BASIC obtains memory from the Android device, sufficient to store each element, plus a bookkeeping area in which BASIC remembers the size of the array. There is no limit on the number of dimensions a BASIC array can have, nor on the number of elements in each dimension. The only inherent limitation on the size of an array is the available memory of the Android device.

• Lists are similar to one-dimensional arrays, but provide BASIC statements that let you do things not possible with arrays, such as insert and delete elements and have subsequent elements change position.
• Arrays are always passed to user-defined functions by reference, which means that code inside the function can read and modify any element of the array.
• The LIST.ADD.ARRAY statement builds a list from values contained in an array.
• The GR.SET.PIXELS draws a figure onto the Graphics Screen using x and y coordinates contained in an array.

Creating arrays

DIM

Create one or more arrays

Syntax
DIM arrayspec{, arrayspec}...

where each arrayspec is:

<variablename>[<dim1_nexp>{,<dim2_nexp>}...]
Description

The DIM statement creates one or more arrays as specified in the statement. Each numeric expression specifies how many elements the array will have in that dimension. The number of numeric expressions following a variable specifies how many dimensions the array will have.

A single DIM statement can create many arrays. Each can be either a numeric array or a string array. When RFO-BASIC! creates an array, it obtains memory from the Android device and initializes each element of the array. Elements of numeric arrays are initialized to 0 and elements of string arrays are initialized to the empty string.

Examples
DIM A
DIM B\$[2,6,8], C[3,1,7,3], D

The first example creates a one-dimensional numeric array (vector) with fifteen elements. The second example creates a three-dimensional string array, a four-dimensional numeric array, and a one-dimensional numeric array.

Create a one-dimensional array and specify its initial values

Syntax
ARRAY.LOAD <variablename>[], <exp>, ...

The ARRAY.LOAD statement creates a new, one-dimensional array with the specified <variablename>. Unlike DIM, the writer does not specify the number of elements of the new array with a numeric expression between the brackets. Instead, it follows the brackets with a list of expressions. Each expression is loaded into an element of the new array, starting with element number 1. The size of the new array is the number of expressions in the list.

If the named array already exists, it is overwritten.

The array may be numeric (such as A[]) or string (such as A\$[]). Each expression in the following list must be the same type as the array.

The list of expressions may be continued onto the next line by ending the line with the ~ character. The ~ character may be used between <exp> parameters where a comma would normally appear. The ~ itself separates the parameters; the comma is optional. The ~ character may not be used within a parameter to split it between two lines.

Examples
ARRAY.LOAD Numbers[], 2, 4, 8 , n^2, 32
ARRAY.LOAD Hours[], 3, 4,7,0, 99, 3, 66~        % comma not required before ~
37, 66, 43, 83,~                                % comma is allowed before ~
83, n*5, q/2 +j
ARRAY.LOAD Letters\$[], "a", "b","c",d\$,"e"

ARRAY.COPY

Copies values from a vector to a one-dimensional array, possibly adding new elements

Syntax
ARRAY.COPY <source_array_vec>, <dest_array_name>[{<start_or_extras_nexp>}]
Description

The ARRAY.COPY statement copies elements of the existing array named by <source_array_vec> to <dest_array_name>. The arrays must either both be string arrays or both be numeric arrays. The <source_array_vec> can be an entire array (such as SourceArray[]) or a segment (such as SourceArray[start, length]).

If <dest_array_name> does not exist, then ARRAY.COPY creates it. If ARRAY.COPY includes <start_or_extras_nexp>, then all the specified elements are copied to it, and it also receives extra elements. Their initial values will be 0 in the case of a numeric array, or the empty string in the case of a string array.

• If <start_or_extras_nexp> is positive, then the specified number of elements are created after the elements copied from <source_array_vec>.
• If <start_or_extras_nexp> is negative, then the (positive) specified number of elements are created at the start of the new array, and all the elements copied from <source_array_vec> will be placed after them.

If <dest_array_name> already exists, then ARRAY.COPY overwrites some or all of its elements with values from <source_array_vec>. If <start_or_extras_nexp> exists, it specifies the position in <dest_array_name> where the copying is to begin. The statement may specify a different number of values to copy than the available space in <dest_array_name>. The statement ends without error if it reaches the end of either <source_array_vec> or <dest_array_name>.

Example

The program Sample_Programs/f26_array_copy.bas, included with the RFO-BASIC! installation, contains working examples of the ARRAY.COPY statement.

ARRAY.FILL

Fill a vector with a specified single value

Syntax
ARRAY.FILL <array_vec>, <value_exp>
Description

The ARRAY.FILL statement sets each element of a vector to the value of <value_exp>. The specified array must already exist. The <array_vec> can be an entire array (such as A[]) or a segment (such as A[start, length]). Either the vector and the expression must both be numeric or they must both be string.

Deleting arrays

Syntax
UNDIM <a_arrayname>{, ...}
ARRAY.DELETE <a_arrayname>{, ...}
Description

The UNDIM and ARRAY.DELETE statement are equivalent statements. Both delete one or more specified arrays. Deleting an array releases back to the Android device the memory that the array used. The array name cannot be used except if it is explicitly or implicitly created again. At that time, it does not need to have the same dimensions as it had before.

Testing arrays

Two RFO-BASIC! statements let a program examine arrays it has already created:

ARRAY.DIMS <source_array>[]{, {<dims_array>[]}{, <num_dims_nvar}}

The ARRAY.DIMS statement indicates how many dimensions <source_array> has and how many elements it has in each dimension. This array must already exist.

If <num_dims_nvar> is provided, ARRAY.DIMS sets it to the number of dimensions of <source_array>.

If <dims_array> is provided, ARRAY.DIMS sets elements of it to the length of <source_array> in each dimension. If <dims_array> exists, it must be a one-dimensional numeric array, and you cannot specify a segment. If <dims_array> does not exist, ARRAY.DIMS creates it with a number of elements equal to the number of dimensions of <source_array>.

ARRAY.LENGTH <length_nvar>, <array_vec>

The ARRAY.LENGTH statement returns, in <length_nvar>, the number of elements in <array_vec>.

• If <array_vec> is a one-dimensional array, then this is its length, whether given in the DIM statement or by later extensions.
• If <array_vec> is a segment (such as A[start, length]), then this is the length of the segment. (If length is provided, this is the result, except when there are fewer elements remaining in the array.)

Vector operations

Three RFO-BASIC! statements easily perform common operations on a vector (a one-dimensional array or a segment of one). Since these operations do not require repeat interpretation, they are much more efficient than coding a BASIC loop to perform the computations. The statements in this section can be used on numeric or string arrays. The statements operate by changing the values of elements. If a statement specifies a segment, then elements outside that segment are never changed.

ARRAY.SORT <array_vec>
The ARRAY.SORT statement puts the values in the segment in ascending order. If there are duplicate values in the segment, there will still be duplicate values after executing ARRAY.SORT.
ARRAY.REVERSE <array_vec>
The ARRAY.REVERSE statement puts the values in the segment in reverse order to the order they occupied at the start.
ARRAY.SHUFFLE <array_vec>
The ARRAY.SHUFFLE statement puts the values in the segment in random order.

ARRAY.SEARCH

Search a vector

Syntax
ARRAY.SEARCH <array_vec>, <value_exp>, <pos_nvar>{, <start_nexp>}
Description

The ARRAY.SEARCH statement searches <array_vec> for the first occurrence of <value_exp> and returns in <pos_nvar> the number, relative to the start of the vector, of this first occurrence. If <value_exp> does not occur in the area searched, the statement sets <pos_nvar> to 0.

If <array_vec> is a one-dimensional array, then <pos_nvar> is the position of the occurrence. If <array_vec> is a segment, then it is the position relative to the start of the segment.

If <start_nexp> is present, then the search does not start at the start of the vector, but that many elements into the vector.

ARRAY.SEARCH conducts an exact search, with no heuristics such as rounding or treating capital and lowercase letters as equivalent.

Example
ARRAY.SEARCH A[15,6], 9999, i, 3

The vector to search is the segment consisting of the six elements A through A. The search begins at element number 3 of this segment; that is, at A. Therefore, ARRAY.SEARCH examines elements A through A. It can set i to 3, 4, 5, or 6; or 0 if none of the four equals the desired value 9999.

Vector arithmetic

When a one-dimensional numeric array, or segment of one, exists and contains a series of numbers, several RFO-BASIC! statements easily perform arithmetic on this series.

ARRAY.MAX <max_nvar>,<array_vec>
Sets <max_nvar> to the highest value within <array_vec>.
ARRAY.MIN <min_nvar>,<array_vec>
Sets <min_nvar> to the lowest value within <array_vec>.
ARRAY.STD_DEV <sd_nvar>,<array_vec>
Sets <sd_nvar> to the standard deviation of the elements of <array_vec>.
ARRAY.SUM <sum_nvar>,<array_vec>
Sets <sum_nvar> to the sum of the elements of <array_vec>.
ARRAY.VARIANCE <v_nvar>,<array_vec>
Sets <v_nvar> to the variance of the elements of <array_vec>.

Sources

Manual contents (Statement index)
Language features ArraysData structuresInterrupt routinesUser-defined functions
Interfaces Audio playerBluetoothGraphicsHTMLSocketsSQL
Programming notes Coexisting with Android