Collection Classes

When you need a container for sets of related values, you can use $LIST format lists and multidimensional arrays.

If you prefer to work with classes, InterSystems IRIS provides list classes and array classes; these are called collections. For more details on collections, see Working with Collections.

List and Array Classes for Use As Standalone Objects

To create list objects, you can use the following classes:

%Library.ListOfDataTypesOpens in a new tab — Defines a list of literal values.
%Library.ListOfObjectsOpens in a new tab — Defines a list of objects (persistent or serial).

Elements in a list are ordered sequentially. Their positions in a list can be accessed using integer key ranging from 1 to N, where N is the position of the last element.

To manipulate a list object, use its methods. For example:

 set Colors = ##class(%Library.ListOfDataTypes).%New()
 do Colors.Insert("Red")
 do Colors.Insert("Green")
 do Colors.Insert("Blue")

 write "Number of list items: ", Colors.Count()
 write !, "Second list item: ", Colors.GetAt(2)

 do Colors.SetAt("Yellow",2)
 write !, "New second item: ", Colors.GetAt(2)

 write !, "Third item before insertion: ", Colors.GetAt(3)
 do Colors.InsertAt("Purple",3)
 write !, "Number of items after insertion: ", Colors.Count()
 write !, "Third item after insertion: ", Colors.GetAt(3)
 write !, "Fourth item after insertion: ", Colors.GetAt(4)

 do Colors.RemoveAt(3)
 write "Number of items after removing item 3: ", Colors.Count()

 write "List items:"
 for i = 1:1:Colors.Count() write Colors.GetAt(i),!

import iris

Colors=iris.cls("%Library.ListOfDataTypes")._New()
Colors.Insert("Red")
Colors.Insert("Green")
Colors.Insert("Blue")

print("Number of list items:", Colors.Count())
print("Second list item:", Colors.GetAt(2))

Colors.SetAt("Yellow",2)
print("New second item: ", Colors.GetAt(2))

print("Third item before insertion: ", Colors.GetAt(3))
Colors.InsertAt("Purple",3)
print("Number of items after insertion: ", Colors.Count())
print("Third item after insertion: ", Colors.GetAt(3))
print("Fourth item after insertion: ", Colors.GetAt(4))

Colors.RemoveAt(3)
print("Number of items after removing item 3: ", Colors.Count())

print("List items:")
for i in range(1, Colors.Count() + 1) print(Colors.GetAt(i))

Similarly, to create array objects, you can use the following classes:

%Library.ArrayOfDataTypesOpens in a new tab — Defines an array of literal values. Each array item has a key and a value.
%Library.ArrayOfObjectsOpens in a new tab — Defines an array of objects (persistent or serial). Each array item has a key and an object value.

To manipulate an array object, use its methods. For example:

 set ItemArray = ##class(%Library.ArrayOfDataTypes).%New()
 do ItemArray.SetAt("example item","alpha")
 do ItemArray.SetAt("another item","beta")
 do ItemArray.SetAt("yet another item","gamma")
 do ItemArray.SetAt("still another item","omega")
 write "Number of items in this array: ", ItemArray.Count()
 write !, "Item that has the key gamma: ", ItemArray.GetAt("gamma")

import iris
ItemArray=iris.cls("%Library.ArrayOfDataTypes")._New()
ItemArray.SetAt("example item", "alpha")
ItemArray.SetAt("another item", "beta")
ItemArray.SetAt("yet another item", "gamma")
ItemArray.SetAt("still another item", "omega")
print("Number of items in this array:", ItemArray.Count())
print("Item that has the key gamma:", ItemArray.GetAt("gamma"))

The SetAt() method adds items to the array, where the first argument is the element to be added and the second argument is the key. Array elements 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.

List and Arrays as Properties

You can also define a property as a list or array.

To define a property as a list, use the following form:

Property MyProperty as list of Classname;

If Classname is a data type class, then InterSystems IRIS uses the interface provided by %Collection.ListOfDTOpens in a new tab. If Classname is an object class, then it uses the interface provided by %Collection.ListOfObjOpens in a new tab.

To define a property as an array, use the following form:

Property MyProperty as array of Classname;

If Classname is a data type class, then InterSystems IRIS uses the interface provided by %Collection.ArrayOfDTOpens in a new tab. If Classname is an object class, then it uses the interface provided by %Collection.ArrayOfObjOpens in a new tab.

Useful ObjectScript Functions

Stream Interface Classes