A result set returned from Execute function is a thin read only wrapper around the libpq result. It can be copied around as it contains only a smart pointer to the underlying result set.
The result set's lifetime is not limited by the transaction in which it was created. In can be used after the transaction is committed or rolled back.
The ResultSet provides interface for range-based iteration over its rows.
Also rows can be accessed via indexing operators.
Fields in a row can be accessed by their index, by field name and can be iterated over. Invalid index or name will throw an exception.
A Field object provides an interface to convert underlying buffer to a C++ variable of supported type. Please see uPg: Supported data types for more information on supported types.
Functions Field::As and Field::To can throw an exception if the field value is null
. Their Field::Coalesce counterparts instead set the result to default value.
All data extraction functions can throw parsing errors (descendants of ResultSetError).
Data can be extracted straight from a Row object to a pack or a tuple of user variables. The number of user variables cannot exceed the number of fields in the result. If it does, an exception will be thrown.
When used without additional parameters, the field values are extracted in the order of their appearance.
When a subset of the fields is needed, the fields can be specified by their indexes or names.
Row's data extraction functions throw exceptions as the field extraction functions. Also a FieldIndexOutOfBounds or FieldNameDoesntExist can be thrown.
Statements that return user-defined PostgreSQL type may be called as returning either one-column row with the whole type in it or as multi-column row with every column representing a field in the type. For the purpose of disambiguation, kRowTag may be used.
When a first column is extracted, it is expected that the result set contains the only column, otherwise an exception will be thrown.
In the following example it is assumed that the row has a single column and the FooBar type is mapped to a PostgreSQL type.
A row can be converted to a user type (tuple, structure, class), for more information on data type requirements see uPg: Typed PostgreSQL results
A result set can be represented as a set of user row types or extracted to a container. For more information see uPg: Typed PostgreSQL results