intersystems-community/iris-agentic-dev/objectscript-list-patterns

// CORRECT — append with _$LISTBUILD. Linear: 80,000 items in 0.002 s (IRIS 2026.2).
Set lst = ""
For i=1:1:values.Count() {
    Set lst = lst _ $LISTBUILD(values.GetAt(i))
}
Set csv = $LISTTOSTRING(lst, ",")   // for CSV output
 
// SLOW in a loop — $LIST(lst, *+1) is quadratic: 80,000 items in 1.71 s on the same instance.
Set lst = ""
For i=1:1:values.Count() {
    Set $LIST(lst, *+1) = values.GetAt(i)
}
 
// ALSO FINE — a %ListOfDataTypes when you need an object collection:
Set result = ##class(%ListOfDataTypes).%New()
For i=1:1:values.Count() {
    Do result.Insert(values.GetAt(i))
}

// O(n²) — WRONG for large lists:
Set result = ""
For i=1:1:values.Count() {
    If (i > 1) { Set result = result _ "," }
    Set result = result _ values.GetAt(i)
}
 
// O(n) — CORRECT:
Set lst = ""
For i=1:1:values.Count() {
    Set lst = lst _ $LISTBUILD(values.GetAt(i))
}
Return $LISTTOSTRING(lst, ",")

// Preferred — no index arithmetic, handles empty list correctly:
Set ptr = 0
While $LISTNEXT(lst, ptr, val) {
    // process val
}
 
// Alternative — $List is 1-based:
For i=1:1:$LISTLENGTH(lst) {
    Set val = $List(lst, i)
    // process val
}
// Note: $LISTLENGTH("") = 0 (truly empty), $LISTLENGTH($LISTBUILD()) = 1 (one empty element!)
// Use "" not $LISTBUILD() to represent an empty list

// WRONG — O(n²), calls Find() for every item:
For i=1:1:list2.Count() {
    Set item = list2.GetAt(i)
    If (result.Find(item) = "") {
        Do result.Insert(item)
    }
}
 
// CORRECT — O(n) with temp array as hash set:
Set seen = ""
For i=1:1:list1.Count() {
    Set item = list1.GetAt(i)
    Set seen(item) = ""
    Do result.Insert(item)
}
For i=1:1:list2.Count() {
    Set item = list2.GetAt(i)
    If '$Data(seen(item)) {
        Set seen(item) = ""
        Do result.Insert(item)
    }
}
Kill seen

// WRONG — removing during forward iteration skips items:
For i=1:1:items.Count() {
    If (items.GetAt(i) [ "DELETE") { Do items.RemoveAt(i) }
}
 
// CORRECT — iterate backwards so indices stay valid:
For i=items.Count():-1:1 {
    If (items.GetAt(i) [ "DELETE") { Do items.RemoveAt(i) }
}

Set csv = "a,b,c"
Set lst = $LISTFROMSTRING(csv, ",")    // creates %List from delimited string
Set back = $LISTTOSTRING(lst, ",")     // "a,b,c"
 
Set lst2 = $LISTBUILD("a", "b", "c")  // creates %List from literal values

// %ListOfDataTypes: object wrapper, use Insert/GetAt/Count/Find/RemoveAt
Set lst = ##class(%ListOfDataTypes).%New()
Do lst.Insert("value")
Set val = lst.GetAt(1)            // 1-based
Set n = lst.Count()
Set pos = lst.Find("value")       // returns "" if not found, else position
 
// %List (raw): use $LISTBUILD/$LIST/$LISTLENGTH/$LISTNEXT
Set lst = $LISTBUILD("a","b")
Set val = $LIST(lst, 1)           // 1-based
Set n = $LISTLENGTH(lst)