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.