1.5 Immutability of objects

1.5.1 Behavior of interfaces

Any interfaces that take or return mutable objects can be classified in a few different ways.

Most functions do not capture their mutable input objects, that is, these functions will either not store the objects at all, or will copy any mutable objects before storing them, or perhaps store only some of the components of the objects. Later modifications to those objects will not affect the internal state of DUIM.

Some functions may capture their mutable input objects. That is, it is not specified whether the mutable inputs to these functions will or will not be captured. For such functions, you should assume that these objects will be captured and must not modify these objects capriciously. Furthermore, the behavior is undefined if these objects are later modified.

Some functions that return mutable objects are guaranteed to create fresh outputs. These objects can be modified without affecting the internal state of DUIM.

Functions that return mutable objects that are not fresh objects fall into two categories:

Those that return read-only state
Those that return read/write state

If a function returns read-only state, programmers must not modify that object; doing so might corrupt the state of DUIM. If a function returns read/write state, the modification of that object is part of the DUIM interface, and you are free to modify the object in ways that make sense.