cursor

Scripts > Class elements and c++ instructions > Interpreted C++ instructions > Container > cursor

A corresponding cursor type belongs to every container type. By means of the cursor single elements of the container can be searched for and the contents of the element can be read.

Every container contains internally a cursor and the methods of the cursor are invoked directly as methods of the container. However, a cursor can be declared also externally. The type name of the cursor arises from the name of the accompanying container, by appending the expression ": :cursor".

Example:

Use of an internal cursor:

vstr v;

v.push_back("tt");

v.push_back("TETRA");

v.reset();

while ( v.gotoNext() )

  out << v.value() << endl;

or declaration of an external cursor:

vstr v;

v.push_back("tt");

v.push_back("TETRA");

vstr::cursor cr = v.getCursor();

while ( cr.gotoNext() )

  out << cr.value() << endl;

The direct call of the internal cursor will be usually preferred to of the declaration of an external cursor because of its simplicity. However, if for example a range of the container shall be marked, then an external cursor is necessary.

The use of the internal cursor also has a side effect. By the change of the position of the internal cursor the state of the container is changed since the position of its cursor is part of this state. The internal cursor cannot be used therefore in a const parser.

The cursor itself can be in three states:

1. it is placed before the first (the same as behind the last) element: the function hasCurrent then returns false.

cr.hasCurrent() == false

2. it denotes a value. Now is

cr.hasCurrent() == true

If the content of the containers is changed by addition or removal of an element, the position of the cursor (not the cursor itself) gets invalid again:

cr.hasCurrent() == false

3. it is invalid, if there is no connection to a container:

cr.isValid() == false

A connection to a container is made by the call of the container method getCursor (see example above). But the connection can get lost, if the container stops existing.

Example:

vstr::cursor GetInvalidCursor( )

{

vstr v;

return vstr::cursor(v);

}

To call a method of an invalid cursor will not create an error, but will be useless.

Different to an external cursor an internal cursor never is invalid; its existence ends with the existence of the container.

This page belongs to the TextTransformer Documentation