Recital Arrays

From Recital Documentation Wiki
Jump to: navigation, search

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

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[] = "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[] = "bill"
tab.age = 25
tab.doj = date()
? tab[2]

However, they are most commonly accessed via their key:

? tab.age

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

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.


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

Searching Arrays

  • ascan() - search an array for an expression
numeric = ascan(arrayname as character, searchfor as expression [, startelement as numeric])
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[] = "Bill"
tab.age = 25
echo tab.age, "\n"

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 <arrayname as character> [, for <condition as logical> [, while <condition as logical>]] 
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]]])
numeric = arow()
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)