Appian a!update()

The shape

a!update() takes something, says which part of it to change, and gives you back a copy with that part changed.

a!update(data, index, value)

What index means depends on what data is: a position when it is a list, a field name when it is a record. One function for both.

a!update({"a", "b", "c"}, 2, "X")        →   {"a", "X", "c"}
a!update(a!map(n: 1), "n", 9)            →   {n: 9}

It never changes what you gave it

The original list or record is untouched. Everything happens in the copy that comes back, so the result has to be captured or it is lost.

This is worth saying twice because nothing complains: update a list, ignore the return value, read the original, and you get the old data with no error anywhere.

Several changes in one call

Hand it a list of positions and a list of values and they pair up in order:

a!update({"a", "b", "c"}, {1, 3}, {"X", "Z"})   →   {"X", "b", "Z"}

Give one value instead of a list and every named position gets that same value. This pairs naturally with where(), which hands you exactly a list of positions:

a!update(scores, where(scores < 60), "n/a")

Records work the same way — a list of field names and a list of values changes several fields at once, and the fields you did not name keep their values.

The trap: a position past the end grows the list

This is the one behaviour that can damage data quietly. Asking to update position 5 of a two-item list does not fail and does not ignore you. It stretches the list and fills the gap with nulls:

a!update({"a", "b"}, 5, "far")   →   {"a", "b", null, null, "far"}

A two-item list became a five-item list with holes in it, and everything downstream now has nulls it did not have before. When the position comes from data rather than from you, check it is within range first.