# AggregatorContext reference

AggregatorContext is one of the arguments passed to the aggregator computation function. It encapsulates the iteration through the aggregation group, in the order of the index on which the aggregator is defined. After the computation function returns, the context becomes invalidated and stops working, so there is no point in saving it between the calls. There is no way to construct the aggregator context directly.

All the methods of the AggregatorContext confess on errors.

An aggregator must never change the table. Any attempt to change the table is a fatal error.

    $result = $ctx->groupSize();

Returns the number of rows in the group.

    $rowType = $ctx->resultType();

Returns the row type of the aggregation result.

    $rh = $ctx->begin();

Returns the first row handle of the iteration. In case of an empty group it would return a NULL handle.

    $rh = $ctx->next($rh);

Returns the next row handle in order. If the argument handle was the last row in the group, returns a NULL handle. So the iteration through the group with a context is similar to iteration through the whole table: it ends when

    begin()

or

    next()

returns a NULL handle.

    $rh = $ctx->last();

Returns the last row handle of the group. In case of an empty group it would return a NULL handle.

    $rh = $ctx->beginIdx($idxType);

Returns the first row in the group, according to a specific index type's order. The index type must belong to the group, otherwise the result is undefined. If the group is empty, will return the same value as

    endIdx()

. If

    $idxType

is non-leaf, the effect is the same as if its first leaf were used.

    $rh = $ctx->endIdx($idxType);

Returns the handle past the last row in the group, according to a specific index type's order. The index type must belong to the group, otherwise the result is undefined and might even result in an endless iteration loop. If

    $idxType

is non-leaf, the effect is the same as if its first leaf were used. This kind of iteration uses the table's

    $t->nextIdx($idxType, $rh)

or

    $rh->next($idxType)

to advance the position. Unlike the general group iteration described in &xrsp;, the aggregator context does allow the iteration by every index in the group. You can pick any index in the group and iterate in its order. And aggregation is where this ability counts the most.

If the group happens to be the last group of this index type (not of

    $idxType

but of the index on which the aggregator is defined) in the table,

    endIdx()

would return a NULL row handle. If it's also empty,

    beginIdx()

would also return a NULL handle, and in general, for an empty group

    beginIdx()

would return the same value as

    endIdx()

. If the group is not the last one,

    endIdx()

returns the handle of the first row in the next group.

    $rh = $ctx->lastIdx($idxType);

Returns the last row in the group according to a particular index type's order. The index type must belong to the group, otherwise the result is undefined. If the group is empty, returns a NULL handle.

    $ctx->send($opcode, $row);

Constructs a result rowop for the aggregator and arranges for it to be sent to the aggregator's output label. The actual sending is delayed: it will be done only after all the aggregators run. The runs before and after the table modifications are separate. The aggregator's output label is not directly visible in the computation function, so the rowop can not be constructed directly. Instead

    send()

takes care of it. The row must be of a type matching the aggregator's result type (and of course the normal practice is to use the aggregator's result type to construct the row). On success returns 1, on error returns

    undef

and the error message.

    $ctx->makeHashSend($opcode, $fieldName => $fieldValue, ...);

A convenience method that produces the row from pairs of field names and values and sends it. A combination of

    makeRowHash()

and

    send()

.

    $ctx->makeArraySend($opcode, @fields);

A convenience function that produces the row from the array of field values and sends it. A combination of

    makeRowArray()

and

    send()

.
AggregatorContext