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.
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. There are 7 VHF television stations in Los Angeles. The procedure below will convert channel numbers into the names of the stations. For example, the procedure converts Channel 7 into KABC.
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,";")
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")
array(myDataArray,3) ☞ 3.14159 array(myDataArray,1) ☞ Bob array(myDataArray,7) ☞ Undefined array value
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.
|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.|