field.hxx

Go to the documentation of this file.

/* Definitions for the pqxx::field class.
 *
 * pqxx::field refers to a field in a query result.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/field instead.
 *
 * Copyright (c) 2000-2026, 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.
 */
#ifndef PQXX_FIELD_HXX
#define PQXX_FIELD_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <optional>
 
#include "pqxx/array.hxx"
#include "pqxx/composite.hxx"
#include "pqxx/internal/gates/result-field_ref.hxx"
#include "pqxx/result.hxx"
#include "pqxx/strconv.hxx"
#include "pqxx/types.hxx"
 
namespace pqxx::internal::gate
{
class field_ref_const_row_iterator;
} // namespace pqxx::internal::gate
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT field_ref final
{
public:
  using size_type = field_size_type;
 
  field_ref() noexcept = default;
  field_ref(field_ref const &) noexcept = default;
  field_ref(field_ref &&) noexcept = default;
  field_ref(
    result const &res, result_size_type row_num,
    row_size_type col_num) noexcept :
          m_result(&res), m_row{row_num}, m_column{col_num}
  {}
  ~field_ref() = default;
 
  field_ref &operator=(field_ref const &) noexcept = default;
  field_ref &operator=(field_ref &&) noexcept = default;
 
  [[nodiscard]] PQXX_PURE result const &home() const noexcept
  {
    return *m_result;
  }
  [[nodiscard]] PQXX_PURE result_size_type row_number() const noexcept
  {
    return m_row;
  }
 
  [[nodiscard]] PQXX_PURE bool operator==(field_ref const &rhs) const noexcept
  {
    return (home() == rhs.home()) and (row_number() == rhs.row_number()) and
           (column_number() == rhs.column_number());
  }
  [[nodiscard]] PQXX_PURE bool operator!=(field_ref const &rhs) const noexcept
  {
    return not operator==(rhs);
  }
 
  [[nodiscard]] PQXX_PURE char const *name(sl loc = sl::current()) const &
  {
    return home().column_name(column_number(), loc);
  }
 
  [[nodiscard]] PQXX_PURE oid type(sl loc = sl::current()) const;
 
  [[nodiscard]] PQXX_PURE oid table(sl = sl::current()) const;
 
  [[nodiscard]] PQXX_PURE constexpr row_size_type
  column_number() const noexcept
  {
    return m_column;
  }
 
  [[nodiscard]] PQXX_PURE row_size_type
  table_column(sl loc = sl::current()) const
  {
    return home().table_column(column_number(), loc);
  }
 
 
  [[nodiscard]] PQXX_PURE std::string_view view() const & noexcept
  {
    return zview{c_str(), size()};
  }
 
 
  [[nodiscard]] PQXX_PURE char const *c_str() const & noexcept;
 
  [[nodiscard]] PQXX_PURE bool is_null() const noexcept;
 
  [[nodiscard]] PQXX_PURE size_type size() const noexcept;
 
 
  template<typename T>
  [[nodiscard]] T as(T const &default_value, sl loc = sl::current()) const
  {
    if (is_null())
      return default_value;
    else
      return from_string<T>(this->view(), make_context(loc));
  }
 
 
  template<typename T> [[nodiscard]] T as(sl loc = sl::current()) const
  {
    if (is_null())
    {
      if constexpr (not has_null<T>())
        internal::throw_null_conversion(name_type<T>(), loc);
      else
        return make_null<T>();
    }
    else
    {
      return from_string<T>(this->view(), make_context(loc));
    }
  }
 
 
  template<typename T> bool to(T &obj, sl loc = sl::current()) const
  {
    if (is_null())
    {
      return false;
    }
    else
    {
      from_string(view(), obj, make_context(loc));
      return true;
    }
  }
 
  template<typename T>
  bool to(T &obj, T const &default_value, sl loc = sl::current()) const
  {
    bool const null{is_null()};
    if (null)
      obj = default_value;
    else
      obj = from_string<T>(this->view(), make_context(loc));
    return not null;
  }
 
 
  template<typename T, template<typename> typename O = std::optional>
  constexpr O<T> get() const
  {
    return as<O<T>>();
  }
 
  template<typename ELEMENT, auto... ARGS>
  [[deprecated("Use as<pqxx::array<ELEMENT, ...>>().")]] [[nodiscard]] array<
    ELEMENT, ARGS...>
  as_sql_array(sl loc = sl::current()) const
  {
    using array_type = array<ELEMENT, ARGS...>;
 
    // There's no such thing as a null SQL array.
    if (is_null())
      internal::throw_null_conversion(name_type<array_type>(), loc);
    else
      return array_type{
        this->view(),
        pqxx::internal::gate::result_field_ref{home()}.encoding(), loc};
  }
 
private:
  friend class pqxx::internal::gate::field_ref_const_row_iterator;
 
  void offset(row_difference_type n) { m_column += n; }
 
  [[nodiscard]] conversion_context make_context(sl loc) const
  {
    return conversion_context{home().get_encoding_group(), loc};
  }
 
  result const *m_result = nullptr;
 
  result_size_type m_row = -1;
 
 
  row_size_type m_column = -1;
};
} // namespace pqxx
 
 
#include "pqxx/internal/gates/field_ref-const_row_iterator.hxx"
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT field final
{
public:
  using size_type = field_size_type;
 
  explicit field(field_ref const &f) :
          m_home{f.home()}, m_row{f.row_number()}, m_col{f.column_number()}
  {}
 
 
  [[deprecated(
    "To compare fields by content, compare their view()s.")]] PQXX_PURE bool
  operator==(field const &) const noexcept;
 
 
  [[deprecated(
    "To compare fields by content, compare their view()s.")]] PQXX_PURE bool
  operator!=(field const &rhs) const noexcept
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    return not operator==(rhs);
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
 
  [[nodiscard]] PQXX_PURE char const *name(sl = sl::current()) const &;
 
  [[nodiscard]] PQXX_PURE oid type(sl loc = sl::current()) const
  {
    return as_field_ref().type(loc);
  }
 
  [[nodiscard]] PQXX_PURE oid table(sl loc = sl::current()) const
  {
    return as_field_ref().table(loc);
  }
 
  [[deprecated("Use column_number().")]] [[nodiscard]] row_size_type
  num() const noexcept
  {
    return column_number();
  }
 
  [[nodiscard]] row_size_type table_column(sl = sl::current()) const;
 
 
  [[nodiscard]] PQXX_PURE std::string_view view() const & noexcept
  {
    return {c_str(), size()};
  }
 
 
  [[nodiscard]] PQXX_PURE PQXX_RETURNS_NONNULL char const *
  c_str() const & noexcept
  {
    return as_field_ref().c_str();
  }
 
  [[nodiscard]] PQXX_PURE bool is_null() const noexcept
  {
    return as_field_ref().is_null();
  }
 
  [[nodiscard]] PQXX_PURE size_type size() const noexcept
  {
    return as_field_ref().size();
  }
 
 
  template<typename T> bool to(T &obj, sl loc = sl::current()) const
  {
    if (is_null())
    {
      return false;
    }
    else
    {
      obj = from_string<T>(view(), make_context(loc));
      return true;
    }
  }
 
 
  template<typename... T> bool composite_to(sl loc, T &...fields) const
  {
    if (is_null())
    {
      return false;
    }
    else
    {
      parse_composite(make_context(loc), view(), fields...);
      return true;
    }
  }
 
 
  template<typename... T> bool composite_to(T &...fields) const
  {
    return composite_to(sl::current(), fields...);
  }
 
  template<typename T>
  [[deprecated("Use to() or as().")]] bool operator>>(T &obj) const
  {
    return to(obj);
  }
 
 
  template<typename T>
  bool to(T &obj, T const &default_value, sl loc = sl::current()) const
  {
    return as_field_ref().to<T>(obj, default_value, make_context(loc));
  }
 
 
  template<typename T>
  [[nodiscard]] T as(T const &default_value, sl loc = sl::current()) const
  {
    return as_field_ref().as<T>(default_value, loc);
  }
 
 
  template<typename T> [[nodiscard]] T as(sl loc = sl::current()) const
  {
    return as_field_ref().as<T>(loc);
  }
 
 
  template<typename T, template<typename> typename O = std::optional>
  constexpr O<T> get() const
  {
    return as<O<T>>();
  }
 
  template<typename ELEMENT, auto... ARGS>
  array<ELEMENT, ARGS...> as_sql_array(sl loc = sl::current()) const
  {
    return as_field_ref().as_sql_array<ELEMENT, ARGS...>(loc);
  }
 
 
  [[deprecated(
    "Avoid pqxx::array_parser.  "
    "Instead, use as_sql_array() to convert to "
    "pqxx::array.")]] [[nodiscard]] array_parser
  as_array() const & noexcept
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    return array_parser{c_str(), m_home.get_encoding_group()};
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
 
  [[nodiscard]] PQXX_PURE result_size_type row_number() const noexcept
  {
    return m_row;
  }
  [[nodiscard]] PQXX_PURE row_size_type column_number() const noexcept
  {
    return m_col;
  }
 
private:
  field(row const &r, row_size_type c) noexcept;
 
  field() noexcept = default;
 
 
  [[nodiscard]] field_ref as_field_ref() const noexcept
  {
    return field_ref{home(), row_number(), column_number()};
  }
 
  [[nodiscard]] constexpr result const &home() const noexcept
  {
    return m_home;
  }
 
  field(result r, result_size_type row_num, row_size_type col_num) noexcept :
          m_home{std::move(r)}, m_row{row_num}, m_col{col_num}
  {}
 
  [[nodiscard]] conversion_context make_context(sl loc) const
  {
    return conversion_context{home().get_encoding_group(), loc};
  }
 
  result m_home;
  result::size_type m_row = 0;
  row_size_type m_col = 0;
};
 
 
inline char const *field_ref::c_str() const & noexcept
{
  return pqxx::internal::gate::result_field_ref{home()}.get_value(
    row_number(), column_number());
}
 
