Text Arrays

An array is a numbered collection of data items. Panorama includes a number of functions and statements that treat a single text data item as if it were a numbered collection of smaller items. The smaller text data items must be separated from each other by a delimiter, for instance a comma or carriage return.

A typical text array is shown below. Panorama would normally treat this as a single text item with a length of 40 characters. When treated as a text array, however, this text would be considered as a collection of 7 elements separated by slashes.

    white/red/orange/yellow/green/blue/black

In this example, the / is the separator character. You can use any character you want for a separator character. Here is the same array, but using the ; character (semi-colon) as the separator character.

    white;red;orange;yellow;green;blue;black

It is possible to use different separator characters at different times. You could even build a multi-level array by using two different separator characters.

Since text arrays are a secondary data type, it is up to you to keep track of the fact that you are using an array and what the separator character is. Panorama won’t stop you from trying to access the array of colors above as if it were delimited with commas instead of semi-colons, but you probably won’t get the results you wanted unless you use the correct separator character.

Any Unicode character can be used as a separator character, so you have tens of thousands of possible choices. Common separators include commas, semi-colons, slashes, carriage returns, spaces and tabs. Note also that Panorama X now supports the use of separators consisting of multiple characters as well as just a single character. Here is an example of an array using a multi-character separator.

    red, green, yellow, white

In this example the separator would consist of the comma and space characters together.

It’s important to pick a separator character that will not occur in the data elements of your array. If your data may include commas, don’t use the comma as a separator character. If the data might include carriage returns, don’t use a carriage return. If you want to be extra sure to avoid conflicts, pick a non-printing character. You can use the chr( function to generate non-printing characters, for example chr(1), chr(2), chr(3). Most chr values below 32 are non-printing except for chr(9) and chr(13), which correspond to tab and carriage return. You can also use tab() and cr() to generate these special characters.

Some Panorama user interface elements and functions use text arrays as parameters or to hold a list of values. For these applications, the separator character is usually required to be a carriage return. For example, the Pop-Up Menu SuperObject uses a carriage return delimited array to define the list of pop-up menu choices. The lookupall( function extracts information from another database and places it into an array with whatever separator you specify. Consult the documentation for each individual statement, function or SuperObject to see the exact specifications for any arrays they may use.

You can easily change the separator character of an array with the replace( function. The assignment statement below changes the separator character of the array Elements from semi-colons to carriage returns.

    Elements=replace(Elements,";",cr())

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.

History

Version | Status | Notes
10.0 | Updated | Carried over from Panorama 6.0. but now allows Unicode and multiple character separators.