row.hxx

Go to the documentation of this file.

/* Definitions for the pqxx::result class and support classes.
 *
 * pqxx::result represents the set of result rows from a database query.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/result 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_ROW_HXX
#define PQXX_ROW_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include "pqxx/except.hxx"
#include "pqxx/field.hxx"
#include "pqxx/result.hxx"
 
 
namespace pqxx::internal
{
template<typename... T> class result_iter;
} // namespace pqxx::internal
 
 
namespace pqxx::internal::gate
{
class row_ref_const_result_iterator;
class row_ref_result;
class row_ref_row;
} // namespace pqxx::internal::gate
 
 
namespace pqxx
{
class field_ref;
 
 
 
class PQXX_LIBEXPORT row_ref final
{
public:
  using size_type = row_size_type;
  using difference_type = row_difference_type;
  using const_iterator = const_row_iterator;
  using iterator = const_iterator;
  using reference = field_ref;
  using pointer = field_ref const *;
  using const_reverse_iterator = const_reverse_row_iterator;
  using reverse_iterator = const_reverse_iterator;
 
  row_ref() = default;
  row_ref(row_ref const &) = default;
  row_ref(row_ref &&) = default;
  row_ref(result const &res, result_size_type index) :
          m_result{&res}, m_index{index}
  {}
  ~row_ref() = default;
 
  row_ref &operator=(row_ref const &) noexcept = default;
  row_ref &operator=(row_ref &&) noexcept = default;
 
  [[nodiscard]] PQXX_PURE bool operator==(row_ref const &rhs) const noexcept
  {
    return rhs.m_result == m_result and rhs.m_index == m_index;
  }
  [[nodiscard]] PQXX_PURE bool operator!=(row_ref const &rhs) const noexcept
  {
    return not operator==(rhs);
  }
 
  [[nodiscard]] const_iterator cbegin() const noexcept;
  [[nodiscard]] const_iterator begin() const noexcept;
  [[nodiscard]] const_iterator end() const noexcept;
  [[nodiscard]] const_iterator cend() const noexcept;
 
  [[nodiscard]] reference front() const noexcept;
  [[nodiscard]] reference back() const noexcept;
 
  [[nodiscard]] const_reverse_row_iterator crbegin() const noexcept;
  [[nodiscard]] const_reverse_row_iterator rbegin() const noexcept;
  [[nodiscard]] const_reverse_row_iterator crend() const noexcept;
  [[nodiscard]] const_reverse_row_iterator rend() const noexcept;
 
  [[nodiscard]] PQXX_PURE reference operator[](size_type i) const noexcept
  {
    return {home(), row_number(), i};
  }
 
#if defined(PQXX_HAVE_MULTIDIM)
  // TODO: There's a proposal to permit a default value for loc.
  [[nodiscard]] PQXX_PURE reference operator[](zview col_name, sl) const;
#endif // PQXX_HAVE_MULTIDIM
 
  [[nodiscard]] PQXX_PURE reference operator[](zview col_name) const;
 
  [[nodiscard]] reference at(size_type i, sl loc = sl::current()) const
  {
    if (m_result == nullptr)
      throw usage_error{"Indexing uninitialised row.", loc};
    if (std::cmp_less(i, 0))
      throw usage_error{"Negative column index.", loc};
    auto const sz{size()};
    if (std::cmp_greater_equal(i, sz))
      throw range_error{
        std::format(
          "Column index out of range: {} in a result of {} column(s).", i, sz),
        loc};
    return operator[](i);
  }
 
 
  [[nodiscard]] reference at(zview col_name, sl loc = sl::current()) const
  {
    if (m_result == nullptr)
      throw usage_error{"Indexing uninitialised row.", loc};
    return operator[](column_number(col_name, loc));
  }
 
  [[nodiscard]] PQXX_PURE size_type size() const noexcept
  {
    return home().columns();
  }
 
  [[nodiscard]] PQXX_PURE constexpr result::size_type
  row_number() const noexcept
  {
    return m_index;
  }
 
 
  [[nodiscard]] size_type
  column_number(zview col_name, sl = sl::current()) const;
 
 
  [[nodiscard]] oid
  column_type(size_type col_num, sl loc = sl::current()) const
  {
    return home().column_type(col_num, loc);
  }
 
 
  [[nodiscard]] oid column_type(zview col_name, sl loc = sl::current()) const
  {
    return column_type(column_number(col_name, loc), loc);
  }
 
 
  [[nodiscard]] oid column_table(size_type col_num, sl = sl::current()) const;
 
 
  [[nodiscard]] oid column_table(zview col_name, sl loc = sl::current()) const
  {
    return column_table(column_number(col_name, loc), loc);
  }
 
 
  [[nodiscard]] size_type
  table_column(size_type col_num, sl loc = sl::current()) const
  {
    return home().table_column(col_num, loc);
  }
 
  [[nodiscard]] size_type
  table_column(zview col_name, sl loc = sl::current()) const
  {
    return table_column(column_number(col_name, loc), loc);
  }
 
 
  template<typename Tuple> void to(Tuple &t, sl loc = sl::current()) const
  {
    check_size(std::tuple_size_v<Tuple>, loc);
    convert(t, loc);
  }
 
 
  template<typename... TYPE>
  [[nodiscard]] std::tuple<TYPE...> as(sl loc = sl::current()) const
  {
    return as_tuple<std::tuple<TYPE...>>(loc);
  }
 
 
  template<typename TUPLE>
  [[nodiscard]] TUPLE as_tuple(sl loc = sl::current()) const
    requires(requires(TUPLE t) { std::get<0>(t); })
  {
    check_size(std::tuple_size_v<TUPLE>, loc);
    using seq = std::make_index_sequence<std::tuple_size_v<TUPLE>>;
    return get_tuple<TUPLE>(seq{}, loc);
  }
 
  [[nodiscard]] PQXX_PURE result const &home() const noexcept
  {
    return *m_result;
  }
 
private:
  friend class pqxx::internal::gate::row_ref_const_result_iterator;
  friend class pqxx::internal::gate::row_ref_result;
  void offset(difference_type d) noexcept { m_index += d; }
 
  void check_size(size_type expected, sl loc) const
  {
    if (size() != expected)
      throw usage_error{
        std::format(
          "Tried to extract {} field(s) from a row of {}.", expected, size()),
        loc};
  }
 
  template<typename... T> friend class pqxx::internal::result_iter;
  template<typename Tuple> void convert(Tuple &t, sl loc) const
  {
    extract_fields(
      t, std::make_index_sequence<std::tuple_size_v<Tuple>>{},
      conversion_context{home().get_encoding_group(), loc});
  }
 
  friend class pqxx::internal::gate::row_ref_row;
  template<typename Tuple, std::size_t... indexes>
  void extract_fields(Tuple &t, std::index_sequence<indexes...>, ctx c) const
  {
    (extract_value<Tuple, indexes>(t, c), ...);
  }
 
  template<typename Tuple, std::size_t index>
  void extract_value(Tuple &t, ctx) const;
 
  template<typename TUPLE, std::size_t... indexes>
  [[nodiscard]] auto get_tuple(std::index_sequence<indexes...>, sl) const
  {
    return std::make_tuple(get_field<TUPLE, indexes>()...);
  }
 
  template<typename TUPLE, std::size_t index>
  [[nodiscard]] auto get_field() const
  {
    return (*this)[index].as<std::tuple_element_t<index, TUPLE>>();
  }
 
  result const *m_result = nullptr;
 
 
  result::size_type m_index = -1;
};
} // namespace pqxx
 
 
#include "pqxx/internal/gates/row_ref-const_result_iterator.hxx"
#include "pqxx/internal/gates/row_ref-row.hxx"
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT row final
{
public:
  // TODO: Set iterator nested types using std::iterator_traits.
  using size_type = row_size_type;
  using difference_type = row_difference_type;
  using reference = field_ref;
  using pointer = const_row_iterator;
  using const_iterator = const_row_iterator;
  using iterator = const_iterator;
  using const_reverse_iterator = const_reverse_row_iterator;
  using reverse_iterator = const_reverse_iterator;
 
  row() noexcept = default;
  row(row &&) noexcept = default;
  row(row const &) noexcept = default;
  explicit row(row_ref const &ref) :
          m_result{ref.home()},
          m_index{ref.row_number()},
          m_end{std::size(ref)}
  {}
  ~row() = default;
  row &operator=(row const &) noexcept = default;
  row &operator=(row &&) noexcept = default;
 
  [[nodiscard]] PQXX_PURE bool operator==(row const &rhs) const noexcept
  {
    return rhs.m_result == m_result and rhs.m_index == m_index;
  }
  [[nodiscard]] PQXX_PURE bool operator!=(row const &rhs) const noexcept
  {
    return not operator==(rhs);
  }
 
  [[nodiscard]] PQXX_PURE const_iterator begin() const noexcept;
  [[nodiscard]] PQXX_PURE const_iterator cbegin() const noexcept;
  [[nodiscard]] PQXX_PURE const_iterator end() const noexcept;
  [[nodiscard]] PQXX_PURE const_iterator cend() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_row_iterator rbegin() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_row_iterator crbegin() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_row_iterator rend() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_row_iterator crend() const noexcept;
 
  [[nodiscard]] field_ref front() const noexcept;
  [[nodiscard]] field_ref back() const noexcept;
 
  [[nodiscard]] PQXX_PURE field_ref operator[](size_type) const noexcept;
 
#if defined(PQXX_HAVE_MULTIDIM)
  [[nodiscard]] PQXX_PURE field_ref operator[](zview col_name, sl loc) const
  {
    // TODO: There's a proposal to permit a default value for loc.
    // Visual Studio 2022 says it has multi-dimensional indexing, but issues a
    // bogus warning that this comma is a sequence operator and the first value
    // is meaningless.  If that were true, well, row_ref has no operator[] that
    // takes just a source_location anyway so the call would have failed.
    // Clearly the warning is a lie.
#  if defined(_MSC_VER)
#    pragma warning(push)
#    pragma warning(disable : 4548)
#  endif
    return as_row_ref()[col_name, loc];
#  if defined(_MSC_VER)
#    pragma warning(pop)
#  endif
  }
#endif
 
  [[nodiscard]] PQXX_PURE field_ref operator[](zview col_name) const
  {
    return as_row_ref()[col_name];
  }
 
  [[nodiscard]] field_ref at(size_type, sl = sl::current()) const;
 
  [[nodiscard]] field_ref at(zview col_name, sl = sl::current()) const;
 
  [[nodiscard]] PQXX_PURE constexpr size_type size() const noexcept
  {
    return m_end;
  }
 
  [[nodiscard, deprecated("Use row_number().")]] constexpr result::size_type
  rownumber() const noexcept
  {
    return m_index;
  }
 
  [[nodiscard]] PQXX_PURE constexpr result::size_type
  row_number() const noexcept
  {
    return m_index;
  }
 
  [[nodiscard]] size_type
  column_number(zview col_name, sl loc = sl::current()) const
  {
    return as_row_ref().column_number(col_name, loc);
  }
 
  [[nodiscard]] oid
  column_type(size_type col_num, sl loc = sl::current()) const
  {
    return as_row_ref().column_type(col_num, loc);
  }
 
  [[nodiscard]] oid column_type(zview col_name, sl loc = sl::current()) const
  {
    return column_type(column_number(col_name, loc), loc);
  }
 
  [[nodiscard]] oid
  column_table(size_type col_num, sl loc = sl::current()) const
  {
    return as_row_ref().column_table(col_num, loc);
  }
 
  [[nodiscard]] oid column_table(zview col_name, sl loc = sl::current()) const
  {
    return column_table(column_number(col_name, loc), loc);
  }
 
 
  [[nodiscard]] size_type
  table_column(size_type col, sl loc = sl::current()) const
  {
    return as_row_ref().table_column(col, loc);
  }
 
  [[nodiscard]] size_type
  table_column(zview col_name, sl loc = sl::current()) const
  {
    return as_row_ref().table_column(col_name, loc);
  }
 
  [[nodiscard]] PQXX_PURE constexpr result::size_type num() const noexcept
  {
    return row_number();
  }
 
 
  template<typename Tuple> void to(Tuple &t, sl loc = sl::current()) const
  {
    check_size(std::tuple_size_v<Tuple>, loc);
    convert(t, loc);
  }
 
 
  template<typename... TYPE>
  [[nodiscard]] std::tuple<TYPE...> as(sl loc = sl::current()) const
  {
    return as_row_ref().as<TYPE...>(loc);
  }
 
 
  template<typename TUPLE>
  [[nodiscard]] TUPLE as_tuple(sl loc = sl::current()) const
    requires(requires(TUPLE t) { std::get<0>(t); })
  {
    return as_row_ref().as_tuple<TUPLE>(loc);
  }
 
  [[deprecated("Swap iterators, not rows.")]] void swap(row &) noexcept;
 
private:
 
  [[nodiscard]] row_ref as_row_ref() const noexcept
  {
    return {m_result, row_number()};
  }
 
  row(result r, result_size_type index, size_type cols) noexcept;
 
  void check_size(size_type expected, sl loc) const
  {
    if (size() != expected)
      throw usage_error{
        std::format(
          "Tried to extract {} field(s) from a row of {}.", expected, size()),
        loc};
  }
 
  [[nodiscard]] result const &home() const { return m_result; }
 
  template<typename Tuple> void convert(Tuple &t, sl loc) const
  {
    auto ref{as_row_ref()};
    pqxx::internal::gate::row_ref_row{ref}.extract_fields(
      t, std::make_index_sequence<std::tuple_size_v<Tuple>>{},
      conversion_context{home().get_encoding_group(), loc});
  }
 
  // TODO: Define gate.
  friend class field;
 
  result m_result;
 
 
  result::size_type m_index = 0;
 
  size_type m_end = 0;
};
 
 
 
class PQXX_LIBEXPORT const_row_iterator
{
public:
  using iterator_category = std::random_access_iterator_tag;
  using value_type = field_ref const;
  using pointer = field_ref const *;
  using size_type = row_size_type;
  using difference_type = row_difference_type;
  using reference = field_ref;
 
  const_row_iterator() noexcept = default;
  const_row_iterator(row_ref const &t, row_size_type c) noexcept :
          m_field{t.home(), t.row_number(), c}
  {}
  explicit const_row_iterator(field_ref const &f) noexcept : m_field{f} {}
  const_row_iterator(const_row_iterator const &) noexcept = default;
  const_row_iterator(const_row_iterator &&) noexcept = default;
  ~const_row_iterator() = default;
 
  PQXX_PURE [[nodiscard]] size_type col() const noexcept
  {
    return m_field.column_number();
  }
 
  [[nodiscard]] PQXX_PURE PQXX_RETURNS_NONNULL constexpr pointer
  operator->() const noexcept
  {
    return &m_field;
  }
  [[nodiscard]] PQXX_PURE reference operator*() const noexcept
  {
    return m_field;
  }
 
  const_row_iterator &operator=(const_row_iterator const &) noexcept = default;
  const_row_iterator &operator=(const_row_iterator &&) noexcept = default;
 
  const_row_iterator operator++(int) & noexcept;
  const_row_iterator &operator++() noexcept
  {
    pqxx::internal::gate::field_ref_const_row_iterator(m_field).offset(1);
    return *this;
  }
  const_row_iterator operator--(int) & noexcept;
  const_row_iterator &operator--() noexcept
  {
    pqxx::internal::gate::field_ref_const_row_iterator(m_field).offset(-1);
    return *this;
  }
 
  const_row_iterator &operator+=(difference_type n) noexcept
  {
    pqxx::internal::gate::field_ref_const_row_iterator(m_field).offset(n);
    return *this;
  }
  const_row_iterator &operator-=(difference_type n) noexcept
  {
    pqxx::internal::gate::field_ref_const_row_iterator(m_field).offset(-n);
    return *this;
  }
 
  [[nodiscard]] bool operator==(const_row_iterator const &i) const noexcept
  {
    return col() == i.col();
  }
  [[nodiscard]] bool operator!=(const_row_iterator const &i) const noexcept
  {
    return col() != i.col();
  }
  [[nodiscard]] bool operator<(const_row_iterator const &i) const noexcept
  {
    return col() < i.col();
  }
  [[nodiscard]] bool operator<=(const_row_iterator const &i) const noexcept
  {
    return col() <= i.col();
  }
  [[nodiscard]] bool operator>(const_row_iterator const &i) const noexcept
  {
    return col() > i.col();
  }
  [[nodiscard]] bool operator>=(const_row_iterator const &i) const noexcept
  {
    return col() >= i.col();
  }
 
  [[nodiscard]] inline const_row_iterator
  operator+(difference_type) const noexcept;
 
  friend const_row_iterator
  operator+(difference_type, const_row_iterator const &) noexcept;
 
  [[nodiscard]] inline const_row_iterator
  operator-(difference_type) const noexcept;
  [[nodiscard]] inline difference_type
  operator-(const_row_iterator const &) const noexcept;
 
  [[nodiscard]] inline field_ref
  operator[](difference_type offset) const noexcept
  {
    return *(*this + offset);
  }
 
private:
  field_ref m_field;
};
 
 
class PQXX_LIBEXPORT const_reverse_row_iterator final
        : private const_row_iterator
{
public:
  using super = const_row_iterator;
  using iterator_type = const_row_iterator;
  using iterator_type::difference_type;
  using iterator_type::iterator_category;
  using iterator_type::pointer;
  using value_type = iterator_type::value_type;
  using reference = iterator_type::reference;
 
  const_reverse_row_iterator() noexcept = default;
  const_reverse_row_iterator(const_reverse_row_iterator const &) noexcept =
    default;
  const_reverse_row_iterator(const_reverse_row_iterator &&) noexcept = default;
 
  explicit const_reverse_row_iterator(super const &rhs) noexcept :
          const_row_iterator{rhs}
  {
    super::operator--();
  }
  ~const_reverse_row_iterator() = default;
 
  [[nodiscard]] PQXX_PURE iterator_type base() const noexcept;
 
  using iterator_type::operator->;
  using iterator_type::operator*;
 
  const_reverse_row_iterator &
  operator=(const_reverse_row_iterator const &r) noexcept = default;
  const_reverse_row_iterator &
  operator=(const_reverse_row_iterator &&r) noexcept = default;
  const_reverse_row_iterator operator++() noexcept
  {
    iterator_type::operator--();
    return *this;
  }
  const_reverse_row_iterator operator++(int) & noexcept;
  const_reverse_row_iterator &operator--() noexcept
  {
    iterator_type::operator++();
    return *this;
  }
  const_reverse_row_iterator operator--(int) &;
  const_reverse_row_iterator &operator+=(difference_type i) noexcept
  {
    iterator_type::operator-=(i);
    return *this;
  }
  const_reverse_row_iterator &operator-=(difference_type i) noexcept
  {
    iterator_type::operator+=(i);
    return *this;
  }
 
  [[nodiscard]] const_reverse_row_iterator
  operator+(difference_type i) const noexcept
  {
    return const_reverse_row_iterator{base() - i};
  }
  [[nodiscard]] const_reverse_row_iterator
  operator-(difference_type i) noexcept
  {
    return const_reverse_row_iterator{base() + i};
  }
  [[nodiscard]] difference_type
  operator-(const_reverse_row_iterator const &rhs) const noexcept
  {
    return rhs.const_row_iterator::operator-(*this);
  }
  [[nodiscard]] inline field_ref
  operator[](difference_type offset) const noexcept
  {
    return *(*this + offset);
  }
 
  [[nodiscard]] bool
  operator==(const_reverse_row_iterator const &rhs) const noexcept
  {
    return iterator_type::operator==(rhs);
  }
  [[nodiscard]] bool
  operator!=(const_reverse_row_iterator const &rhs) const noexcept
  {
    return !operator==(rhs);
  }
 
  [[nodiscard]] bool
  operator<(const_reverse_row_iterator const &rhs) const noexcept
  {
    return iterator_type::operator>(rhs);
  }
  [[nodiscard]] bool
  operator<=(const_reverse_row_iterator const &rhs) const noexcept
  {
    return iterator_type::operator>=(rhs);
  }
  [[nodiscard]] bool
  operator>(const_reverse_row_iterator const &rhs) const noexcept
  {
    return iterator_type::operator<(rhs);
  }
  [[nodiscard]] bool
  operator>=(const_reverse_row_iterator const &rhs) const noexcept
  {
    return iterator_type::operator<=(rhs);
  }
};
 
 
const_row_iterator
const_row_iterator::operator+(difference_type o) const noexcept
{
  return {
    {m_field.home(), m_field.row_number()},
    static_cast<row_size_type>(
      static_cast<difference_type>(m_field.column_number()) + o)};
}
 
inline const_row_iterator operator+(
  const_row_iterator::difference_type o, const_row_iterator const &i) noexcept
{
  return i + o;
}
 
inline const_row_iterator
const_row_iterator::operator-(difference_type o) const noexcept
{
  return {
    {m_field.home(), m_field.row_number()},
    static_cast<row_size_type>(
      static_cast<difference_type>(m_field.column_number()) - o)};
}
 
inline const_row_iterator::difference_type
const_row_iterator::operator-(const_row_iterator const &i) const noexcept
{
  return difference_type(m_field.column_number() - i.m_field.column_number());
}
 
 
template<typename Tuple, std::size_t index>
inline void row_ref::extract_value(Tuple &t, ctx c) const
{
  using field_type = std::remove_cvref_t<decltype(std::get<index>(t))>;
  field_ref const f{*m_result, m_index, index};
  std::get<index>(t) = from_string<field_type>(f, c);
}
 
 
inline row_ref::const_iterator row_ref::cbegin() const noexcept
{
  return {{home(), row_number()}, 0};
}
 
inline row_ref::const_iterator row_ref::begin() const noexcept
{
  return cbegin();
}
 
inline row_ref::const_iterator row_ref::cend() const noexcept
{
  return {{home(), row_number()}, home().columns()};
}
 
inline row_ref::const_iterator row_ref::end() const noexcept
{
  return cend();
}
 
inline row_ref::const_reverse_iterator row_ref::crbegin() const noexcept
{
  return const_reverse_iterator{end()};
}
 
inline row_ref::const_reverse_iterator row_ref::rbegin() const noexcept
{
  return crbegin();
}
 
inline row_ref::const_reverse_iterator row_ref::crend() const noexcept
{
  return const_reverse_iterator{begin()};
}
 
inline row_ref::const_reverse_iterator row_ref::rend() const noexcept
{
  return crend();
}
 
inline field_ref row_ref::front() const noexcept
{
  return {home(), row_number(), 0};
}
 
inline field_ref row_ref::back() const noexcept
{
  return {home(), row_number(), home().columns() - 1};
}
 
inline row_size_type row_ref::column_number(zview col_name, sl loc) const
{
  return home().column_number(col_name, loc);
}
 
inline oid row_ref::column_table(row_size_type col_num, sl loc) const
{
  return home().column_table(col_num, loc);
}
 
inline row::const_iterator row::cbegin() const noexcept
{
  return as_row_ref().cbegin();
}
 
inline row::const_iterator row::begin() const noexcept
{
  return cbegin();
}
 
inline row::const_iterator row::cend() const noexcept
{
  return {{m_result, row_number()}, m_end};
}
 
inline row::const_iterator row::end() const noexcept
{
  return cend();
}
 
inline row::const_reverse_iterator row::crbegin() const noexcept
{
  return const_reverse_iterator{end()};
}
 
inline row::const_reverse_iterator row::rbegin() const noexcept
{
  return crbegin();
}
 
inline row::const_reverse_iterator row::crend() const noexcept
{
  return const_reverse_iterator{begin()};
}
 
inline row::const_reverse_iterator row::rend() const noexcept
{
  return crend();
}
} // namespace pqxx
#endif