Difference between revisions of "Recital Arrays"

From Recital Documentation Wiki
Jump to: navigation, search
(Miscellaneous Array Functions)
 
(48 intermediate revisions by one user not shown)
Line 1: Line 1:
 
==Recital Arrays==
 
==Recital Arrays==
 
===An Overview of Arrays in Recital===
 
===An Overview of Arrays in Recital===
===How to Create a Static Array 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====
+
 
 +
===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.  
 
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.  
Line 21: Line 22:
 
// declare the array and init all elements to false
 
// declare the array and init all elements to false
 
declare tab[10, 10]
 
declare tab[10, 10]
 +
 +
// or
 +
dimension tab(10, 10)
  
 
// init all elements to zero
 
// init all elements to zero
Line 39: Line 43:
 
</code>
 
</code>
  
You can view the contents of a static array using the '''echo''' or '''?''' commands.
+
You can view the contents of a static array using the [[ECHO|echo]] or [[?]] commands.
  
 
<code lang="recital">
 
<code lang="recital">
Line 45: Line 49:
 
</code>
 
</code>
  
===How to Create an Associative Array in Recital===
+
====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]''.
 +
 
 +
<code lang="recital">
 +
? array1[3]
 +
? array2[2,4]
 +
? array3(5,2)
 +
</code>
 +
 
 +
* [[AELEMENT()|aelement()]] - return the number of an array element from the element subscripts
 +
 
 +
<pre>
 +
numeric = aelement(arrayname as character, row as numeric [, column as numeric])
 +
</pre>
 +
 
 +
* [[ASUBSCRIPT()|asubscript()]] - return the row or column subscript of an array element from the element number
 +
 
 +
<pre>
 +
numeric = asubscript(arrayname as character, element as number, roworcolumn as numeric)
 +
</pre>
 +
 
 +
* [[ALEN()|alen()]] - return the number of elements, rows or columns of an array
 +
 
 +
<pre>
 +
numeric = alen(arrayname as character [, rowsorcolumns as numeric])
 +
</pre>
 +
 
 +
===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.
 
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.
  
Line 53: Line 84:
 
tab["name"] = "bill"
 
tab["name"] = "bill"
 
tab["age"] = 25
 
tab["age"] = 25
tab["dob"] = date()
+
tab["doj"] = date()
 +
 
 +
// Alternative syntax
 +
private tab[]
 +
 
 +
tab.name = "bill"
 +
tab.age = 25
 +
tab.doj = date()
 
</code>
 
</code>
  
Associative arrays can be created and initialized in one statement using the '''array( )''' function.
+
Associative arrays can be created and initialized in one statement using the [[ARRAY()|array( )]] function.
  
 
<code lang="recital">
 
