Functions: Iterators
These functions are used to navigate through the data model (iterators).
eplCreateEmptyIterator
EplHandle
eplCreateEmptyIterator(EplSession s,
EplTypeId iterType);
|
Function for creating an empty iterator. An iterator can only take on one object type. The type of the elements to be taken up is indicated during the generation.
Using the eplInsert, eplInsertAt, and eplRemove functions, elements can be added or removed.
Return |
Description |
EplHandle |
Handle of the iterator if it could be correctly created, otherwise EPL_ERROR.
|
Input |
Type |
Description |
s |
EplSession |
Session to which the handle of the iterator is to belong. The handles that are contained in the iterator all belong to the same session. The user him-/herself is responsible that no handles of other sessions are inserted in the iterator.
|
iterType |
EplTypeId |
Type of the iterator |
eplOpenIterator
EplHandle
eplOpenIterator (EplSession s,
EplHandle parent,
EplTypeId iterType);
|
Function for creating a new iterator. In the case of some iterators such as EPL_ITERATOR_PROJECTS, no parent needs to be specified. In this case, the value "-1" must be transferred as parent.
Return |
Description |
EplHandle |
Handle of the iterator if it could be correctly created, otherwise EPL_ERROR.
|
Input |
Type |
Description |
s |
EplSession |
Session to which the handle of the iterator is to belong. The handles that are contained in the iterator all belong to the same session. The user him-/herself is responsible that no handles of other sessions are inserted in the iterator.
|
parent |
EplHandle |
Object to which the iterator refers. Can be -1 for some iterators. |
iterType |
EplTypeId |
Type of the iterator |
eplCount
EplHandle
eplCount (EplSession s,
EplHandle iterHandle);
|
Determines the number of elements in an iterator.
Return |
Description |
long
|
Number of elements in the iterator.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
eplAt
EplHandle
eplAt (EplSession s,
EplHandle iterHandle,
long pos);
|
Access to the element at position "pos" in the iterator. "pos" must be a valid value within the range [0..eplCount(s, iterHandle)]. If an invalid value is entered, the function returns the EPL_ERROR error code.
The position of the iterator is not changed by eplAt. For this reason, the command sequence "eplFirst(...); eplAt(..., 42); eplNext(...)" returns the second element of the iterator!
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
pos
|
long
|
Position of the desired element.
|
eplFirst
EplHandle
eplFirst (EplSession s,
EplHandle iterHandle);
|
Positions the iterator onto the first element and returns its handle or EPL_ERROR, if the iterator is empty.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
eplNext
EplHandle
eplNext (EplSession s,
EplHandle iterHandle);
|
Positions the iterator onto the next element and returns its handle or EPL_ERROR, if there is no other element in the iterator any more.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
eplInsert
EplHandle
eplInsert (EplSession s,
EplHandle iterHandle,
EplHandle obj);
|
Inserts a new element at the end of the iterator.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
obj
|
EplHandle
|
Handle of the element which is to be inserted into the iterator.
|
eplInsertAt
EplHandle
eplInsertAt (EplSession s,
EplHandle iterHandle,
EplHandle obj,
long pos);
|
Inserts a new element into the iterator at a certain position.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
obj
|
EplHandle
|
Handle of the new element.
|
pos
|
long
|
Position of the new element to be inserted. "pos" must be a valid value within the range [0..eplCount(s, iterHandle)].
|
eplRemove
EplHandle
eplRemove (EplSession s,
EplHandle iterHandle,
EplHandle obj);
|
Removes an element from an iterator. The element to be removed is identified by its handle.
Removing the element does not result in its destruction.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|
obj
|
EplHandle
|
Handle of the object to be removed.
|
eplRemoveAt
EplHandle
eplRemoveAt (EplSession s,
EplHandle iterHandle,
long pos);
|
Removes an element from an iterator. The element to be removed is determined by its position.
Removing the element from the iterator does not result in its destruction.
Return |
Description |
EplHandle
|
Handle of the element determined by the parameter pos.
|
Input |
Type |
Description |
s
|
EplSession
|
Handle of the session to which the iterator belongs.
|
iterHandle
|
EplHandle
|
Handle of the iterator.
|