# pqxx::result::result::field Class Reference

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

`#include <result.hxx>`

Inheritance diagram for pqxx::result::result::field:

[legend]

List of all members.

## Public Types
typedef size_t | size_type
## Public Member Functions
| field (const tuple &T, tuple::size_type C) throw ()
| Constructor.
template<>
bool | to (const char *&Obj) const
| Specialization: `to(const char *&)`.
Comparison
bool | operator== (const field &) const
| Byte-by-byte comparison of two fields (all nulls are considered equal).
bool | operator!= (const field &rhs) const
| Byte-by-byte comparison (all nulls are considered equal).
Column information
const char * | name () const
| Column name.
oid | type () const
| Column type.
oid | table () const
| What table did this column come from? Requires PostgreSQL 7.4 C API.
tuple::size_type | num () const
tuple::size_type | table_column () const
| What column number in its originating table did this column come from?
Content access
const char * | c_str () const
| Read as plain C string.
template<typename T >
bool | to (T &Obj) const
| Read value into Obj; or leave Obj untouched and return `false` if null.
template<typename T >
bool | operator>> (T &Obj) const
| Read value into Obj; or leave Obj untouched and return `false` if null.
template<typename T >
bool | to (T &Obj, const T &Default) const
| Read value into Obj; or use Default & return `false` if null.
template<typename T >
T | as (const T &Default) const
| Return value as object of given type, or Default if null.
template<typename T >
T | as () const
| Return value as object of given type, or throw exception if null.
bool | is_null () const
size_type | size () const throw ()
## Protected Member Functions
tuple::size_type | col () const throw ()
## Protected Attributes
tuple | m_tup
tuple::size_type | m_col

## Detailed Description

Reference to a field in a result set.

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

## Member Typedef Documentation

typedef size_t pqxx::result::result::field::size_type

Reimplemented in pqxx::result::result::const_fielditerator.

## Constructor & Destructor Documentation

pqxx::result::result::field::field | ( | const tuple & | T,
|  | tuple::size_type | C |
| ) |  |  | throw ()

Constructor.

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

Parameters:

  | T | Tuple that this field is part of.
  | C | Column number of this field.

## Member Function Documentation

template<typename T >

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

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

template<typename T >

T pqxx::result::result::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.

const char* pqxx::result::result::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::binarystring::binarystring(), pqxx::from_string(), pqxx::result::result::field::operator==(), and pqxx::to_string().

tuple::size_type pqxx::result::result::field::col | ( |  | ) | const throw ()`[protected]`

Referenced by pqxx::result::result::const_fielditerator::operator+(), pqxx::result::result::const_fielditerator::operator-(), and pqxx::result::result::const_fielditerator::operator==().

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

Referenced by pqxx::result::result::field::operator==().

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

Column name.

tuple::size_type pqxx::result::result::field::num | ( |  | ) | const

Referenced by pqxx::result::result::const_fielditerator::operator-().

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

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

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

bool pqxx::result::result::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 pqxx::result::result::field::c_str(), pqxx::result::result::field::is_null(), and pqxx::result::result::field::size().

template<typename T >

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

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

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

Referenced by pqxx::binarystring::binarystring(), pqxx::from_string(), pqxx::result::result::field::operator==(), and pqxx::to_string().

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

What table did this column come from? Requires PostgreSQL 7.4 C API.

Only defined if the libpqxx library was compiled against a libpq version that supports the `PQftable` function.

If you get a link error saying this function is undefined, that must be because libpqxx was compiled against an older version of libpq. The `PQftable` function first became available in PostgreSQL 7.4.

tuple::size_type pqxx::result::result::field::table_column | ( |  | ) | const

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

template<>

bool pqxx::result::result::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.

template<typename T >

bool pqxx::result::result::field::to | ( | T & | Obj,
|  | const T & | Default |
| ) |  |  | const

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

template<typename T >

bool pqxx::result::result::field::to | ( | T & | Obj | ) | const

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

References pqxx::from_string().

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

Column type.

## Member Data Documentation

tuple::size_type pqxx::result::result::field::m_col`[protected]`

Referenced by pqxx::result::result::const_fielditerator::operator++(), and pqxx::result::result::const_fielditerator::operator--().

tuple pqxx::result::result::field::m_tup`[protected]`

Referenced by pqxx::result::result::const_fielditerator::operator+(), and pqxx::result::result::const_fielditerator::operator-().

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

- result.hxx
- result.cxx