Collection Alteration and Allocation

The contents of a collection are the key/value pairs stored in the collection. The contents are said to be altered when:

Keys are added or removed (according to the collection's key test).
The value of a key (according to the key test) changes (as tested by ==).
The ordering of the key/value pairs changes. This type of alteration is only possible for explicit key collections that are stable under iteration.

A function destructively modifies its argument collection if calling the function could alter the contents of the argument collection. Unless explicitly documented to do so, functions do not destructively modify their arguments.

The ! convention, described on page 24, is used to indicate some destructive operations.

Unless explicity noted, destructive operations are not required to leave their arguments in a well-defined state. More particularly, a destructive operation does not in general turn the argument into the result. It may reuse components of the argument or alter the argument in some unpredictable way in order to produce the result. As a general rule, the return value of the function should be used.

A collection C is fresh if modification of any pre-existing collection's contents can never modify the contents of C and if modifications to C can never modify the contents of any pre-existing collection. Immutable collections cannot be modified, so a fresh immutable collection can share structure with other immutable collections.

For example, given that <pair> is mutable and the result of a call to list is a fresh instance of <pair>, we can guarantee that the following expression is always false:

list(1) == list(1)