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  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.

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

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  through. 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  operates on a different element depending on the value of. In this way, you can write code that refers to different array elements at different times.

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

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  means an array segment containing ,  ,  ,  , and. Omitting the first index (such as ) assumes 1, which starts at element 1 of the array. Omitting the second index (such as ) continues to the end of the array. Therefore, omitting both (such as  denotes the entire array.  The syntax   also denotes the entire array.
 * Segments

Wherever this chapter specifies a vector or describes a parameter with a name ending in _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.

Private version. Oli-BASIC lets the programmer perform a wide variety of mathematical operations on all the elements of an array. This is much faster than looping and gaining access to the elements, one at a time, with an index variable.  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.
 * Implementation


 * See also
 * Lists are similar to one-dimensional arrays, but additional BASIC statements add helpful operations, such as insert and delete, where subsequent elements shift 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.

DIM
Create one or more arrays

DIM arrayspec{, arrayspec}... where each  is: [{,}...]
 * Syntax

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.
 * Description

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.

DIM A[15] DIM B$[2,6,8], C[3,1,7,3], D[8], E[3, 4]
 * Examples

The first example creates a one-dimensional numeric array (vector) with fifteen elements (A). The second example creates a three-dimensional string array (B$), a four-dimensional numeric array (C), a one-dimensional numeric array (D), and a two-dimensional numeric array (E).

ARRAY.LOAD
Create a one-dimensional array and specify its initial values

ARRAY.LOAD [],, ...
 * Syntax

The ARRAY.LOAD statement creates a new, one-dimensional array with the specified. 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 ) or string (such as  ). 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 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.

ARRAY.LOAD Numbers[], 2, 4, 8, n^2, 32
 * Examples

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

ARRAY.COPY ) or a segment (such as  start  length ).
 * Syntax

If  does not exist, then ARRAY.COPY creates it. If ARRAY.COPY includes , 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  is positive, then the specified number of elements are created after the elements copied from, included with the RFO-BASIC! installation, contains working examples of the ARRAY.COPY statement.

ARRAY.FILL
Fill a vector with a specified single value

ARRAY.FILL , 
 * Syntax

The ARRAY.FILL statement sets each element of a vector to the value of . The specified array must already exist. The  can be an entire array (such as ) or a segment (such as  start  length ). Either the vector and the expression must both be numeric or they must both be string.
 * Description

Deleting arrays
UNDIM {, ...}
 * Syntax

ARRAY.DELETE {, ...}

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.
 * Description

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

ARRAY.DIMS 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.)

String operations
Two RFO-BASIC! statements parse a string into an array, and reassemble an array into a string. This technique might seem to add a data conversion step to the program's computation, but getting the pieces of a string into an array, and operating on them there, is actually many times faster than operating on substrings in interpreted BASIC code.

SPLIT
Split a string into pieces and populate an array with them

SPLIT{.ALL} $[],  are required. If this array exists, SPLIT overwrites it; otherwise, SPLIT creates a new array.
 * Synopsis

The SPLIT statement looks for a separator to define the pieces of the source string. Normally, the separator is any white space (one or more spaces, tabs, or separator characters), so the pieces of the string are discrete words of text; any punctuation not separated by white space is included in this "word." You can specify a different separator by providing the optional third parameter. It is a UNIX Regular Expression (as defined in http://developer.android.com/reference/java/util/regex/Pattern.html), a language often used for pattern-matching.

Here are some interesting values for :
 * means match on any white space, which is the same effect as omitting this parameter entirely.
 * is a regular expression that matches on anything. Its effect is to divide   is used in the example below to indicate that   is the separator.

The following rules describe cases where array elements are set to the empty string:
 * If the source string begins with the separator, then there is an implicit null first piece, so the first element of the array gets the empty string. (The WORD$ function works differently; it strips leading and trailing occurrences of the separator before splitting the string.)
 * If the separator occurs twice in a row (with nothing between them), then the piece of the string between them is null, and the corresponding element of the array gets the empty string.
 * If the string ends with one or more occurrences of the separator:
 * The SPLIT statement does not create corresponding elements of the array.
 * The SPLIT.ALL statement does create one element of the array for each null trailing piece.
 * (Again, the WORD$ function strips trailing occurrences of the separator.)

This example uses  as the separator. Thus, there is an empty piece at the start, one in the middle, and one at the end of the string. string$ = ":a:b::c:d:" SPLIT result$[], string$, ":" ARRAY.LENGTH length, result$[] FOR I = 1 TO length PRINT "{" + result$[i] + "}"; NEXT I PRINT
 * Example

The output is. But SPLIT.ALL would include a seventh array element for the trailing null piece, and the test program would output.

JOIN
The JOIN statement does the reverse of SPLIT: It assembles elements of a string array into a single string.

JOIN{.ALL}. Enclose the entire thing in double quotes to form a valid literal.
 * Synopsis

This example uses both the SPLIT statement described above and the JOIN statement. It produces a string in the CSV format (comma-separated values), with each value quoted with double quotes. So we want the separator between values to be  (a double quote to end the preceding piece and another to introduce the following piece) and the wrapper at the start and end of the result to be. InnerPlanets$ = "Mercury Venus Earth Mars" % Each planet a "word" SPLIT IP$[], InnerPlanets$                 % Get one planet in each array element JOIN IP$[], CSV$,  "\","\"",  "\""         % Create a CSV string PRINT CSV$
 * Example

The output from this test program is: "Mercury","Venus","Earth","Mars"

As another example, this code simply reverses the characters in the variable var$: SPLIT tmp$[], var$, "\\\\|"   % Separate each character! ARRAY.REVERSE tmp$[]          % See Vector operations below JOIN tmp$[], var$             % No separator, no wrapper

It is not only more elegant and readable than stepping through the string in a FOR/NEXT loop but many times faster.

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 


 * 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 


 * 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

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

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.
 * Description

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.

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

The vector to search is the segment consisting of the six elements A[15] through A[20]. The search begins at element number 3 of this segment; that is, at A[17]. Therefore, ARRAY.SEARCH examines elements A[17] through A[20]. 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>.