Reference to a field in a result set. More...
#include <field.hxx>
Public Types | |
| using | size_type = field_size_type |
Public Member Functions | |
| field (row const &r, row_size_type c) noexcept | |
| Constructor. More... | |
| field ()=default | |
| template<> | |
| bool | to (char const *&obj) const |
Specialization: to(char const *&). More... | |
Comparison | |
| bool | operator== (field const &) const |
| Byte-by-byte comparison of two fields (all nulls are considered equal) More... | |
| bool | operator!= (field const &rhs) const |
| Byte-by-byte comparison (all nulls are considered equal) More... | |
Column information | |
| char const * | 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 | |
| std::string_view | view () const |
Read as string_view. More... | |
| char const * | 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, char const *>::value), bool >::type |
Read value into obj; or if null, leave obj untouched and return false. 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<(not std::is_pointer< T >::value or std::is_same< T, char const *>::value), bool >::type |
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... | |
| array_parser | as_array () const |
| Parse the field as an SQL array. More... | |
Protected Member Functions | |
| result const & | home () const noexcept |
| result::size_type | idx () const noexcept |
| row_size_type | col () const noexcept |
Protected Attributes | |
| row_size_type | m_col |
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
Constructor & Destructor Documentation
◆ field() [1/2]
|
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-2020, 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/2]
|
default |
Member Function Documentation
◆ as() [1/2]
| 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() [2/2]
| 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_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()
| 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.
References col(), home(), and idx().
Referenced by pqxx::binarystring::binarystring(), pqxx::icursorstream::icursorstream(), operator==(), pqxx::to_string(), and pqxx::field_streambuf< CHAR, TRAITS >::underflow().
◆ col()
|
protectednoexcept |
Referenced by c_str(), is_null(), name(), pqxx::const_row_iterator::operator!=(), pqxx::const_row_iterator::operator<(), pqxx::const_row_iterator::operator<=(), pqxx::const_row_iterator::operator==(), pqxx::const_row_iterator::operator>(), pqxx::const_row_iterator::operator>=(), size(), table(), table_column(), and type().
◆ get()
| constexpr O<T> pqxx::field::get | ( | ) | const |
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()
|
protectednoexcept |
◆ idx()
|
protectednoexcept |
◆ is_null()
|
noexcept |
◆ name()
| char const * pqxx::field::name | ( | ) | const |
Column name.
References col(), pqxx::result::column_name(), and home().
◆ num()
| row_size_type pqxx::field::num | ( | ) | const |
References pqxx::is_null().
Referenced by pqxx::const_row_iterator::operator-().
◆ operator!=()
| bool pqxx::field::operator!= | ( | field const & | 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== | ( | field const & | 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.
◆ operator>>()
| bool pqxx::field::operator>> | ( | T & | obj | ) | const |
Read value into obj; or leave obj untouched and return false if null.
◆ size()
|
noexcept |
Return number of bytes taken up by the field's value.
Includes the terminating zero byte.
References col(), home(), and idx().
Referenced by operator==(), pqxx::to_string(), and pqxx::field_streambuf< CHAR, TRAITS >::underflow().
◆ table()
| pqxx::oid pqxx::field::table | ( | ) | const |
What table did this column come from?
References col(), pqxx::result::column_table(), and home().
◆ table_column()
| pqxx::row::size_type pqxx::field::table_column | ( | ) | const |
What column number in its originating table did this column come from?
References col(), home(), and pqxx::result::table_column().
◆ to() [1/3]
| auto pqxx::field::to | ( | T & | obj | ) | const -> typename std::enable_if< (not std::is_pointer<T>::value or std::is_same<T, char const *>::value), bool>::type |
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(), and pqxx::is_null().
◆ to() [2/3]
| auto pqxx::field::to | ( | T & | obj, |
| T const & | default_value | ||
| ) | const -> typename std::enable_if< (not std::is_pointer<T>::value or std::is_same<T, char const *>::value), bool>::type |
Read value into obj; or if null, use default value and return false.
Note this can be used with optional types (except pointers other than C-strings)
◆ to() [3/3]
| 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 pqxx::is_null().
◆ type()
| pqxx::oid pqxx::field::type | ( | ) | const |
Column type.
References col(), pqxx::result::column_type(), and home().
◆ view()
| std::string_view pqxx::field::view | ( | ) | const |
Read as string_view.
Referenced by pqxx::from_string().
Member Data Documentation
◆ 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
