sequence

<Default Package>
Type sequence < TYPE >

Type Parameters:: TYPE - Element Type

An ordered sequence of elements.

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 dynamic, and new entries can be added and existing entries deleted as needed.

The first element of a sequence has index 0 and the last has an index one less than the number of entries given by size(). Negative indexes can be used to indicate elements relative to the end of the sequence, for example seq[-1] provides access to the last item of the sequence. The subscript operator ([]) will throw IndexOutOfBoundsException if the index is not in range (either a number between 0 and size()-1, or a negative number greater than or equal to -size()).

The individual elements of a sequence can be referenced in several ways:

With subscripts — Use the [ ] operators in combination with an integral expression, to reference sequence elements as an array. For example, seq[3] refers to the fourth element of a sequence. The first element is seq[0]. The last, for a sequence with n elements is seq[n-1], which can also be written seq[-1].
With the for loop — Use the for loop to iterate over the individual elements of the sequence from first to last.
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]

The empty sequence sorts earliest of all.

The syntax for sequence is:

sequence<TYPE> varname

For example:

// 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. For example:

sequence<sequence<float>> seqOfSeq;

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:

sequence<integer> someNumbers;
someNumbers := new sequence<integer>;

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:

sequence<integer> someNumbers := [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

Use [] to delimit the sequence and a comma (,) to delimit individual elements.

You can use a for loop to iterate over all the elements in the sequence:

sequence<integer> si := [1, 2, 3, 4];
integer i;
for i in si {
  print i.toString();
}

You must never add or remove items from the sequence while looping over its contents.

A sequence variable can be a potentially cyclic type — a type that directly or indirectly refers to itself.

Sequences can be routed, parsed and compared as long as their element type can be.

Action summary
`boolean`	`static` `canParse(string s)` Check if the string argument can be successfully parsed as a sequence.
`sequence<TYPE>`	`static` `parse(string s)` Parse a string as a sequence.
`void`	`append(TYPE item)` Append an item to the sequence.
`void`	`appendSequence(sequence<TYPE> items)` Append all the items from another sequence to this sequence.
`void`	`clear()` Set the size of the sequence to 0.
`sequence<TYPE>`	`clone()` Create a deep copy of this sequence.
`boolean`	`contains(TYPE item)` Determine whether this sequence contains the specified item.
`TYPE`	`getOr(integer index, TYPE default)` Return the item at the specified index if it exists, or a provided default value if it does not.
`integer`	`hash()` Get an integer hash representation of the underlying object.
`integer`	`indexOf(TYPE item)` Find an item within the sequence.
`void`	`insert(TYPE item, integer index)` Insert an item at a specific location in the sequence.
`boolean`	`isEmpty()` Determine whether the sequence has no items.
`void`	`remove(integer index)` Remove an entry from the sequence by position.
`void`	`reverse()` Reverse the order of this sequence.
`void`	`setCapacity(integer size)` Set the amount of memory allocated for the sequence.
`void`	`setSize(integer size)` Set the size of the sequence to the specified value.
`integer`	`size()` Get the size of this sequence.
`void`	`sort()` Sort this sequence in ascending order.
`string`	`toString()` Return a string form of this sequence.

Action detail

canParse

boolean static canParse(string s)

Check if the string argument can be successfully parsed as a sequence.

Parameters:: s - The string to test for parseability.

Returns:: True if the string could be parsed as this sequence type, false otherwise.

See Also:: sequence.parse() - See the parse method for how sequences are parsed.

parse

sequence<TYPE> static parse(string s)

Parse a string as a sequence.

The string form of a sequence is "[" [ VALUE "," ]* "]" where VALUE is the string form of the members. You can only parse a sequence containing members of the element type of that sequence.

Parameters:: s - The string to parse.

Returns:: The sequence corresponding to the string.

See Also:: sequence.canParse() - Use canParse to test whether the string can be parsed without throwing an exception.

append

void append(TYPE item)

Append an item to the sequence.

Parameters:: item - The item to append to the sequence.

See Also:: sequence.insert(); sequence.appendSequence()

appendSequence

void appendSequence(sequence<TYPE> items)

Append all the items from another sequence to this sequence.

All items in the new sequence will be added after all existing items in this sequence.

Parameters:: items - The items to append to the sequence.

clear

void clear()

Set the size of the sequence to 0.

Deletes all the items in the sequence.

clone

sequence<TYPE> clone()

Create a deep copy of this sequence.

All the members of the sequence will be copied into the new sequence.

Returns:: A copy of this sequence.

contains

boolean contains(TYPE item)

Determine whether this sequence contains the specified item.

This method is only available if the element type is comparable.

Parameters:: item - The item to search the sequence for.

Returns:: Returns true if it is contained. This is equivalent to indexOf(item) >= 0.

Since:: 10.15.4.0

See Also:: sequence.indexOf() - To return the index at which the item is contained.

getOr

TYPE getOr(integer index, TYPE default)

Return the item at the specified index if it exists, or a provided default value if it does not.

Unlike using the [] operator, this method does not throw an exception if the index does not exist.

Parameters:: index - The index to look up. Negative indexes can be used to specify items at the end of the sequence, for example -1 indicates the last item and -2 the last item but one.; default - The value to return if there is no item at the specified index.

Returns:: The value for index or default.

Since:: 10.15.4.0

hash

integer hash()

Get an integer hash representation of the underlying object.

This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.

If TYPE is not hashable, sequence will not have a hash() method.

Returns:: An integer respresentation of the underlying object.

indexOf

integer indexOf(TYPE item)

Find an item within the sequence.

This method is only available if the element type is comparable.

If you search for NaN in a float sequence which contains NaN, this method will return -1 since NaN compares not-equal to itself.

Parameters:: item - The item to search the sequence for.

Returns:: The position in the sequence, starting from 0, or -1 if the item is not found.

See Also:: sequence.contains() - To determine whether the item is contained without returning the index.

insert

void insert(TYPE item, integer index)

Insert an item at a specific location in the sequence.

The specified index must be in the range 0 to the size of the sequence.

seq.insert(item, seq.size());

is equivalent to

seq.append(item);

Parameters:: item - The item to insert.; index - The position to insert the item. 0 will insert at the start of the sequence. -1 will insert before the last item of the sequence. sequence.size() will insert at the end of the sequence (equivalent to append).

Throws:: Throws IndexOutOfBoundsException if index is out of range.

See Also:: sequence.append()

isEmpty

boolean isEmpty()

Determine whether the sequence has no items.

Returns:: true if size()=0, otherwise false.

Since:: 10.15.4.0

See Also:: sequence.size()

remove

void remove(integer index)

Remove an entry from the sequence by position.

Do not perform mutations such as this while looping over a sequence (the results are undefined).

Parameters:: index - The index into the sequence to remove, starting from 0.

Throws:: Throws IndexOutOfBoundsException if index is out of range.

reverse

void reverse()

Reverse the order of this sequence.

Do not perform mutations such as this while looping over a sequence (the results are undefined).

setCapacity

void setCapacity(integer size)

Set the amount of memory allocated for the sequence.

The sequence will still allocate more memory if needed to contain all the elements. Setting the capacity before inserting a lot of items can improve performance by preventing repeated calls to reallocate the space for the sequence.

Calling this method does not change the behavior of your code.

Parameters:: size - The number of elements to allocate memory for.

Throws:: Throws MemoryAllocationException if size is negative or too large to allocate memory on this platform.

setSize

void setSize(integer size)

Set the size of the sequence to the specified value.

If size is larger than this sequence, new default-initialized values will be appended to the sequence to make it the correct size. If size is smaller than this sequence, items will be removed from the end of the sequence.

Do not perform mutations such as this while looping over a sequence (the results are undefined).

Parameters:: size - The number of elements to set the size of this sequence to.

Throws:: Throws MemoryAllocationException if size is negative or too large to allocate memory on this platform.

size

integer size()

Get the size of this sequence.

Note that if you call setCapacity(), this will still return the number of actual elements in the sequence.

Returns:: The number of items in this sequence.

See Also:: sequence.isEmpty()

sort

void sort()

Sort this sequence in ascending order.

This method is only available if the element type is comparable.

Throws:: Throws ArithmeticException if a sequence of floats or decimals contains NaN.

toString

string toString()

Return a string form of this sequence.

The return value of this method can be parsed using the parse() method.

Returns:: The string form of this sequence.

See Also:: sequence.parse() - See the parse method for the string form of sequences.

<Default Package>Type sequence < TYPE >