Lightweight reference to a field in a result set. More...

#include <field.hxx>

Public Types
using	size_type = field_size_type
	A type for holding the number of bytes in a field. More...

Public Member Functions
	field_ref () noexcept=default

	field_ref (field_ref const &) noexcept=default

	field_ref (field_ref &&) noexcept=default

	field_ref (result const &res, result_size_type row_num, row_size_type col_num) noexcept

	~field_ref ()=default

field_ref &	operator= (field_ref const &) noexcept=default

field_ref &	operator= (field_ref &&) noexcept=default

PQXX_PURE result const &	home () const noexcept

PQXX_PURE result_size_type	row_number () const noexcept

template<>
zview	as (sl loc) const
	Efficient specialisation: you can convert a field to a `zview`. More...

Comparison
Equality between two `field_ref` objects means that they both refer to the same row and column 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 `field_ref` in the one will never be equal to a `field_ref` in the other.
PQXX_PURE bool	operator== (field_ref const &rhs) const noexcept

PQXX_PURE bool	operator!= (field_ref const &rhs) const noexcept

Column information
PQXX_PURE char const *	name (sl loc=sl::current()) const &
	Column name. More...

PQXX_PURE oid	type (sl loc=sl::current()) const
	Column type. More...

PQXX_PURE oid	table (sl=sl::current()) const
	What table did this column come from? More...

constexpr PQXX_PURE row_size_type	column_number () const noexcept
	Return column number. The first column is 0, the second is 1, etc. More...

PQXX_PURE row_size_type	table_column (sl loc=sl::current()) const
	What column number in its originating table did this column come from? More...

Content access
You can read a `field_ref` as any C++ type for which a conversion from PostgreSQL's text format is defined. See Supporting additional data types for how this works. This mechanism is weakly typed: the conversions do not care what SQL type a field had in the database, only that its actual contents convert to the target type without problems. So for instance, you can read a `text` field as an `int`, so long as the string in the field spells out a valid `int` number. Many built-in types come with conversions predefined. To find out how to add your own, see Supporting additional data types.
class	pqxx::internal::gate::field_ref_const_row_iterator

PQXX_PURE std::string_view	view () const &noexcept
	Read as zview, or an empty one if null. More...

PQXX_PURE char const *	c_str () const &noexcept
	Read as plain C string. More...

PQXX_PURE bool	is_null () const noexcept
	Is this field's value null? More...

PQXX_PURE size_type	size () const noexcept
	Return number of bytes taken up by the field's value. More...

template<typename T >
T	as (T const &default_value, sl loc=sl::current()) const
	Return value as object of given type, or `default value` if null. More...

template<typename T >
T	as (sl loc=sl::current()) const
	Return value as object of given type, or throw exception if null. More...

template<typename T >
bool	to (T &obj, sl loc=sl::current()) const
	Read value into `obj`; or if null, leave `obj` untouched. More...

template<typename T >
bool	to (T &obj, T const &default_value, sl loc=sl::current()) const
	Read value into `obj`; or if null, set default value and return `false`. More...

template<typename T , template< typename > typename O = std::optional>
constexpr O< T >	get () const
	Return value wrapped in some optional type (empty for nulls). More...

template<typename ELEMENT , auto... ARGS>
array< ELEMENT, ARGS... >	as_sql_array (sl loc=sl::current()) const
	Read SQL array contents as a pqxx::array. More...

Detailed Description

Lightweight reference to a field in a result set.

Like field, represents one field in a query result set. Unlike with field, however, for as long as you're using a field_ref, the result object must...

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

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

You can query whether a field_ref is null, and if not, you can convert its value from its textual "SQL representation" to a more suitable C++ type.

Member Typedef Documentation

◆ size_type

using pqxx::field_ref::size_type = field_size_type

A type for holding the number of bytes in a field.

Constructor & Destructor Documentation

◆ field_ref() [1/4]

pqxx::field_ref::field_ref ( )

defaultnoexcept

◆ field_ref() [2/4]

pqxx::field_ref::field_ref ( field_ref const & )

defaultnoexcept

◆ field_ref() [3/4]

pqxx::field_ref::field_ref ( field_ref && )

defaultnoexcept

◆ field_ref() [4/4]

pqxx::field_ref::field_ref	(	result const &	res,
		result_size_type	row_num,
		row_size_type	col_num
	)

inlinenoexcept

◆ ~field_ref()

pqxx::field_ref::~field_ref ( )

default

Member Function Documentation

◆ as() [1/3]

template<>

zview pqxx::field_ref::as ( sl loc ) const

inline

Efficient specialisation: you can convert a field to a zview.

String conversions generally accept std::string_view. You can't just "convert" any old std::string_view to a pqxx::zview because zview is a promise that the string is zero-terminated. One can't generally make that promise based on a string_view.

◆ as() [2/3]

template<typename T >

