# RowHandle reference

A RowHandle is essentially the glue that keeps a row in the table. A row's handle keeps the position of the row in the table and allows to navigate from it in the direction of every index. It also keeps the helper information for the indexes. For example, the Hashed index calculates the has value for the row's fields once and remembers it in the handle. The table operates always on the handles, never directly on the rows. The table methods that accept rows as arguments, implicitly wrap them into handles before doing any operations.

A row handle always belongs to a particular table, and can not be mixed between the tables, even if the tables are of the same type. Even before a row handle has been inserted into the table and after it has been removed, it still belongs to that table and can not be inserted into any other one.

Just as the tables are single-threaded, the row handles are single-threaded.

    $rh = $table->makeRowHandle($row);

Creates the RowHandle. The newly created row handle is not inserted in the table. The type of the argument row must be matching the table's row type.

    $result = $rh->isInTable();

Finds out, whether the row handle is inserted in the table. If the row handle is NULL, it will quietly return 0.

    $result = $rh->isNull();

Finds out if the RowHandle is NULL. A RowHandle may be NULL to indicate the special conditions. It pretty much means that there is only the Perl wrapper layer of RowHandle but no actual RowHandle under it. This happens to be much more convenient than dealing with undefined values at Perl level. The NULL row handles are returned by the certain table calls to indicate that the requested data was not found in the table.

    $rh = $table->makeNullRowHandle();

Creates a NULL RowHandle.

    $result = $rh1->same($rh2);

The usual comparison for sameness.

    $row = $rh->getRow();
    $row = $rh->getRowSafe();

Extracts the row from the handle. The row will have the type of the table's row type. A row can not be extracted from a NULL row handle, in this situation

    getRow()

will confess and

    getRowSafe()

will return

    undef

.

    $rh = $rh->next();
    $rh = $rh->nextIdx($idxType);
    $rh = $rh->firstOfGroupIdx($idxType);
    $rh = $rh->nextGroupIdx($idxType);

These methods work exactly the same as the same-named table methods. They are essentially syntactic sugar over the table methods.

RowHandle