Caché MultiValue Basic Reference
CATS
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Concatenates the values of corresponding elements in two dynamic arrays.
Synopsis
CATS(dynarray1,dynarray2)
Arguments
dynarray An expression that resolves to a dynamic array.
Description
The CATS function concatenates the value of each element in dynarray1 to the corresponding element in dynarray2. It then returns a dynamic array containing the results of these concatenations. If a dynamic array element contains an empty string or an element is missing, no concatenation is performed for that element, and the element value from the other dynamic array is returned.
For two elements to be concatenated, they must be on the same dynamic array level. For example, you cannot concatenate a value mark (@VM) dynamic array element to a subvalue mark (@SM) dynamic array element.
Caché MVBasic converts numbers to canonical form (resolving signs, removing leading and trailing zeros, removing a leading plus sign, removing a trailing decimal point) before concatenating. Caché MVBasic does not convert numeric strings to canonical form before concatenating.
If the two dynamic arrays have different numbers of elements, the returned dynamic array has the number of elements of the longer dynamic array. By default, the shorter dynamic array is padded with null string ("") value elements for the purpose of the concatenation operation. You can use the REUSE function to concatenate a default value (instead of the null string) when the dynamic arrays differ in length.
You can use the REUSE function with CATS to concatenate the same value to all of the elements of a dynamic array. You can use the SPLICE function to concatenate the elements of two dynamic arrays, supplying a separator character (or string of characters) that is inserted between the components of each element.
Examples
The following example uses the CATS function to concatenate the elements of two dynamic arrays:
ucase="A":@VM:"B":@VM:"C":@VM:"D"
lcase="aa":@VM:"bb":@VM:"cc":@VM:"dd"
PRINT CATS(ucase,lcase)
      ! returns AaaýBbbýCccýDdd
The following example concatenates two dynamic arrays of different lengths containing empty strings and missing elements:
ucase="A":@VM:"":@VM:@VM:"D"
lcase="aa":@VM:@VM:"cc":@VM:"dd":@VM:"":@VM:"ff"
PRINT CATS(ucase,lcase)
      ! returns AaaýýccýDddýýff
See Also