array( function

array(

ARRAY

ITEM

SEPARATOR

)

The array( function extracts a single data item from a text array or a data array (see Text Arrays and Data Arrays).

Parameters

This function has three parameters:

array – an array that contains the data you want to extract. This parameter can also be a binary value as long as the binary value contains text encoded using UTF-8.

item – number of the data item you want to extract. The first item is 1, the second item is 2, the third is 3, etc. or you can use negative values, -1 (last item), -2 (second to last), etc.

separator – the separator character or characters for this array. This can be a single or multiple characters.

Description

This function returns an item of text from the array. Only the item itself is returned, the separator characters on each end are not included (there are, of course, no separators if the target array is a data array). If the item does not exist (for example if you ask for item 12 from a 7 item array) the function will return empty text (“”) if you are operating on a text array but you will get an error message, “Undefined array value”, if you are operating on a data array.

array("Red,Green,Blue",1,",") ☞ Red
array("Red,Green,Blue",2,",") ☞ Green
array("Red,Green,Blue",3,",") ☞ Blue
array("Red,Green,Blue",4,",") ☞ 
array("Red,Green,Blue",0,",") ☞ 
array("gold/silver/bronze",2,"/") ☞ silver
array("this is a test",4," ") ☞ test
array("Apples and Peaches and Grapes",2," and ")☞ Peaches

If the item number is negative, the array elements will be counted from the end instead of from the beginning. For example using -1 returns the final element in the array, no matter how many elements there are.

array("Red,Green,Blue",-1,",") ☞ Blue
array("Red,Green,Blue,Brown,Black",-1,",") ☞ Black
array("Red,Green,Blue,Brown,Black,White",-1,",") ☞ White

Let’s take a look at a couple of real world examples. At the beginning of 2009, there were 7 VHF television stations in Los Angeles. (On June 12,2009 they were forced to shut down by the FCC as all stations were mandated to go digital.) The procedure below will convert channel numbers into the names of the stations. For example, the procedure converts Channel 7 into KABC.

Stations=",KCBS,,KNBC,KTLA,,KABC,,KCAL,,KTTV,,KCOP"
ChannelName=array(Stations,7,",")

The example uses an array called Stations. This array uses commas as a separator character. Note that the first character in the array is a comma separator - this means that the first array element is empty. Similarly, consecutive separators indicate empty elements.

The more complete example below displays the name of an element after the user enters an atomic number from 1 to 103. In this example, the variable, Elements, contains an array of atomic element names, separated by semicolons (some of the assignment statement has been left out for clarity).

local Elements,AtomicNumber,AtomicName
Elements="Hydrogen;Helium;Lithium;Beryllium;Boron;"+
   "Carbon;Nitrogen;Oxygen;Fluorine;Neon;"+
   ...
   "Mendelevium;Nobelium;Lawrencium"
AtomicNumber="1"
gettext "Enter Atomic Number",AtomicNumber
AtomicNumber=val(AtomicNumber)
if error
    AtomicNumber=0
endif
AtomicName=array(Elements,AtomicNumber,";")

Data Array Items

The array( function can be used with a data array as well as a text array. Because Data Arrays have no separators between elements, the separator parameter is omitted when targeting a data array.

Suppose we have a data array, myDataArray, defined as below (noting that a data array can contain text, numeric, binary and other data types):

myDataArray = dataarray("Bob",123,3.14159,"Green")

Then

array(myDataArray,3) ☞ 3.14159
array(myDataArray,1) ☞ Bob
array(myDataArray,7) ☞ Undefined array value

Error Messages

array( function: TEXT parameter must be text. – The array (first parameter) must be text, not a number.

array( function: ITEM parameter must be numeric. – The item (second parameter) must be a number, not text.

array( function: SEPARATOR parameter must be text. – The separator character or characters (third parameter) must be text, not a number.

See Also

arrayelement( -- converts between character positions and array element numbers in a text array.
arrayrange( -- extracts a series of data items from a text array or a data array (see Text Arrays and Data Arrays).
arraysearch( -- searches a text array or a data array (see Text Arrays and Data Arrays) to see if it contains a specific value.
arraysize( -- returns the number of elements in a text array or a data array (see Text Arrays and Data Arrays).
extract( -- extracts a single data item from a text array, and can also be used to count the number of items in the array.
Text Arrays -- A numbered collection of text values.

History

Version	Status	Notes
10.0	Updated	Carried over from Panorama 6.0, but the item number can now be negative to designate that it should be counted from the end of the string instead of from the beginning. More than one character is now allowed for use as the separator parameter.