pqxx::row_ref Class Reference

Lightweight 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	const_iterator = const_row_iterator
using	iterator = const_iterator
using	reference = field_ref
using	pointer = field_ref const *
using	const_reverse_iterator = const_reverse_row_iterator
using	reverse_iterator = const_reverse_iterator

Public Member Functions
	row_ref ()=default
	row_ref (row_ref const &)=default
	row_ref (row_ref &&)=default
	row_ref (result const &res, result_size_type index)
	~row_ref ()=default
row_ref &	operator= (row_ref const &) noexcept=default
row_ref &	operator= (row_ref &&) noexcept=default
Comparison
Equality between two row_ref objects means that they both refer to the same row in _the exact same result object._ So, if you copy a result, even though the two copies refer to the exact same underlying data structure, a row_ref in the one will never be equal to a row_ref in the other. void test_equality(pqxx::result const &r1) { pqxx::result const r2{r1}; if (not r1.empty()) { assert(r1[0] == r1[0]); assert(r2[0] != r1[0]); } }
PQXX_PURE bool	operator== (row_ref const &rhs) const noexcept
PQXX_PURE bool	operator!= (row_ref const &rhs) const noexcept
const_iterator	cbegin () const noexcept
const_iterator	begin () const noexcept
const_iterator	end () const noexcept
const_iterator	cend () const noexcept
Field access
reference	front () const noexcept
reference	back () const noexcept
const_reverse_row_iterator	crbegin () const noexcept
const_reverse_row_iterator	rbegin () const noexcept
const_reverse_row_iterator	crend () const noexcept
const_reverse_row_iterator	rend () const noexcept
PQXX_PURE reference	operator[] (size_type i) const noexcept
PQXX_PURE reference	operator[] (zview col_name) const
reference	at (size_type i, sl loc=sl::current()) const
	Address a field by number, but check that the number is in range. More...
reference	at (zview col_name, sl loc=sl::current()) const
	Address field by name. More...
