pqxx::internal::sql_cursor Class Reference

Cursor with SQL positioning semantics. More...

#include <cursor.hxx>

Inheritance diagram for pqxx::internal::sql_cursor:

Collaboration diagram for pqxx::internal::sql_cursor:

Public Types
enum	accesspolicy {   forward_only,   random_access }
	Cursor access-pattern policy. More...
typedef result::difference_type	difference_type
enum	ownershippolicy {   owned,   loose }
	Cursor destruction policy. More...
typedef result::size_type	size_type
enum	updatepolicy {   read_only,   update }
	Cursor update policy. More...

Public Member Functions
	sql_cursor (transaction_base &t, const PGSTD::string &query, const PGSTD::string &cname, cursor_base::accesspolicy ap, cursor_base::updatepolicy up, cursor_base::ownershippolicy op, bool hold)
	sql_cursor (transaction_base &t, const PGSTD::string &cname, cursor_base::ownershippolicy op)
	~sql_cursor () throw ()
void	close () throw ()
const result &	empty_result () const throw ()
	Return zero-row result for this cursor. More...
difference_type	endpos () const throw ()
	End position, or -1 for unknown. More...
result	fetch (difference_type rows, difference_type &displacement)
result	fetch (difference_type rows)
difference_type	move (difference_type rows, difference_type &displacement)
difference_type	move (difference_type rows)
const PGSTD::string &	name () const throw ()
	Name of underlying SQL cursor. More...
difference_type	pos () const throw ()
	Current position, or -1 for unknown. More...

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

Protected Attributes
const PGSTD::string	m_name

Private Member Functions
difference_type	adjust (difference_type hoped, difference_type actual)
void	init_empty_result (transaction_base &)
	Initialize cached empty result. Call only at beginning or end! More...

Static Private Member Functions
static PGSTD::string	stridestring (difference_type)

Private Attributes
bool	m_adopted
	Is this cursor adopted (as opposed to created by this cursor object)? More...
int	m_at_end
	At starting position (-1), somewhere in the middle (0), or past end (1) More...
result	m_cached_current_row
result	m_empty_result
	Zero-row result from this cursor (or plain empty one if cursor is adopted) More...
difference_type	m_endpos
	End position, or -1 for unknown. More...
connection_base &	m_home
	Connection this cursor lives in. More...
cursor_base::ownershippolicy	m_ownership
	Will this cursor object destroy its SQL cursor when it dies? More...
difference_type	m_pos
	Position, or -1 for unknown. More...

Detailed Description

Cursor with SQL positioning semantics.

Thin wrapper around an SQL cursor, with SQL's ideas of positioning.

SQL cursors have pre-increment/pre-decrement semantics, with on either end of the result set a special position that does not repesent a row. This class models SQL cursors for the purpose of implementing more C++-like semantics on top.

Positions of actual rows are numbered starting at 1. Position 0 exists but does not refer to a row. There is a similar non-row position at the end of the result set.

Don't use this at home. You deserve better. Use the stateles_cursor instead.

Member Typedef Documentation

typedef result::difference_type pqxx::cursor_base::difference_type

inherited

typedef result::size_type pqxx::cursor_base::size_type

inherited

Member Enumeration Documentation

enum pqxx::cursor_base::accesspolicy

inherited

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.

enum pqxx::cursor_base::ownershippolicy

inherited

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.

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.

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.

enum pqxx::cursor_base::updatepolicy

inherited

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

pqxx::internal::sql_cursor::sql_cursor	(	transaction_base &	t,
		const PGSTD::string &	query,
		const PGSTD::string &	cname,
		cursor_base::accesspolicy	ap,
		cursor_base::updatepolicy	up,
		cursor_base::ownershippolicy	op,
		bool	hold
	)

pqxx::internal::sql_cursor::sql_cursor	(	transaction_base &	t,
		const PGSTD::string &	cname,
		cursor_base::ownershippolicy	op
	)

pqxx::internal::sql_cursor::~sql_cursor ( ) throw ()

inline

Member Function Documentation

difference_type pqxx::internal::sql_cursor::adjust ( difference_type  hoped, difference_type  actual  )

private

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

inlinestaticinherited

Special value: read until end.

Returns

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

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

inlinestaticinherited

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().

Here is the caller graph for this function:

void pqxx::internal::sql_cursor::close

(

)

throw ()

const result& pqxx::internal::sql_cursor::empty_result ( ) const throw ()

inline

Return zero-row result for this cursor.

difference_type pqxx::internal::sql_cursor::endpos ( ) const throw ()

inline

End position, or -1 for unknown.

Returns the final position, just after the last row in the result set. The starting position, just before the first row, counts as position zero.

End position is unknown until it is encountered during use.

result pqxx::internal::sql_cursor::fetch	(	difference_type	rows,
		difference_type &	displacement
	)

result pqxx::internal::sql_cursor::fetch ( difference_type  rows )

inline

References fetch().

Referenced by fetch().

Here is the call graph for this function:

Here is the caller graph for this function:

void pqxx::internal::sql_cursor::init_empty_result ( transaction_base &  )

private

Initialize cached empty result. Call only at beginning or end!

difference_type pqxx::internal::sql_cursor::move	(	difference_type	rows,
		difference_type &	displacement
	)

difference_type pqxx::internal::sql_cursor::move ( difference_type  rows )

inline

References move().

Referenced by move().

Here is the call graph for this function:

Here is the caller graph for this function:

const PGSTD::string& pqxx::cursor_base::name ( ) const throw ()

inlineinherited

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!

static difference_type pqxx::cursor_base::next ( ) throw ()

inlinestaticinherited

Special value: read one row only.

Returns

Unsurprisingly, 1

difference_type pqxx::internal::sql_cursor::pos ( ) const throw ()

inline

Current position, or -1 for unknown.

The starting position, just before the first row, counts as position zero.

Position may be unknown if (and only if) this cursor was adopted, and has never hit its starting position (position zero).

static difference_type pqxx::cursor_base::prior ( ) throw ()

inlinestaticinherited

Special value: read backwards, one row only.

Returns

Unsurprisingly, -1

static PGSTD::string pqxx::internal::sql_cursor::stridestring ( difference_type  )

staticprivate

Member Data Documentation

bool pqxx::internal::sql_cursor::m_adopted

private

Is this cursor adopted (as opposed to created by this cursor object)?

int pqxx::internal::sql_cursor::m_at_end

private

At starting position (-1), somewhere in the middle (0), or past end (1)

result pqxx::internal::sql_cursor::m_cached_current_row

private

result pqxx::internal::sql_cursor::m_empty_result

private

Zero-row result from this cursor (or plain empty one if cursor is adopted)

difference_type pqxx::internal::sql_cursor::m_endpos

private

End position, or -1 for unknown.

connection_base& pqxx::internal::sql_cursor::m_home

private

Connection this cursor lives in.

const PGSTD::string pqxx::cursor_base::m_name

protectedinherited

cursor_base::ownershippolicy pqxx::internal::sql_cursor::m_ownership

private

Will this cursor object destroy its SQL cursor when it dies?

difference_type pqxx::internal::sql_cursor::m_pos

private

Position, or -1 for unknown.

---

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

• /usr/include/pqxx/cursor.hxx