sequence

Values of the sequence type are finite ordered sets or arrays of entries whose values are all of the same primitive or reference type. The type can be any Apama type.

Sequences are indexed by nonnegative integers from 0 to one less than the number of entries given by their size inbuilt method. Sequences are dynamic and new entries can be added and existing entries deleted as needed.

With subscripts — use the [ ] operators in combination with an integral expression, to reference sequence elements as an array. For example, aSequence[3] refers to the fourth element of a sequence. The first element is aSequence[0]. The last, for a sequence with n elements is aSequence[n -1]

With the for loop — use the for loop to iterate over the individual elements of the sequence from first to last. See The for statement.

With instance methods — you can use the indexOf, insert, delete (and others) methods to operate on individual elements.

Two sequences are equal if they are the same length and corresponding elements are equal. Otherwise, they sort according to the earliest difference. For example:

"abc" sorts earlier than "abcXYZ"

[1,2,3] sorts earlier than [1,3,0]

[1,2,3] sorts earlier than [1,2,3,77,88,99]

// A sequence to hold the names and volume of all my stocks
// (assuming the StockNameAndPrice event type includes a string
// for stock name and float for the volume)
sequence<StockNameAndPrice> MyPortfolio;

// A sequence to hold a list of prices
sequence<float> myPrices;

Note that sequences of sequences (and so on) are also supported. Care must be taken in how these are specified by separating trailing > characters with white space, to distinguish them from the right-shift operator >>. For example:

// A correctly specified sequence containing sequence elements
sequence< sequence<float> > willWork;

// An incorrectly specified sequence containing sequence elements
sequence<sequence<float>> willnotWork;

A global variable of type sequence is initialized by default to an empty instance of the type defined. On the other hand, you must explicitly initialize a local variable using the new operator, as follows

It is also possible to both declare and populate a variable of type sequence as a single statement, regardless of the scope in which the variable is declared, as follows:

A sequence variable can be a potentially cyclic type — a type that directly or indirectly refers to itself. For details about the behavior of such objects, see Potentially cyclic types.

append(item) – appends the item to the end of the sequence.

appendSequence(sequence) – appends the sequence to the end of the sequence that this method is called on. The appended sequence must be the same type as the sequence this method is called on.

canParse() — this method is available only on sequences where the item type is parseable. Returns true if the string argument can be successfully parsed to create a sequence object. For more information about the parseable type property, see the table in Type properties summary.

clear() – sets the size of the sequence to 0, deleting all entries.

clone() – returns a new sequence that is an exact copy of the sequence. All the sequence's contents are cloned into the new sequence, and if they were complex types themselves, their contents are cloned as well.

When the sequence you are cloning is a potentially cyclic type, the correlator preserves multiple references, if they exist, to the same object. That is, the correlator does not create a copy of the object to correspond to each reference. See also Potentially cyclic types.

indexOf(item) – return as an integer the location of the first matching item within the sequence. This method is available only if the item type is a comparable type. For details about whether a type is comparable and, if so, how the comparison is done, see Comparable types. The value returned by indexOf() will be from 0 to size() – 1 if the item is found, or -1 if the item is not a member of the sequence. A call to indexOf() to find the index of a NaN value in a sequence of decimal or float values returns -1 because NaN values cannot be compared for equality by using the standard operator.

insert(item, integer) – insert the item specified into the location indicated by the second parameter. The location must be a valid index within the sequence, or the next index due to be filled. That means that the only valid values are from 0 to size(), inclusive. An invalid value will cause a runtime error, which will terminate the enclosing monitor instance.

parse() – this method is available only on sequences where the item type is parseable. Returns the sequence object represented by the string argument. For more information about the parseable type property, see the table in Type properties summary. You can call this method on the sequence type or on an instance of a sequence type. The more typical use is to call parse() directly on the sequence type.

The parse() method takes a single string as its argument. This string must be the string form of a sequence object. The string must adhere to the format described in Event file format. For example:

You can specify the parse() method after an expression or type name. If the correlator is unable to parse the string, it is a runtime error and the monitor instance that the EPL is running in terminates.

remove(integer) – remove the nth element in the sequence, moving all the elements above it down and reducing the size by 1. Note that in EPL sequence elements are indexed from 0, i.e. the first element is at location 0.

reverse() – modifies the sequence by reversing the order of the items in the sequence. For example, if the sequence contains 1, 2, 3, 4, then after execution of reverse() the updated sequence contains 4, 3, 2, 1. There is no return value; the method modifies the sequence in place and does not create a new sequence nor does it create any new items.

setCapacity(integer) – sets the amount of memory initially allocated for the sequence. Note that this does not limit the amount of memory the sequence can use. By default, as you add more elements to a sequence, the correlator allocates more memory. Calling sequence.setCapacity() can improve performance because it removes the need to add more memory repeatedly as you add elements to the sequence. For example, consider a sequence that you intend to populate with 1000 elements. A call to setCapacity(1000) removes the need to allocate additional memory unless more than 1000 elements are added. A call to this method does not change the behavior of your code.

setSize(integer) – sets the number of elements in the sequence to the specified integer, either deleting entries from the end or adding initialized (using default values of variables) entries to the end.

size() – returns as an integer the number of elements in the sequence.

sort() – Sorts the sequence it is called on in ascending order. The type of the sequence items must be comparable. See Comparable types. There is no return value; the method modifies the sequence in place and does not create a new sequence nor does it create any new items. A sequence of decimal or float values that contains NaN values cannot be sorted and will result in termination of the monitor instance that contains the method call.

toString() – convert the entire sequence to a string. This will create a string containing all the elements enclosed within square brackets [ ], separated by commas (,). That is, [<item1> , ... , <itemn> ]

[integer] – retrieve or overwrite an existing entry from the sequence, specifically the one located at the index specified. Note that in EPL sequence elements are indexed from 0, that is, the first element is number 0. The index specified must be valid, that is it must be between 0 and size() - 1, inclusive, as otherwise a runtime error will occur and the monitor instance will terminate.

You can iterate over a sequence both on the elements and on the indices. The indices are numbered from 0 to size() – 1, inclusive. For example:

sequence<string> seq := ["zero", "one", "two"];

// sequence elements
string s;
for s in seq {
   print s;
}

// sequence indices
integer i := 0;
while i < seq.size() {
   print seq[i];
   i := i + 1;
}