pqxx::icursorstream Class Reference

Simple read-only cursor represented as a stream of results. More...

#include <cursor.hxx>

Inheritance diagram for pqxx::icursorstream:

List of all members.

Public Member Functions
	icursorstream (transaction_base &Context, const PGSTD::string &Query, const PGSTD::string &Basename, difference_type Stride=1)
	Set up a read-only, forward-only cursor.
	icursorstream (transaction_base &Context, const result::field &Name, difference_type Stride=1)
	Adopt existing SQL cursor. Use with care.
icursorstream &	get (result &res)
	Read new value into given result object; same as operator >>.
icursorstream &	operator>> (result &res)
	Read new value into given result object; same as get(result &).
icursorstream &	ignore (PGSTD::streamsize n=1)
	Move given number of rows forward (ignoring stride) without reading data.
void	set_stride (difference_type stride)
	Change stride, i.e. the number of rows to fetch per read operation.
difference_type	stride () const throw ()
Friends
class	icursor_iterator

---

Detailed Description

Simple read-only cursor represented as a stream of results.

Data is fetched from the cursor as a sequence of result objects. Each of these will contain the number of rows defined as the stream's stride, except of course the last block of data which may contain fewer rows.

This class can create or adopt cursors that live in nontransactions, i.e. outside any backend transaction, which your backend version may not support.

---

Constructor & Destructor Documentation

pqxx::icursorstream::icursorstream (  transaction_base &  Context, const PGSTD::string &  Query, const PGSTD::string &  Basename, difference_type  Stride = 1 )

Set up a read-only, forward-only cursor. Roughly equivalent to a C++ Standard Library istream, this cursor type supports only two operations: reading a block of rows while moving forward, and moving forward without reading any data. Parameters: Context  Transaction context that this cursor will be active in Query  SQL query whose results this cursor shall iterate Basename  Suggested name for the SQL cursor; a unique code will be appended by the library to ensure its uniqueness Stride  Number of rows to fetch per read operation; must be a positive number

pqxx::icursorstream::icursorstream (  transaction_base &  Context, const result::field &  Name, difference_type  Stride = 1 )

Adopt existing SQL cursor. Use with care. Forms a cursor stream around an existing SQL cursor, as returned by e.g. a server-side function. The SQL cursor will be cleaned up by the stream's destructor as if it had been created by the stream; cleaning it up by hand or adopting the same cursor twice is an error. Passing the name of the cursor as a string is not allowed, both to avoid confusion with the other constructor and to discourage unnecessary use of adopted cursors. Warning: It is technically possible to adopt a "WITH HOLD" cursor, i.e. a cursor that stays alive outside its creating transaction. However, any cursor stream (including the underlying SQL cursor, naturally) must be destroyed before its transaction context object is destroyed. Therefore the only way to use SQL's WITH HOLD feature is to adopt the cursor, but defer doing so until after entering the transaction context that will eventually destroy it. Parameters: Context  Transaction context that this cursor will be active in Name  Result field containing the name of the SQL cursor to adopt Stride  Number of rows to fetch per read operation; must be a positive number

---

Member Function Documentation

icursorstream& pqxx::icursorstream::get (  result &  res  )

Read new value into given result object; same as operator >>. The result set may continue any number of rows from zero to the chosen stride, inclusive. An empty result will only be returned if there are no more rows to retrieve. Returns: Reference to this very stream, to facilitate "chained" invocations ( C.get(r1).get(r2); )

pqxx::icursorstream & pqxx::icursorstream::ignore (  PGSTD::streamsize  n = 1  )

Move given number of rows forward (ignoring stride) without reading data. Returns: Reference to this very stream, to facilitate "chained" invocations ( C.ignore(2).get(r).ignore(4); )

icursorstream& pqxx::icursorstream::operator>> (  result &  res  )

Read new value into given result object; same as get(result &). The result set may continue any number of rows from zero to the chosen stride, inclusive. An empty result will only be returned if there are no more rows to retrieve. Returns: Reference to this very stream, to facilitate "chained" invocations ( C >> r1 >> r2; )

void pqxx::icursorstream::set_stride (  difference_type  stride  )

Change stride, i.e. the number of rows to fetch per read operation. Parameters: stride  Must be a positive number

difference_type pqxx::icursorstream::stride (   )  const throw ()

---

Friends And Related Function Documentation

friend class icursor_iterator [friend]

---

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

• cursor.hxx
• cursor.cxx

---