libpqxx  7.7.1
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
 
resultoperator= (result const &rhs) noexcept=default
 Assign one result to another. More...
 
resultoperator= (result &&rhs) noexcept=default
 Assign one result to another, invaliding the old one. More...
 
template<typename... TYPE>
auto iter () const
 Iterate rows, reading them directly into a tuple of "TYPE...". More...
 
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. More...
 
row operator[] (size_type i) const noexcept
 Index a row by number. More...
 
row at (size_type) const
 Index a row by number, but check that the row number is valid. More...
 
field at (size_type, row_size_type) const
 Index a field by row number and column number. More...
 
void clear () noexcept
 Let go of the result's data. More...
 
PQXX_PURE std::string const & query () const &noexcept
 Query that produced this result, if available (empty string otherwise) More...
 
PQXX_PURE oid inserted_oid () const
 If command was an INSERT of 1 row, return oid of the inserted row. More...
 
PQXX_PURE size_type affected_rows () const
 If command was INSERT, UPDATE, or DELETE: number of affected rows. More...
 
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. More...
 
bool operator!= (result const &rhs) const noexcept
 Compare two results for inequality. More...
 
Column information
PQXX_PURE row_size_type columns () const noexcept
 Number of columns in result. More...
 
row_size_type column_number (zview name) const
 Number of given column (throws exception if it doesn't exist). More...
 
char const * column_name (row_size_type number) const &
 Name of column with this number (throws exception if it doesn't exist) More...
 
oid column_type (row_size_type col_num) const
 Return column's type, as an OID from the system catalogue. More...
 
oid column_type (zview col_name) const
 Return column's type, as an OID from the system catalogue. More...
 
oid column_table (row_size_type col_num) const
 What table did this column come from? More...
 
oid column_table (zview col_name) const
 What table did this column come from? More...
 
row_size_type table_column (row_size_type col_num) const
 What column in its table did this column come from? More...
 
row_size_type table_column (zview col_name) const
 What column in its table did this column come from? More...
 

Friends

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
 

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

◆ iterator

◆ pointer

◆ reference

◆ reverse_iterator

◆ size_type

Constructor & Destructor Documentation

◆ result() [1/3]

pqxx::result::result ( )
noexcept

◆ result() [2/3]

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

◆ result() [3/3]

pqxx::result::result ( result &&  rhs)
defaultnoexcept

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.

Referenced by pqxx::connection::get_variable().

◆ 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::row::column_number(), and 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.

Referenced by pqxx::row::column_table(), and pqxx::field::table().

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

Referenced by pqxx::row::column_type(), and pqxx::field::type().

◆ 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

◆ 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 const &  rhs)
defaultnoexcept

Assign one result to another.

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

◆ operator=() [2/2]

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

Assign one result to another, invaliding the old one.

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

Referenced by 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().

Referenced by pqxx::field::table_column(), and pqxx::row::table_column().

◆ 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?

References pqxx::internal::clear_result().

Friends And Related Function 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: