Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

pqxx::Cursor Class Reference

SQL cursor class. More...

#include <cursor.h>

List of all members.

Public Types

typedef Result::size_type size_type
enum  pos { pos_unknown = -1, pos_start = 0 }

Public Member Functions

 Cursor (TransactionItf &T, const char Query[], const PGSTD::string &BaseName="cur", size_type Count=NEXT())
 Constructor. Creates a cursor.

 Cursor (TransactionItf &T, const Result::Field &Name, size_type Count=NEXT())
 Special-purpose constructor. Adopts existing SQL cursor. Use with care.

size_type SetCount (size_type)
 Set new stride, ie. the number of rows to fetch at a time.

Result Fetch (size_type Count)
 Fetch Count rows of data.

size_type Move (size_type Count)
 Move forward by Count rows (negative for backwards) through the data set.

void MoveTo (size_type)
Cursor & operator>> (Result &)
 Fetch rows.

 operator bool () const throw ()
 May there be more rows coming?

bool operator! () const throw ()
 Are we done?

Cursor & operator+= (size_type N)
 Move N rows forward.

Cursor & operator-= (size_type N)
 Move N rows backward.

size_type size () const throw ()
 Number of actual tuples, or pos_unknown if not currently known.

size_type Pos () const throw (unknown_position)
 Current cursor position.


Static Public Member Functions

size_type ALL () throw ()
 Constant: "next fetch/move should span as many rows as possible.".

size_type NEXT () throw ()
 Constant: "next fetch/move should cover just the next row.".

size_type PRIOR () throw ()
 Constant: "next fetch/move should go back one row.".

size_type BACKWARD_ALL () throw ()


Detailed Description

SQL cursor class.

Cursor behaves as an output stream generating Result objects. It may be used to fetch rows individually or in blocks, in which case each Result coming out of the stream may contain more than one Tuple. A cursor may be positioned on any row of data, or on an "imaginary" row before the first actual row, or on a similar imaginary row beyond the last one. This differs from standard C++ practice, where a container only has an imaginary element (called end()) beyond its last actual element.

When data is fetched, the cursor is moved before data is collected, so that afterwards the cursor will be positioned on the last row it returned. A freshly created cursor is positioned on the imaginary row (numbered 0) before its first * actual one (which is numbered 1). Thus, a simple Fetch(1) will then return the first actual row, i.e. row 1.

Postgres does not currently support modification of data through a cursor. Also, not all queries support cursors that go backwards. Unfortunately there is no documentation on which queries do and which queries don't so you may have to experiment before using cursors for anything but plain forward-only result set iteration.

A Cursor is only valid within the transaction in which it was created.


Member Typedef Documentation

typedef Result::size_type pqxx::Cursor::size_type
 


Member Enumeration Documentation

enum pqxx::Cursor::pos
 

Enumeration values:
pos_unknown 
pos_start 


Constructor & Destructor Documentation

pqxx::Cursor::Cursor TransactionItf   T,
const char    Query[],
const PGSTD::string &    BaseName = "cur",
size_type    Count = NEXT()
 

Constructor. Creates a cursor.

Parameters:
T is the transaction that this cursor lives in.
Query defines a data set that the cursor should traverse.
BaseName optional name for the cursor, must begin with a letter and contain letters and digits only.
Count the stride of the cursor, ie. the number of rows fetched at a time. This defaults to 1.

pqxx::Cursor::Cursor TransactionItf   T,
const Result::Field   Name,
size_type    Count = NEXT()
 

Special-purpose constructor. Adopts existing SQL cursor. Use with care.

Forms a Cursor object around an existing SQL cursor, as returned by e.g. a function. The SQL cursor will be destroyed by the Cursor destructor as if it had been created by the Cursor object. The cursor can only be used inside the transaction that created it.

Use this creation method only with great care. Read on for important caveats.

The Cursor object does not know the current position of the SQL cursor. For complicated technical reasons, this will cause trouble when the cursor reaches the end of the result set. Therefore, before you ever move the resulting Cursor forward, you should always move it backwards with a Move(Cursor::BACKWARD_ALL()). This will reset the internal position counter to the beginning of the result set.

