Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Arguments
Aggregate Operations
Filter Operations
Numeric Operations
String Operations
Grouping Operations
Miscellaneous Operations
Informative Operations
See Also

$vectorop (ObjectScript)

Performs various operations on vectors defined through ObjectScript

Synopsis

Aggregate Operations

$vectorop("count", vexpr [ , bitexpr ] )
$vectorop("max", vexpr [ , bitexpr ] )
$vectorop("min", vexpr [ , bitexpr ] )
$vectorop("sum", vexpr [ , bitexpr ] )

Filter Operations

$vectorop("defined", vexpr)
$vectorop("undefined", vexpr)
$vectorop("<", vexpr, expr1)
$vectorop("<=", vexpr, expr1)
$vectorop(">", vexpr, expr1)
$vectorop(">=", vexpr, expr1)
$vectorop("=", vexpr, expr1)
$vectorop("!=", vexpr, expr1)
$vectorop("between", vexpr, expr1, expr2)

Vector-wise Filter Operations

$vectorop("v<", vexpr1, vexpr2)
$vectorop("v<=", vexpr1, vexpr2)
$vectorop("v>", vexpr1, vexpr2)
$vectorop("v>=", vexpr1, vexpr2)
$vectorop("v=", vexpr1, vexpr2)
$vectorop("v!=", vexpr1, vexpr2)
$vectorop("vbetween", vexpr1, vexpr2, vexpr3)

Numeric Operations