inline bool field_ref::is_null() const noexcept
{
  return pqxx::internal::gate::result_field_ref{home()}.get_is_null(
    row_number(), column_number());
}
 
inline field_size_type field_ref::size() const noexcept
{
  return pqxx::internal::gate::result_field_ref{home()}.get_length(
    row_number(), column_number());
}
 
inline oid field_ref::type(sl loc) const
{
  return pqxx::internal::gate::result_field_ref{home()}.column_type(
    column_number(), loc);
}
 
inline oid field_ref::table(sl loc) const
{
  return pqxx::internal::gate::result_field_ref{home()}.column_table(
    column_number(), loc);
}
 
 
 
template<> inline bool field::to<zview>(zview &obj, sl) const
{
  bool const null{is_null()};
  if (not null)
    obj = zview{c_str(), size()};
  return not null;
}
 
 
template<>
inline bool field::to<zview>(zview &obj, zview const &default_value, sl) const
{
  bool const null{is_null()};
  if (null)
    obj = default_value;
  else
    obj = zview{c_str(), size()};
  return not null;
}
 
 
 
template<> inline zview field_ref::as<zview>(sl loc) const
{
  if (is_null())
    internal::throw_null_conversion(name_type<zview>(), loc);
  return zview{c_str(), size()};
}
 
 
template<> inline zview field::as<zview>(zview const &default_value, sl) const
{
  return is_null() ? default_value : zview{c_str(), size()};
}
 
 
template<typename CHAR = char, typename TRAITS = std::char_traits<CHAR>>
class field_streambuf final : public std::basic_streambuf<CHAR, TRAITS>
{
public:
  using char_type = CHAR;
  using traits_type = TRAITS;
  using int_type = typename traits_type::int_type;
  using pos_type = typename traits_type::pos_type;
  using off_type = typename traits_type::off_type;
  using openmode = std::ios::openmode;
  using seekdir = std::ios::seekdir;
 
