Working with sequence

Sequences are the most complex data type currently supported in the API. As the DumpAP_Type function in the example demonstrates, AP_Type functions and operators exist to:

cout << "sequence type = " << arg.sequenceType() << endl;
cout << "sequence size = " << arg.sequenceLength() << endl;
for (uint32 i = 0; i < arg.sequenceLength(); i++) {
cout << "sequence element[" << i << "]: ";
DumpAP_Type(arg[i]);
ModifyAP_Type(arg[i]);
}

It is also possible to map some or all of the sequence elements onto traditional C/C++ arrays, consisting either of AP_Type objects encapsulating the individual elements of the sequence, or of the “native” objects stored in each element. For example, the elements of an EPL sequence<integer> object can be mapped onto a native int64 array like this:

int64 * intArray = arg.integerSequenceElements();
for (uint32 i = 0; i < arg.sequenceLength(); i++) {
cout << intArray[i] << endl;
}

Alternatively, a “slice” containing a range of elements from the sequence can be mapped. The example below maps elements 20 through 59 of the sequence onto a native int64 array of length 40. Note that an exception will be thrown if the specified slice lies outside the bounds of the sequence.

int64* intSlice = arg.integerSequenceElements(20, 40);
for (uint32 i = 0; i < 40; i++) {
cout << intSlice[i] << endl;
}

Mapping sequence elements in this way may be relatively inefficient. EPL sequences are not necessarily stored as native object arrays internally, so it may be necessary to copy the element data into the native array when performing the mapping. Likewise, the EPL sequence must be updated to reflect any changes to the elements made by the plug-in function, before returning to EPL. This latter operation is achieved by the family of release<type>SequenceElements() functions. For the integer sequence in the example above, it is necessary to call

before returning from the plug-in function. Note that this will immediately invalidate the arrays returned by all calls to integerSequenceElements() made by the plug-in function, so it should typically only be used once per function invocation, once the function is finished with any mapped sequence data.

Any necessary release<type>SequenceElements() calls will in fact be made automatically when a plug-in function terminates. These functions are provided to plug-in writers so that mapped data can be released early if it is necessary to make memory available. It is also possible to access elements of a sequence using the visitor idiom by calling visitSequenceElements with an appropriate functor. Although less convenient than other sequence element accessors, it is more efficient as it entails no memory allocation.