result.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_RESULT_HXX
#define PQXX_RESULT_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <format>
#include <functional>
#include <ios>
#include <list>
#include <memory>
#include <stdexcept>
 
#include "pqxx/except.hxx"
#include "pqxx/types.hxx"
#include "pqxx/util.hxx"
#include "pqxx/zview.hxx"
 
#include "pqxx/internal/encodings.hxx"
 
 
namespace pqxx::internal
{
PQXX_LIBEXPORT void clear_result(pq::PGresult const *) noexcept;
} // namespace pqxx::internal
 
 
namespace pqxx::internal::gate
{
class result_connection;
class result_creation;
class result_field_ref;
class result_pipeline;
class result_row;
class result_sql_cursor;
} // namespace pqxx::internal::gate
 
 
namespace pqxx::internal
{
// 9.0: Remove this, just use the notice handler in connection/result.
struct notice_waiters final
{
  // NOLINTBEGIN(misc-non-private-member-variables-in-classes)
  std::function<void(zview)> notice_handler;
  std::list<errorhandler *> errorhandlers;
  // NOLINTEND(misc-non-private-member-variables-in-classes)
 
  notice_waiters() = default;
  notice_waiters(notice_waiters const &) = delete;
  notice_waiters(notice_waiters &&) = delete;
  ~notice_waiters() = default;
  notice_waiters &operator=(notice_waiters const &) = delete;
  notice_waiters &operator=(notice_waiters &&) = delete;
};
} // namespace pqxx::internal
 
 
namespace pqxx
{
class row_ref;
class field_ref;
 
 
 
class PQXX_LIBEXPORT result final
{
public:
  using size_type = result_size_type;
  using difference_type = result_difference_type;
  using reference = row_ref;
  using const_iterator = const_result_iterator;
  using pointer = const_iterator;
  using iterator = const_iterator;
  using const_reverse_iterator = const_reverse_result_iterator;
  using reverse_iterator = const_reverse_iterator;
 
  result() noexcept = default;
  result(result const &rhs) noexcept = default;
  result(result &&rhs) noexcept = default;
  ~result() = default;
 
 
  result &operator=(result const &rhs) noexcept = default;
 
  result &operator=(result &&rhs) noexcept = default;
 
  [[nodiscard]] bool operator==(result const &rhs) const noexcept
  {
    return rhs.m_data == m_data;
  }
  [[nodiscard]] bool operator!=(result const &rhs) const noexcept
  {
    return not operator==(rhs);
  }
 
 
  template<typename... TYPE> auto iter() const;
 
  [[nodiscard]] PQXX_PURE const_reverse_iterator rbegin() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_iterator crbegin() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_iterator rend() const noexcept;
  [[nodiscard]] PQXX_PURE const_reverse_iterator crend() const noexcept;
 
  [[nodiscard]] PQXX_PURE const_iterator begin() const noexcept;
  [[nodiscard]] PQXX_PURE const_iterator cbegin() const noexcept;
  [[nodiscard]] PQXX_PURE inline const_iterator end() const noexcept;
  [[nodiscard]] PQXX_PURE inline const_iterator cend() const noexcept;
 
  [[nodiscard]] PQXX_PURE row_ref front() const noexcept;
  [[nodiscard]] PQXX_PURE row_ref back() const noexcept;
 
  [[nodiscard]] PQXX_PURE size_type size() const noexcept;
  [[nodiscard]] PQXX_PURE bool empty() const noexcept;
  [[nodiscard]] PQXX_PURE size_type capacity() const noexcept
  {
    return size();
  }
 
 
  void swap(result &) noexcept;
 
 
  [[nodiscard]] PQXX_PURE row_ref operator[](size_type i) const noexcept;
 
#if defined(PQXX_HAVE_MULTIDIM)
  [[nodiscard]] PQXX_PURE field_ref
  operator[](size_type row_num, row_size_type col_num) const noexcept;
#endif // PQXX_HAVE_MULTIDIM
 
  [[nodiscard]] row_ref at(size_type, sl = sl::current()) const;
 
  [[nodiscard]] field_ref
    at(size_type, row_size_type, sl = sl::current()) const;
 
 
  void clear() noexcept
  {
    m_data.reset();
    m_query = nullptr;
  }
 
  [[nodiscard]] PQXX_PURE row_size_type columns() const noexcept;
 
 
  [[nodiscard]] row_size_type
  column_number(zview name, sl = sl::current()) const;
 
  [[nodiscard]] PQXX_RETURNS_NONNULL char const *
  column_name(row_size_type number, sl = sl::current()) const &;
 
 
  [[nodiscard]] int
  column_storage(row_size_type number, sl = sl::current()) const;
 
 
  [[nodiscard]] int column_type_modifier(row_size_type number) const noexcept;
 
  [[nodiscard]] oid
  column_type(row_size_type col_num, sl = sl::current()) const;
 
 
  [[nodiscard]] oid column_type(zview col_name, sl loc = sl::current()) const
  {
    return column_type(column_number(col_name, loc));
  }
 
