Working with Collections
This page describes how to use the collection APIs (lists and arrays) in InterSystems IRIS® data platform. You can use collections as properties of objects, and you can also use them standalone.
Introduction to Collections
A collection is an object class that contains multiple elements of the same type. These types can be literal values, such as strings or integers, or objects. Each element in a collection consists of a key (the position of that element within the collection) and a value (the data stored at that position). Using collection methods and properties, you can perform actions such as:
-
Access elements based on their keys and modify their values.
-
Insert or delete elements at specified key positions.
-
Count the number of elements in a collection.
InterSystems IRIS® data platform provides APIs for two kinds of collections: list and arrays.
-
In list collections, elements are ordered sequentially. The keys in a list are integers from 1 to N, where N is the last element in the list. This example sets the second element of a list (that is, the element with a key of 2) to the string value red.
do myList.SetAt("red",2)
-
In array collections, elements are accessed based on arbitrary key names that you specify when you create the element. You can specify string or numeric key names. This example sets the color key of an array to the string value red.
do myArray.SetAt("red","color")
Elements in an array are ordered by key, with numeric keys first, sorted from smallest to largest, and string keys next, sorted alphabetically with uppercase letters coming before lowercase letters. For example: -2, -1, 0, 1, 2, A, AA, AB, a, aa, ab.
See Using Property Methods for information on the samplepropBuildValueArray() method.
Defining Collection Properties
To define list or array properties, use these property definition syntaxes:
Property MyProp as list of Type;
Property MyProp as array of Type;
Here, MyProp is the property name, and Type is either a data type class or an object class.
This example shows how to define a property for a list of %StringOpens in a new tab values.
Property Colors as list of %String;
This code shows how to define a property for an array of Doctor objects.
Property Doctors as array of Doctor;
InterSystems IRIS stores collection properties as instances of classes in the %Collection package. These classes contain the methods and properties that you can use to work with collections.
This table summarizes the ways to define collection properties and the %Collection classes used to store them.
Collection Type | %Collection Class |
---|---|
List of strings, integers, or other data type |
%Collection.ListOfDTOpens in a new tab |
List of objects |
%Collection.ListOfObjOpens in a new tab |
Array of strings, integers, or other data type |
%Collection.ArrayOfDTOpens in a new tab |
Array of objects |
%Collection.ArrayOfObjOpens in a new tab |
Do not use the %Collection classes directly as the type of a property. For example, do not create a property definition like this:
Property MyProp as %Collection.ArrayOfDT;
Defining Standalone Collections
As an alternative to defining collection properties, you can define standalone collections, such as for use as a method argument or return value. To define a standalone collection, InterSystems IRIS® data platform provides classes in the %Library package that provide similar functionality to the %Collection classes used to store collection properties.
To create a standalone collection, call the %New() method of the suitable class to obtain an instance of that class. Then use methods of that instance to perform collection operations. For example, this code creates a list of strings using the %Library.ListOfDataTypesOpens in a new tab class, inserts three elements into the list, and then displays the number of elements in the list:
set mylist=##class(%ListOfDataTypes).%New()
do mylist.Insert("red")
do mylist.Insert("green")
do mylist.Insert("blue")
write mylist.Count()
This table summarizes the ways to define standalone collections and the %Library classes used to create them.
Collection Type | %Library Class | Sample Creation Syntax |
---|---|---|
List of strings, integers, or other data type |
%ListOfDataTypesOpens in a new tab |
set myList = ##class(%ListOfDataTypes).%New() |
List of objects |
%ListOfObjectsOpens in a new tab |
set myList = ##class(%ListOfObjects).%New() |
Array of strings, integers, or other data type |
%ArrayOfDataTypesOpens in a new tab |
set myArray = ##class(%ArrayOfDataTypes).%New() |
Array of objects |
%ArrayOfObjectsOpens in a new tab |
set myArray = ##class(%ArrayOfObjects).%New() |
Working with List Collections
The examples in these sections show how to work with list properties, but you can use similar syntaxes to work with lists that are in a standalone collection.
Insert List Elements
To insert an element at the end of a list, use the Insert() method. For example, suppose that obj is a reference to an object, and Colors is a list property of the associated object. This property is defined as follows:
Property Colors as list of %String;
This code inserts three elements into the list. If the list was previously empty, then these elements are located at positions 1, 2, and 3, respectively.
do obj.Colors.Insert("Red") // key = 1
do obj.Colors.Insert("Green") // key = 2
do obj.Colors.Insert("Blue") // key = 3
To insert an element at a specific position within a list, use the InsertAt() method. For example, this code inserts the string Yellow into the second position of the Colors property of obj.
do obj.Colors.InsertAt("Yellow",2)
The list elements now have this order: "Red", "Yellow", "Green", "Blue". The new element is at position 2 and the elements previously at position 2 and 3 ("Green" and "Blue") move to positions 3 and 4 to make room for the new element.
The insertion of list elements works the same for objects. For example, suppose that pat is an object reference, and Diagnoses is a list property of the associated object. This property is defined as follows, where PatientDiagnosis is the name of a class:
Property Diagnoses as list of PatientDiagnosis;
This code creates a new class instance of PatientDiagnosis, stored in object reference patdiag, and inserts this object at the end of the Diagnoses list.
Set patdiag = ##class(PatientDiagnosis).%New()
Set patdiag.DiagnosisCode=code
Set patdiag.DiagnosedBy=diagdoc
Set status=pat.Diagnoses.Insert(patdiag)
Access List Elements
To access list elements, you can use these collection methods:
-
GetAt(key) – Return the element value at the position specified by key.
-
GetPrevious(key) – Return the element value at the position immediately before key.
-
GetNext(key) – Return the element value at the position immediately after key.
-
Find(value, key) – Starting after key, return the key of the next list element that equals value.
For example, this code iterates over a list and displays the elements of that list in order. The Count property of collections determines the number of elements to iterate over.
set p = ##class(Sample.Person).%OpenId(1)
for i = 1:1:p.FavoriteColors.Count() {write !, p.FavoriteColors.GetAt(i)}
Modify List Elements
To modify a value at a specified key, you can use the SetAt() method, as shown by this syntax:
do oref.PropertyName.SetAt(value,key)
Here, oref is an object reference and PropertyName is the name of a list property of that object. For example, suppose that person.FavoriteColors is a list property of favorite colors containing elements red, blue, and green. This code changes the second color in the list to yellow:
do person.FavoriteColors.SetAt("yellow",2)
Remove List Elements
To remove a list element, use the RemoveAt() method. For example, suppose that person.FavoriteColors is a list property of favorite colors containing elements red, blue, and green. This code removes the element at position 2 (blue)
do person.FavoriteColors.RemoveAt(2)
The list elements now have this order: red, green. The element previously at position 3 (green) moves to position 2 to fill the gap caused by the removed element.
Working with Array Collections
To add an element to an array, use the SetAt() method. For example, myArray.SetAt(value,key) sets the array element at position key to the specified value. This code inserts a new color into an array of RGB values:
do palette.Colors.SetAt("255,0,0","red")
Here, palette is a reference to the object that contains the array, Colors is the name of the array property, and "red" is the key to access the value "255,0,0".
Do not include a sequential pair of vertical bars (||) within the value that you use as the array key. This restriction is imposed by the InterSystems SQL mechanism.
The SetAt() methods also modifies the values of existing elements. For example, this code changes the value stored at the "red" key to the hexadecimal format:
do palette.Colors.SetAt("#FF0000","red")
To iterate over the contents in an array, pass the key by reference to the GetNext() method, which causes the loop to iterate over both keys and values. For example, this code writes the keys and values of an string array in order. The elements are ordered alphabetically by key.
set arr=##class(%ArrayOfDataTypes).%New()
do arr.SetAt("red","color")
do arr.SetAt("large","size")
do arr.SetAt("expensive","price")
set key=""
for {set value=arr.GetNext(.key) quit:key="" write !,key," = ",value}
color = red
price = expensive
size = large
Copying Collection Data
To copy the items in one collection into another collection, set the recipient collection equal to the source collection. This copies the contents of the source into the recipient (not the OREF of the collection itself). Some examples of such a command are:
Set person2.Colors = person1.Colors
Set dealer7.Inventory = owner3.cars
where person2, person1, dealer7, and owner3 are all instances of classes and Colors, Inventory, and cars are all collection properties. The first line of code looks as it might for copying data between two instances of a single class and the second line of code as it might for copying data from an instance of one class to an instance of a different class.
If the recipient collection is a list and the source collection is an array, InterSystems IRIS copies only the data of the array (not its key values). If the recipient collection is an array and the source collection is a list, the InterSystems IRIS generates key values for the recipient array; these key values are integers based on the position of the item in the source list.
There is no way to copy the OREF from one collection to another. It is only possible to copy the data.