Skip to main content

$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 built by $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.

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 a value of 1 will be used in the aggregate operation.

  • $VECTOROP("count", vexpr [ , bitexpr ] ) counts the number of defined elements in the vector vexpr. Undefined elements are ignored. 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 value of 1 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 value of 1 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 have defined elements in the vector and for which bitexpr has a value of 1 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 the sum in 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 have defined elements in the vector and for which bitexpr has a value of 1 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 each bit is set to 1 or 0 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 position in a vector has an undefined value, the resulting vector has an undefined value at that position. Furthermore, 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 <MAXNUMBER> 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 have a value of 1 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.

    // 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.

    // vec = <4,6,7,10>
    zwrite $VECTOROP("-",vec,7)  // writes <-3,-1,0,3>
    
  • $VECTOROP("-", vexpr ) returns a vector containing the negative of each defined element in vexpr.

    // vec = <4,6,7,10>
    zwrite $VECTOROP("-",vec)  // writes <-4,-6,-7,-10>
    
  • $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.

    // 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.

    // 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.

    // 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.

    // 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.

    // 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.

    // 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 have a value of 1 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 be a vector of type integer; vexpr2 represents the number of mircoseconds to add to the timestamp in vexpr1.

    // 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 vexpr2 are subtracted from the elements of vexpr1 . 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 be a vector of type integer; vexpr2 represents the number of mircoseconds to subtract from the timestamp in vexpr1.

    // 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 integer vectors, the operation performs integer division.

    // 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.

    // 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.

    // 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.

    // 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 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 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. Furthermore, if a vector argument is undefined or is the empty string, these operations return the empty string.

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 expr is concatenated to each defined element of the vector. 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 value of 1.

    // 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. 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 value of 1.

    // 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 value of 1.

    // 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.

intexpr1 and intexpr2 may be specified from the back of the string by using an asterisk (*) and a minus sign (-) to indicate their positions from the end of the string, similar to the syntax in $VECTOR.

If intexpr1 is greater than intexpr2, the operation returns the empty string.

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 whitespace, like spaces and tabs, 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 at both the beginning and the end. 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 at the beginning (the left side). 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 at the end (the right side). 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 the number of new keys that were added to the output array.

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 1; 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 1, 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 1.

// vec = <10,8,6,15,3,17,18,2,7,100,101>
kill arr, bits
for i=1,4,5,7,9 set $bit(bits,i)=1
zwrite $VECTOROP("group",vec,bits,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 value of 1.

  • $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 value of 1. 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, bits
for i=1,3,4,7,8 set $bit(bits,i)=1
zwrite $VECTOROP("countgb",vec,bits,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:

    • 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).

    • 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")  // writes <1,0,4,0,10>
    
    // 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 = 2:2: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 every 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
    for i=2,5,6,7,8,9 set $bit(bits,i)=1
    zwrite $VECTOROP("mask",vec,bits)  // 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.

    for i=2,3,4,6 set $bit(bits,i)=1
    zwrite $VECTOROP("positions",bits)  // 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 value of 1 set to expr, implicitly coerced into the vector’s type using ObjectScript conversion rules. The operation raises a <MAXNUMBER> error in cases where the supplied value does not fit the vector’s data type range.

    The length of the returned vector is the greater between the length of vexpr and the last position for which bitexpr has a value of 1.

    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 value of 1. 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
    for i=1,2,3,4,5,6 set $bit(bits,i)=1
    zwrite $VECTOROP("set",vec,16,"int",bits)
    // writes <16,16,16,16,16,16,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 value of 1 in bitexpr. The returned vector’s length is either the length of vexpr1 or is the last position for which both bitexpr has a value of 1 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 value of 1. 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 value of 1 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 0.

    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 the empty string.

    for i = 1:1:10 set $VECTOR(vec,i,"integer") = i
    write $VECTOROP("",vec)  // writes "integer"
    

See Also

FeedbackOpens in a new tab