Reference to a field in a result set. More...

#include <field.hxx>

Inheritance diagram for pqxx::field:

Public Types
using	size_type = field_size_type

Public Member Functions
	field (row const &r, row_size_type c) noexcept
	Constructor. Do not call this yourself; libpqxx will do it for you. More...

	field () noexcept=default
	Constructor. Do not call this yourself; libpqxx will do it for you. More...

template<>
bool	to (char const *&obj) const
	Specialization: `to(char const *&)`. More...

template<>
bool	to (zview &obj) const

template<>
bool	to (zview &obj, zview const &default_value) const

template<>
zview	as () const

template<>
zview	as (zview const &default_value) const

Comparison
PQXX_PURE bool	operator== (field const &) const noexcept
	Byte-by-byte comparison of two fields (all nulls are considered equal) More...

PQXX_PURE bool	operator!= (field const &rhs) const noexcept
	Byte-by-byte comparison (all nulls are considered equal) More...

Column information
PQXX_PURE char const *	name () const &
	Column name. More...

oid PQXX_PURE	type () const
	Column type. More...

PQXX_PURE oid	table () const
	What table did this column come from? More...

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

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

Content access
You can read a field 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.
PQXX_PURE std::string_view	view () const &
	Read as `string_view`, or an empty one if null. More...

PQXX_PURE char const *	c_str () const &
	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 >
auto	to (T &obj) const -> typename std::enable_if_t< (not std::is_pointer< T >::value or std::is_same< T, char const * >::value), bool >
	Read value into obj; or if null, leave obj untouched and return `false`. More...

template<typename... T>
bool	composite_to (T &...fields) const
	Read field as a composite value, write its components into `fields`. More...

template<typename T >
bool	operator>> (T &obj) const
	Read value into obj; or leave obj untouched and return `false` if null. More...

template<typename T >
auto	to (T &obj, T const &default_value) const -> typename std::enable_if_t< (not std::is_pointer< T >::value or std::is_same< T, char const * >::value), bool >
	Read value into obj; or if null, use default value and return `false`. More...

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

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

template<typename T , template< typename > class 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 () const
	Read SQL array contents as a pqxx::array. More...

array_parser	as_array () const &noexcept
	Parse the field as an SQL array. More...

Protected Member Functions
constexpr result const &	home () const noexcept

constexpr result::size_type	idx () const noexcept

constexpr row_size_type	col () const noexcept

	field (result const &r, result_size_type row_num, row_size_type col_num) noexcept

Protected Attributes
row_size_type	m_col

Friends
class	pqxx::result

class	pqxx::row

Detailed Description

Reference to a field in a result set.

A field represents one entry in a row. It represents an actual value in the result set, and can be converted to various types.

Member Typedef Documentation

using pqxx::field::size_type = field_size_type

Constructor & Destructor Documentation

pqxx::field::field	(	pqxx::row const &	r,
		row_size_type	c
	)

noexcept

Constructor. Do not call this yourself; libpqxx will do it for you.

Create field as reference to a field in a result set.

Parameters

r	Row that this field is part of.
c	Column number of this field.

Implementation of the pqxx::field class.

pqxx::field refers to a field in a query result.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

pqxx::field::field ( )

defaultnoexcept

Constructor. Do not call this yourself; libpqxx will do it for you.

pqxx::field::field	(	result const &	r,
		result_size_type	row_num,
		row_size_type	col_num
	)

inlineprotectednoexcept

Member Function Documentation

template<typename T >

T pqxx::field::as ( T const & default_value ) 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.

template<typename T >

T pqxx::field::as ( ) 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

template<>

zview pqxx::field::as ( ) const

inline

template<>

zview pqxx::field::as ( zview const & default_value ) const

inline

array_parser pqxx::field::as_array ( ) const

inlinenoexcept

Parse the field as an SQL array.

Call the parser to retrieve values (and structure) from the array.

Make sure the result object stays alive until parsing is finished. If you keep the row of field object alive, it will keep the result object alive as well.

template<typename ELEMENT , auto... ARGS>

array<ELEMENT, ARGS...> pqxx::field::as_sql_array ( ) const

inline

Read SQL array contents as a pqxx::array.

char const * pqxx::field::c_str ( ) const

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 to() or as() functions to convert the string to other types such as int, or to C++ strings.

