The elements of the VARIANT varRightOperand are “append concatenated” to the VARIANT varLeftOperand and the resulting array is returned. This operator is very much shape-aware and shape-dependent. Its purpose is to return an result which adds to (increases the size of) the outer-most (i.e., the left-most or row) dimension of the left-hand operand expression. Use the “simple concatenate” operator, McOpConcat, to extend the length of a 1-dimensional array.
As illustrated in the example, the result can be accessed as an McObject instance by assigning with the “Set” keyword, or it can be accessed as a numeric Variant (the default McObject.Value property) by assigning to a Variant variable without the “Set” keyword. McToText and all of the vector operations will take either type of Variant as arguments. When performing sequential vector operations on large arrays, an extra copy is avoided by passing results from one operation to the next an McObject instance instead of as a Variant numeric array.
The formal shape changing rules are:
1. If and only if the left-hand expression's shape is one-dimensional, a copy of the left-hand operand is promoted to two-dimensions by adding a VAR'iable left-most row dimension of length one; the column dimension is set to the vector length of the left-hand operand (this column dimension is made VAR'iable if the operand is a VAR'iable length vector, FIX'ed if the operand is FIX'ed). If the left-hand operand's shape already had two or more dimensions, no dimension is added. For the self assignment version of the operator, ::=, the left hand side must be an named object which has already been declared with two or more dimensions, and the outer dimension must be VAR'iable (so that it can be increased).
2. The expression on the right of the operator must have either the same number of, or one fewer, dimensions than the (possibly promoted) left hand operand. If the number of dimensions of the right operand is the same as the left operand, then the resulting shape has a new outer dimension which is the sum of the two operand's outer dimensions (e.g., if we append a 3 by 2 object to a 4 by 2 object, we will get a 7 by 2 object). The shape of the right operand must “fit” with the shape of the left operand; that is, if a left operand dimension is FIX'ed size, then the corresponding dimension of the right operand must also be of that size (i.e., either FIX'ed and the same size, or VAR'iable with all instances of that size).
3. If the number of dimensions of the right operand is the one less than the left operand, then the returned shape has a new outer dimension which is the left operand's outer dimension incremented by one (e.g., if we append a length-2 vector to a 4 by 2 object, we will get a 5 by 2 object). Here too the shape of the right operand must “fit” with the shape of the left operand. That is, each left operand dimension of FIX'ed size must be matched with a corresponding dimension in the right operand of the same size; the “corresponding” dimension on the right will be the left dimension number minus one (e.g., dimension 1 on the left must be matched by dimension 0, the outer-most, on the right).
McOpConcatConcat Method
