pqxx::cursor_base Class Reference

Common definitions for cursor types. More...

#include <cursor.hxx>

Inheritance diagram for pqxx::cursor_base:

Inheritance graph
[legend]
List of all members.

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...
typedef result::size_type size_type
typedef result::difference_type difference_type

Public Member Functions

virtual ~cursor_base () throw ()
 operator void * () const
 Does it make sense to try reading from this cursor again?
bool operator! () const
 Is this cursor finished?
const PGSTD::string & name () const throw ()
 Name of underlying SQL cursor.
virtual result fetch (difference_type)=0
 Fetch up to given number of rows of data.
virtual result fetch (difference_type, difference_type &)=0
 Fetch result, but also return the number of rows of actual displacement.
virtual difference_type move (difference_type)=0
 Move cursor by given number of rows, returning number of data rows skipped.
virtual difference_type move (difference_type, difference_type &)=0
 Move cursor, but also return actual displacement in output parameter.
void close () throw ()

Static Public Member Functions

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

Protected Member Functions

 cursor_base (transaction_base *, const PGSTD::string &Name, bool embellish_name=true)
void declare (const PGSTD::string &query, accesspolicy, updatepolicy, ownershippolicy, bool hold)
void adopt (ownershippolicy)
template<accesspolicy A>
void check_displacement (difference_type) const

Static Protected Member Functions

static PGSTD::string stridestring (difference_type)

Protected Attributes

transaction_basem_context
bool m_done

Classes

struct  cachedquery

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

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

Reimplemented in pqxx::absolute_cursor< ACCESS, UPDATE >.

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

Reimplemented in pqxx::absolute_cursor< ACCESS, UPDATE >.


Member Enumeration Documentation

enum pqxx::cursor_base::accesspolicy

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::updatepolicy

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.

enum pqxx::cursor_base::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.

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.


Constructor & Destructor Documentation

virtual pqxx::cursor_base::~cursor_base (  )  throw () [virtual]

pqxx::cursor_base::cursor_base ( transaction_base ,
const PGSTD::string &  Name,
bool  embellish_name = true 
) [protected]


Member Function Documentation

pqxx::cursor_base::operator void * (  )  const

Does it make sense to try reading from this cursor again?

Returns:
Null pointer if finished, or some arbitrary non-null pointer otherwise.

bool pqxx::cursor_base::operator! (  )  const

Is this cursor finished?

The logical negation of the converstion-to-pointer operator.

Returns:
Whether the last attempt to read failed

cursor_base::difference_type pqxx::cursor_base::all (  )  throw () [static]

Special value: read until end.

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

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

Special value: read one row only.

Returns:
Unsurprisingly, 1

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

Special value: read backwards, one row only.

Returns:
Unsurprisingly, -1

cursor_base::difference_type pqxx::cursor_base::backward_all (  )  throw () [static]

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

Returns:
Minimum value for result::difference_type

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

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!

pqxx::result pqxx::cursor_base::fetch ( difference_type   )  [pure virtual]

Fetch up to given number of rows of data.

pqxx::result pqxx::cursor_base::fetch ( difference_type  ,
difference_type  
) [pure virtual]

Fetch result, but also return the number of rows of actual displacement.

The relationship between actual displacement and result size gets tricky at the edges of the cursor's range of movement. As an example, consider a fresh cursor that's been moved forward by 2 rows from its starting position; we can move it backwards from that position by 1 row and get a result set of 1 row, ending up on the first actual row of data. If instead we move it backwards by 2 or more rows, we end up back at the starting position--but the result is still only 1 row wide!

The output parameter compensates for this, returning true displacement (which is also signed, so it includes direction).

pqxx::cursor_base::difference_type pqxx::cursor_base::move ( difference_type   )  [pure virtual]

Move cursor by given number of rows, returning number of data rows skipped.

The number of data rows skipped is equal to the number of rows of data that would have been returned if this were a fetch instead of a move command.

Returns:
the number of data rows that would have been returned if this had been a fetch() command.

pqxx::cursor_base::difference_type pqxx::cursor_base::move ( difference_type  ,
difference_type  
) [pure virtual]

Move cursor, but also return actual displacement in output parameter.

As with the fetch functions, the actual displacement may differ from the number of data rows skipped by the move.

Returns:
the number of data rows that would have been returned if this had been a fetch() command.

void pqxx::cursor_base::close (  )  throw ()

void pqxx::cursor_base::declare ( const PGSTD::string &  query,
accesspolicy  ,
updatepolicy  ,
ownershippolicy  ,
bool  hold 
) [protected]

void pqxx::cursor_base::adopt ( ownershippolicy   )  [protected]

string pqxx::cursor_base::stridestring ( difference_type   )  [static, protected]

template<accesspolicy A>
void pqxx::cursor_base::check_displacement ( difference_type   )  const [protected]


Member Data Documentation

transaction_base* pqxx::cursor_base::m_context [protected]

bool pqxx::cursor_base::m_done [protected]


The documentation for this class was generated from the following files:
Generated on Thu Feb 1 17:12:31 2007 for libpqxx by  doxygen 1.5.1