T pqxx::field_ref::as ( sl loc = sl::current() ) const

inline

Return value as object of given type, or throw exception if null.

Use as as<std::optional<int>>() or as<my_untemplated_optional_t>() as an alternative to get<int>(); this is disabled for use with raw pointers (other than C-strings) because storage for the value can't safely be allocated here

◆ as() [3/3]

template<typename T >

T pqxx::field_ref::as	(	T const &	default_value,
		sl	loc = `sl::current()`
	)		const

inline

Return value as object of given type, or default value if null.

Note that unless the function is instantiated with an explicit template argument, the Default value's type also determines the result type.

◆ as_sql_array()

template<typename ELEMENT , auto... ARGS>

array< ELEMENT, ARGS...> pqxx::field_ref::as_sql_array ( sl loc = sl::current() ) const

inline

Read SQL array contents as a pqxx::array.

◆ c_str()

char const * pqxx::field_ref::c_str ( ) const &

inlinenoexcept

Read as plain C string.

Since the field's data is stored internally in the form of a zero-terminated C string, this is the fastest way to read it. Use the is_null() and as() functions to convert the string to other types such as int, or to C++ strings.

Warning: Binary data may contain null bytes, so do not use c_str() for those. Instead, convert the value to a binary type using as(), e.g. f.as<pqxx::bytes>().

◆ column_number()

constexpr PQXX_PURE row_size_type pqxx::field_ref::column_number ( ) const

inlineconstexprnoexcept

Return column number. The first column is 0, the second is 1, etc.

◆ get()

template<typename T , template< typename > typename O = std::optional>

constexpr O<T> pqxx::field_ref::get ( ) const

inlineconstexpr

Return value wrapped in some optional type (empty for nulls).

Use as get<int>() as before to obtain previous behavior, or specify container type with get<int, std::optional>()

◆ home()

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

inlinenoexcept

◆ is_null()

bool pqxx::field_ref::is_null ( ) const

inlinenoexcept

Is this field's value null?

◆ name()

PQXX_PURE char const* pqxx::field_ref::name ( sl loc = sl::current() ) const &

inline

Column name.

◆ operator!=()

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

inlinenoexcept

◆ operator=() [1/2]

field_ref& pqxx::field_ref::operator= ( field_ref && )

defaultnoexcept

◆ operator=() [2/2]

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

defaultnoexcept

◆ operator==()

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

inlinenoexcept

◆ row_number()

PQXX_PURE result_size_type pqxx::field_ref::row_number ( ) const

inlinenoexcept

◆ size()

field_size_type pqxx::field_ref::size ( ) const

inlinenoexcept

Return number of bytes taken up by the field's value.

◆ table()

oid pqxx::field_ref::table ( sl loc = sl::current() ) const

inline

What table did this column come from?

◆ table_column()

PQXX_PURE row_size_type pqxx::field_ref::table_column ( sl loc = sl::current() ) const

inline

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

◆ to() [1/2]

template<typename T >

bool pqxx::field_ref::to	(	T &	obj,
		sl	loc = `sl::current()`
	)		const

inline

Read value into obj; or if null, leave obj untouched.

This can be handy to read a field's value but also check for nullness along the way.

Returns: Whether the field contained an actual value. So: true for a non-null field, or false for a null field.

◆ to() [2/2]

template<typename T >

bool pqxx::field_ref::to	(	T &	obj,
		T const &	default_value,
		sl	loc = `sl::current()`
	)		const

inline

Read value into obj; or if null, set default value and return false.

◆ type()

oid pqxx::field_ref::type ( sl loc = sl::current() ) const

inline

Column type.

◆ view()

PQXX_PURE std::string_view pqxx::field_ref::view ( ) const &

inlinenoexcept

Read as zview, or an empty one if null.

A zview is also a std::string_view. It just adds the promise that there is a terminating zero right behind the string.

Friends And Related Function Documentation

◆ pqxx::internal::gate::field_ref_const_row_iterator

friend class pqxx::internal::gate::field_ref_const_row_iterator

friend

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

include/pqxx/field.hxx

Public Types

Public Member Functions

Content access

Detailed Description

Member Typedef Documentation

◆ size_type

Constructor & Destructor Documentation

◆ field_ref() [1/4]

◆ field_ref() [2/4]

◆ field_ref() [3/4]

◆ field_ref() [4/4]

◆ ~field_ref()

Member Function Documentation

◆ as() [1/3]

◆ as() [2/3]

◆ as() [3/3]

◆ as_sql_array()

◆ c_str()

◆ column_number()

◆ get()

◆ home()

◆ is_null()

◆ name()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ row_number()

◆ size()

◆ table()

◆ table_column()

◆ to() [1/2]

◆ to() [2/2]

◆ type()

◆ view()

Friends And Related Function Documentation

◆ pqxx::internal::gate::field_ref_const_row_iterator