  [[nodiscard]] oid
  column_table(row_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]] row_size_type
  table_column(row_size_type col_num, sl = sl::current()) const;
 
 
  [[nodiscard]] row_size_type
  table_column(zview col_name, sl loc = sl::current()) const
  {
    return table_column(column_number(col_name), loc);
  }
 
  [[nodiscard]] PQXX_PURE std::string const &query() const & noexcept;
 
 
  [[nodiscard]] PQXX_PURE oid inserted_oid(sl = sl::current()) const;
 
 
  [[nodiscard]] PQXX_PURE size_type affected_rows() const;
 
 
  template<typename CALLABLE>
  inline void for_each(CALLABLE &&func, sl = sl::current()) const;
 
  // NOLINTBEGIN(modernize-use-nodiscard)
 
 
  result const &expect_rows(size_type n, sl loc = sl::current()) const
  {
    auto const sz{size()};
    if (sz != n)
    {
      // TODO: See whether result contains a generated statement.
      if (not m_query or m_query->empty())
        throw unexpected_rows{
          std::format("Expected {} row(s) from query, got {}.", n, sz), loc};
      else
        throw unexpected_rows{
          std::format(
            "Expected {} row(s) from query '{}', got {}.", n, *m_query, sz),
          loc};
    }
    return *this;
  }
 
 
  row one_row(sl = sl::current()) const;
 
 
  row_ref one_row_ref(sl = sl::current()) const;
 
 
  std::optional<row> opt_row(sl = sl::current()) const;
 
 
  std::optional<row_ref> opt_row_ref(sl = sl::current()) const;
 
  result const &no_rows(sl loc = sl::current()) const
  {
    expect_rows(0, loc);
    return *this;
  }
 
 
  result const &
  expect_columns(row_size_type cols, sl loc = sl::current()) const
  {
    auto const actual{columns()};
    if (actual != cols)
    {
      // TODO: See whether result contains a generated statement.
      if (not m_query or m_query->empty())
        throw usage_error{
          std::format(
            "Expected {} column(s) from query, got {}.", cols, actual),
          loc};
      else
        throw usage_error{
          std::format(
            "Expected {} column(s) from query '{}', got {}.", cols, *m_query,
            actual),
          loc};
    }
    return *this;
  }
 
 
  field one_field(sl = sl::current()) const;
 
 
  field_ref one_field_ref(sl = sl::current()) const;
 
  // NOLINTEND(modernize-use-nodiscard)
 
  [[nodiscard]] encoding_group get_encoding_group() const noexcept
  {
    return m_encoding;
  }
 
private:
  using data_pointer = std::shared_ptr<internal::pq::PGresult const>;
 
  void check_one_row(sl loc) const
  {
    auto const sz{size()};
    if (sz != 1)
    {
      if (not m_query or m_query->empty())
        throw unexpected_rows{
          std::format("Expected 1 row from query, got {}.", sz), loc};
      else
        throw unexpected_rows{
          std::format("Expected 1 row from query '{}', got {}.", *m_query, sz),
          loc};
    }
  }
 
  data_pointer m_data;
 
  friend class pqxx::internal::gate::result_pipeline;
  PQXX_PURE [[nodiscard]] std::shared_ptr<std::string const>
  query_ptr() const noexcept
  {
    return m_query;
  }
 
  // TODO: Could we colocate some members in a single struct?
  std::shared_ptr<std::string const> m_query;
 
 
  std::shared_ptr<pqxx::internal::notice_waiters> m_notice_waiters;
 
  encoding_group m_encoding = encoding_group::unknown;
 
  static std::string const s_empty_string;
 
  friend class pqxx::internal::gate::result_field_ref;
  PQXX_PURE PQXX_RETURNS_NONNULL [[nodiscard]] char const *
  get_value(size_type row, row_size_type col) const noexcept;
  PQXX_PURE [[nodiscard]] bool
  get_is_null(size_type row, row_size_type col) const noexcept;
  PQXX_PURE [[nodiscard]] field_size_type
    get_length(size_type, row_size_type) const noexcept;
 
  friend class pqxx::internal::gate::result_creation;
  result(
    std::shared_ptr<internal::pq::PGresult> const &rhs,
    std::shared_ptr<std::string> const &query,
    std::shared_ptr<pqxx::internal::notice_waiters> const &waiters,
    encoding_group enc);
 
  PQXX_PRIVATE void check_status(std::string_view desc, sl loc) const;
 
  friend class pqxx::internal::gate::result_connection;
  friend class pqxx::internal::gate::result_row;
  bool operator!() const noexcept { return m_data.get() == nullptr; }
  // NOLINTNEXTLINE(google-explicit-constructor,hicpp-explicit-conversions)
  operator bool() const noexcept { return m_data.get() != nullptr; }
 
  [[noreturn]] PQXX_COLD PQXX_PRIVATE void
  throw_sql_error(std::string const &Err, std::string const &Query, sl) const;
  PQXX_PURE PQXX_PRIVATE [[nodiscard]] int errorposition() const;
  PQXX_PRIVATE [[nodiscard]] std::string status_error(sl) const;
 
  friend class pqxx::internal::gate::result_sql_cursor;
  PQXX_PURE [[nodiscard]] char const *cmd_status() const noexcept;
};
} // namespace pqxx
#endif