» 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 is currently unstable, see below.

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`)

» Return Value of append

Although append currently returns the edited list, this behavior is unstable and will change in future releases to undefined, to bring its implementation in line with what is in the Sentinel Language Specification.

To explain why this is not recommended and why it will change in the future, let's look at the use of the function in the context of a rule. 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 }

The side effects of this behavior introduce complexity in policies that makes them prone to logical errors which are difficult to track. As a result, functions like these should return undefined and modify values in-place.