Do not use this for BYTEA values, or other binary values. To read those, convert the value to your desired type using to() or as(). For example: f.as<pqx::bytes>().

constexpr row_size_type pqxx::field::col ( ) const

inlineprotectednoexcept

template<typename... T>

bool pqxx::field::composite_to ( T &... fields ) const

inline

Read field as a composite value, write its components into fields.

Warning: This is still experimental. It may change or be replaced.

Returns whether the field was null. If it was, it will not touch the values in fields.

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

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

inline

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

constexpr result const& pqxx::field::home ( ) const

inlineprotectednoexcept

constexpr result::size_type pqxx::field::idx ( ) const

inlineprotectednoexcept

bool pqxx::field::is_null ( ) const

noexcept

Is this field's value null?

char const * pqxx::field::name ( ) const

Column name.

PQXX_PURE constexpr row_size_type pqxx::field::num ( ) const

inlinenoexcept

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

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

inlinenoexcept

Byte-by-byte comparison (all nulls are considered equal)

Warning: See operator==() for important information about this operator

bool pqxx::field::operator== ( field const & rhs ) const

noexcept

Byte-by-byte comparison of two fields (all nulls are considered equal)

Warning: null handling is still open to discussion and change!

Handling of null values differs from that in SQL where a comparison involving a null value yields null, so nulls are never considered equal to one another or even to themselves.

Null handling also probably differs from the closest equivalent in C++, which is the NaN (Not-a-Number) value, a singularity comparable to SQL's null. This is because the builtin == operator demands that a == a.

The usefulness of this operator is questionable. No interpretation whatsoever is imposed on the data; 0 and 0.0 are considered different, as are null vs. the empty string, or even different (but possibly equivalent and equally valid) encodings of the same Unicode character etc.

template<typename T >

bool pqxx::field::operator>> ( T & obj ) const

inline

Read value into obj; or leave obj untouched and return false if null.

pqxx::field::size_type pqxx::field::size ( ) const

noexcept

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

pqxx::oid pqxx::field::table ( ) const

What table did this column come from?

pqxx::row::size_type pqxx::field::table_column ( ) const

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

template<typename T >

auto pqxx::field::to ( T & obj ) const -> typename std::enable_if_t< (not std::is_pointer<T>::value or std::is_same<T, char const *>::value), bool>

inline

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

This can be used with optional types (except pointers other than C-style strings).

template<typename T >

auto pqxx::field::to	(	T &	obj,
		T const &	default_value
	)		const -> typename std::enable_if_t< (not std::is_pointer<T>::value or std::is_same<T, char const *>::value), bool>

inline

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

This can be used with std::optional, as well as with standard smart pointer types, but not with raw pointers. If the conversion from a PostgreSQL string representation allocates a pointer (e.g. using new), then the object's later deallocation should be baked in as well, right from the point where the object is created. So if you want a pointer, use a smart pointer, not a raw pointer.

There is one exception, of course: C-style strings. Those are just pointers to the field's internal text data.

template<>

bool pqxx::field::to ( char const *& obj ) const

inline

Specialization: to(char const *&).

The buffer has the same lifetime as the data in this result (i.e. of this result object, or the last remaining one copied from it etc.), so take care not to use it after the last result object referring to this query result is destroyed.

template<>

bool pqxx::field::to ( zview & obj ) const

inline

template<>

bool pqxx::field::to	(	zview &	obj,
		zview const &	default_value
	)		const

inline

pqxx::oid pqxx::field::type ( ) const

Column type.

PQXX_PURE std::string_view pqxx::field::view ( ) const

inline

Read as string_view, or an empty one if null.

The result only remains usable while the data for the underlying result exists. Once all result objects referring to that data have been destroyed, the string_view will no longer point to valid memory.

Friends And Related Function Documentation

friend class pqxx::result

friend

friend class pqxx::row

friend

Member Data Documentation

row_size_type pqxx::field::m_col

protected

You'd expect this to be unsigned, but due to the way reverse iterators are related to regular iterators, it must be allowed to underflow to -1.

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

/tmp/B.ciyvkay4/BUILD/libpqxx-7.10.7-build/libpqxx-7.10.7/include/pqxx/field.hxx
/tmp/B.ciyvkay4/BUILD/libpqxx-7.10.7-build/libpqxx-7.10.7/src/field.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation