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(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.

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

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

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]))

The cartesian product operation of self and c2.

selectByKind(TT)(type : TT[?]) : Collection(TT)

selectByType(TT)(type : TT[?]) : Collection(TT)

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).