pqxx::cursor_base Class Reference

Common definitions for cursor types. More...

#include <cursor.hxx>

Inheritance diagram for pqxx::cursor_base:

Public Types

enum  accesspolicy { forward_only, random_access }
 Cursor access-pattern policy. More...
enum  updatepolicy { read_only, update }
 Cursor update policy. More...
enum  ownershippolicy { owned, loose }
 Cursor destruction policy. More...
using size_type = result_size_type
using difference_type = result_difference_type

Public Member Functions

 cursor_base ()=delete
 cursor_base (const cursor_base &)=delete
cursor_baseoperator= (const cursor_base &)=delete
const std::string & name () const noexcept
 Name of underlying SQL cursor. More...

Static Public Member Functions

Special movement distances.
static difference_type all () noexcept
 Special value: read until end. More...
static difference_type next () noexcept
 Special value: read one row only. More...
static difference_type prior () noexcept
 Special value: read backwards, one row only. More...
static difference_type backward_all () noexcept
 Special value: read backwards from current position back to origin. More...

Protected Member Functions

 cursor_base (connection_base &, const std::string &Name, bool embellish_name=true)

Protected Attributes

const std::string m_name

Detailed Description

Common definitions for cursor types.

In C++ terms, fetches are always done in pre-increment or pre-decrement fashion–i.e. the result does not include the row the cursor is on at the beginning of the fetch, and the cursor ends up being positioned on the last row in the result.

There are singular positions akin to end() at both the beginning and the end of the cursor's range of movement, although these fit in so naturally with the semantics that one rarely notices them. The cursor begins at the first of these, but any fetch in the forward direction will move the cursor off this position and onto the first row before returning anything.

Member Typedef Documentation

◆ difference_type

◆ size_type

Member Enumeration Documentation

◆ accesspolicy

Cursor access-pattern policy.

Allowing a cursor to move forward only can result in better performance, so use this access policy whenever possible.


Cursor can move forward only.


Cursor can move back and forth.

◆ ownershippolicy

Cursor destruction policy.

The normal thing to do is to make a cursor object the owner of the SQL cursor it represents. There may be cases, however, where a cursor needs to persist beyond the end of the current transaction (and thus also beyond the lifetime of the cursor object that created it!), where it can be "adopted" into a new cursor object. See the basic_cursor documentation for an explanation of cursor adoption.

If a cursor is created with "loose" ownership policy, the object representing the underlying SQL cursor will not take the latter with it when its own lifetime ends, nor will its originating transaction.

Use this feature with care and moderation. Only one cursor object should be responsible for any one underlying SQL cursor at any given time.
Don't "leak" cursors! As long as any "loose" cursor exists, any attempts to deactivate or reactivate the connection, implicitly or explicitly, are quietly ignored.

Destroy SQL cursor when cursor object is closed at end of transaction.


Leave SQL cursor in existence after close of object and transaction.

◆ updatepolicy

Cursor update policy.

Not all PostgreSQL versions support updatable cursors.

Cursor can be used to read data but not to write.


Cursor can be used to update data as well as read it.

Constructor & Destructor Documentation

◆ cursor_base() [1/3]

pqxx::cursor_base::cursor_base ( )

◆ cursor_base() [2/3]

pqxx::cursor_base::cursor_base ( const cursor_base )

◆ cursor_base() [3/3]

pqxx::cursor_base::cursor_base ( connection_base context,
const std::string &  Name,
bool  embellish_name = true 

Member Function Documentation

◆ all()

pqxx::cursor_base::difference_type pqxx::cursor_base::all ( )

Special value: read until end.

Maximum value for result::difference_type, so the cursor will attempt to read the largest possible result set.

Referenced by pqxx::internal::sql_cursor::close(), and pqxx::internal::obtain_stateless_cursor_size().

◆ backward_all()

pqxx::cursor_base::difference_type cursor_base::backward_all ( )

Special value: read backwards from current position back to origin.

Minimum value for result::difference_type.

Referenced by pqxx::internal::sql_cursor::close(), and pqxx::stateless_cursor< up, op >::stateless_cursor().

◆ name()

const std::string& pqxx::cursor_base::name ( ) const

Name of underlying SQL cursor.

Name of SQL cursor, which may differ from original given name.
Don't use this to access the SQL cursor directly without going through the provided wrapper classes!

Referenced by pqxx::internal::sql_cursor::close(), and pqxx::internal::sql_cursor::sql_cursor().

◆ next()

static difference_type pqxx::cursor_base::next ( )

Special value: read one row only.

Unsurprisingly, 1.

◆ operator=()

cursor_base& pqxx::cursor_base::operator= ( const cursor_base )

◆ prior()

static difference_type pqxx::cursor_base::prior ( )

Special value: read backwards, one row only.

Unsurprisingly, -1.

Member Data Documentation

◆ m_name

const std::string pqxx::cursor_base::m_name

The documentation for this class was generated from the following files: