libpqxx
The C++ client library for PostgreSQL
Public Types | Public Member Functions | List of all members
pqxx::row Class Referencefinal

Reference to one row in a result. More...

#include <row.hxx>

Public Types

using size_type = row_size_type
 
using difference_type = row_difference_type
 
using reference = field_ref
 
using pointer = const_row_iterator
 
using const_iterator = const_row_iterator
 
using iterator = const_iterator
 
using const_reverse_iterator = const_reverse_row_iterator
 
using reverse_iterator = const_reverse_iterator
 

Public Member Functions

 row () noexcept=default
 
 row (row &&) noexcept=default
 
 row (row const &) noexcept=default
 
 row (row_ref const &ref)
 
 ~row ()=default
 
row & operator= (row const &) noexcept=default
 
row & operator= (row &&) noexcept=default
 
Comparison
Warning
The meaning of the comparison operators has changed in 8.0. The old behaviour was to go through all the data in the two rows (but not the metadata) and look for differences. This was never fully specified.

Equality between two row objects means that they refer to the same row in the same data structure that we originally received from the database. So the two may have been created from different result objects, so long as those are both copies of (or the same as) the same original result that you received from the database.

void test_row_equality(pqxx::result const &r1)
{
pqxx::result r2{r1};
pqxx::row row1{r1[0]}, row2{r2};
assert(row1 == row2);
}
pqxx::result
Result set containing data returned by a query or command.
Definition: result.hxx:101
pqxx::row
Reference to one row in a result.
Definition: row.hxx:415
PQXX_PURE bool operator== (row const &rhs) const noexcept
 
PQXX_PURE bool operator!= (row const &rhs) const noexcept
 
Iteration

A row acts like a container of fields.

PQXX_PURE const_iterator begin () const noexcept
 
PQXX_PURE const_iterator cbegin () const noexcept
 
PQXX_PURE const_iterator end () const noexcept
 
PQXX_PURE const_iterator cend () const noexcept
 
PQXX_PURE const_reverse_row_iterator rbegin () const noexcept
 
PQXX_PURE const_reverse_row_iterator crbegin () const noexcept
 
PQXX_PURE const_reverse_row_iterator rend () const noexcept
 
PQXX_PURE const_reverse_row_iterator crend () const noexcept
 
Field access
field_ref front () const noexcept
 
field_ref back () const noexcept
 
PQXX_PURE field_ref operator[] (size_type) const noexcept
 
PQXX_PURE field_ref operator[] (zview col_name) const
 
field_ref at (size_type, sl=sl::current()) const
 Address a field by number, but check that the number is in range. More...
 
field_ref at (zview col_name, sl=sl::current()) const
 
constexpr PQXX_PURE size_type size () const noexcept
 
constexpr result::size_type rownumber () const noexcept
 Row number, assuming this is a real row and not end()/rend(). More...
 
constexpr PQXX_PURE result::size_type row_number () const noexcept
 Row number, assuming this is a real row and not end()/rend(). More...
 

Column information

class field
 
