$vector (ObjectScript)

Assign Vector Data

• set $vector(vector,position,type) = value assigns the vector element at the specified index position to the specified value. The element is of the specified data type. Valid data types are "integer" (or "int"), "double", "decimal", "string", and "timestamp".

  • If vector is undefined, then the $vector function creates the vector, set its type, and assigns the element value. For example, this code creates a vector of type "integer" and assigns the third element a value of 10. The first and second elements are undefined.

    set $vector(vector,3,"integer") = 10
    

    

  • If vector is already defined, then the $vector function assigns the element value and type must be the previously defined data type of the vector. For example, calling set $vector(vector,1,"integer") = 3 on a vector of type "double" results in a <VECTOR> error.

Example: Create Vector and Update Vector Elements

Return Vector Data

• $vector(vector,position) returns the vector element value that is at the specified index position. For example, the following code assigns the value of the second element of the vector to the variable x:

  set x = $vector(vector,2)
  

  

• $vector(vector,startPosition,endPosition) returns a new vector of the same type as vector that contains the elements between index positions startPosition and endPosition in the original vector, as well as the elements at both startPosition and endPosition. For example, the following code stores in variable vector2 a vector that contains the third through fifth elements of the original vector:

  set vector2 = $vector(vector,3,5)
  

  

  Additionally, you can substitute use an asterisk (*) in either startPosition and endPosition to indicate the end of the vector. For example, the following code stores in variable vector2 a vector that contains all elements from the fourth position onward:

  set vector2 = $vector(vector,4,*)
  

  

  Furthermore, you can indicate an offset of the asterisk to specify a certain element from the end of the vector as a boundary. An offset can be applied to an asterisk in either startPosition or endPosition or both. For example, the following code stores in variable vector2 a vector that contains all elements from the fourth position to the second-to-last position:

  set vector2 = $vector(vector,4,*-1)
  

  

  In the following example, the code stores in variable vector2 a vector that contains all elements from the fourth position to the second-to-last position:

  set vector2 = $vector(vector,4,*-1)
  

  

  In the following example, the code stores in variable vector2 a vector that contains all elements from the fifth position from the end to the second-to-last position:

  set vector2 = $vector(vector,*-5,*-1)
  

  

  If both startPosition and endPosition are valid elements in the vector, but startPosition is greater than endPosition, the function returns the empty string.

Example: Get Vector Data

Delete Vector Data

• kill $vector(vector,position) deletes the element at the specified position from the vector and sets that element to be undefined. For example, the following code deletes the first element of the vector:

  kill $vector(vector,1)
  

  

  If deleting an element results in a vector with no elements, then:

  • If vector is a global variable, it becomes undefined.

  • If vector is a local variable, it is set to an empty string ("").

Example: Create Vector and Update Vector Elements

vector

Global or local variable specifying the input vector.

• If vector is not a vector ($isvector(vector) = 0), then $vector raises a <VECTOR> error.

• If vector is undefined or holds an empty string (""), then:

  • $vector returns an empty string.

  • set $vector(vector,position,type) = value assigns a new vector with the specified arguments to vector.

  • kill $vector(vector,position) performs no operation.

position

Positive integer specifying the vector element position to assign, return, or delete. If position is less than 1, then $vector raises a <VECTOR> error.

If position exceeds the length of the vector, then the behavior of $vector depends on the operation:

You can also specify position as an asterisk (*), which is equivalent to specifying the last assigned position of the vector.

type

Data type of vector, specified as one of these strings:

All elements assigned to vector are of this data type.

value

Value to assign to a vector element. Before storing value in a vector, the $vector function converts this value to the specified type using the standard ObjectScript type conversion rules. For example, this table shows how the storage of a value of 3.14 changes depending on the data type.

For more details on ObjectScript conversion rules, see Variable Typing and Conversion.

startPosition

A positive integer specifying the first index position of the slice of the vector to return.

The $vector(vector,startPosition,endPosition) syntax returns a new vector containing the elements of vector that are located between the startPosition and endPosition elements. The new vector is of length endPosition-startPosition-1. All elements in the new vector are of the same type as the elements in the original vector.

The $vector function returns an empty string ("") under these conditions:

• endPosition is less than startPosition.

• startPosition is greater than the position of the last defined element of vector.

• None of the elements between startPositionand endPositionare defined.

endPosition

A positive integer specifying the last index position of the slice of the vector to return.

The $vector(vector,startPosition,endPosition) syntax returns a new vector containing the elements of vector that are located between the startPosition and endPosition elements. The new vector is of length endPosition-startPosition-1. All elements in the new vector are of the same type as the elements in the original vector.

If endPosition exceeds the length of the vector, then the $vector function returns the elements from startPosition to the end of the vector. This case is equivalent to using the asterisk syntax (*) to specify the end of the vector. For example, in this code, vectors v1 and v2 both include only the fourth and fifth elements of vector.

for i=1:1:5 set $vector(vector,i,"integer") = $random(100)+1
set v1 = $vector(vector,4,10)
set v2 = $vector(vector,4,*)

The $vector function returns an empty string ("") under the following conditions:

• endPosition is less than startPosition.

• None of the elements between startPosition and endPosition are defined.

offset

An integer specifying the number of elements by which to offset the last index position of the vector. Use offset with the asterisk syntax (*) to return slices that are relative to the last vector element. For example, $vector(vector,1,*-1) returns up to the second-to-last element, $vector(vector,1,*-2) returns up to the third-to-last element, and so on.

Create Vector and Update Vector Elements

Create a three-element string vector and display the vector contents by using the zwrite command. The vector type is set to "string" and cannot be changed after you create the vector. The element count and vector length are both set to 3.

set $vector(v,1,"string") = "a"
set $vector(v,2,"string") = "b"
set $vector(v,3,"string") = "c"
zwrite v

Remove the second element from the vector. The element count decreases to 2. The vector length remains set to 3, because the length of a vector is equal to the position of the last defined element. The element at position 2 is now undefined, as indicated by the consecutive commas between elements 1 ("a") and 3 ("c").

kill $vector(v,2)
zwrite v

Add a new element at position 10. The vector count increases to 3 and the vector length increases to 10. The elements at positions 4 through 9 are undefined.

set $vector(v,10,"string") = "d"
zwrite v

Update the value at position 10. The vector length and count remain the same, but the $vector function updates the element value.

set $vector(v,10,"string") = "j"
zwrite v

Update the vector in a loop to populate the missing elements. Use the $char function to convert the ASCII codes of lowercase letters to their string representations. The vector now has its first ten elements defined.

set asciiOffset = 96 // lowercase letters start with ASCII code 97
for i = 1:1:10 set $vector(v,i,"string") = $char(i + asciiOffset)
zwrite v

Get Data from Vector

Create a ten-element vector containing random integers from 1 to 100. Display the contents by using the zwrite command. Your output will vary.

for i = 1:1:10 set $vector(v1,i,"integer") = $random(100)+1
zwrite v1

Set various elements of the vector to a variable. The returned values are of the same type as the vector (in this case, integer). The exception is the out-of-bounds element, which is set to the empty string.

set element1 = $vector(v1,1)
set element2 = $vector(v1,2)
set element100 = $vector(v1,100)
zwrite element1, element2, element100

Get the first five elements of the vector. To obtain a range of consecutive elements from a vector, you return a new vector containing only those values. This vector is sometime called a vector slice.

set v2 = $vector(v1,1,5)
zwrite v2

Delete the first element from the original vector and get the first five elements again. The returned vector slice contains five elements, but the first element is undefined.

kill $vector(v1,1)
set v2 = $vector(v1,1,5)
zwrite v2

Delete the fifth element from the original vector and get the first five elements again. The returned vector slice does not include undefined element 5, because this element comes at the end of the vector.

kill $vector(v1,5)
set v2 = $vector(v1,1,5)
zwrite v2

Get the elements from element 6 up to the second-to-last element of the original vector. Store these elements in a new vector. Specify the second-to-last element as relative to *, which refers to the index position of the last vector element.

set v3 = $vector(v1,6,*-1)

Get the last element of the vector and specify an out-of-range end position. The $vector function returns a one-element vector containing only the last element of the original vector.

set v4 = $vector(v1,*,100)

Store and Display Timestamp Vectors

Vectors encode timestamps in an integer-based format called Posix time (sometimes called Unix time or Epoch time), where each integer is the number of seconds since (or before) January 1, 1970 00:00:00. For more details on this format, see %Library.PosixTimeOpens in a new tab.

Capture the current time in one-second increments for five seconds. Use the $datetime function to convert the times to the Posix format, which has a conversion code of –2 for this function. Store these times in a vector and display the vector contents. Your times will vary.

set posix = -2
for i=1:1:5 set $vector(v,i,"timestamp") = $zdatetime($now(),posix) hang 1
zwrite v

Display the times stored in the vector in a readable format.

for i=1:1:5 set ts=$vector(v,i) write !,$zdatetime($zdatetimeh(ts,posix))

You can also convert between timestamp displays by using the LogicalToDisplay and DisplayToLogical methods of %Library.PosixTimeOpens in a new tab. For example, this routine converts raw timestamp dates to the Posix time format, stores the timestamp dates in a vector, and then displays that time in a readable format.

set dates = "10/10/2010 10:10:10;11/11/2011 11:11:11;12/12/2012 12:12:12"
set delimiter = ";"
set numDates = $length(dates,delimiter)

for i = 1:1:numDates
{
  set dateString = $piece(dates,delimiter,i)
  set datePosix = ##class(%Library.PosixTime).DisplayToLogical(dateString)
  set $vector(v,i,"timestamp") = datePosix
  write !,##class(%Library.PosixTime).LogicalToDisplay($vector(v,i))
}