# Collection(T)

## `Collection(T)`

Collection is the abstract supertype of all collection types in the OCL Standard Library. Each occurrence of an object in a collection is called an element. If an object occurs twice in a collection, there are two elements.

This sub clause defines the properties on Collections that have identical semantics for all collection subtypes. Some operations may be defined within the subtype as well, which means that there is an additional postcondition or a more specialized return value. Collection is itself an instance of the metatype CollectionType.

The definition of several common operations is different for each subtype. These operations are not mentioned in this sub clause.

The semantics of the collection operations is given in the form of a postcondition that uses the IterateExp of the IteratorExp construct. The semantics of those constructs is defined in Clause 10 (“Semantics Described using UML”). In several cases the postcondition refers to other collection operations, which in turn are defined in terms of the IterateExp or IteratorExp constructs.

Well-formedness rules

A collection cannot contain `invalid` values.

context Collection inv: self->forAll(not oclIsInvalid())

conformsTo `OclAny`

Attributes

`lower : Integer[1]`

Evaluates to the lower bound on the number of collection elements.

`upper : Integer[1]`

Evaluates to the upper bound on the number of collection elements.

Associations

`elementType : T[1]`

Evaluates to the type of the collection elements.

Operations

`=(object2 : OclSelf[?]) : Boolean[1]` precedence: `EQUALITY`

True if c is a collection of the same kind as `self` and contains the same elements in the same quantities and in the same order, in the case of an ordered collection type.

`<>(object2 : OclSelf[?]) : Boolean[1]` precedence: `EQUALITY`

True if c is not equal to `self`.

`asBag() : Bag(T)`

The Bag that contains all the elements from `self`.

`asOrderedSet() : OrderedSet(T)`

An OrderedSet that contains all the elements from `self`, with duplicates removed, in an order dependent on the particular concrete collection type.

`asSequence() : Sequence(T)`

A Sequence that contains all the elements from `self`, in an order dependent on the particular concrete collection type.

`asSet() : Set(T)`

The Set containing all the elements from `self`, with duplicates removed.

`count(object : OclAny[?]) : Integer[1]`

The number of times that object occurs in the collection `self`.

`excludes(object : OclAny[?]) : Boolean[1]`

True if object is not an element of `self`, `false` otherwise.

`excludesAll(T2)(c2 : Collection(T2)) : Boolean[1]`

Does `self` contain none of the elements of c2 ?

`excluding(object : OclAny[?]) : Collection(T)`

The collection containing all elements of `self` apart from object.

`excludingAll(objects : Collection(OclAny)) : Collection(T)`

The collection containing all elements of `self` apart from all occurrences of all objects.

`flatten(T2)() : Collection(T2)`

If the element type is not a collection type, this results in the same collection as `self`. If the element type is a collection type, the result is a collection containing all the elements of all the recursively flattened elements of `self`.

`includes(object : OclAny[?]) : Boolean[1]`

True if object is an element of `self`, `false` otherwise.

`includesAll(T2)(c2 : Collection(T2)) : Boolean[1]`

Does `self` contain all the elements of c2 ?

`including(object : T[?]) : Collection(T)`

The collection containing all elements of `self` plus object.

`includingAll(objects : Collection(T)) : Collection(T)`

The collection containing all elements of `self` and objects.

`intersection(c : Collection(T)) : Bag(T)`

The intersection of `self` and bag; the bag of all elements that are in both `self` and c.

`intersection(u : UniqueCollection(T)) : Set(T)`

The intersection of `self` and a unique collection; the set of all elements that are in both `self` and u.

`isEmpty() : Boolean[1]`

Is `self` the empty collection?

Note: `null->isEmpty()` returns `true` in virtue of the implicit casting from `null` to `Bag{}`.

`max() : T[1]`

The element with the maximum value of all elements in `self`. Elements must be of a type supporting the max operation. The max operation – supported by the elements – must take one parameter of type T and be both associative and commutative. UnlimitedNatural, Integer and Real fulfill this condition.

`min() : T[1]`

