pqxx::icursorstream Class Reference

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

#include <cursor.hxx>

Collaboration diagram for pqxx::icursorstream:

Public Types
typedef cursor_base::difference_type	difference_type
typedef cursor_base::size_type	size_type

Public Member Functions
	icursorstream (transaction_base &context, const PGSTD::string &query, const PGSTD::string &basename, difference_type sstride=1)
	Set up a read-only, forward-only cursor. More...
	icursorstream (transaction_base &context, const field &cname, difference_type sstride=1, cursor_base::ownershippolicy op=cursor_base::owned)
	Adopt existing SQL cursor. Use with care. More...
icursorstream &	get (result &res)
	Read new value into given result object; same as operator >> More...
icursorstream &	ignore (PGSTD::streamsize n=1)
	Move given number of rows forward (ignoring stride) without reading data. More...
	operator bool () const throw ()
icursorstream &	operator>> (result &res)
	Read new value into given result object; same as get(result &) More...
void	set_stride (difference_type stride)
	Change stride, i.e. the number of rows to fetch per read operation. More...
difference_type	stride () const throw ()

Private Member Functions
result	fetchblock ()
size_type	forward (size_type n=1)
void	insert_iterator (icursor_iterator *) throw ()
void	remove_iterator (icursor_iterator *) const throw ()
void	service_iterators (difference_type)

Private Attributes
internal::sql_cursor	m_cur
bool	m_done
icursor_iterator *	m_iterators
difference_type	m_realpos
difference_type	m_reqpos
difference_type	m_stride

Friends
class	internal::gate::icursorstream_icursor_iterator

Detailed Description

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

SQL cursors can be tricky, especially in C++ since the two languages seem to have been designed on different planets. An SQL cursor has two singular positions akin to end() on either side of the underlying result set.

These cultural differences are hidden from view somewhat by libpqxx, which tries to make SQL cursors behave more like familiar C++ entities such as iterators, sequences, streams, and containers.

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 outside any backend transaction, which your backend version may not support.

Member Typedef Documentation

typedef cursor_base::difference_type pqxx::icursorstream::difference_type

typedef cursor_base::size_type pqxx::icursorstream::size_type

Constructor & Destructor Documentation

pqxx::icursorstream::icursorstream	(	transaction_base &	context,
		const PGSTD::string &	query,
		const PGSTD::string &	basename,
		difference_type	sstride = 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
sstride	Number of rows to fetch per read operation; must be a positive number

pqxx::icursorstream::icursorstream	(	transaction_base &	context,
		const field &	cname,
		difference_type	sstride = 1,
		cursor_base::ownershippolicy	op = cursor_base::owned
	)

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.
cname	Result field containing the name of the SQL cursor to adopt.
sstride	Number of rows to fetch per read operation; must be a positive number.
op	Ownership policy. Determines whether the cursor underlying this stream will be destroyed when the stream is closed.

Member Function Documentation

result pqxx::icursorstream::fetchblock ( )

private

size_type pqxx::icursorstream::forward ( size_type  n = 1 )

private

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

inline

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);")

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);")

void pqxx::icursorstream::insert_iterator ( icursor_iterator *  ) throw ()

private

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

inline

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

inline

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::remove_iterator ( icursor_iterator *  ) const throw ()

private

void pqxx::icursorstream::service_iterators ( difference_type  )

private

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

inline

Friends And Related Function Documentation

friend class internal::gate::icursorstream_icursor_iterator

friend

Member Data Documentation

internal::sql_cursor pqxx::icursorstream::m_cur

private

bool pqxx::icursorstream::m_done

private

icursor_iterator* pqxx::icursorstream::m_iterators

mutableprivate

difference_type pqxx::icursorstream::m_realpos

private

difference_type pqxx::icursorstream::m_reqpos

private

difference_type pqxx::icursorstream::m_stride

private

---

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

• /usr/include/pqxx/cursor.hxx