cursor.hxx

Go to the documentation of this file.

/* Definition of the iterator/container-style cursor classes.
 *
 * C++-style wrappers for SQL cursors.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/cursor 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_CURSOR_HXX
#define PQXX_CURSOR_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <limits>
#include <stdexcept>
 
#include "pqxx/result.hxx"
#include "pqxx/transaction_base.hxx"
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT cursor_base
{
public:
  using size_type = result_size_type;
  using difference_type = result_difference_type;
 
 
  enum access_policy
  {
    forward_only,
    random_access
  };
 
 
  enum update_policy
  {
    read_only,
    update
  };
 
 
  enum ownership_policy
  {
    owned,
    loose
  };
 
  cursor_base() = delete;
  cursor_base(cursor_base const &) = delete;
  cursor_base(cursor_base &&) = delete;
 
  // Really weird: gcc complains that this accesses deprecated m_name.
#include "pqxx/internal/ignore-deprecated-pre.hxx"
  ~cursor_base() = default;
#include "pqxx/internal/ignore-deprecated-post.hxx"
 
  cursor_base &operator=(cursor_base const &) = delete;
  cursor_base &operator=(cursor_base &&) = delete;
 
 
 
  [[nodiscard]] static constexpr difference_type all() noexcept
  {
    return (std::numeric_limits<int>::max)() - 1;
  }
 
 
  [[nodiscard]] static constexpr difference_type next() noexcept { return 1; }
 
 
  [[nodiscard]] static constexpr difference_type prior() noexcept
  {
    return -1;
  }
 
 
  [[nodiscard]] static constexpr difference_type backward_all() noexcept
  {
    return (std::numeric_limits<int>::min)() + 1;
  }
 
 
 
  [[nodiscard]] constexpr std::string const &name() const noexcept
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    return m_name;
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
 
protected:
  cursor_base(
    connection &, std::string_view Name, bool embellish_name = true,
    sl loc = sl::current());
 
  [[nodiscard]] sl created_loc() const
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    return m_created_loc;
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
 
  // NOLINTBEGIN(
  //    cppcoreguidelines-non-private-member-variables-in-classes,
  //    misc-non-private-member-variables-in-classes
  // )
 
  [[deprecated(
    "This will become private.  Use name() instead.")]] std::string const
    m_name;
 
  [[deprecated("This will become private.  Use created_loc() instead.")]] sl
    m_created_loc;
 
  // NOLINTEND(
  //    cppcoreguidelines-non-private-member-variables-in-classes,
  //    misc-non-private-member-variables-in-classes
  // )
};
} // namespace pqxx
 
 
#include <pqxx/internal/sql_cursor.hxx>
 
 
namespace pqxx
{
 
template<cursor_base::update_policy up, cursor_base::ownership_policy op>
class stateless_cursor final
{
public:
  using size_type = result_size_type;
  using difference_type = result_difference_type;
 
 
  stateless_cursor(
    transaction_base &tx, std::string_view query, std::string_view cname,
    bool hold, sl loc = sl::current()) :
          m_cur{tx, query, cname, cursor_base::random_access,
                up, op,    hold,  loc}
  {}
 
 
  stateless_cursor(
    transaction_base &tx, std::string_view adopted_cursor,
    sl loc = sl::current()) :
          m_cur{tx, adopted_cursor, op}
  {
    // Put cursor in known position
    m_cur.move(cursor_base::backward_all(), loc);
  }
 
  stateless_cursor(stateless_cursor &&) = default;
  stateless_cursor(stateless_cursor const &) = delete;
  ~stateless_cursor() = default;
 
  stateless_cursor &operator=(stateless_cursor &&) = default;
  stateless_cursor &operator=(stateless_cursor const &) = delete;
 
 
  void close(sl loc = sl::current()) { m_cur.close(loc); }
 
 
  [[nodiscard]] size_type size(sl loc = sl::current())
  {
    return internal::obtain_stateless_cursor_size(m_cur, loc);
  }
 
 
  result retrieve(
    difference_type begin_pos, difference_type end_pos, sl loc = sl::current())
  {
    return internal::stateless_cursor_retrieve(
      m_cur, result::difference_type(size()), begin_pos, end_pos, loc);
  }
 
  [[nodiscard]] constexpr std::string const &name() const noexcept
  {
    return m_cur.name();
  }
 
private:
  internal::sql_cursor m_cur;
};
 
 
class icursor_iterator;
} // namespace pqxx
 
 
namespace pqxx::internal::gate
{
class icursor_iterator_icursorstream;
class icursorstream_icursor_iterator;
} // namespace pqxx::internal::gate
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT icursorstream final
{
public:
  using size_type = cursor_base::size_type;
  using difference_type = cursor_base::difference_type;
 
 
  icursorstream(
    transaction_base &context, std::string_view query,
    std::string_view basename, difference_type sstride = 1,
    sl = sl::current());
 
 
  icursorstream(
    transaction_base &context, field const &cname, difference_type sstride = 1,
    cursor_base::ownership_policy op = cursor_base::owned, sl = sl::current());
 
  // NOLINTBEGIN(google-explicit-constructor,hicpp-explicit-conversions)
 
  constexpr operator bool() const & noexcept { return not m_done; }
 
  // NOLINTEND(google-explicit-constructor,hicpp-explicit-conversions)
 
 
  icursorstream &get(result &res, sl loc = sl::current())
  {
    res = fetchblock(loc);
    return *this;
  }
 
  icursorstream &operator>>(result &res) { return get(res); }
 
 
  icursorstream &ignore(std::streamsize n = 1, sl = sl::current()) &;
 
 
  void set_stride(difference_type stride, sl = sl::current()) &;
  [[nodiscard]] constexpr difference_type stride() const noexcept
  {
    return m_stride;
  }
 
  [[nodiscard]] PQXX_PURE sl created_loc() const noexcept
  {
    return m_cur.created_loc();
  }
 
private:
  result fetchblock(sl);
 
  friend class internal::gate::icursorstream_icursor_iterator;
  size_type forward(size_type n = 1);
  void insert_iterator(icursor_iterator *) noexcept;
  void remove_iterator(icursor_iterator *) const noexcept;
 
  void service_iterators(difference_type, sl);
 
  internal::sql_cursor m_cur;
 
  mutable icursor_iterator *m_iterators = nullptr;
 
  difference_type m_stride;
  difference_type m_realpos, m_reqpos;
 
  bool m_done = false;
};
 
 
 
class PQXX_LIBEXPORT icursor_iterator final
{
public:
  using iterator_category = std::input_iterator_tag;
  using value_type = result;
  using pointer = result const *;
  using reference = result const &;
  using istream_type = icursorstream;
  using size_type = istream_type::size_type;
  using difference_type = istream_type::difference_type;
 
  icursor_iterator() noexcept;
  explicit icursor_iterator(istream_type &) noexcept;
  icursor_iterator(icursor_iterator const &) noexcept;
  icursor_iterator(icursor_iterator &&) = delete;
  ~icursor_iterator() noexcept;
 
  icursor_iterator &operator=(icursor_iterator &&) = delete;
 
  result const &operator*() const noexcept
  {
    refresh(created_loc());
    return m_here;
  }
  PQXX_RETURNS_NONNULL result const *operator->() const noexcept
  {
    refresh(created_loc());
    return &m_here;
  }
  icursor_iterator &operator++();
  icursor_iterator operator++(int) &;
  icursor_iterator &operator+=(difference_type);
  icursor_iterator &operator=(icursor_iterator const &) noexcept;
 
  [[nodiscard]] bool operator==(icursor_iterator const &rhs) const;
  [[nodiscard]] bool operator!=(icursor_iterator const &rhs) const noexcept
  {
    return not operator==(rhs);
  }
  [[nodiscard]] bool operator<(icursor_iterator const &rhs) const;
  [[nodiscard]] bool operator>(icursor_iterator const &rhs) const
  {
    return rhs < *this;
  }
  [[nodiscard]] bool operator<=(icursor_iterator const &rhs) const
  {
    return not(*this > rhs);
  }
  [[nodiscard]] bool operator>=(icursor_iterator const &rhs) const
  {
    return not(*this < rhs);
  }
 
private:
  void refresh(sl) const;
 
  friend class internal::gate::icursor_iterator_icursorstream;
  [[nodiscard]] difference_type pos() const noexcept { return m_pos; }
  void fill(result const &);
 
 
  [[nodiscard]] PQXX_PURE sl created_loc(sl loc = sl::current()) const noexcept
  {
    return (m_stream == nullptr) ? loc : m_stream->created_loc();
  }
 
  [[nodiscard]] sl
  best_location(icursor_iterator const &other, sl loc = sl::current()) const
  {
    if (m_stream != nullptr)
      return created_loc();
    else
      return other.created_loc(loc);
  }
 
  icursorstream *m_stream{nullptr};
  result m_here;
  difference_type m_pos;
 
  icursor_iterator *m_prev{nullptr}, *m_next{nullptr};
};
} // namespace pqxx
#endif