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 (const row &R, row_size_type C) noexcept
| Constructor. More...
template<>
bool | to (const char *&Obj) const
| Specialization: `to(const char *&)`. More...
Comparison
bool | operator== (const field &) const
| Byte-by-byte comparison of two fields (all nulls are considered equal) More...
bool | operator!= (const field &rhs) const
| Byte-by-byte comparison (all nulls are considered equal) More...
Column information
const char * | name () const
| Column name. More...
oid | type () const
| Column type. More...
oid | table () const
| What table did this column come from? More...
row_size_type | num () const
row_size_type | table_column () const
| What column number in its originating table did this column come from? More...

## Content access

long | m_col
const char * | c_str () const
| Read as plain C string. More...
bool | is_null () const noexcept
| Is this field's value null? More...
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<(not std::is_pointer< T >::value or std::is_same< T, const char * >::value), bool >::type
| Read value into Obj; or leave Obj untouched and return `false` if null. 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, const T &Default) const -> typename std::enable_if<(not std::is_pointer< T >::value or std::is_same< T, const char * >::value), bool >::type
| Read value into Obj; or use Default & return `false` if null. More...
template<typename T >
T | as (const T &Default) const
| Return value as object of given type, or Default 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>
constexpr O< T > | get () const
| Return value wrapped in some optional type (empty for nulls) More...
array_parser | as_array () const
| Parse the field as an SQL array. More...
const result & | home () const noexcept
size_t | idx () const noexcept
row_size_type | col () const 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()

pqxx::field::field | ( | const row & | R,
|  | row_size_type | C
| ) |  |

noexcept

Constructor.

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-2019, 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.

## Member Function Documentation

## as() [1/2]

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

## as() [2/2]

template<typename T >

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

Return value as object of given type, or Default 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_array()

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

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

const char * 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.

Referenced by pqxx::from_string(), pqxx::icursorstream::icursorstream(), pqxx::operator<<(), operator==(), to(), and pqxx::to_string().

## col()

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

protected noexcept

## get()

template<typename T , template< typename > class O>

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 (i.e. only usable when `std::optional` or `std::experimental::optional` are available), or specify container type with `get<int, std::optional>()`

## home()

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

protected noexcept

## idx()

size_t pqxx::field::idx | ( |  | ) | const

protected noexcept

## is_null()

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

noexcept

Is this field's value null?

Referenced by operator==(), and to().

## name()

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

Column name.

## num()

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

Referenced by pqxx::const_row_iterator::operator-().

## operator!=()

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

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

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

## operator==()

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

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.

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

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

Includes the terminating zero byte.

Referenced by pqxx::from_string(), pqxx::operator<<(), operator==(), and pqxx::to_string().

## 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/3]

template<>

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

Specialization: `to(const char *&)`.

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/3]

template<typename T >

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

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

Note this can be used with optional types (except pointers other than C-strings)

References pqxx::from_string().

## to() [3/3]

template<typename T >

auto pqxx::field::to | ( | T & | Obj,
|  | const T & | Default
| ) |  | const -> typename std::enable_if<( not std::is_pointer<T>::value or std::is_same<T, const char*>::value ), bool>::type

Read value into Obj; or use Default & return `false` if null.

Note this can be used with optional types (except pointers other than C-strings)

## type()

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

Column type.

## Member Data Documentation

## m_col

long pqxx::field::m_col

protected

You'd expect this to be a size_t, 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