  explicit field_streambuf(field const &f) : m_field{f} { initialize(); }
 
protected:
  int sync() override { return traits_type::eof(); }
 
  pos_type seekoff(off_type, seekdir, openmode) override
  {
    return traits_type::eof();
  }
  pos_type seekpos(pos_type, openmode) override { return traits_type::eof(); }
  int_type overflow(int_type) override { return traits_type::eof(); }
  int_type underflow() override { return traits_type::eof(); }
 
private:
  // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
  field const &m_field;
 
  int_type initialize()
  {
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
    auto g{static_cast<char_type *>(const_cast<char *>(m_field.c_str()))};
    this->setg(g, g, g + std::size(m_field));
    return int_type(std::size(m_field));
  }
};
 
 
// NOLINTBEGIN(fuchsia-multiple-inheritance)
 
 
template<typename CHAR = char, typename TRAITS = std::char_traits<CHAR>>
class basic_fieldstream final : public std::basic_istream<CHAR, TRAITS>
{
  using super = std::basic_istream<CHAR, TRAITS>;
 
public:
  using char_type = CHAR;
  using traits_type = TRAITS;
  using int_type = typename traits_type::int_type;
  using pos_type = typename traits_type::pos_type;
  using off_type = typename traits_type::off_type;
 
  [[deprecated("Use field::as<...>() or field::c_str().")]]
  explicit basic_fieldstream(field const &f) :
          super{nullptr}, m_buf{f}
  {
    super::init(&m_buf);
  }
 
private:
  field_streambuf<CHAR, TRAITS> m_buf;
};
 