$vectorop("+", vexpr, expr [ , bitexpr ] )
$vectorop("-", vexpr, expr [ , bitexpr ] )
$vectorop("/", vexpr, expr [ , bitexpr ] )
$vectorop("*", vexpr, expr [ , bitexpr ] )
$vectorop("**", vexpr, expr [ , bitexpr ] )
$vectorop("#", vexpr, expr [ , bitexpr ] )
$vectorop("e-", vexpr, expr [ , bitexpr ] )
$vectorop("e/", vexpr, expr [ , bitexpr ] )
$vectorop("v+", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("v-", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("v/", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("v*", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("v**", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("v#", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("ceiling", vexpr)
$vectorop("floor", vexpr)

String Operations

$vectorop("_", vexpr, expr [ , bitexpr ] )
$vectorop("e_", vexpr, expr [ , bitexpr ] )
$vectorop("v_", vexpr1, vexpr2 [ , bitexpr ] )
$vectorop("lower", vexpr)
$vectorop("upper", vexpr)
$vectorop("substring", vexpr, intexpr1 [ , intexpr2 ... ] )
$vectorop("trim", vexpr)
$vectorop("triml", vexpr)
$vectorop("trimr", vexpr)

Grouping Operations

$vectorop("group", vexpr, bitexpr, array)
$vectorop("countg", vexpr1, vexpr2, array [ , bitexpr ] )
$vectorop("maxg", vexpr1, vexpr2, array [ , bitexpr ] )
$vectorop("ming", vexpr1, vexpr2, array [ , bitexpr ] )
$vectorop("sumg", vexpr1, vexpr2, array [ , bitexpr ] )
$vectorop("countgb", vexpr, bitexpr, array)

Miscellaneous Operations

$vectorop("convert", vexpr, expr [ , restrict ] )
$vectorop("length", vexpr)
$vectorop("mask", vexpr, expr)
$vectorop("positions", vexpr, bitexpr)
$vectorop("set", vexpr, expr)
$vectorop("set", vexpr, expr, type, bitexpr)
$vectorop("vset", vexpr1, vexpr2, [ , bitexpr ] )

Informative Operations

$vectorop("bytesize", vexpr)
$vectorop("type", vexpr)

Arguments

Argument	Description
vexpr	A valid ObjectScript expression that resolves to a vector. Some vector operations require this vector to be of a specific type.
expr	A valid ObjectScript expression. Vector operations often require this argument to be of a specific type.
bitexpr	A bitstring expression. This argument may be the global variable name of a bitstring built with $bit or an expression that can be passed into $bit. Often, this is an optional argument in vector operations. When it is included, the specific operation is applied only at positions in the vector that have corresponding 1 values in the bitexpr.
intexpr	A valid ObjectScript expression that either resolves to an integer or can be coerced into an integer.
array	The name of an array that the vector operation populates with data. Can be undefined before the call to vectorop is made.

Abbreviated Form: $vop

Aggregate Operations

Aggregate operations take in a vector and return a number. They perform an operation across the entries in a vector. If a position in the vector is undefined, it is ignored.

All aggregate operations have an optional third argument, bitexpr. This argument can be used to specify specific elements of the vector to perform the operation on. When it is included, only vector elements in positions that correspond with positions in the bitstring that have true values will be used in the aggregate operation.

$vectorop("count", vexpr [ , bitexpr ] ) counts the number of defined elements in the vector vexpr. It ignores undefined elements from the count. As a result, the return value is always less than or equal to the length of vexpr.
If a third argument is provided, the operation only counts positions that contain a defined element if the bitexpr has a true value at the same position.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i  // defines a 10-element vector
write $vectorop("count",vec)  // writes 10
```
$vectorop("max", vexpr [ , bitexpr ] ) returns the maximum element of vexpr in the vector’s datatype. Undefined elements are ignored.
If a third argument is provided, only positions that have defined elements in the vector for which bitexpr has a true value are considered as possible maximum values to return.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("max", vec)  // writes 10
```
$vectorop("min", vexpr [ , bitexpr ] ) returns the minimum element of vexpr in the vector’s datatype. Undefined elements are ignored.
If a third argument is provided, only positions that both have defined elements in the vector and for which bitexpr has a true value are considered as possible minimum values to return.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("min",vec)  // writes 1
```
$vectorop("sum", vexpr [ , bitexpr ] ) adds all the elements in a vector and returns an integer, a double, or a decimal, depending on the vector’s datatype. This operation raises a <FUNCTION> error when it is called on a vector with a string or timestamp datatype.
If a third argument is provided, only positions that both have defined elements in the vector and for which bitexpr has a true value are added to the sum.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("sum",vec)  // writes 55
```

Filter Operations

The $vectorop operation provides a number of operations to filter vectors. There are two main kinds of filter operations: standard and vector-wise. A standard filter operation is performed over a vector, similar to how a filter operation might be performed over a list or an array. A vector-wise filter operation compares elements in identical positions in two different vectors and returns a vector with the elements that satisfy the condition of the specific operation.

The empty string is returned if any of the input vectors is undefined or is the empty string. In other cases where an argument is not a vector (for example, if an argument is a numeric type), the operation raises a <VECTOR> error.

Standard Filter Operations

Filter operations return a bitstring the same length of the input vector, where the defined positions of the vector are replaced with true or false values depending on how the specified operation evaluates the argument in the vector at the corresponding position.

$vectorop("defined", vexpr) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are defined and a 0 in positions corresponding to elements in the vector that are undefined.
```
// vec = <1,,3,4,,6,,,9,10>
zwrite $vectorop("defined",vec)  // writes the bitstring 1011010011
```
$vectorop("undefined", vexpr) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are undefined and a 0 in positions corresponding to elements in the vector that are defined.
```
// vec = <1,,3,4,,6,,,9,10>
zwrite $vectorop("undefined",vec)  // writes the bitstring 0100101100
```
$vectorop("<", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are less than the value of expr1 and a 0 in positions corresponding to elements in the vector that are greater than or equal to the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop("<",vec, 5)  // writes the bitstring 1011000000
```
$vectorop("<=", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are less than or equal to the value of expr1 and a 0 in positions corresponding to elements in the vector that are greater than the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop("<=",vec, 5)  // writes the bitstring 1011100000
```
$vectorop(">", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are greater than the value of expr1 and a 0 in positions corresponding to elements in the vector that are less than or equal to the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop(">",vec, 5)  // writes the bitstring 0000010011
```
$vectorop(">=", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are greater than or equal to the value of expr1 and a 0 in positions corresponding to elements in the vector that are less than the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop(">=",vec, 5)  // writes the bitstring 0000110011
```
$vectorop("=", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are equal to the value of expr1 and a 0 in positions corresponding to elements in the vector that are not equal to the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop("=",vec, 5)  // writes the bitstring 0000100000
```
$vectorop("!=", vexpr, expr1) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are not equal to the value of expr1 and a 0 in positions corresponding to elements in the vector that are equal to the value of expr1. This operation also returns a 0 in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop("!=",vec, 5)  // writes the bitstring 1111011111
```
$vectorop("between", vexpr, expr1, expr2) returns a bitstring the same length as the input vector with a 1 in positions corresponding to elements in the vector that are both greater than or equal to the value of expr1 and less than or equal to the value of expr2. It returns a 0 in positions corresponding to elements in the vector that are not between the values of expr1 and expr2, as well as in positions that are undefined.
```
// vec = <1,,3,4,5,6,,,9,10>
zwrite $vectorop("between",vec, 3, 9)  // writes the bitstring 0011110010
```

Vector-wise Filter Operations

Vector-wise filter operations take in more than one vector and return a bitstring with a 0 or 1 value based on the supplied operator comparing elements at corresponding positions in the input vectors. The bitstring that is returned has a length equal to the shortest of the two vectors used for comparison; the extra elements of the longer vector are ignored.

If the input vectors are not all of the same type, the operation raises a <FUNCTION> error.

$vectorop("v<", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is less than the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v<",vec1,vec2)  // writes 1000
```
$vectorop("v<=", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is less than or equal to the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v<=",vec1,vec2)  // writes 1011
```
$vectorop("v>", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is greater than the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v>",vec1,vec2)  // writes 0100
```
$vectorop("v>=", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is greater than or equal to the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v>=",vec1,vec2)  // writes 0111
```
$vectorop("v=", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is equal to the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v=",vec1,vec2)  // writes 0011
```
$vectorop("v!=", vexpr1, vexpr2) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is not equal to the value in vexpr2. Otherwise, the value is 0. If the element is undefined in either vexpr1 or vexpr2, the corresponding value in the bitstring is 0.
```
// vec1 = <1,2,1,2>
// vec2 = <2,1,1,2>
zwrite $vectorop("v!=",vec1,vec2)  // writes 1100
```
$vectorop("vbetween", vexpr1, vexpr2, vexpr3) returns a bitstring where the value at each position is 1 if the corresponding value in vexpr1 is both greater than or equal to the value in vexpr2 and less than or equal to the value in vexpr3. Otherwise, the value is 0. If the element is undefined in either vexpr1, vexpr2 or vexpr3, the corresponding value in the bitstring is 0.
```
// vec1 = <5,6,7>
// vec2 = <4,7,8>
// vec3 = <9,9,9>
zwrite $vectorop("vbetween",vec1,vec2,vec3)  // writes 100
```

Numeric Operations

Numeric operations perform arithmetic operations on input vectors, returning a new vector that contains the result of the arithmetic expression defined by the operation’s arguments. If a vector argument is undefined or is the empty string, these operations return the empty string.

If a vector argument has a string data type, a <FUNCTION> error is thrown.

Basic Arithmetic Operations

Basic arithmetic operations take in a vector and a single expression. This expression is implicitly coerced into the data type of the vector. The operation raises a <MAXERROR> error in cases where the supplied value does not fit the vector data type’s range.

In basic arithmetic operations, an optional bitstring argument may be specified. If this argument has been provided, the operation will only be applied at positions that correspond with a true value in the bitstring; as a result, only these positions will be defined in the resulting vector.

$vectorop("+", vexpr, expr [ , bitexpr ]) returns a vector of the same length and type as the input vector where the value of expr has been added to each defined element of vexpr.
This operation can be applied to vectors with a timestamp data type. In this case, expr should be the number of microseconds to add to the values in vexpr.
If a third argument is provided, addition between an element of vexpr and expr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("+",vec,7)  // writes <11,13,14,17>
```
$vectorop("-", vexpr [ , expr , bitexpr ] ) returns a vector of the same length and type as the input vector where the value of expr has been subtracted from each defined element of vexpr. If expr has not been specified, the returned vector contains the negative of each defined element in vexpr.
This operation can be applied to vectors with a timestamp data type. In this case, expr should be the number of microseconds to subtract from the values in vexpr.
If a third argument is provided, subtraction between an element of vexpr and expr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("-",vec,7)  // writes <-3,-1,0,3>
```
$vectorop("/", vexpr, expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where each element has the value of the quotient resulting from dividing each element of vexpr by the value of expr.
This operation can be applied to vectors with a timestamp data type. In this case, expr should be the number of microseconds to add or subtract from the values in vexpr.
If a third argument is provided, division between an element of vexpr and expr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("/",vec,2)  // writes <2,3,3,5>
```
$vectorop("*", vexpr, expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where each defined element of vexpr has been multiplied by the value of expr.
If a third argument is provided, multiplication between an element of vexpr and expr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("*",vec,2)  // writes <8,12,14,20>
```
$vectorop("**", vexpr, expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where each defined element of vexpr has been raised to the power defined by the value of expr.
If a third argument is provided, exponentiation of an element of vexpr to the power ofexpr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("**",vec,2)  // writes <16,36,49,100>
```
$vectorop("#", vexpr, expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where each element has the value of the remainder resulting from dividing each element of vexpr by the value of expr.
If a third argument is provided, the remainder of the division between an element of vexpr and expr is only returned for positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,11>
zwrite $vectorop("#",vec,3)  // writes <1,0,1,2>
```
$vectorop("e-", vexpr , expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where the value of each defined element of vexpr has been subtracted from expr.
If a third argument is provided, subtraction between expr and an element of vexpr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("e-",vec,7)  // writes <3,1,0,-3>
```
$vectorop("e/", vexpr, expr [ , bitexpr ] ) returns a vector of the same length and type as the input vector where each element has the value of the quotient resulting from dividing expr by the value of each element of vexpr.
If a third argument is provided, division between expr and an element of vexpr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <4,6,7,10>
zwrite $vectorop("e/",vec,8)  // writes <2,1,1,0>
```

Vector-wise Arithmetic Operations

Vector-wise arithmetic operations take in two vectors and apply the specified operation on elements at corresponding positions. The returned vector is the length of the shorter of the two input vectors. The operation raises a <VECTOR> error if either of the two required arguments are not vectors.

In vector-wise arithmetic operations, an optional bitstring argument may be specified. If this argument has been provided, the operation will only be applied at positions that correspond with a true value in the bitstring; as a result, only these positions will be defined in the resulting vector.

$vectorop("v+", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector where the elements in corresponding positions in vexpr1 and vexpr2 are added together. If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error.
If vexpr1 is a vector of type timestamp, vexpr2 must have be a vector of type integer; vexpr2 represents the number of mircoseconds to add to the timestamp in vexpr1.
If a third argument is provided, addition between elements of vexpr1 and vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
zwrite $vectorop("v+",vec1,vec2)  // writes <4,9,9,14>
```
$vectorop("v-", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector where the elements of vexpr1 are subtracted by the elements of vexpr2 . If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error.
If vexpr1 is a vector of type timestamp, vexpr2 must have be a vector of type integer; vexpr2 represents the number of mircoseconds to subtract from the timestamp in vexpr1.
If a third argument is provided, subtraction between elements of vexpr1 and vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
zwrite $vectorop("v-",vec1,vec2)  // writes <2,3,-5,-4>
```
$vectorop("v/", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector where the elements of vexpr1 are divided by the elements of vexpr2. If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error. If vexpr1 and vexpr2 are integers, the operations performs integer division and the result is an integer vector.
If a third argument is provided, division between elements of vexpr1 and vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
zwrite $vectorop("v/",vec1,vec2)  // writes <3,2,0,0>
```
$vectorop("v*", vexpr1, vexpr2 < , bitexpr ] ) returns a vector where the elements of vexpr1 are multiplied by the elements of vexpr2. If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error.
If a third argument is provided, multiplication between elements of vexpr1 and vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
write $vectorop("v*",vec1,vec2)  // writes <3,18,14,45>
```
$vectorop("v**", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector where the elements of vexpr1 are raised to the power of the elements of vexpr2. If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error.
If a third argument is provided, exponentiation of an element of vexpr1 to the power of the corresponding element of vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
zwrite $vectorop("v**",vec1,vec2)  // writes <3,216,128,1953125>
```
$vectorop("v#", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector containing the remainders of the division of elements of vexpr1 by the elements of vexpr2. If vexpr1 has type integer, decimal, or double, vexpr2 must have the same type; if it does not, the operation raises a <FUNCTION> error.
If a third argument is provided, the remainder of the division between an element of vexpr1 and a corresponding element of vexpr2 is only returned for positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <3,6,2,5>
// vec2 = <1,3,7,9>
zwrite $vectorop("v#",vec1,vec2)  // writes <0,0,2,5>
```

Rounding Operations

$vectorop("ceiling", vexpr) returns a vector whose element values are the result of applying a rounding up operation on each element of vexpr. If a position in vexpr is not defined, it remains undefined in the resulting vector. If vexpr is not a vector of type integer, decimal, or double, the operation raises a <FUNCTION> error.
```
// vec = <2.4, 2.5, 2.7, 2.81, 2.19, 2.0>
zwrite $vectorop("ceiling",vec)  // writes <3,3,3,3,3,2>
```
$vectorop("floor", vexpr) returns a vector whose element values are the result of applying a rounding down operation on each element of vexpr. If a position in vexpr is not defined, it remains undefined in the resulting vector. If vexpr is not a vector of type integer, decimal, or double, the operation raises a <FUNCTION> error.
```
// vec = <2.4, 2.5, 2.7, 2.81, 2.19, 2.0>
zwrite $vectorop("floor",vec)  // writes <2,2,2,2,2,2>
```

String Operations

String operations return a string vector of the same length as the input vector, with element values at each position based on the result of the specified string operation. If a position has an undefined value, the resulting vector has an undefined value at that position.

If the vector input does not have a string datatype, the operation raises a <FUNCTION> error.

Concatenation Operations

Concatenation operations take in string vectors and concatenate another argument to each element of the vector.

$vectorop("_", vexpr, expr [ , bitexpr ] ) returns a vector where each defined element is concatenated with the expr. If a position in vexpr is not defined, it remains undefined in the resulting vector.
If a third argument is provided, concatenation between an element of vexpr and expr is only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <"b","great","larg">
zwrite $vectorop("_",vec,"est")  // writes <"best","greatest","largest">
```
$vectorop("e_", vexpr, expr [ , bitexpr ] ) returns a vector where each defined element is concatenated with the expr. This operation differs from $vectorop(“_”, ... ) only by the order in which the vexpr and expr arguments are used. If a position in vexpr is not defined, it remains undefined in the resulting vector.
If a third argument is provided, addition between an element of expr and vexpris only performed on positions that have defined elements in the vector and for which bitexpr has a true value.
```
// vec = <"b","great","larg">
zwrite $vectorop("e_",vec,"est")  // writes <"estb","estgreat","estlarg">
```
$vectorop("v_", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector where each defined element in vexpr1 is concatenated with the corresponding defined element in vexpr2. If a position in vexpr1 or vexpr2 is not defined, then that position in the resulting vector will not be defined.
If a third argument is provided, concatenation between elements of vexpr1 and vexpr2 is only performed on positions that have defined elements in both vectors and for which bitexpr has a true value.
```
// vec1 = <"take on", "take me", "I'll be">
// vec2 = <" me", " on", " gone">
zwrite $vectorop("v_",vec1,vec2)  // writes <"take on me","take me on","I'll be gone">
```

Capitalization Operations

Capitalization operations alter the capitalization of the strings in the vector.

$vectorop("lower", vexpr) returns a vector where each element of vexpr has been converted to lowercase. If a position in vexpr is not defined, it remains undefined in the resulting vector.
```
// vec = <"UpPeR","UPPER","upper"
zwrite $vectorop("lower",vec)  // writes <"upper","upper","upper">
```
$vectorop("upper", vexpr) returns a vector where each element of vexpr has been converted to uppercase. If a position in vexpr is not defined, it remains undefined in the resulting vector.
```
// vec = <"UpPeR","UPPER","upper"
zwrite $vectorop("upper",vec)  // writes <"UPPER","UPPER","UPPER">
```

Substring

$vectorop("substring", vexpr, intexpr1 [ , intexpr2 ] ) takes substrings from each defined element of vexpr and returns a new vector with the substrings. If a position in vexpr is not defined, it remains undefined in the resulting vector.

The bounds of the substring are determined by intexpr1 and the optional intexpr2. If only intexpr1 is supplied, the resulting strings contain only the character at position intexpr1. If intexpr2 is supplied, then intexpr1 identifies the position to begin the substrings and intexpr2 identifies the position to end the substrings; the characters at both position intexpr1 and intexpr2 are included in the substrings. If intexpr2 is greater than the length of a particular string, the operation does not raise an error, but instead returns the substring that begins with intexpr1 and ends at the end of the string.

// vec = <"long","short",,,"headstrong","teleport">
zwrite $vectorop("substring",vec,3,6)
// writes <"ng","ort",,,"adst","lepo">

Trim Operations

Trim operations remove characters from the beginning or the end of a string or both.

$vectorop("trim", vexpr) returns a vector where each element of vexpr has been trimmed. If a position in vexpr is not defined, it remains undefined in the resulting vector.
```
// vec = <"  left", "right  ","  middle  ">
zwrite $vectorop("trim",vec)  // writes <"left","right","middle">
```
$vectorop("triml", vexpr) returns a vector where each element of vexpr has been trimmed. If a position in vexpr is not defined, it remains undefined in the resulting vector.
```
// vec = <"  left", "right  ","  middle  ">
zwrite $vectorop("triml",vec)  // writes <"left","right  ","middle  ">
```
$vectorop("trimr", vexpr) returns a vector where each element of vexpr has been trimmed. If a position in vexpr is not defined, it remains undefined in the resulting vector.
```
// vec = <"  left", "right  ","  middle  ">
zwrite $vectorop("trimr",vec)  // writes <"  left","right","  middle">
```

Grouping Operations

Grouping operations allow you to perform various operations on subsets of a vector. The results are stored in a multidimensional array. The return value for all grouping operations is undefined.

Basic Grouping

$vectorop("group", vexpr, bitexpr, array) populates an array, array, with subscripts for each value in vexpr for which the corresponding position in bitexpr is true; values in vexpr that correspond to positions in bitexpr that are false are ignored.

If there are any undefined positions in vexpr for which the corresponding position in bitexpr is true, array is set to undefined. If the array already has elements defined in it, this operation will not mark the array as undefined, but will not append new elements to the array.

When vexpr is undefined or the empty string, only the top level node of array may be modified, depending on whether there are positions there is a position in bitexpr set to true.

// vec = <10,8,6,15,3,17,18,2,7,100,101>
kill arr
zwrite $vectorop("group",vec,$factor(345),arr)  // writes ""
zwrite arr

arr(3)=""
arr(7)=""
arr(10)=""
arr(15)=""
arr(18)=""

Vector Grouping

Vector grouping operations take in two vectors (vexpr1 and vexpr2), a multidimensional array (array), and, optionally, a bitstring (bitexpr). After grouping data together, the specified operation is performed on the group and stores the result in the multidimensional array.

Elements in vexpr2 are split into groups identified by the elements of vexpr1 that they positionally correspond with; for example, the element at position 5 of vexpr2 belongs to the group identified by the value at position 5 in vexpr1. array contains one subscript per unique value in vexpr1 and stores the sum of the group at the subscript. Positions that are defined in vexpr2, but undefined vexpr1, belong to the group associated with the top level node of array.

Pre-existing subscripts in array are not overwritten. If one of the subscripts is an element of vexpr1the summed value for the group is appended to the end of the value already stored at that subscript.

If the optional bitexpr argument is passed in, the groups are only formed for values in vexpr2 where bitexpr has a true value.

$vectorop("countg", vexpr1, vexpr2, array [ , bitexpr ] ) counts the number of elements in the groups and stores them in subscripts of array.

// vec1 = <"g1","g2","g1","g1","g2","g2","g2","g2","g1">
// vec2 = <10,8,6,15,3,17,16,2,7,100,101>
kill arr
zwrite $vectorop("countg",vec1,vec2,arr)  // writes ""
zwrite arr

arr=2
arr("g1")=4
arr("g2")=5

$vectorop("maxg", vexpr1, vexpr2, array [ , bitexpr ] ) finds the maximum values of the groups and stores them in subscripts of array.

// vec1 = <"g1","g2","g1","g1","g2","g2","g2","g2","g1">
// vec2 = <10,8,6,15,3,17,16,2,7,100,101>
kill arr
zwrite $vectorop("maxg",vec1,vec2,arr)  // writes ""
zwrite arr

arr=101
arr("g1")=15
arr("g2")=17

$vectorop("ming", vexpr1, vexpr2, array [ , bitexpr ] ) finds the minimum values of the groups and stores them in subscripts of array.

// vec1 = <"g1","g2","g1","g1","g2","g2","g2","g2","g1">
// vec2 = <10,8,6,15,3,17,16,2,7,100,101>
kill arr
zwrite $vectorop("ming",vec1,vec2,arr)  // writes ""
zwrite arr

arr=100
arr("g1")=6
arr("g2")=2

$vectorop("sumg", vexpr1, vexpr2, array [ , bitexpr ] ) finds the sum of the groups and stores them in subscripts of array.

The operation raises a <FUNCTION> error when vexpr2 is of type string or timestamp.

// vec1 = <"g1","g2","g1","g1","g2","g2","g2","g2","g1">
// vec2 = <10,8,6,15,3,17,16,2,7,100,101>
kill arr
zwrite $vectorop("sumg",vec1,vec2,arr)  // writes ""
zwrite arr

arr=201
arr("g1")=38
arr("g2")=46

Bitmap Grouping

$vectorop("countgb", vexpr, bitexpr, array) groups identical values in vexpr from the subset of positions that correspond to positions in bitexpr that have a true value. The operation adds this subset of vexpr values as subscripts to array and stores the count of how many times that value appears in the subset. Like the vector grouping operations, this function populates the array argument and has an undefined return value.

// vec = <"x","y","x","y","x","y","y","y","x">
kill arr
zwrite $vectorop("countgb",vec,$factor(205),arr)  // writes ""
zwrite arr

arr("x")=2
arr("y")=3

Miscellaneous Operations

InterSystems IRIS offers a number of other vector operations for a variety of uses, including describing the information in a vector, converting the type of the vector, and setting elements of the vector.

$vectorop("convert", vexpr, expr [ , restrict ] ) returns a new vector where each element of vexpr has been coerced into the type expr following ObjectScript conversion rules. The operation raises a <MAXNUMBER> error when an element in vexpr does not fit the target’s type range. expr must be a valid vector type, represented as a string.
The optional restrict argument, which by default is set to 0, can be set to 1 to restrict the returned vector to have undefined values at positions where the corresponding value in vexpr does not conform to the requested type. The three cases in which this might occur are:
- when a string value in vexpr is not a valid numeric expression
- the conversion would imply a loss of precision (as when converting to the integer type)
- if a <MAXNUMBER> error would be raised
Positions that are undefined in vexpr are also undefined in the returned vector.
If vexpr is undefined or is the empty string, this operation returns the empty string. If vexpr is not a vector or expr does not evaluate to a valid vector type, the operation raises a <VECTOR> error.
```
// vec = <"1", "one", "4", "seven", "10">
zwrite $vectorop("convert", vec, "int", 1)  // writes <1,,4,,10>
```
$vectorop("length", vexpr) returns the length of vexpr. The length of a vector is implicitly defined as the last position for which it has a defined element. vexpr may contain multiple undefined elements.
If vexpr is undefined or the empty string, this operation returns 0.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("length",vec)  // writes 10
```
$vectorop("mask", vexpr, bitexpr) returns a vector of the same type as vexpr with undefined positions where bitexpr has a 0 value. The resulting vector is the length of bitexpr. If the resulting vector would have only undefined elements due to 0 values in bitexpr at ever position for which vexpr has a defined value, then the empty string is returned.
If vexpr is either undefined or is the empty string, this operation returns the empty string. Furthermore, if bitexpr is longer than vexpr, this operation returns an empty string.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
zwrite $vectorop("mask",vec,$factor(500))  // writes <,,3,,5,6,7,8,9>
```
$vectorop("positions", bitexpr) returns an integer vector where each position in vexpr at which bitexpr is 1 is set to the position integer itself. Positions where bitexpr is 0 are undefined.
```
// bitexpr = $factor(46)
zwrite $vectorop("positions",bitexpr)  // writes <,2,3,4,,6>
```
$vectorop("set", vexpr, expr) returns a new vector of the same type and length as vexpr, but with each element set to expr. The type of expr is coerced into the type of the vector. The operation raises a <MAXNUMBER> error in cases where the supplied value does not fit the vector’s data type range.
If vexpr is undefined or the empty string, this operation returns the empty string. If vexpr is a defined value, but is neither a vector nor the empty string, the operation raises a <VECTOR> error.
```
// vec = <60,40,80,90>
$vectorop("set", vec, 500)  // writes <500,500,500,500>
```
$vectorop("set", vexpr, expr, type, bitexpr) returns a new vector of the same type and length as vexpr where all positions for which the supplied bitexpr has a true value set to expr, implicitly coerced into the vector’s type using ObjectScript conversion rules. The length of the returned vector is the length of bitexpr. The operation raises a <MAXNUMBER> error in cases where the supplied value does not fit the vector’s data type range.
If vexpr is undefined or the empty string, the length of the returned vector is defined through the last position for which bitexpr has a true value. In this case, the type of the returned vector is the type specified by type. If vexpr is defined, then type must match its type. type must always be defined as a valid vector type, or the operation raises a <VECTOR> error.
If bitexpr is undefined or the empty string, the returned vector will be identical to vexpr.
If vexpr is defined, but is not a vector, the operation raises a <VECTOR> error. If both vexpr and bitexpr are undefined or the empty string, this operation returns the empty string.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
zwrite $vectorop("set",vec,16,"int",$factor(63))
// writes <1,100,100,4,100,100,7,8,9,10>
```
$vectorop("vset", vexpr1, vexpr2 [ , bitexpr ] ) returns a vector of the same type and length as vexpr1, where each position’s element is set to the corresponding value in vexpr2, if it is defined, or the value in vexpr1 if the value in vexpr2 is undefined. If vexpr1 is undefined or is the empty string, this operation will return a copy of vexpr2.
If the fourth argument is provided, the operation is performed only for positions that correspond to a true value in bitexpr. The returned vector’s length is either the length of vexpr1 or is the last position for which both bitexpr has a true value and vexpr2 is defined, whichever is highest.
If the optional bitexpr argument is included, but is undefined or is the empty string, the operation assumes bitexpr has only false values and returns a copy of vexpr1. If a position is undefined in vexpr2, either because it is explicitly undefined or because bitexpr is longer than vexpr2, the resulting vector will have an undefined value in the positions for which bitexpr has a true value. If vexpr1 is undefined or the empty string, this operation will return a vector of the same type as vexpr2 with any positions for which the supplied bitexpr has a true value set to the element value at the corresponding position in vexpr2.
```
// vec1 = <1,,3,4,,6>
// vec2 = <,2,10,11,,12>
zwrite $vectorop("vset",vec1,vec2)  // writes <1,2,10,11,,12>
```

Informative Operations

$vectorop("bytesize", vexpr) returns the current size of vexpr, expressed in the number of bytes. If vexpr is undefined or the empty string, the operation returns an empty string.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("bytesize",vec)  // writes 320
```
$vectorop("type", vexpr) returns the type of vexpr, expressed a string. The possible values are “integer”, “decimal”, “double”, “timestamp”, and “string”. If vexpr is undefined or the empty string, this operation returns an empty string.
```
for i = 1:1:10 set $vector(vec,i,"integer") = i
write $vectorop("",vec)  // writes "integer"
```

$vectorop (ObjectScript)

Synopsis

Arguments

Aggregate Operations

Filter Operations

Standard Filter Operations

Vector-wise Filter Operations

Numeric Operations

Basic Arithmetic Operations

Vector-wise Arithmetic Operations

Rounding Operations

String Operations

Concatenation Operations

Capitalization Operations

Substring

Trim Operations

Grouping Operations

Basic Grouping

Vector Grouping

Bitmap Grouping

Miscellaneous Operations

Informative Operations

See Also