pqxx::result Class Reference

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

`#include <result.hxx>`

## 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 () noexcept
| 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)
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.

## 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 Typedef Documentation

## const_iterator

using pqxx::result::const_iterator = const_result_iterator

## const_reverse_iterator

using pqxx::result::const_reverse_iterator = const_reverse_result_iterator

## difference_type

using pqxx::result::difference_type = result_difference_type

## iterator

using pqxx::result::iterator = const_iterator

## pointer

using pqxx::result::pointer = const_iterator

## reference

using pqxx::result::reference = row

## reverse_iterator

using pqxx::result::reverse_iterator = const_reverse_iterator

## size_type

using pqxx::result::size_type = result_size_type

## Constructor & Destructor Documentation

## result() [1/3]

pqxx::result::result | ( |  | ) |

noexcept

## result() [2/3]

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

default noexcept

## result() [3/3]

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

default noexcept

## Member Function Documentation

## affected_rows()

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

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.

## at() [1/2]

pqxx::row pqxx::result::at | ( | size_type | i | ) | const

Index a row by number, but check that the row number is valid.

## at() [2/2]

pqxx::field pqxx::result::at | ( | size_type | row_num,
|  | pqxx::row_size_type | col_num
| ) |  | const

Index a field by row number and column number.

## back()

pqxx::result::reference pqxx::result::back | ( |  | ) | const

noexcept

## begin()

pqxx::result::const_iterator pqxx::result::begin | ( |  | ) | const

noexcept

## capacity()

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

noexcept

## cbegin()

pqxx::result::const_iterator pqxx::result::cbegin | ( |  | ) | const

noexcept

## cend()

const_iterator pqxx::result::cend | ( |  | ) | const

noexcept

## clear()

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

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_name()

char const * pqxx::result::column_name | ( | row_size_type | number | ) | const &

Name of column with this number (throws exception if it doesn't exist)

Referenced by pqxx::field::name().

## column_number()

pqxx::row::size_type pqxx::result::column_number | ( | zview | name | ) | const

Number of given column (throws exception if it doesn't exist).

References pqxx::zview::c_str().

Referenced by pqxx::row::column_number().

## column_table() [1/2]

pqxx::oid pqxx::result::column_table | ( | row_size_type | col_num | ) | const

What table did this column come from?

References pqxx::oid_none.

## column_table() [2/2]

oid pqxx::result::column_table | ( | zview | col_name | ) | const

What table did this column come from?

## column_type() [1/2]

pqxx::oid pqxx::result::column_type | ( | row_size_type | col_num | ) | const

Return column's type, as an OID from the system catalogue.

References pqxx::oid_none.

## column_type() [2/2]

oid pqxx::result::column_type | ( | zview | col_name | ) | const

Return column's type, as an OID from the system catalogue.

## columns()

pqxx::row::size_type pqxx::result::columns | ( |  | ) | const

noexcept

Number of columns in result.

## crbegin()

pqxx::result::const_reverse_iterator pqxx::result::crbegin | ( |  | ) | const

## crend()

pqxx::result::const_reverse_iterator pqxx::result::crend | ( |  | ) | const

## empty()

bool pqxx::result::empty | ( |  | ) | const

noexcept

## end()

const_iterator pqxx::result::end | ( |  | ) | const

noexcept

## for_each()

template<typename CALLABLE >

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

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.

References pqxx::internal::clear_result().

## front()

pqxx::result::reference pqxx::result::front | ( |  | ) | const

noexcept

## inserted_oid()

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

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

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.

## operator!=()

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

noexcept

Compare two results for inequality.

## operator=() [1/2]

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

default noexcept

Assign one result to another, invaliding the old one.

## operator=() [2/2]

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==()

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

noexcept

Compare two results for equality.

## operator[]()

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

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&`.

## query()

std::string const & pqxx::result::query | ( |  | ) | const &

noexcept

Query that produced this result, if available (empty string otherwise)

## rbegin()

pqxx::result::const_reverse_iterator pqxx::result::rbegin | ( |  | ) | const

## rend()

pqxx::result::const_reverse_iterator pqxx::result::rend | ( |  | ) | const

## size()

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

noexcept

## 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.

References pqxx::row::swap().

## table_column() [1/2]

pqxx::row::size_type pqxx::result::table_column | ( | row_size_type | col_num | ) | const

What column in its table did this column come from?

References pqxx::to_string().

## table_column() [2/2]

row_size_type pqxx::result::table_column | ( | zview | col_name | ) | const

What column in its table did this column come from?

## Friends And Related Symbol Documentation

## pqxx::field

friend class pqxx::field

friend

## pqxx::internal::gate::result_connection

friend class pqxx::internal::gate::result_connection

friend

## pqxx::internal::gate::result_creation

friend class pqxx::internal::gate::result_creation

friend

## pqxx::internal::gate::result_pipeline

friend class pqxx::internal::gate::result_pipeline

friend

## pqxx::internal::gate::result_row

friend class pqxx::internal::gate::result_row

friend

## pqxx::internal::gate::result_sql_cursor

friend class pqxx::internal::gate::result_sql_cursor

friend

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

- result.hxx
- result.cxx