// NOLINTEND(fuchsia-multiple-inheritance)
 
 
using fieldstream = basic_fieldstream<char>;
 
 
 
template<typename CHAR>
[[deprecated("To write a pqxx::field, use its view() method.")]] inline std::
  basic_ostream<CHAR> &
  operator<<(std::basic_ostream<CHAR> &s, field const &value)
{
  s.write(value.c_str(), std::streamsize(std::size(value)));
  return s;
}
 
 
 
template<typename T> inline T from_string(field const &value, ctx c = {})
{
  if (value.is_null())
  {
    if constexpr (has_null<T>())
      return make_null<T>();
    else
      internal::throw_null_conversion(name_type<T>(), c.loc);
  }
  else
  {
    return from_string<T>(value.view(), c);
  }
}
 
 
 
template<typename T> inline T from_string(field_ref const &value, ctx c = {})
{
  if (value.is_null())
  {
    if constexpr (has_null<T>())
      return make_null<T>();
    else
      internal::throw_null_conversion(name_type<T>(), c.loc);
  }
  else
  {
    return from_string<T>(value.view(), c);
  }
}
 
 
// TODO: Can we make this generic across all "always-null" types?
// TODO: Do the same for streams.
 
template<>
inline std::nullptr_t from_string<std::nullptr_t>(field const &value, ctx c)
{
  if (not value.is_null())
    throw conversion_error{
      "Extracting non-null field into nullptr_t variable.", c.loc};
  return nullptr;
}
 
 
// clang-tidy rule bug:
// NOLINTBEGIN(misc-unused-parameters)
 
template<>
PQXX_LIBEXPORT inline std::string to_string(field_ref const &value, ctx)
{
  return std::string{value.view()};
}
 
// NOLINTEND(misc-unused-parameters)
 
template<> PQXX_LIBEXPORT inline std::string to_string(field const &value, ctx)
{
  return std::string{value.view()};
}
} // namespace pqxx
#endif