You can use subSequence in an OCL expression to return an inclusive range of elements from an ordered Sequence; it is for anyone who needs a smaller, position-based part of a collection.
Syntax
collection->subSequence(startIndex, endIndex)| Parameter | Type | Meaning |
|---|---|---|
startIndex
|
Integer
|
The position of the first element to include. |
endIndex
|
Integer
|
The position of the last element to include. |
The result is a Sequence(T), where T is the element type of the source collection.
Indexing and range rules
subSequence uses 1-based indexing. The first element is at position 1, not 0.
Both positions are inclusive: the elements at startIndex and endIndex are included in the returned sequence.
For example:
Sequence{1..20}->subSequence(10, 15)Result:
Sequence{10, 11, 12, 13, 14, 15}Common uses
Return one element as a sequence
Use the same value for both indexes when you need a sequence containing one positioned element.
Sequence{'A', 'B', 'C'}->subSequence(2, 2)Result:
Sequence{'B'}The result remains a sequence. It is not the string 'B' by itself.
Take the first items
To take the first two elements of an ordered sequence, start at index 1.
Sequence{'A', 'B', 'C', 'D'}->subSequence(1, 2)Result:
Sequence{'A', 'B'}Use it after ordering a result
Position only has a defined meaning when the input collection is ordered. When you retrieve objects and need a particular range, order the collection before taking the subsequence.
For example, if allInstances returns cars and RegistrationNumber defines their desired order, you can take the first two ordered cars:
Car.allInstances->orderBy(RegistrationNumber)->subSequence(1, 2)This pattern is useful when you want a limited range from a larger result. See Turnkey session 7: Expressions for an introduction to collection expressions and ordering.
Boundary behavior
If either supplied index is outside the source collection, subSequence returns an empty sequence.
For example, the source sequence has three elements, so index 4 is beyond its end:
Sequence{'A', 'B', 'C'}->subSequence(4, 4)Result:
Sequence{}Check the size of a collection when the available number of elements can vary, and ensure that the indexes you supply are within that collection.