You use excluding in OCL to return a collection with one specified object removed; it is for expressions that need a filtered result without changing the original collection.
Syntax
collection->excluding(object)| Part | Meaning |
|---|---|
collection
|
The source collection, also called self in the operator definition.
|
object
|
One object or value of the collection element type T.
|
| Result | A Collection(T) containing the elements of the source collection except for all occurrences of object.
|
Exclude one object
excluding takes one object, not a second collection. For example, when the source collection contains 1, 3, 5 and the object to exclude is 3:
collectionOne->excluding(3)The result is 1, 5.
If the supplied object does not occur in the source collection, every source element remains in the result. For example:
collectionOne->excluding(4)When collectionOne is 1, 3, 5, the result remains 1, 3, 5.
Use an object selected from another collection
When you have another collection, first select one object from it and pass that object to excluding. The following expression excludes the first object in collectionTwo from collectionOne:
collectionOne->excluding(collectionTwo->first())For example, if collectionOne is 1, 3, 5 and collectionTwo->first() is 3, the result is 1, 5. If the first object of collectionTwo is 4, which is not in collectionOne, the result is unchanged.
This is different from an operation that removes all objects found in another collection. excluding evaluates one argument object only.
Result only; it does not detach data
Use excluding when you need a derived collection for an OCL expression. It returns a result and does not physically detach an object from an association or collection in the model.
If you need to modify an association or collection as part of an executable action, use remove instead. For example, remove detaches an object from the actual collection, whereas excluding can provide a collection in which that object is absent for the current expression.
OrderedSet limitation
At the time of writing, the OCL standard library has a known issue in which excluding elements can change an OrderedSet into a Set. Check the resulting collection type and ordering when your expression depends on OrderedSet behavior.
Related operator
The opposite operationâadding an object to a collection resultâis Append.
For a live example that changes the selected first object and shows how the result changes, watch the excluding walkthrough.