#include <cursor.hxx>
Inheritance diagram for pqxx::cursor_base:
Public Types | |
| typedef result::size_type | size_type |
| typedef result::difference_type | difference_type |
| forward_only | |
| Cursor can move forward only. | |
| random_access | |
| Cursor can move back and forth. | |
| read_only | |
| Cursor can be used to read data but not to write. | |
| update | |
| Cursor can be used to update data as well as read it. | |
| owned | |
| Destroy SQL cursor when cursor object is closed at end of transaction. | |
| loose | |
| Leave SQL cursor in existence after close of object and transaction. | |
| enum | accesspolicy { forward_only, random_access } |
| Cursor access-pattern policy. More... | |
| enum | updatepolicy { read_only, update } |
| Cursor update policy. More... | |
| enum | ownershippolicy { owned, loose } |
| Cursor destruction policy. More... | |
Public Member Functions | |
| virtual | ~cursor_base () throw () |
| operator void * () const | |
| Does it make sense to try reading from this cursor again? | |
| bool | operator! () const |
| Is this cursor finished? | |
| const PGSTD::string & | name () const throw () |
| Name of underlying SQL cursor. | |
| virtual result | fetch (difference_type) |
| Fetch up to given number of rows of data. | |
| virtual result | fetch (difference_type, difference_type &) |
| Fetch result, but also return the number of rows of actual displacement. | |
| virtual difference_type | move (difference_type) |
| Move cursor by given number of rows, returning number of data rows skipped. | |
| virtual difference_type | move (difference_type, difference_type &) |
| Move cursor, but also return actual displacement in output parameter. | |
| void | close () throw () |
Static Public Member Functions | |
Special movement distances | |
| static difference_type | all () throw () |
| Special value: read until end. | |
| static difference_type | next () throw () |
| Special value: read one row only. | |
| static difference_type | prior () throw () |
| Special value: read backwards, one row only. | |
| static difference_type | backward_all () throw () |
| Special value: read backwards from current position back to origin. | |
Protected Member Functions | |
| cursor_base (transaction_base *, const PGSTD::string &Name, bool embellish_name=true) | |
| void | declare (const PGSTD::string &query, accesspolicy, updatepolicy, ownershippolicy, bool hold) |
| void | adopt (ownershippolicy) |
| template<accesspolicy A> | |
| void | check_displacement (difference_type) const |
Static Protected Member Functions | |
| static PGSTD::string | stridestring (difference_type) |
Protected Attributes | |
| transaction_base * | m_context |
| bool | m_done |
Classes | |
| struct | cachedquery |
In C++ terms, fetches are always done in pre-increment or pre-decrement fashion--i.e. the result does not include the row the cursor is on at the beginning of the fetch, and the cursor ends up being positioned on the last row in the result.
There are singular positions akin to end() at both the beginning and the end of the cursor's range of movement, although these fit in so naturally with the semantics that one rarely notices them. The cursor begins at the first of these, but any fetch in the forward direction will move the cursor off this position and onto the first row before returning anything.
Reimplemented in pqxx::absolute_cursor< ACCESS, UPDATE >.
Reimplemented in pqxx::absolute_cursor< ACCESS, UPDATE >.
Cursor destruction policy.
The normal thing to do is to make a cursor object the owner of the SQL cursor it represents. There may be cases, however, where a cursor needs to persist beyond the end of the current transaction (and thus also beyond the lifetime of the cursor object that created it!), where it can be "adopted" into a new cursor object. See the basic_cursor documentation for an explanation of cursor adoption.
If a cursor is created with "loose" ownership policy, the object representing the underlying SQL cursor will not take the latter with it when its own lifetime ends, nor will its originating transaction.
Don't "leak" cursors! As long as any "loose" cursor exists, any attempts to deactivate or reactivate the connection, implicitly or explicitly, are quietly ignored.
| virtual pqxx::cursor_base::~cursor_base | ( | ) | throw () [virtual] |
| pqxx::cursor_base::cursor_base | ( | transaction_base * | , | |
| const PGSTD::string & | Name, | |||
| bool | embellish_name = true | |||
| ) | [protected] |
| void pqxx::cursor_base::adopt | ( | ownershippolicy | ) | [protected] |
| cursor_base::difference_type pqxx::cursor_base::all | ( | ) | throw () [static] |
Special value: read until end.
| cursor_base::difference_type pqxx::cursor_base::backward_all | ( | ) | throw () [static] |
Special value: read backwards from current position back to origin.
| void pqxx::cursor_base::check_displacement | ( | difference_type | ) | const [protected] |
| void pqxx::cursor_base::close | ( | ) | throw () |
| void pqxx::cursor_base::declare | ( | const PGSTD::string & | query, | |
| accesspolicy | , | |||
| updatepolicy | , | |||
| ownershippolicy | , | |||
| bool | hold | |||
| ) | [protected] |
| pqxx::result pqxx::cursor_base::fetch | ( | difference_type | , | |
| difference_type & | ||||
| ) | [virtual] |
Fetch result, but also return the number of rows of actual displacement.
The relationship between actual displacement and result size gets tricky at the edges of the cursor's range of movement. As an example, consider a fresh cursor that's been moved forward by 2 rows from its starting position; we can move it backwards from that position by 1 row and get a result set of 1 row, ending up on the first actual row of data. If instead we move it backwards by 2 or more rows, we end up back at the starting position--but the result is still only 1 row wide!
The output parameter compensates for this, returning true displacement (which is also signed, so it includes direction).
| pqxx::result pqxx::cursor_base::fetch | ( | difference_type | ) | [virtual] |
Fetch up to given number of rows of data.
| pqxx::cursor_base::difference_type pqxx::cursor_base::move | ( | difference_type | , | |
| difference_type & | ||||
| ) | [virtual] |
Move cursor, but also return actual displacement in output parameter.
As with the fetch functions, the actual displacement may differ from the number of data rows skipped by the move.
| pqxx::cursor_base::difference_type pqxx::cursor_base::move | ( | difference_type | ) | [virtual] |
Move cursor by given number of rows, returning number of data rows skipped.
The number of data rows skipped is equal to the number of rows of data that would have been returned if this were a fetch instead of a move command.
| const PGSTD::string& pqxx::cursor_base::name | ( | ) | const throw () |
Name of underlying SQL cursor.
| static difference_type pqxx::cursor_base::next | ( | ) | throw () [static] |
Special value: read one row only.
| pqxx::cursor_base::operator void * | ( | ) | const |
Does it make sense to try reading from this cursor again?
| bool pqxx::cursor_base::operator! | ( | ) | const |
Is this cursor finished?
The logical negation of the converstion-to-pointer operator.
| static difference_type pqxx::cursor_base::prior | ( | ) | throw () [static] |
Special value: read backwards, one row only.
| string pqxx::cursor_base::stridestring | ( | difference_type | ) | [static, protected] |
transaction_base* pqxx::cursor_base::m_context [protected] |
bool pqxx::cursor_base::m_done [protected] |
1.4.7