<code lang="recital">
tab = array("name" => "bill", "age" => 25, ""dob" => date())  
+
tab = array("name" => "bill", "age" => 25, ""doj" => date())  
 
</code>
 
</code>
  
You can view the contents of an associative array using the '''echo''' or '''?''' commands.
+
You can view the contents of an associative array using the [[ECHO|echo]] or [[?]] commands.
  
 
<code lang="recital">
 
<code lang="recital">
Line 68: Line 106:
 
</code>
 
</code>
  
===Accessing Elements in a Static Array===
+
====Accessing Elements in an Associative Array====
===Accessing Elements in an Associative Array===
+
Like static arrays, associative arrays can also be accessed via their element number in square brackets:
 +
 
 +
<code lang="recital">
 +
private tab[]
 +
tab.name = "bill"
 +
tab.age = 25
 +
tab.doj = date()
 +
 
 +
? tab[2]
 +
        25
 +
</code>
 +
 
 +
However, they are most commonly accessed via their '''key''':
 +
 
 +
<code lang="recital">
 +
? tab.age
 +
        25
 +
</code>
 +
 
 +
When setting the element value, the key must be used.
 +
 
 +
<code lang="recital">
 +
tab["age"] = 26
 +
</code>
 +
 
 
===Changing, Adding and Removing Elements From Arrays===
 
===Changing, Adding and Removing Elements From Arrays===
 +
* [[AADD()|aadd()]] - add a new element to the end of an array
 +
 +
<pre>
 +
expression = aadd(arrayname as character, newelement as expression)
 +
</pre>
 +
 +
* [[ADEL()|adel()]] - delete an element from an array
 +
 +
<pre>
 +
logical = adel(arrayname as character, element as numeric | row as numeric [, dimension as numeric])
 +
</pre>
 +
 +
* [[AINS()|ains()]] - insert an element into an array
 +
 +
<pre>
 +
logical = ains(arrayname as character, element as numeric [, value as expression])
 +
</pre>
 +
 +
* [[ASIZE()|asize()]] - resize an array
 +
 +
<pre>
 +
asize(arrayname as character, elements as numeric)
 +
</pre>
 +
 
===Looping Through Arrays===
 
===Looping Through Arrays===
 +
The [[FOREACH|foreach...endfor]] command is used to iterate over each element in an array or member in an object or associative array.
 +
 +
<pre>
 +
foreach <array> as <value as variable> | <array> as <key variable> => <value as variable>
 +
<statements>
 +
endfor
 +
</pre>
 +
 +
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'''
 +
 +
<code lang="recital">
 +
// 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
 +
</code>
 +
 +
===Searching Arrays===
 +
* [[ASCAN()|ascan()]] - search an array for an expression
 +
 +
<pre>
 +
numeric = ascan(arrayname as character, searchfor as expression [, startelement as numeric])
 +
</pre>
 +
 +
* [[IN_ARRAY()|in_array()]] - search an array for an expression
 +
 +
<pre>
 +
logical = in_array(searchfor as expression, arrayname as character)
 +
</pre>
 +
 
===Replacing Sections of an Array===
 
===Replacing Sections of an Array===
 +
* [[ACOPY()|acopy()]] - copy elements from one array to another
 +
 +
<pre>
 +
logical = acopy(fromarrayname as character, toarrayname as character [, fromstartelement as numeric
 +
  [, elements as numeric [, tostartelement as numeric]]])
 +
</pre>
 +
 +
* [[AFILL()|afill()]] - fill a defined section of an array with an expression
 +
 +
<pre>
 +
logical = afill(arrayname as character, fillwith as expression [, startelement as numeric [, elements as numeric]])
 +
</pre>
 +
 
===Sorting an Array===
 
===Sorting an Array===
 
* [[ASORT()|asort()]] - sort the character elements of the specified array
 
* [[ASORT()|asort()]] - sort the character elements of the specified array
Line 81: Line 219:
  
 
===Passing Arrays as Function Arguments===
 
===Passing Arrays as Function Arguments===
===Miscellaneous Array Functions===
+
Both static and dynamic arrays are passed to functions by reference, allowing the original of the array to be updated by the called function.
 +
 
 +
<code lang="recital">
 +
function func1
 +
    parameter p1
 +
    p1.age = 27
 +
return .t.
 +
 
 +
private tab[]
 +
tab.name = "Bill"
 +
tab.age = 25
 +
func1(tab)
 +
echo tab.age, "\n"
 +
      27
 +
</code>
 +
 
 +
===Miscellaneous Array Commands and Functions===
 +
* [[IS_ARRAY()|is_array()]] - check whether an expression is the name of an array
 +
 
 +
<pre>
 +
logical = is_array(checkthis as expression)
 +
</pre>
 +
 
 +
====Copying Table Data to and from Arrays====
 +
* [[APPEND FROM ARRAY|append from array]] - copy data from an array to a table
 +
 
 +
<pre>
 +
append from array <arrayname as character> [, for <condition as logical> [, while <condition as logical>]]
 +
</pre>
 +
 
 +
* [[COPY TO ARRAY|copy to array]] - copy data from a table to an array
 +
 
 +
<pre>
 +
copy to array <arrayname as character> [, fields <fieldlist as list> [, for <condition as logical> [, while <condition as logical>]]]
 +
</pre>
 +
 
 +
* [[SCATTER|scatter]] - copy fields in a record to the elements of an array
 +
 
 +
<pre>
 +
scatter to <arrayname as character> [, fields <fieldlist as list>]
 +
</pre>
 +
 
 +
* [[GATHER|gather]] - replace fields in a record with elements from an array
 +
 
 +
<pre>
 +
gather from <arrayname as character> [, fields <fieldlist as list>]
 +
</pre>
 +
 
 +
====Table and File Information in Arrays====
 +
* [[ABROWSE()|abrowse()]] - browse a two-dimensional array in a spreadsheet style format
 +
 
 +
<pre>
 +
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]]])
 +
</pre>
 +
 
 +
* [[ACOL()|acol()]] - return a column coordinate from an array in [[ABROWSE()|abrowse()]]
 +
 
 +
<pre>
 +
numeric = arow()
 +
</pre>
 +
 
 +
* [[AROW()|arow()]] - return a row coordinate from an array in [[ABROWSE()|abrowse()]]
 +
 
 +
<pre>
 +
numeric = arow()
 +
</pre>
 +
 
 +
* [[ADIR()|adir()]] - return the number of files matching a file pattern
 +
 
 +
<pre>
 +
numeric = adir(pattern as character [, filenames as array [, filesizes as array [, filedates as array [, filetimes as array [, compatibility as array]]]]])
 +
</pre>
 +
 
 +
* [[AFIELDS()|afields()]] - fill a series of arrays with table structure details
 +
 
 +
<pre>
 +
numeric = afields(fieldnames as array [, datatypes as array [, lengths as array [, decimals as array]]])
 +
</pre>
 +
 
 +
In FoxPro, Foxbase or VFP [[SET COMPATIBLE|compatibility mode]], Visual FoxPro syntax is supported:
 +
 
 +
<pre>
 +
numeric = afields(fieldinfo as array [, workarea as numeric | alias as character])
 +
</pre>
 +
 
 +
* [[ADESC()|adesc()]] - fill an array with field descriptions, returning the number of fields
 +
 
 +
<pre>
 +
numeric = adesc(descriptions as array)
 +
</pre>
 +
 
 
====Converting a String Into an Array====
 
====Converting a String Into an Array====
 +
* [[ALINES()|alines()]] - fill an array from a string with separate character elements, separated with a line feed by default, and return the number of elements
 +
 +
<pre>
 +
numeric = alines(arrayname, string as character, [, flags as numeric [, separator as character]])
 +
</pre>
 +
 
* [[ASTORE()|astore()]] - fill an array from a string with separate character elements and return the number of elements
 
* [[ASTORE()|astore()]] - fill an array from a string with separate character elements and return the number of elements
  
Line 108: Line 343:
 
</pre>
 
</pre>
  
===Summary===
+
====Numeric Array Functions====
 +
* [[AAVERAGE()|aaverage()]] - calculate the average of element values in an array
 +
 
 +
<pre>
 +
numeric = aaverage(arrayname as character)
 +
</pre>
 +
 
 +
* [[AMAX()|amax()]] - return the highest element value in an array
 +
 
 +
<pre>
 +
numeric = amax(arrayname as character)
 +
</pre>
 +
 
 +
* [[AMIN()|amin()]] - return the lowest element value in an array
 +
 
 +
<pre>
 +
numeric = amin(arrayname as character)
 +
</pre>
 +
 
 +
* [[ASUM()|asum()]] - calculate the sum of element values in an array
 +
 
 +
<pre>
 +
numeric = asum(arrayname as character)
 +
</pre>

Latest revision as of 15:31, 9 January 2012

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