pqxx::cursor_base Class Reference

Common definitions for cursor types. More...

`#include <cursor.hxx>`

## Public Types

enum | access_policy { forward_only , random_access }
| Cursor access-pattern policy. More...
enum | update_policy { read_only , update }
| Cursor update policy. More...
enum | ownership_policy { 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 (cursor_base const &)=delete
cursor_base & | operator= (cursor_base const &)=delete

## Special movement distances.

std::string const | m_name
constexpr std::string const & | name () const noexcept
| Name of underlying SQL cursor.
static constexpr difference_type | all () noexcept
| Special value: read until end.
static constexpr difference_type | next () noexcept
| Special value: read one row only.
static constexpr difference_type | prior () noexcept
| Special value: read backwards, one row only.
static constexpr difference_type | backward_all () noexcept
| Special value: read backwards from current position back to origin.
| cursor_base (connection &, std::string_view Name, bool embellish_name=true)

## 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

using pqxx::cursor_base::difference_type = result_difference_type

## size_type

using pqxx::cursor_base::size_type = result_size_type

## Member Enumeration Documentation

## access_policy

enum pqxx::cursor_base::access_policy

Cursor access-pattern policy.

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

Enumerator
forward_only | Cursor can move forward only.
random_access | Cursor can move back and forth.

## ownership_policy

enum pqxx::cursor_base::ownership_policy

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.

Warning
  Use this feature with care and moderation. Only one cursor object should be responsible for any one underlying SQL cursor at any given time.

Enumerator
owned | Destroy SQL cursor when cursor object is closed at end of transaction.
loose | Leave SQL cursor in existence after close of object and transaction.

## update_policy

enum pqxx::cursor_base::update_policy

Cursor update policy.

Warning
  Not all PostgreSQL versions support updatable cursors.

Enumerator
read_only | Cursor can be used to read data but not to write.
update | Cursor can be used to update data as well as read it.

## Constructor & Destructor Documentation

## cursor_base() [1/3]

pqxx::cursor_base::cursor_base | ( |  | ) |

delete

## cursor_base() [2/3]

pqxx::cursor_base::cursor_base | ( | cursor_base const & |  | ) |

delete

## cursor_base() [3/3]

pqxx::cursor_base::cursor_base | ( | connection & | context,
|  | std::string_view | Name,
|  | bool | embellish_name = `true`
| ) |  |

protected

Implementation of libpqxx STL-style cursor classes.

These classes wrap SQL cursors in STL-like interfaces.

Copyright (c) 2000-2023, 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.

## Member Function Documentation

## all()

static constexpr difference_type pqxx::cursor_base::all | ( |  | ) |

static constexpr noexcept

Special value: read until end.

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

## backward_all()

static constexpr difference_type pqxx::cursor_base::backward_all | ( |  | ) |

static constexpr noexcept

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

Returns
  Minimum value for result::difference_type.

Referenced by pqxx::stateless_cursor< up, op >::stateless_cursor().

## name()

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

constexpr noexcept

Name of underlying SQL cursor.

Returns
  Name of SQL cursor, which may differ from original given name.

Warning
  Don't use this to access the SQL cursor directly without going through the provided wrapper classes!

## next()

static constexpr difference_type pqxx::cursor_base::next | ( |  | ) |

static constexpr noexcept

Special value: read one row only.

Returns
  Unsurprisingly, 1.

## operator=()

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

delete

## prior()

static constexpr difference_type pqxx::cursor_base::prior | ( |  | ) |

static constexpr noexcept

Special value: read backwards, one row only.

Returns
  Unsurprisingly, -1.

## Member Data Documentation

## m_name

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

protected

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

- cursor.hxx
- cursor.cxx