Loading...
Searching...
No Matches
pqxx::result Class Reference

Result set containing data returned by a query or command. More...

## Public Types

using | size_type = result_size_type
using | difference_type = result_difference_type
using | reference = row
using | const_iterator = const_result_iterator
using | pointer = const_iterator
using | iterator = const_iterator
using | const_reverse_iterator = const_reverse_result_iterator
using | reverse_iterator = const_reverse_iterator

## Public Member Functions

| result (result const &rhs) noexcept=default
| result (result &&rhs) noexcept=default
result & | operator= (result const &rhs) noexcept=default
| Assign one result to another.
result & | operator= (result &&rhs) noexcept=default
| Assign one result to another, invaliding the old one.
Comparisons
You can compare results for equality. Beware: this is a very strict, dumb comparison. The smallest difference between two results (such as a string "Foo" versus a string "foo") will make them unequal.
bool | operator== (result const &) const noexcept
| Compare two results for equality.
bool | operator!= (result const &rhs) const noexcept
| Compare two results for inequality.
template<typename... TYPE>
auto | iter () const
| Iterate rows, reading them directly into a tuple of "TYPE...".
const_reverse_iterator | rbegin () const
const_reverse_iterator | crbegin () const
const_reverse_iterator | rend () const
const_reverse_iterator | crend () const
const_iterator | begin () const noexcept
const_iterator | cbegin () const noexcept
const_iterator | end () const noexcept
const_iterator | cend () const noexcept
reference | front () const noexcept
reference | back () const noexcept
PQXX_PURE size_type | size () const noexcept
PQXX_PURE bool | empty () const noexcept
size_type | capacity () const noexcept
void | swap (result &) noexcept
| Exchange two result values in an exception-safe manner.
row | operator[] (size_type i) const noexcept
| Index a row by number.
row | at (size_type) const
| Index a row by number, but check that the row number is valid.
field | at (size_type, row_size_type) const
| Index a field by row number and column number.
void | clear () noexcept
| Let go of the result's data.

## Column information

