Builtin Function: append

The built-in function append appends a value to the end of a list. The list is modified in-place. The return value will always be undefined.

append called on any value other than a list or undefined will result in an immediate error.

Examples:

append([1,2], 3)      // [1, 2, 3]
append(1, 3)          // error()
append(undefined, 3)  // error()
append([], undefined) // [undefined] (a list containing `undefined`)

Why does this function return undefined?

This function returns undefined to avoid unintended side effects of the function in the context of a rule.

For example, if append returned the list value as a result, the following policy would depend on the order in which rules are referenced:

list = []
a = rule { append(list, 1) contains 1 }
b = rule { append(list, 2) contains 2 }

// Scenario 1: list becomes [1, 2]
main = rule { a and b }

// Scenario 2: list becomes [2, 1]
main = rule { b and a }

This sort of side effect behavior introduces complex and difficult to track logical errors in programs. As a result, functions like this return undefined and modify values in-place.