The element with the minimum value of all elements in `self`. Elements must be of a type supporting the min operation. The min operation – supported by the elements – must take one parameter of type T and be both associative and commutative. UnlimitedNatural, Integer and Real fulfill this condition.

`notEmpty() : Boolean[1]`

Is `self` not the empty collection?

`null->notEmpty()` returns `false` in virtue of the implicit casting from `null` to `Bag{}`.

`product(T2)(c2 : Collection(T2)) : Set(Tuple(first:T[1], second:T2[1]))[*|1]`

The cartesian product operation of `self` and c2.

`selectByKind(TT)(type : TT[?]) : Collection(TT)[*|1]`

`selectByType(TT)(type : TT[?]) : Collection(TT)[*|1]`

`size() : Integer[1]`

The number of elements in the collection `self`.

`sum() : T[1]`

The addition of all elements in `self`. Elements must be of an `OclSummable` type to provide the zero() and sum() operations. The sum operation must be both associative: a.sum(b).sum© = a.sum(b.sum©), and commutative: a.sum(b) = b.sum(a). Integer and Real fulfill this condition.

If the sum operation is not both associative and commutative, the sum expression is not well-formed, which may result in unpredictable results during evaluation. If an implementation is able to detect a lack of associativity or commutativity, the implementation may bypass the evaluation and return an `invalid` result.

`union(c : Collection(T)) : Bag(T)`

The bag consisting of all elements in `self` and all elements in c.

Iterations

`any(i : T[?] | body : Lambda T() : Boolean[1]) : T[?]`

Returns any element in the source collection for which body evaluates to `true`. Returns `invalid` if the body evaluates to `invalid` for any element, otherwise if there are one or more elements for which the body is `true`, an indeterminate choice of one of them is returned, otherwise the result is `invalid`.

let source : Collection(T) = ..., body : Lambda T() : Boolean = ... in source->any(iterator | body) = source->select(iterator | body) >asSequence()>first()

`collect(V)(i : T[?] | lambda : Lambda T() : V[?]) : Collection(V)`

The Collection of elements that results from applying body to every member of the source set. The result is flattened. Notice that this is based on collectNested, which can be of different type depending on the type of source. collectNested is defined individually for each subclass of CollectionType.

`collectNested(V)(i : T[?] | lambda : Lambda T() : V[?]) : Collection(V)`

The Collection of elements which results from applying body to every member of the source collection.

`exists(i : T[?] | lambda : Lambda T() : Boolean[?]) : Boolean[?]`

Results in `true` if body evaluates to `true` for at least one element in the source collection.

`exists(i : T[?], j : T[?] | lambda : Lambda T() : Boolean[?]) : Boolean[?]`

`forAll(i : T[?] | lambda : Lambda T() : Boolean[?]) : Boolean[?]`

Results in `true` if the body expression evaluates to `true` for each element in the source collection; otherwise, result is `false`.

`forAll(i : T[?], j : T[?] | lambda : Lambda T() : Boolean[?]) : Boolean[?]`

`isUnique(i : T[?] | lambda : Lambda T() : OclAny[?]) : Boolean[1]`

Results in `true` if body evaluates to a different value for each element in the source collection; otherwise, result is `false`.

`iterate(Tacc)(i : T[?]acc : ; Tacc[?] | lambda : Lambda T() : Tacc[?]) : Tacc[?]`

`one(i : T[?] | lambda : Lambda T() : Boolean[1]) : Boolean[1]`

Results in `true` if there is exactly one element in the source collection for which body is `true`.

`reject(i : T[?] | lambda : Lambda T() : Boolean[1]) : Collection(T)`

The sub-collection of the source collection for which body is `false`.

`select(i : T[?] | lambda : Lambda T() : Boolean[1]) : Collection(T)`

The sub-collection of the source collection for which body is `true`.

`sortedBy(i : T[?] | lambda : Lambda T() : OclAny[?]) : Sequence(T)`

Results in the Collection containing all elements of the source collection. The element for which body has the lowest value comes first, and so on. The type of the body expression must have the < operation defined. The < operation must return a Boolean value and must be transitive (i.e., if a < b and b < c then a < c).