pqxx::field Class Reference

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

`#include <field.hxx>`

Inheritance diagram for pqxx::field:
[legend]

## 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.
| field () noexcept=default
| Constructor. Do not call this yourself; libpqxx will do it for you.
template<>
bool | to (char const *&obj) const
| Specialization: `to(char const *&)`.
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)
PQXX_PURE bool | operator!= (field const &rhs) const noexcept
| Byte-by-byte comparison (all nulls are considered equal)
Column information
PQXX_PURE char const * | name () const &
| Column name.
oid PQXX_PURE | type () const
| Column type.
PQXX_PURE oid | table () const
| What table did this column come from?
PQXX_PURE constexpr row_size_type | num () const noexcept
| Return row number. The first row is row 0, the second is row 1, etc.
PQXX_PURE row_size_type | table_column () const
| What column number in its originating table did this column come from?

## Content access

class | pqxx::result
class | pqxx::row
row_size_type | m_col
PQXX_PURE std::string_view | view () const &
| Read as `string_view`, or an empty one if null.
PQXX_PURE char const * | c_str () const &
| Read as plain C string.
PQXX_PURE bool | is_null () const noexcept
| Is this field's value null?
PQXX_PURE size_type | size () const noexcept
| Return number of bytes taken up by the field's value.
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`.
template<typename... T>
bool | composite_to (T &...fields) const
| Read field as a composite value, write its components into `fields`.
template<typename T >
bool | operator>> (T &obj) const
| Read value into obj; or leave obj untouched and return `false` if null.
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`.
template<typename T >
T | as (T const &default_value) const
| Return value as object of given type, or default value if null.
template<typename T >
T | as () const
| Return value as object of given type, or throw exception if null.
template<typename T , template< typename > class O = std::optional>
constexpr O< T > | get () const
| Return value wrapped in some optional type (empty for nulls).
array_parser | as_array () const &noexcept
| Parse the field as an SQL array.
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

## 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

## size_type

using pqxx::field::size_type = field_size_type

## Constructor & Destructor Documentation

## field() [1/3]

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.

Copyright (c) 2000-2023, Jeroen T. Vermeulen.

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.

## field() [2/3]

pqxx::field::field | ( |  | ) |

default noexcept

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

## field() [3/3]

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

protected noexcept

## Member Function Documentation

## as() [1/4]

template<typename T >

T pqxx::field::as | ( |  | ) | const

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

References pqxx::nullness< TYPE, ENABLE >::null(), and pqxx::internal::throw_null_conversion().

## as() [2/4]

template<>

zview pqxx::field::as | ( |  | ) | const

References c_str(), is_null(), size(), and pqxx::internal::throw_null_conversion().

## as() [3/4]

template<typename T >

T pqxx::field::as | ( | T const & | default_value | ) | const

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() [4/4]

template<>

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

References c_str(), is_null(), and size().

## as_array()

array_parser pqxx::field::as_array | ( |  | ) | const &

noexcept

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.

## c_str()

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<std::basic_string<std::byte>>()`.

Referenced by as(), as(), pqxx::binarystring::binarystring(), to(), to(), to(), and pqxx::to_string().

## col()

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

constexpr protected noexcept

Referenced by name().

## composite_to()

template<typename... T>

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

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`.

References pqxx::parse_composite().

## get()

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

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

constexpr

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

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

constexpr protected noexcept

Referenced by name().

## idx()

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

constexpr protected noexcept

## is_null()

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

noexcept

Is this field's value null?

Referenced by as(), as(), pqxx::from_string(), pqxx::from_string< std::nullptr_t >(), to(), to(), and to().

## name()

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

Column name.

References col(), pqxx::result::column_name(), and home().

## num()

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

constexpr noexcept

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

## operator!=()

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

noexcept

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

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

## operator==()

bool PQXX_COLD 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.

## operator>>()

template<typename T >

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

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

## size()

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

noexcept

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

Referenced by as(), as(), to(), and to().

## table()

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

What table did this column come from?

## table_column()

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

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

## to() [1/5]

template<>

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

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.

References c_str(), and is_null().

## to() [2/5]

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>

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

References pqxx::from_string().

## to() [3/5]

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>

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.

## to() [4/5]

template<>

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

References c_str(), is_null(), and size().

## to() [5/5]

template<>

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

References c_str(), is_null(), and size().

## type()

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

Column type.

## view()

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

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.

Referenced by pqxx::from_string().

## Friends And Related Symbol Documentation

## pqxx::result

friend class pqxx::result

friend

## pqxx::row

friend class pqxx::row

friend

## Member Data Documentation

## m_col

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:

- field.hxx
- field.cxx