Recital Arrays

Recital Arrays

An Overview of Arrays in Recital

Recital supports the use of one and two-dimensional static arrays, which have a defined number of elements, and multi-dimensional associative arrays which have a dynamic structure.

Static Arrays

A static array is an ordered list of elements (variables) that is of a fixed size (number of elements). You declare a static array by specifying the number of elements when you declare a variable.

private tab[ 20 ]    // declare a static array of 20 elements all initialized to False
 
// iterate through the array (note the use of the alen( ) function to find the length of the array
for i=1 to alen( tab )
    // change each array element to hold a numeric value
    tab[ i ] = i
endfor

You can initialize a static array with one statement.

// declare the array and init all elements to false
declare tab[10, 10]
 
// or
dimension tab(10, 10)
 
// init all elements to zero
tab = 0

You can create and initialize static arrays using static array initializers.

// simple one dimensional array with 2 elements
private tab = { "Hello", "world" }
 
// two-dimensional array of two rows with three columns in each row
private tab2 = { { "Hello", 10, date() ], { "world", 20, date()+1 } }
 
// create an array on the fly
mytab = { 10, 20, 30, 40, 50, 60 }

You can view the contents of a static array using the echo or ? commands.

? tab

Accessing Elements in a Static Array

Elements in a static array are accessed using the element number, or the element subscripts in the case of two-dimensional arrays. Array element numbers and subscripts start from 1 and are specified in square or round brackets after the array name. Row and column subscripts are separated by a comma: [row,column].

? array1[3]
? array2[2,4]
? array3(5,2)

• aelement() - return the number of an array element from the element subscripts

numeric = aelement(arrayname as character, row as numeric [, column as numeric])

• asubscript() - return the row or column subscript of an array element from the element number

numeric = asubscript(arrayname as character, element as number, roworcolumn as numeric)

• alen() - return the number of elements, rows or columns of an array

numeric = alen(arrayname as character [, rowsorcolumns as numeric])

Associative Arrays

An associative array (also known as a dynamic array) is a collection of key/value pairs where the key can be used to retrieve the value. Associative arrays are dynamic, meaning that elements can be added and removed dynamically.

private tab[]    // note the use of [] to denote a dynamic array
 
tab["name"] = "bill"
tab["age"] = 25
tab["doj"] = date()
 
// Alternative syntax
private tab[]
 
tab.name = "bill"
tab.age = 25
tab.doj = date()

Associative arrays can be created and initialized in one statement using the array( ) function.