class | pqxx::internal::gate::result_pipeline
class | pqxx::field
class | pqxx::internal::gate::result_creation
class | pqxx::internal::gate::result_connection
class | pqxx::internal::gate::result_row
class | pqxx::internal::gate::result_sql_cursor
PQXX_PURE row_size_type | columns () const noexcept
| Number of columns in result.
row_size_type | column_number (zview name) const
| Number of given column (throws exception if it doesn't exist).
char const * | column_name (row_size_type number) const &
| Name of column with this number (throws exception if it doesn't exist).
int | column_storage (row_size_type number) const
| Server-side storage size for field of column's type, in bytes.
int | column_type_modifier (row_size_type number) const noexcept
| Type modifier of the column with this number.
oid | column_type (row_size_type col_num) const
| Return column's type, as an OID from the system catalogue.
oid | column_type (zview col_name) const
| Return column's type, as an OID from the system catalogue.
oid | column_table (row_size_type col_num) const
| What table did this column come from?
oid | column_table (zview col_name) const
| What table did this column come from?
row_size_type | table_column (row_size_type col_num) const
| What column in its table did this column come from?
row_size_type | table_column (zview col_name) const
| What column in its table did this column come from?
PQXX_PURE std::string const & | query () const &noexcept
| Query that produced this result, if available (empty string otherwise).
PQXX_PURE oid | inserted_oid () const
| If command was an INSERT of 1 row, return oid of the inserted row.
PQXX_PURE size_type | affected_rows () const
| If command was INSERT, UPDATE, or DELETE: number of affected rows.
template<typename CALLABLE>
void | for_each (CALLABLE &&func) const
| Run func on each row, passing the row's fields as parameters.
result | expect_rows (size_type n) const
| Check that result contains exactly n rows.
row | one_row () const
| Check that result contains exactly 1 row, and return that row.
std::optional< row > | opt_row () const
| Expect that result contains at moost one row, and return as optional.
result | no_rows () const
| Expect that result contains no rows. Return result for convenience.
result | expect_columns (row_size_type cols) const
| Expect that result consists of exactly cols columns.
field | one_field () const
| Expect that result consists of exactly 1 row and 1 column.

## Detailed Description

Result set containing data returned by a query or command.

This behaves as a container (as defined by the C++ standard library) and provides random access const iterators to iterate over its rows. You can also access a row by indexing a result R by the row's zero-based number:

for (result::size_type i=0; i < std::size(R); ++i) Process(R[i]);

Result sets in libpqxx are lightweight, reference-counted wrapper objects which are relatively small and cheap to copy. Think of a result object as a "smart pointer" to an underlying result set.

Warning
  The result set that a result object points to is not thread-safe. If you copy a result object, it still refers to the same underlying result set. So never copy, destroy, query, or otherwise access a result while another thread may be copying, destroying, querying, or otherwise accessing the same result set–even if it is doing so through a different result object!

## Member Function Documentation

## affected_rows()

pqxx::result::size_type pqxx::result::affected_rows | ( |  | ) | const

nodiscard

If command was INSERT, UPDATE, or DELETE: number of affected rows.

Returns
  Number of affected rows if last command was INSERT, UPDATE, or DELETE; zero for all other commands.

## clear()

void pqxx::result::clear | ( |  | ) |

inline noexcept

Let go of the result's data.

Use this if you need to deallocate the result data earlier than you can destroy the result object itself.

Multiple result objects can refer to the same set of underlying data. The underlying data will be deallocated once all result objects that refer to it are cleared or destroyed.

## column_storage()

int pqxx::result::column_storage | ( | row_size_type | number | ) | const

nodiscard

Server-side storage size for field of column's type, in bytes.

Returns the size of the server's internal representation of the column's data type. A negative value indicates the data type is variable-length.

## column_type_modifier()

int pqxx::result::column_type_modifier | ( | row_size_type | number | ) | const

nodiscard noexcept

Type modifier of the column with this number.

The meaning of modifier values is type-specific; they typically indicate precision or size limits.

Use this only if you know what you're doing. Most applications do not need it, and most types do not use modifiers.

The value -1 indicates "no information available."

Warning
  There is no check for errors, such as an invalid column number.

## expect_columns()

result pqxx::result::expect_columns | ( | row_size_type | cols | ) | const

inline

Expect that result consists of exactly cols columns.

Returns
  The result itself, for convenience.

Exceptions

ref usage_error otherwise.

## expect_rows()

result pqxx::result::expect_rows | ( | size_type | n | ) | const

inline

Check that result contains exactly n rows.

Returns
  The result itself, for convenience.

Exceptions

ref unexpected_rows if the actual count is not equal to n.

## for_each()

template<typename CALLABLE>

void pqxx::result::for_each | ( | CALLABLE && | func | ) | const

inline

Run func on each row, passing the row's fields as parameters.

Goes through the rows from first to last. You provide a callable func.

For each row in the result, for_each will call func. It converts the row's fields to the types of func's parameters, and pass them to func.

(Therefore func must have a single signature. It can't be a generic lambda, or an object of a class with multiple overloaded function call operators. Otherwise, for_each will have no way to detect a parameter list without ambiguity.)

If any of your parameter types is std::string_view, it refers to the underlying storage of this result.

If any of your parameter types is a reference type, its argument will refer to a temporary value which only lives for the duration of that single invocation to func. If the reference is an lvalue reference, it must be const.

For example, this queries employee names and salaries from the database and prints how much each would like to earn instead:

tx.exec("SELECT name, salary FROM employee").for_each(
[](std::string_view name, float salary){
std::cout << name << " would like " << salary * 2 << ".\n";
})

If func throws an exception, processing stops at that point and propagates the exception.

Exceptions

  pqxx::usage_error | if func's number of parameters does not match the number of columns in this result.

The parameter types must have conversions from PostgreSQL's string format defined; see Supporting additional data types.

## inserted_oid()

pqxx::oid pqxx::result::inserted_oid | ( |  | ) | const

nodiscard

If command was an INSERT of 1 row, return oid of the inserted row.

Returns
  Identifier of inserted row if exactly one row was inserted, or oid_none otherwise.

## iter()

template<typename... TYPE>

auto pqxx::result::iter | ( |  | ) | const

inline

Iterate rows, reading them directly into a tuple of "TYPE...".

Converts the fields to values of the given respective types.

Use this only with a ranged "for" loop. The iteration produces std::tuple<TYPE...> which you can "unpack" to a series of auto variables.

## one_field()

pqxx::field pqxx::result::one_field | ( |  | ) | const

Expect that result consists of exactly 1 row and 1 column.

Returns
  The one pqxx::field in the result.

Exceptions

ref usage_error otherwise.

## one_row()

pqxx::row pqxx::result::one_row | ( |  | ) | const

Check that result contains exactly 1 row, and return that row.

Returns
  pqxx::row

Exceptions

ref unexpected_rows if the actual count is not equal to n.

## operator=()

result & pqxx::result::operator= | ( | result const & | rhs | ) |

default noexcept

Assign one result to another.

Copying results is cheap: it copies only smart pointers, but the actual data stays in the same place.

## operator[]()

pqxx::row pqxx::result::operator[] | ( | size_type | i | ) | const

nodiscard noexcept

Index a row by number.

This returns a row object. Generally you should not keep the row around as a variable, but if you do, make sure that your variable is a row, not a row&.

## opt_row()

std::optional< pqxx::row > pqxx::result::opt_row | ( |  | ) | const

Expect that result contains at moost one row, and return as optional.

Returns an empty std::optional if the result is empty, or if it has exactly one row, a std::optional containing the row.

Exceptions

ref unexpected_rows is the row count is not 0 or 1.

## swap()

void pqxx::result::swap | ( | result & | rhs | ) |

noexcept

Exchange two result values in an exception-safe manner.

If the swap fails, the two values will be exactly as they were before.

The swap is not necessarily thread-safe.

The documentation for this class was generated from the following files:

- /build/libpqxx-hcWu4i/libpqxx-7.10.0/include/pqxx/result.hxx
- /build/libpqxx-hcWu4i/libpqxx-7.10.0/src/result.cxx
- /build/libpqxx-hcWu4i/libpqxx-7.10.0/include/pqxx/internal/result_iter.hxx
- /build/libpqxx-hcWu4i/libpqxx-7.10.0/include/pqxx/internal/result_iterator.hxx