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.
! convention, described on page 23, 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)
Generated with Harlequin WebMaker