PQXX_PURE size_type	size () const noexcept
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
using	seq = std::make_index_sequence< std::tuple_size_v< TUPLE > >
class	pqxx::internal::gate::row_ref_const_result_iterator
class	pqxx::internal::gate::row_ref_result
template<typename... T>
class	pqxx::internal::result_iter
class	pqxx::internal::gate::row_ref_row
size_type	column_number (zview col_name, sl=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=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_num, 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...
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...
return	get_tuple (seq{}, loc)
PQXX_PURE result const &	home () const noexcept
	The result object to which this row_ref refers. More...

Detailed Description

Lightweight reference to one row in a result.

Like row, represents one row in a query result set. Unlike with row, however, for as long as you're using a row_ref, the result object to which it refers must...

1. remain valid, i.e. you can't destroy it;
2. and in the same place in memory, i.e. you can't move it;
3. and keep the same value, i.e. you can't assign to it.

When you use row_ref, it is your responsibility to ensure all that.

A row_ref is one way of accessing the fields themselves.

Member Typedef Documentation

const_iterator

using pqxx::row_ref::const_iterator = const_row_iterator

const_reverse_iterator

using pqxx::row_ref::const_reverse_iterator = const_reverse_row_iterator

difference_type

using pqxx::row_ref::difference_type = row_difference_type

iterator

using pqxx::row_ref::iterator = const_iterator

pointer

using pqxx::row_ref::pointer = field_ref const *

reference

using pqxx::row_ref::reference = field_ref

reverse_iterator

using pqxx::row_ref::reverse_iterator = const_reverse_iterator

seq

using pqxx::row_ref::seq = std::make_index_sequence<std::tuple_size_v<TUPLE> >

Initial value:

{
    check_size(std::tuple_size_v<TUPLE>, loc)

size_type

using pqxx::row_ref::size_type = row_size_type

Constructor & Destructor Documentation

row_ref() [1/4]

pqxx::row_ref::row_ref ( )

default

row_ref() [2/4]

pqxx::row_ref::row_ref ( row_ref const &  )

default

row_ref() [3/4]

pqxx::row_ref::row_ref ( row_ref &&  )

default

row_ref() [4/4]

pqxx::row_ref::row_ref ( result const &  res, result_size_type  index  )

inline

~row_ref()

pqxx::row_ref::~row_ref ( )

default

Member Function Documentation

as()

template<typename... TYPE>

std::tuple<TYPE...> pqxx::row_ref::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_error

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

as_tuple()

template<typename TUPLE >

TUPLE pqxx::row_ref::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_error

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

at() [1/2]

reference pqxx::row_ref::at ( size_type  i, sl  loc = sl::current()  ) const

inline

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

at() [2/2]

reference pqxx::row_ref::at ( zview  col_name, sl  loc = sl::current()  ) const

inline

Address field by name.

Warning

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

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

back()

field_ref pqxx::row_ref::back ( ) const

inlinenoexcept

begin()

row_ref::const_iterator pqxx::row_ref::begin ( ) const

inlinenoexcept

cbegin()

row_ref::const_iterator pqxx::row_ref::cbegin ( ) const

inlinenoexcept

cend()

row_ref::const_iterator pqxx::row_ref::cend ( ) const

inlinenoexcept

column_number()

row_size_type pqxx::row_ref::column_number ( zview  col_name, sl  loc = sl::current()  ) const

inline

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

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

column_table() [1/2]

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

inline

What table did this column come from?

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

column_table() [2/2]

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

inline

What table did this column come from?

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

column_type() [1/2]

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

inline

Return a column's type.

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

column_type() [2/2]

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

inline

Return a column's type.

This function could perhaps be marked as "pure," but in clang and some gcc configurations this may move exceptions out of try blocks that are meant to catch them.

crbegin()

row_ref::const_reverse_iterator pqxx::row_ref::crbegin ( ) const

inlinenoexcept

crend()

row_ref::const_reverse_iterator pqxx::row_ref::crend ( ) const

inlinenoexcept

end()

row_ref::const_iterator pqxx::row_ref::end ( ) const

inlinenoexcept

front()

field_ref pqxx::row_ref::front ( ) const

inlinenoexcept

get_tuple()

return pqxx::row_ref::get_tuple	(	seq{}	,
		loc
	)

home()

PQXX_PURE result const& pqxx::row_ref::home ( ) const

inlinenoexcept

The result object to which this row_ref refers.

operator!=()

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

inlinenoexcept

operator=() [1/2]

row_ref& pqxx::row_ref::operator= ( row_ref &&  )

defaultnoexcept

operator=() [2/2]

row_ref& pqxx::row_ref::operator= ( row_ref const &  )

defaultnoexcept

operator==()

PQXX_PURE bool pqxx::row_ref::operator== ( row_ref const &  rhs ) const

inlinenoexcept

operator[]() [1/2]

PQXX_PURE reference pqxx::row_ref::operator[] ( size_type  i ) const

inlinenoexcept

operator[]() [2/2]

pqxx::field_ref pqxx::row_ref::operator[]

(

zview

col_name

)

const

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_ref::const_reverse_iterator pqxx::row_ref::rbegin ( ) const

inlinenoexcept

rend()

row_ref::const_reverse_iterator pqxx::row_ref::rend ( ) const

inlinenoexcept

row_number()

constexpr PQXX_PURE result::size_type pqxx::row_ref::row_number ( ) const

inlineconstexprnoexcept

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

size()

PQXX_PURE size_type pqxx::row_ref::size ( ) const

inlinenoexcept

table_column() [1/2]

size_type pqxx::row_ref::table_column ( size_type  col_num, 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_num

a 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_ref::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_ref::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_error

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

Friends And Related Function Documentation

pqxx::internal::gate::row_ref_const_result_iterator

friend class pqxx::internal::gate::row_ref_const_result_iterator

friend

pqxx::internal::gate::row_ref_result

friend class pqxx::internal::gate::row_ref_result

friend

pqxx::internal::gate::row_ref_row

friend class pqxx::internal::gate::row_ref_row

friend

pqxx::internal::result_iter

template<typename... T>

friend class pqxx::internal::result_iter

friend

---

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

• include/pqxx/row.hxx
• src/row.cxx