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

Combines two dynamic arrays into a new dynamic array.
Synopsis
SPLICE(dynarray1,separator,dynarray2)
Arguments
dynarray An expression that resolves to a dynamic array.
separator An expression that resolves to a character or string of characters. SPLICE inserts separator when concatenating two elements from different dynamic arrays. If you specify a null string, no separator is inserted between concatenated elements.
Description
The SPLICE function concatenates two dynamic arrays on an element-by-element basis. It returns a dynamic array containing all of the element values of dynarray1 and dynarray2, with a separator between the components of each element.
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. SPLICE inserts the separator in every element of the returned dynamic array, even when a source element is missing or is the null string. 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 SPLICE to concatenate the same value to all of the elements of a dynamic array. You can use the CATS function to concatenate the elements of two dynamic arrays with no separator between the element components.
Examples
The following example uses SPLICE to return a concatenated dynamic array including all of the elements in dynamic arrays a and b:
a=10:@VM:20:@VM:30:@VM:40
b=15:@VM:25:@VM:35:@VM:45
PRINT SPLICE(a,'/',b)
      ! returns 10/15v20/25v30/35v40/45
The following example uses SPLICE to concatenate a dynamic array with itself, specifying a null string separator:
a=10:@VM:20:@VM:30:@VM:40
PRINT SPLICE(a,'',a)
      ! returns 1010v2020v3030v4040
The following example uses SPLICE to concatenate two dynamic arrays with different delimited levels:
a=10:@VM:20:@VM:30:@VM:40
c=11:@SM:12:@SM:13:@SM:14
PRINT SPLICE(a,'/',c)
      ! returns 10/11s/12s/13s/14v20v30v40
See Also