tab = array("name" => "bill", "age" => 25, ""doj" => date())

You can view the contents of an associative array using the echo or ? commands.

? tab

Accessing Elements in an Associative Array

Like static arrays, associative arrays can also be accessed via their element number in square brackets:

private tab[]
tab.name = "bill"
tab.age = 25
tab.doj = date()
 
? tab[2]
        25

However, they are most commonly accessed via their key:

? tab.age
        25

When setting the element value, the key must be used.

tab["age"] = 26

Changing, Adding and Removing Elements From Arrays

• aadd() - add a new element to the end of an array

expression = aadd(arrayname as character, newelement as expression)

• adel() - delete an element from an array

logical = adel(arrayname as character, element as numeric | row as numeric [, dimension as numeric])

• ains() - insert an element into an array

logical = ains(arrayname as character, element as numeric [, value as expression])

• asize() - resize an array

asize(arrayname as character, elements as numeric)

Looping Through Arrays

The foreach...endfor command is used to iterate over each element in an array or member in an object or associative array.

foreach <array> as <value as variable> | <array> as <key variable> => <value as variable>
<statements>
endfor

The array must be the name of an existing array or object. The value is a reference to be loaded with the contents of each element or member in turn. Using the <key> => <value> syntax, the member names of an object or associative array can also be accessed.

Examples

// static array
numbers = array(1,2,3,4,5,6,7,8,9,10)
foreach numbers as elem
    ? elem * elem
endfor
 
// associative array
private myarray = array("Name" => "Recital", "Description" => "database")
foreach myarray as key => value
    echo "key=" + key + " value=" + value + "\n"
endfor

Searching Arrays

• ascan() - search an array for an expression

numeric = ascan(arrayname as character, searchfor as expression [, startelement as numeric])

• in_array() - search an array for an expression

logical = in_array(searchfor as expression, arrayname as character)

Replacing Sections of an Array

• acopy() - copy elements from one array to another

logical = acopy(fromarrayname as character, toarrayname as character [, fromstartelement as numeric 
  [, elements as numeric [, tostartelement as numeric]]])

• afill() - fill a defined section of an array with an expression

logical = afill(arrayname as character, fillwith as expression [, startelement as numeric [, elements as numeric]])

Sorting an Array

• asort() - sort the character elements of the specified array

logical = asort(arrayname as character [, startelement as numeric [, endelement as numeric [, reverse as numeric]]])

Passing Arrays as Function Arguments

Both static and dynamic arrays are passed to functions by reference, allowing the original of the array to be updated by the called function.

function func1
    parameter p1
    p1.age = 27
return .t.
 
private tab[]
tab.name = "Bill"
tab.age = 25
func1(tab)
echo tab.age, "\n"
       27

Miscellaneous Array Commands and Functions

• is_array() - check whether an expression is the name of an array

logical = is_array(checkthis as expression)

Copying Table Data to and from Arrays

• append from array - copy data from an array to a table

append from array <arrayname as character> [, for <condition as logical> [, while <condition as logical>]] 

• copy to array - copy data from a table to an array

copy to array <arrayname as character> [, fields <fieldlist as list> [, for <condition as logical> [, while <condition as logical>]]] 

• scatter - copy fields in a record to the elements of an array

scatter to <arrayname as character> [, fields <fieldlist as list>]

• gather - replace fields in a record with elements from an array

gather from <arrayname as character> [, fields <fieldlist as list>]

Table and File Information in Arrays

• abrowse() - browse a two-dimensional array in a spreadsheet style format

abrowse(startrow as numeric, startcolumn as numeric, endrow as numeric, endcolumn as numeric, data as array
  [, udf as character [, pictureformat as array [, headings as array]]])

• acol() - return a column coordinate from an array in abrowse()

numeric = arow()

• arow() - return a row coordinate from an array in abrowse()

numeric = arow()

• adir() - return the number of files matching a file pattern

numeric = adir(pattern as character [, filenames as array [, filesizes as array [, filedates as array [, filetimes as array [, compatibility as array]]]]]) 

• afields() - fill a series of arrays with table structure details

numeric = afields(fieldnames as array [, datatypes as array [, lengths as array [, decimals as array]]]) 

In FoxPro, Foxbase or VFP compatibility mode, Visual FoxPro syntax is supported:

numeric = afields(fieldinfo as array [, workarea as numeric | alias as character])

• adesc() - fill an array with field descriptions, returning the number of fields

numeric = adesc(descriptions as array)

Converting a String Into an Array

• alines() - fill an array from a string with separate character elements, separated with a line feed by default, and return the number of elements

numeric = alines(arrayname, string as character, [, flags as numeric [, separator as character]])

• astore() - fill an array from a string with separate character elements and return the number of elements

numeric = astore(arrayname, string as character, separator as character)

• explode() - separate a character string into individual elements and return as an array

array = explode(separator as chatacter, string as character)

Converting an Array into a String

• astring() - return an array as a character string, with the elements separated by a comma or other specified character

character = astring(arrayname [, separator as character])

• implode() - return an array as a character string, with the elements separated by a specified character

character = implode(separator as character, arrayname)

Numeric Array Functions

• aaverage() - calculate the average of element values in an array

numeric = aaverage(arrayname as character)

• amax() - return the highest element value in an array

numeric = amax(arrayname as character)

• amin() - return the lowest element value in an array

numeric = amin(arrayname as character)

• asum() - calculate the sum of element values in an array

numeric = asum(arrayname as character)