<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 indexed by non-negative 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.
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, 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.
- With instance methods — You can use the indexOf, insert, delete (and others) methods to operate on individual elements.
The subscript operator ([]) will throw IndexOutOfBoundsException if the argument is not between 0 and size() - 1.
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. 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: 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 si := [1, 2, 3, 4];
integer i;
for i in si {
print i.toString();
}
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 |
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. |
boolean | static canParse(string s)
Check if the string argument can be successfully parsed as a sequence. |
void | clear()
Set the size of the sequence to 0. |
sequence<TYPE> | clone()
Create a deep copy of this sequence. |
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. |
sequence<TYPE> | static parse(string s)
Parse a string as a sequence. |
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. |
append
void append(TYPE item)
Append an item to the sequence.
-
Parameters:
-
item - The item to append to the sequence.
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.
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.
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.
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.
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. sequence.size() will insert at the end of the sequence.
-
Throws:
- Throws IndexOutOfBoundsException if index is out of range.
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.
remove
void remove(integer index)
Remove an entry from the sequence by position.
-
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.
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.
-
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.
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.