size_type column_number (zview col_name, sl loc=sl::current()) const
 Number of given column (throws exception if it doesn't exist). More...
 
oid column_type (size_type col_num, sl loc=sl::current()) const
 Return a column's type. More...
 
oid column_type (zview col_name, sl loc=sl::current()) const
 Return a column's type. More...
 
oid column_table (size_type col_num, sl loc=sl::current()) const
 What table did this column come from? More...
 
oid column_table (zview col_name, sl loc=sl::current()) const
 What table did this column come from? More...
 
size_type table_column (size_type col, sl loc=sl::current()) const
 What column number in its table did this result column come from? More...
 
size_type table_column (zview col_name, sl loc=sl::current()) const
 What column number in its table did this result column come from? More...
 
constexpr PQXX_PURE result::size_type num () const noexcept
 
template<typename Tuple >
void to (Tuple &t, sl loc=sl::current()) const
 Extract entire row's values into a tuple. More...
 
template<typename... TYPE>
std::tuple< TYPE... > as (sl loc=sl::current()) const
 Extract entire row's values into a tuple. More...
 
template<typename TUPLE >
TUPLE as_tuple (sl loc=sl::current()) const requires(requires(TUPLE t)
 Convert to a given tuple of values,. More...
 
void swap (row &) noexcept
 

Detailed Description

Reference to one row in a result.

A row is a reference to one particular row of data in a query result set (represented by a result object).

This is like a row_ref, except (as far as this class is concerned) it is safe to destroy the result object or move it to a different place in memory. That's because unlike row_ref, a row contains its own copy of the internal smart pointer referring to the actual data in memory. You do pay a performance price for this, so prefer row_ref where possible.

A row also acts as a container, mapping column numbers or names to field values:

cout << row["date"].c_str() << ": " << row["name"].c_str() << endl;
pqxx::row::row
row() noexcept=default

Member Typedef Documentation

◆ const_iterator

using pqxx::row::const_iterator = const_row_iterator

◆ const_reverse_iterator

using pqxx::row::const_reverse_iterator = const_reverse_row_iterator

◆ difference_type

using pqxx::row::difference_type = row_difference_type

◆ iterator

using pqxx::row::iterator = const_iterator

◆ pointer

using pqxx::row::pointer = const_row_iterator

◆ reference

using pqxx::row::reference = field_ref

◆ reverse_iterator

using pqxx::row::reverse_iterator = const_reverse_iterator

◆ size_type

using pqxx::row::size_type = row_size_type

Constructor & Destructor Documentation

◆ row() [1/4]

pqxx::row::row ( )
defaultnoexcept

◆ row() [2/4]

pqxx::row::row ( row &&  )
defaultnoexcept

◆ row() [3/4]

pqxx::row::row ( row const &  )
defaultnoexcept

◆ row() [4/4]

pqxx::row::row ( row_ref const &  ref)
inlineexplicit

◆ ~row()

pqxx::row::~row ( )
default

Member Function Documentation

◆ as()

template<typename... TYPE>
std::tuple<TYPE...> pqxx::row::as ( sl  loc = sl::current()) const
inline

Extract entire row's values into a tuple.

Converts to the types of the tuple's respective fields.

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

Exceptions
usage_errorIf the number of columns in the row does not match the number of fields in t.

◆ as_tuple()

template<typename TUPLE >
TUPLE pqxx::row::as_tuple ( sl  loc = sl::current()) const
inline

Convert to a given tuple of values,.

Useful in cases where we have a full tuple of field types, but not a parameter pack.

TUPLE should be a tuple type, with the same number of elements as the result has columns.

Exceptions
usage_errorIf the number of columns in the row does not match the number of fields in TUPLE.

◆ at() [1/2]

pqxx::field_ref pqxx::row::at ( size_type  i,
sl  loc = sl::current() 
) const

Address a field by number, but check that the number is in range.

◆ at() [2/2]

pqxx::field_ref pqxx::row::at ( zview  col_name,
sl  loc = sl::current() 
) const

Address field by name.

Warning
This is much slower than indexing by number, or iterating.

◆ back()

pqxx::field_ref pqxx::row::back ( ) const
noexcept

◆ begin()

row::const_iterator pqxx::row::begin ( ) const
inlinenoexcept

◆ cbegin()

row::const_iterator pqxx::row::cbegin ( ) const
inlinenoexcept

◆ cend()

row::const_iterator pqxx::row::cend ( ) const
inlinenoexcept

◆ column_number()

size_type pqxx::row::column_number ( zview  col_name,
sl  loc = sl::current() 
) const
inline

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

◆ column_table() [1/2]

oid pqxx::row::column_table ( size_type  col_num,
sl  loc = sl::current() 
) const
inline

What table did this column come from?

◆ column_table() [2/2]

oid pqxx::row::column_table ( zview  col_name,
sl  loc = sl::current() 
) const
inline

What table did this column come from?

◆ column_type() [1/2]

oid pqxx::row::column_type ( size_type  col_num,
sl  loc = sl::current() 
) const
inline

Return a column's type.

◆ column_type() [2/2]

oid pqxx::row::column_type ( zview  col_name,
sl  loc = sl::current() 
) const
inline

Return a column's type.

◆ crbegin()

row::const_reverse_iterator pqxx::row::crbegin ( ) const
inlinenoexcept

◆ crend()

row::const_reverse_iterator pqxx::row::crend ( ) const
inlinenoexcept

◆ end()

row::const_iterator pqxx::row::end ( ) const
inlinenoexcept

◆ front()

pqxx::field_ref pqxx::row::front ( ) const
noexcept

◆ num()

constexpr PQXX_PURE result::size_type pqxx::row::num ( ) const
inlineconstexprnoexcept

◆ operator!=()

PQXX_PURE bool pqxx::row::operator!= ( row const &  rhs) const
inlinenoexcept

◆ operator=() [1/2]

row& pqxx::row::operator= ( row &&  )
defaultnoexcept

◆ operator=() [2/2]

row& pqxx::row::operator= ( row const &  )
defaultnoexcept

◆ operator==()

PQXX_PURE bool pqxx::row::operator== ( row const &  rhs) const
inlinenoexcept

◆ operator[]() [1/2]

pqxx::field_ref pqxx::row::operator[] ( size_type  i) const
noexcept
Warning
This function is marked as "pure." This means that if it fails, depending on your compiler, the exception may occur in a different place than you expected. The compiler may even find scenarios where it can avoid calling this operator, meaning that the exception does not happen at all. If you need more deterministic exception behaviour, use at().

◆ operator[]() [2/2]

PQXX_PURE field_ref pqxx::row::operator[] ( zview  col_name) const
inline

Address field by name.

Warning
This is much slower than indexing by number, or iterating.
This function is marked as "pure." This means that if it fails, depending on your compiler, the exception may occur in a different place than you expected. The compiler may even find scenarios where it can avoid calling this operator, meaning that the exception does not happen at all. If you need more deterministic exception behaviour, use at().

◆ rbegin()

row::const_reverse_iterator pqxx::row::rbegin ( ) const
inlinenoexcept

◆ rend()

row::const_reverse_iterator pqxx::row::rend ( ) const
inlinenoexcept

◆ row_number()

constexpr PQXX_PURE result::size_type pqxx::row::row_number ( ) const
inlineconstexprnoexcept

Row number, assuming this is a real row and not end()/rend().

◆ rownumber()

constexpr result::size_type pqxx::row::rownumber ( ) const
inlineconstexprnoexcept

Row number, assuming this is a real row and not end()/rend().

◆ size()

constexpr PQXX_PURE size_type pqxx::row::size ( ) const
inlineconstexprnoexcept

◆ swap()

void pqxx::row::swap ( row &  rhs)
noexcept

◆ table_column() [1/2]

size_type pqxx::row::table_column ( size_type  col,
sl  loc = sl::current() 
) const
inline

What column number in its table did this result column come from?

A meaningful answer can be given only if the column in question comes directly from a column in a table. If the column is computed in any other way, a logic_error will be thrown.

Parameters
col_numa zero-based column number in this result set
Returns
a zero-based column number in originating table

◆ table_column() [2/2]

size_type pqxx::row::table_column ( zview  col_name,
sl  loc = sl::current() 
) const
inline

What column number in its table did this result column come from?

◆ to()

template<typename Tuple >
void pqxx::row::to ( Tuple &  t,
sl  loc = sl::current() 
) const
inline

Extract entire row's values into a tuple.

Converts to the types of the tuple's respective fields.

The types in the tuple must have conversions from PostgreSQL's text format defined; see Supporting additional data types.

Exceptions
usage_errorIf the number of columns in the row does not match the number of fields in t.

Friends And Related Function Documentation

◆ field

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