pqxx::Cursor Class Reference

SQL cursor class. More...

#include <cursor.h>

List of all members.

Public Types
typedef result::size_type	size_type
typedef result::difference_type	difference_type
enum	pos { pos_unknown = -1, pos_start = 0 }
Public Member Functions
template<typename TRANSACTION>
	Cursor (TRANSACTION &T, const char Query[], const PGSTD::string &BaseName="cur", difference_type Count=dist_next)
	Constructor. Creates a cursor.
template<typename TRANSACTION>
	Cursor (TRANSACTION &T, const result::field &Name, difference_type Count=dist_next)
	Special-purpose constructor. Adopts existing SQL cursor. Use with care.
difference_type	SetCount (difference_type)
	Set new stride, ie. the number of rows to fetch at a time.
result	Fetch (difference_type Count)
	Fetch Count rows of data.
difference_type	Move (difference_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+= (difference_type N)
	Move N rows forward.
Cursor &	operator-= (difference_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
difference_type	ALL () throw ()
	Constant: "next fetch/move should span as many rows as possible.".
difference_type	NEXT () throw ()
	Constant: "next fetch/move should cover just the next row.".
difference_type	PRIOR () throw ()
	Constant: "next fetch/move should go back one row.".
difference_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.

Warning:

A Cursor is only valid within the transaction in which it was created. The result set must not change during its existence, or the cursor's positioning logic will get horribly confused. For this reason, Cursor should only be used inside serializable transactions. This class is to be replaced by a C++-style iterator interface.

Deprecated:

This class was not ported to the 2.x libpqxx API because it is to be replaced by a container/iterator interface.

---

Member Typedef Documentation

typedef result::difference_type pqxx::Cursor::difference_type

typedef result::size_type pqxx::Cursor::size_type

---

Member Enumeration Documentation

enum pqxx::Cursor::pos

Enumeration values: pos_unknown  pos_start

---

Constructor & Destructor Documentation

template<typename TRANSACTION> pqxx::Cursor::Cursor (  TRANSACTION &  T, const char  Query[], const PGSTD::string &  BaseName = "cur", difference_type  Count = dist_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.

template<typename TRANSACTION> pqxx::Cursor::Cursor (  TRANSACTION &  T, const result::field &  Name, difference_type  Count = dist_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

pqxx::Cursor::difference_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.

pqxx::Cursor::difference_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 (  difference_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::difference_type pqxx::Cursor::Move (  difference_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   )

difference_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+= (  difference_type  N  )

Move N rows forward.

Cursor& pqxx::Cursor::operator-= (  difference_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.

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

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

pqxx::Cursor::difference_type pqxx::Cursor::SetCount (  difference_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:

• cursor.h
• oldcursor.cxx

---