Once the Cursor object is created, never try to access the underlying SQL cursor in any way. There is no way for libpqxx to check for this, and it could potentially undermine operation of the Cursor object in unexpected ways.

Passing the name of the cursor as a string is not allowed, both to avoid confusion with the constructor that creates its own SQL cursor, and to discourage unnecessary manual cursor creation.

Parameters:
T must be the transaction in which the cursor was created.
Name query result field with the name of the existing SQL cursor.
Count the stride of the cursor, ie. the number of rows fetched at a time. This defaults to 1.


Member Function Documentation

size_type pqxx::Cursor::ALL   throw () [static]
 

Constant: "next fetch/move should span as many rows as possible.".

If the number of rows ahead exceeds the largest number your machine can comfortably conceive, this may not actually be all remaining rows in the result set.

size_type pqxx::Cursor::BACKWARD_ALL   throw () [static]
 

If the number of rows behind the cursor exceeds the largest number your machine can comfortably conceive, this may not bring you all the way back to the beginning.

pqxx::Result pqxx::Cursor::Fetch size_type    Count
 

Fetch Count rows of data.

The first row returned, if any, will be the one directly before (if Count is negative) or after (if Count is positive) the cursor's current position. If an exception occurs during the operation, the cursor will be left in an unknown position. Fetching from a cursor in an unknown position may still work, but libpqxx cannot determine its current position until the cursor is moved off either edge of the result set.

The number of rows fetched will not exceed Count, but it may be lower.

pqxx::Result::size_type pqxx::Cursor::Move size_type    Count
 

Move forward by Count rows (negative for backwards) through the data set.

Returns the number of rows skipped. This need not be the same number reported by PostgreSQL, which has a different but deceptively similar meaning.

Also, note that cursors may reside on nonexistant rows, and that any exception during the operation will leave the cursor in an unknown position.

void pqxx::Cursor::MoveTo size_type   
 

size_type pqxx::Cursor::NEXT   throw () [static]
 

Constant: "next fetch/move should cover just the next row.".

pqxx::Cursor::operator bool   const throw ()
 

May there be more rows coming?

bool pqxx::Cursor::operator!   const throw ()
 

Are we done?

Cursor& pqxx::Cursor::operator+= size_type    N
 

Move N rows forward.

Cursor& pqxx::Cursor::operator-= size_type    N
 

Move N rows backward.

pqxx::Cursor & pqxx::Cursor::operator>> Result  
 

Fetch rows.

The number of rows retrieved will be no larger than (but may be lower than) the rowcount set using the SetCount() function, or passed to the constructor as the Count argument. The default is 1. This operator lends itself to "while (Cur >> R) { ... }"-style use; the Cursor's conversion to bool tests whether it has arrived at the end of its data set.

size_type pqxx::Cursor::Pos   const throw (unknown_position)
 

Current cursor position.

If an exception occurs while moving or fetching, the cursor's position may be left in an unknown state. Moving the cursor off either edge of its result set will bring it back to a known position.

Requesting a cursor's position while it is in an unknown state will cause an unknown_position exception to be thrown.

size_type pqxx::Cursor::PRIOR   throw () [static]
 

Constant: "next fetch/move should go back one row.".

pqxx::Cursor::size_type pqxx::Cursor::SetCount size_type   
 

Set new stride, ie. the number of rows to fetch at a time.

size_type pqxx::Cursor::size   const throw ()
 

Number of actual tuples, or pos_unknown if not currently known.

Size will become known when the cursor passes the end of the result set, either by moving past it or by attempting to fetch more rows than are available. The count only includes actual tuples of data, but not the two "imaginary" rows before the first actual row and after the last actual row, respectively.

If an exception occurs while moving or fetching, the cursor's position may be left in unknown state, and in this condition the cursor will not be able to compute its size until it has been moved to one of the two imaginary rows on either side of the actual result set.


The documentation for this class was generated from the following files:
Generated on Fri Feb 28 19:23:33 2003 for libpqxx by doxygen1.3-rc3