arrayrange(
arrayrange(
ARRAY
,
FIRSTITEM
,
LASTITEM
,
SEPARATOR
)

The arrayrange( function extracts a series of data items from a text array or a data array (see Text Arrays and Data Arrays).

Parameters

This function has four parameters:

array – The text array or data array that contains the data you want to extract.

firstitem – The number of the first data item you want to extract. The items are numbered starting from 1 (1, 2, 3, …). Note: You can also use a negative value, in which case the position is specified from the end of the array, for example –1 for the last item, –2 for the second to the last item, etc.

lastitem – The number of the last data item you want to extract. The items are numbered starting from 1 (1, 2, 3, …). Note: You can also use a negative value, in which case the position is specified from the end of the array, for example –1 for the last item, –2 for the second to the last item, etc.

separator – Is the separator character for this array (omit this parameter for data arrays).

Description

This function returns a series of items from the array. It returns the first item, the last item, and everything in between (including any separators that are in between). If the last item does not exist (for example if you ask for item 12 from a 7 item array) the function will return up to the actual last item in the array. If both requested items do not exist, the function will return empty text (""). If LASTITEM is less than FIRSTITEM, the function will return empty text.

    arrayrange("Red,Green,Blue",1,2,",") ☞ Red,Green
    arrayrange("Red,Green,Blue",2,3",") ☞ Green,Blue
    arrayrange("Red,Green,Blue",2,4,",") ☞ Green,Blue
    arrayrange("Red,Green,Blue",4,7,",") ☞
    arrayrange("Red,Green,Blue",0,3,",") ☞
    arrayrange("gold/silver/bronze",1,2,"/") ☞ gold/silver
    arrayrange("this is a test",3,4," ") ☞ a test

If either the first or last item number is negative, the array elements will be counted from the end instead of from the beginning. For example using –2,–1 returns the final two elements in the array, no matter how many elements there are.

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

Let’s take a look at a couple of real world examples. This example will fill the variable WeekDays with the text Mon,Tue,Wed,Thu,Fri.

    Days="Sun,Mon,Tue,Wed,Thu,Fri,Sat"
    WeekDays=arrayrange(Days,2,6,",")

The arrayrange( function is very handy for removing elements from the start or end of an array. The example below calculates what lessons a person still must complete to graduate, based on a numeric field or variable named Completed.

    Lessons="Basic,Intermediate,Advanced"
    ToDo=arrayrange(Lessons,Completed,-1,",")

If the person has completed 1 lesson, ToDo will be Intermediate,Advanced. If the person has completed 2 lessons, ToDo will be Advanced.

#### Working with Data Arrays

This function works with both data and text arrays. Because Data Arrays have no separators between elements, the separator parameter is omitted when targeting a data array.

This example uses the arrayrange( function:

    arrayrange(dataarray("Bob",123,rectangle(2,4,6,8),3.14159,"Green"),3,5)

to create a new data array containing the third, fourth and fifth elements, viz. rectangle(2,4,6,8), 3.14159, and Green.

If you specify a second item position less than the first item position, the result will be an empty string.

If you specify a first item position beyond the range of the array and a second item position greater than the first item position, you will get the error message, “Undefined array value”.

See Also

- array( -- extracts a single data item from a text array or a data array (see Text Arrays and Data Arrays).
- 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, with the ability to use negative numbers for the first and last item numbers, and also now has the ability to handle data arrays.