libpqxx  7.5.0
pqxx::icursorstream Class Reference

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

#include <cursor.hxx>

Public Types

using size_type = cursor_base::size_type
 
using difference_type = cursor_base::difference_type
 

Public Member Functions

 icursorstream (transaction_base &context, std::string_view query, std::string_view basename, difference_type sstride=1)
 Set up a read-only, forward-only cursor. More...
 
 icursorstream (transaction_base &context, field const &cname, difference_type sstride=1, cursor_base::ownership_policy op=cursor_base::owned)
 Adopt existing SQL cursor. Use with care. More...
 
 operator bool () const noexcept
 Return true if this stream may still return more data. More...
 
icursorstreamget (result &res)
 Read new value into given result object; same as operator >> More...
 
icursorstreamoperator>> (result &res)
 Read new value into given result object; same as get(result &) More...
 
icursorstreamignore (std::streamsize n=1)
 Move given number of rows forward (ignoring stride) without reading data. 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 noexcept
 

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

◆ difference_type

◆ size_type

Constructor & Destructor Documentation

◆ icursorstream() [1/2]

pqxx::icursorstream::icursorstream ( transaction_base context,
std::string_view  query,
std::string_view  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
contextTransaction context in which this cursor will be active.
querySQL query whose results this cursor shall iterate.
basenameSuggested name for the SQL cursor; the library will append a unique code to ensure its uniqueness.
sstrideNumber of rows to fetch per read operation; must be a positive number.

References pqxx::cursor_base::forward_only, pqxx::cursor_base::owned, pqxx::cursor_base::read_only, and set_stride().

◆ icursorstream() [2/2]

pqxx::icursorstream::icursorstream ( transaction_base context,
field const &  cname,
difference_type  sstride = 1,
cursor_base::ownership_policy  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
contextTransaction context in which this cursor will be active.
cnameResult field containing the name of the SQL cursor to adopt.
sstrideNumber of rows to fetch per read operation; must be a positive number.
opOwnership policy. Determines whether the cursor underlying this stream will be destroyed when the stream is closed.

References pqxx::field::c_str(), and set_stride().

Member Function Documentation

◆ get()

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

◆ ignore()

pqxx::icursorstream & pqxx::icursorstream::ignore ( std::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);")

◆ operator bool()

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

Return true if this stream may still return more data.

◆ operator>>()

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

◆ set_stride()

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

Change stride, i.e. the number of rows to fetch per read operation.

Parameters
strideMust be a positive number

References stride().

Referenced by icursorstream().

◆ stride()

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

Referenced by set_stride().

Friends And Related Function Documentation

◆ internal::gate::icursorstream_icursor_iterator

friend class internal::gate::icursorstream_icursor_iterator
friend

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