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

#include <field.hxx>

Public Types
using	size_type = field_size_type

Public Member Functions
	field (field_ref const &f)

template<>
bool	to (zview &obj, sl) const
	Specialization: `to(zview &)`. More...

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

template<>
zview	as (zview const &default_value, sl) 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 (sl=sl::current()) const &
	Column name. More...

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

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

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

row_size_type	table_column (sl=sl::current()) 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 &noexcept
	Read as zview (which is also a `string_view`). More...

PQXX_PURE PQXX_RETURNS_NONNULL 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 >
bool	to (T &obj, sl loc=sl::current()) const
	Read value into `obj`; or if null, leave `obj` untouched. More...

template<typename... T>
bool	composite_to (sl loc, T &...fields) const
	Read field as a composite value, write its components into `fields`. 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 >
bool	to (T &obj, T const &default_value, sl loc=sl::current()) const
	Read value into obj; or if null, use default value and return `false`. 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 , 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...

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

PQXX_PURE result_size_type	row_number () const noexcept
	This field's row number within the result. More...

PQXX_PURE row_size_type	column_number () const noexcept
	This field's column number within the result. More...

Detailed Description

Reference to a field in a result set.

This is like field_ref, except it's safe to destroy the result object or move it to a different place in memory.

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

◆ size_type

using pqxx::field::size_type = field_size_type

Constructor & Destructor Documentation

◆ field()

pqxx::field::field ( field_ref const & f )

inlineexplicit

Member Function Documentation

◆ as() [1/3]

template<typename T >

T pqxx::field::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() [2/3]

template<typename T >

T pqxx::field::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() [3/3]

template<>

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

inline

◆ as_array()

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.

◆ as_sql_array()

template<typename ELEMENT , auto... ARGS>

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

inline

Read SQL array contents as a pqxx::array.

◆ c_str()

PQXX_PURE PQXX_RETURNS_NONNULL char const* pqxx::field::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 to() or as() functions to convert the string to other types such as int, or to C++ strings.

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

If the field is null, returns an empty string.

◆ column_number()

PQXX_PURE row_size_type pqxx::field::column_number ( ) const

inlinenoexcept

This field's column number within the result.

◆ composite_to() [1/2]

template<typename... T>

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

inline

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

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

◆ composite_to() [2/2]

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 version does not accept a std::source_location (what in libpqxx we call pqxx::sl for short). That means that should conversion fail with an exception, the exception will refer to this function. It's generally more helpful to pass a location that's more meaningful in the context of your codebase, using the version of this function that takes it as a first argumet.

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

◆ get()

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

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

◆ is_null()

PQXX_PURE bool pqxx::field::is_null ( ) const

inlinenoexcept

Is this field's value null?

◆ name()

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

Column name.

◆ num()

row_size_type pqxx::field::num ( ) const

inlinenoexcept

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

◆ operator!=()

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

◆ operator==()

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

noexcept

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

Warning: This differs from what comparisons do in result, row, row_ref, field, field_ref, and the iterator classes. It will change in the future to compare only the fields' identities, not the actual data.

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.

◆ operator>>()

template<typename T >

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

inline

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

◆ row_number()

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

inlinenoexcept

This field's row number within the result.

◆ size()

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

inlinenoexcept

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

◆ table()

PQXX_PURE oid pqxx::field::table ( sl loc = sl::current() ) const

inline

What table did this column come from?

◆ table_column()

pqxx::row::size_type pqxx::field::table_column ( sl loc = sl::current() ) const

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

◆ to() [1/4]

template<typename T >

bool pqxx::field::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/4]

template<typename T >

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

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.

◆ to() [3/4]

template<>

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

inline

Specialization: to(zview &).

This conversion is not generally available, since the general conversion would not know whether there was indeed a terminating zero at the end of the string. (It could check, but it would have no way of knowing that a zero occurring after the string in memory was actually part of the same allocation.)

◆ to() [4/4]

template<>

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

inline

◆ type()

PQXX_PURE oid pqxx::field::type ( sl loc = sl::current() ) const

inline

Column type.

◆ view()

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

inlinenoexcept

Read as zview (which is also a string_view).

Returns an empty view if the field is 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 view will no longer point to valid memory.

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

include/pqxx/field.hxx
src/field.cxx

Public Types

Public Member Functions

Content access

Detailed Description

Member Typedef Documentation

◆ size_type

Constructor & Destructor Documentation

◆ field()

Member Function Documentation

◆ as() [1/3]

◆ as() [2/3]

◆ as() [3/3]

◆ as_array()

◆ as_sql_array()

◆ c_str()

◆ column_number()

◆ composite_to() [1/2]

◆ composite_to() [2/2]

◆ get()

◆ is_null()

◆ name()

◆ num()

◆ operator!=()

◆ operator==()

◆ operator>>()

◆ row_number()

◆ size()

◆ table()

◆ table_column()

◆ to() [1/4]

◆ to() [2/4]

◆ to() [3/4]

◆ to() [4/4]

◆ type()

◆ view()