SUBSTRINGS

Returns a substring for each element of a dynamic array.

Synopsis

```SUBSTRINGS(dynarray,start,length)
```

Arguments

 dynarray An expression that resolves to a dynamic array of elements from which a dynamic array of substrings is to be extracted. start An expression that resolves to a positive integer specifying the start position (counting from 1) within each element to begin extracting a substring. length An expression that resolves to a positive integer specifying the number of characters to extract from each element, beginning with the start position.

Description

The SUBSTRINGS function returns a dynamic array of substrings, each substring element containing the specified length number of characters from the corresponding dynarray element. SUBSTRINGS returns a substring for every element, regardless of the element's level delimiter.

If start is 1, substrings are extracted starting with the first character of each element. If start is 0, a negative number, the null string, or a non-numeric string, SUBSTRINGS behaves as if start=1. If start is greater than the character length of an element, the returned dynamic array contains only the level delimiter for that element.

If length is greater than the dynarray element's length, the full element value is returned. If length is 0, a negative number, the null string, or a non-numeric string, the length is parsed as 0; the returned dynamic array contains only the level delimiters from the original dynarray.

If start or length is a mixed numeric string, the numeric part is parsed until a non-numeric character is encountered. Thus “7dwarves” is parsed as 7.

You can use the [] string operator to perform a similar substring extract from a string. For further details, refer to the Operators page of this manual.

Examples

The following example uses the SUBSTRINGS function to return a dynamic array containing the first three characters of each element of a dynamic array:

``````cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
alphalist=SUBSTRINGS(cities,1,3)
PRINT alphalist
! Returns: "NewýLonýChiýBosýLos"
``````