Replacing Elements Using SET $LIST

You can use SET $LIST(list,position) to replace an element’s value or append an element to the list. In this two-argument form, you specify the new element value.
You can use SET $LIST(list,position,end) to remove one or more elements, replace one or more element values, or append one or more elements to the list. In this three-argument form, you must specify the new element value(s) as an encoded list.

SET $LIST does not support $LIST(list,start1:end1,start2:end2) syntax.

When $LIST is used with SET on the left hand side of the equals sign, list can be a valid variable name. If the variable does not exist, SET $LIST defines it. The list argument can also be a multidimensional property reference; it cannot be a non-multidimensional object property. Attempting to use SET $LIST on a non-multidimensional object property results in an <OBJECT DISPATCH> error.

You cannot use SET (a,b,c,...)=value syntax with $LIST on the left of the equals sign. You must instead use SET a=value,b=value,c=value,... syntax (or multiple SET statements).

You can also use $LISTUPDATE to replace one or more elements in a list or append element to a list by element position. $LISTUPDATE replaces list elements, performing a boolean test for each element replacement. Unlike SET $LIST, $LISTUPDATE does not modify the initial list, but returns a copy of that list with the specified element replacements.

Two Argument Operations

You can perform the following two-argument operations. Specifying an element value as a list creates a sublist within the list.

Replace one element value with a new value:

  SET $LIST(fruit,2)="orange"   ; count from beginning of list
  SET $LIST(fruit,*)="pear"     ; element at end of list
  SET $LIST(fruit,*-2)="peach"  ; offset from end of list
  SET $LIST(fruit,2)=""         ; sets the value to the null string

Append an element to a list. You can append to the end of the list, or to a location past the end of the list, by using *+n syntax. SET $LIST inserts null value elements as needed to pad to the specified position:
```
  SET $LIST(fruit,*+1)="plum"
```

Replace one element with a sublist of elements:

  SET $LIST(fruit,3)=$LISTBUILD("orange","banana")

Three Argument Operations

You can perform the following three-argument (range) operations. Note that range operations specify element values as a list, even when specifying a single element value.

Replace one element with several elements:

  SET $LIST(fruit,3,3)=$LISTBUILD("orange","banana")

Replace a range of element values with the same number of new values:
```
  SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
```
Replace a range of element values with a larger or smaller number of new values:
```
  SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach")
```
Remove a range of element values (this sets the element values to the null string; it does not remove the element positions):
```
  SET $LIST(fruit,2,3)=$LISTBUILD("","")
```
Remove a range of element values and their positions:
```
  SET $LIST(fruit,2,3)=""
```
Append a range of element to a list. You can append to the end of the list, or to a location past the end of the list, by using *+n syntax. SET $LIST inserts null value elements as needed to pad to the specified position:
```
  SET $LIST(fruit,*+1,*+2)=$LISTBUILD("plum","pear")
```
SET $LIST only appends the specified element values. If the end position is larger than the specified elements, empty trailing element positions are not created.

Examples

$LIST Errors