An object to iterate storages. More...

#include <cursor.hpp>

Public Member Functions
	Cursor ()
	Creates an empty cursor.

	Cursor (Storage< K, V > *parent)
	Creates a cursor.

	Cursor (const Cursor &other)=delete

	Cursor (Cursor &&other)
	Moves from another cursor.

	~Cursor ()
	Destroys a cursor.

Cursor &	operator= (const Cursor &other)=delete

Cursor &	operator= (Cursor &&other)
	A private function that turns cursor into an empty one.

void	open ()
	Opens the cursor for operations.

void	open (const Transaction &transaction)
	Opens the cursor for operations.

void	renew ()
	Renews a cursor.

void	renew (const Transaction &transaction)
	Renews a cursor.

void	close ()
	Termiates a sequence of operations with the cursor.

bool	opened () const
	Tells if the cursor is open.

bool	empty () const
	Returns true if the cursor is empty.

void	drop ()
	Turns cursor into an empty one, releasing resources.

std::pair< K, V >	first ()
	Queries the first element in the storage.

std::pair< K, V >	last ()
	Queries the last element in the storage.

std::pair< K, V >	next ()
	Queries the next element from the storage.

std::pair< K, V >	prev ()
	Queries the previous element from the storage.

std::pair< K, V >	current () const
	Returns current cursor element from the storage.

bool	set (const K &target)
	Sets cursors to the defined position.

void	first (K &key, V &value)
	Queries the first element in the storage.

void	last (K &key, V &value)
	Queries the last element in the storage.

void	next (K &key, V &value)
	Queries the next element from the storage.

void	prev (K &key, V &value)
	Queries the previous element from the storage.

void	current (K &key, V &value) const
	Returns current cursor element from the storage.

Friends
class	Storage< K, V >

Detailed Description

template<class K, class V>
class LMDBAL::Cursor< K, V >

An object to iterate storages.

Template Parameters

K	type of the keys in the storage that this cursor would iterate
V	type of the values in the storage that this cursor would iterate

Cursor allowes you to perform sequential querries, navigate from one element to another at reduced operation price. For now Cursors are read only but in the future you might also be able to write to the storage with them.

Cursors are owned by the storage, they die with the storage. They also get closed if the storage is closed (if you close by the database for example)

You can obtain an instance of this class calling LMDBAL::Storage::createCursor() and destory it calling LMDBAL::Storage::destoryCursor() at any time, LMDBAL::Base doesn't necessarily need to be opened.

You are not supposed to instantiate or destory instances of this class yourself!

Constructor & Destructor Documentation

◆ Cursor() [1/2]

template<class K , class V >

LMDBAL::Cursor< K, V >::Cursor ( )

Creates an empty cursor.

It's not usable, but can exist just to be a target of moves

◆ Cursor() [2/2]

template<class K , class V >

LMDBAL::Cursor< K, V >::Cursor ( Storage< K, V > * parent )

Creates a cursor.

Parameters

[in] parent a storage that created this cursor

◆ ~Cursor()

template<class K , class V >

LMDBAL::Cursor< K, V >::~Cursor ( )

Destroys a cursor.

If the cursor wasn't properly closed - it's going to be upon destruction

Member Function Documentation

◆ close()

template<class K , class V >

void LMDBAL::Cursor< K, V >::close ( )

Termiates a sequence of operations with the cursor.

This is a normal way to tell that you're done with the cursor and don't want to continue the sequence of queries. The state of the cursor is lost after calling this method, some inner resorce is freed.

If the cursor was opened with the private transaction - the owner storage will be notified of the aborted transaction.

This function does nothing on a closed cursor.

◆ current() [1/2]

template<class K , class V >

std::pair< K, V > LMDBAL::Cursor< K, V >::current ( ) const

Returns current cursor element from the storage.

If there was no operation before this method throws LMDBAL::Unknown for some reason

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Returns: std::pair where first is element key and second is element value

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	probably never thrown but there might be still some corner case I don't know about
LMDBAL::Unknown	thrown if there was no positioning operation before of if there was some unexpected problem with lmdb

◆ current() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::current	(	K &	key,
		V &	value ) const

Returns current cursor element from the storage.

If there was no operation before this method throws LMDBAL::Unknown for some reason

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Parameters

[out]	key	a reference to an object the key of queried element is going to be assigned
[out]	value	a reference to an object the value of queried element is going to be assigned

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	probably never thrown but there might be still some corner case I don't know about
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ drop()

template<class K , class V >

void LMDBAL::Cursor< K, V >::drop ( )

Turns cursor into an empty one, releasing resources.

This function is called from LMDBAL::Storage, when it gets destroyed, but still has some valid. Those cursors will become empty, and can't be used anymore

◆ empty()

template<class K , class V >

bool LMDBAL::Cursor< K, V >::empty ( ) const

Returns true if the cursor is empty.

Empty cursors can't be used, they can be only targets of move operations

◆ first() [1/2]

template<class K , class V >

std::pair< K, V > LMDBAL::Cursor< K, V >::first ( )

Queries the first element in the storage.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Returns: std::pair where first is element key and second is element value

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ first() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::first	(	K &	key,
		V &	value )

Queries the first element in the storage.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Parameters

[out]	key	a reference to an object the key of queried element is going to be assigned
[out]	value	a reference to an object the value of queried element is going to be assigned

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ last() [1/2]

template<class K , class V >

std::pair< K, V > LMDBAL::Cursor< K, V >::last ( )

Queries the last element in the storage.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Returns: std::pair where first is element key and second is element value

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ last() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::last	(	K &	key,
		V &	value )

Queries the last element in the storage.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Parameters

[out]	key	a reference to an object the key of queried element is going to be assigned
[out]	value	a reference to an object the value of queried element is going to be assigned

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ next() [1/2]

template<class K , class V >

std::pair< K, V > LMDBAL::Cursor< K, V >::next ( )

Queries the next element from the storage.

If there was no operation before this method positions the cursor on the first element and returns it so, it's basically doing the same as LMDBAL::Cursor::first().

It will also throw LMDBAL::NotFound if you call this method being on the last element or if there are no elements in the database.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Returns: std::pair where first is element key and second is element value

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if the cursor already was on the last element or if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ next() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::next	(	K &	key,
		V &	value )

Queries the next element from the storage.

If there was no operation before this method positions the cursor on the first element and returns it so, it's basically doing the same as LMDBAL::Cursor::first(K key, V value).

It will also throw LMDBAL::NotFound if you call this method being on the last element or if there are no elements in the database.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Parameters

[out]	key	a reference to an object the key of queried element is going to be assigned
[out]	value	a reference to an object the value of queried element is going to be assigned

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if the cursor already was on the last element or if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ open() [1/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::open ( )

Opens the cursor for operations.

This is a normal way to start the sequence of operations with the cursor. This variant of the function creates a read only transaction just for this cursor

This function should be called when the LMDBAL::Storage is already opened and before any query with this cursor! It will do nothing to a cursor that was already opened (no matter what way).

Exceptions

LMDBAL::Closed	thrown if you try to open the cursor on a closed database
LMDBAL::Unknown	thrown if there was a problem opening the cursor by the lmdb, or to begin a transaction
LMDBAL::CursorEmpty	thrown if the cursor was empty

◆ open() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::open ( const Transaction & transaction )

Opens the cursor for operations.

This is a normal way to start the sequence of operations with the cursor. This variant of the function uses for queries a transaction you have obtained somewhere else.

This function should be called when the LMDBAL::Storage is already opened and before any query with this cursor! It will do nothing to a cursor that was already opened (no matter what way).

Parameters

[in] transaction - a transaction, can be read only

Exceptions

LMDBAL::Closed	thrown if you try to open the cursor on a closed database
LMDBAL::Unknown	thrown if there was a problem opening the cursor by the lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error
LMDBAL::CursorEmpty	thrown if the cursor was empty

◆ operator=()

template<class K , class V >

LMDBAL::Cursor< K, V > & LMDBAL::Cursor< K, V >::operator= ( Cursor< K, V > && other )

A private function that turns cursor into an empty one.

This function is called from LMDBAL::Storage, when it gets destroyed, but still has some valid. Those cursors will become empty, and can't be used anymore

◆ prev() [1/2]

template<class K , class V >

std::pair< K, V > LMDBAL::Cursor< K, V >::prev ( )

Queries the previous element from the storage.

If there was no operation before this method positions the cursor on the last element and returns it so, it's basically doing the same as LMDBAL::Cursor::last().

It will also throw LMDBAL::NotFound if you call this method being on the first element or if there are no elements in the database.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Returns: std::pair where first is element key and second is element value

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if the cursor already was on the first element or if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ prev() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::prev	(	K &	key,
		V &	value )

Queries the previous element from the storage.

If there was no operation before this method positions the cursor on the last element and returns it so, it's basically doing the same as LMDBAL::Cursor::last(K key, V value).

It will also throw LMDBAL::NotFound if you call this method being on the first element or if there are no elements in the database.

Notifies the storage of the queried element calling LMDBAL::Storage::discoveredRecord()

Parameters

[out]	key	a reference to an object the key of queried element is going to be assigned
[out]	value	a reference to an object the value of queried element is going to be assigned

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::NotFound	thrown if the cursor already was on the first element or if there are no elements in the storage
LMDBAL::Unknown	thrown if there was some unexpected problem with lmdb

◆ renew() [1/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::renew ( )

Renews a cursor.

This function aborts current transaction if the cursor was opened with it's own transaction (does not mess up if the transaction was public), creates new private transaction and rebinds this cursor to it.

Theoretically you could call this method if your public transaction was aborted (or commited) but you wish to continue to keep working with your cursor. Or if you just want to rebind your cursor to a new private transaction.

This function does nothing if the cursor is closed

Exceptions

LMDBAL::Closed	thrown if you try to renew the cursor on a closed database
LMDBAL::Unknown	thrown if there was a problem beginning new transaction or if there was a problem renewing the cursor by lmdb
LMDBAL::CursorEmpty	thrown if the cursor was empty

◆ renew() [2/2]

template<class K , class V >

void LMDBAL::Cursor< K, V >::renew ( const Transaction & transaction )

Renews a cursor.

This function aborts current transaction if the cursor was opened with it's own transaction (does not mess up if the transaction was public), and rebinds this cursor to a passed new transaction.

Theoretically you could call this method if your previous public transaction was aborted (or commited) but you wish to continue to keep working with your cursor. Or if you just want to rebind your cursor to another public transaction.

This function does nothing if the cursor is closed

Parameters

[in] transaction - a transaction you wish this cursor to be bound to

Exceptions

LMDBAL::Closed	thrown if you try to renew the cursor on a closed database
LMDBAL::Unknown	thrown if there was a problem renewing the cursor by lmdb
LMDBAL::TransactionTerminated	thrown if the passed transaction not active, any action with it's inner ID is an error
LMDBAL::CursorEmpty	thrown if the cursor was empty

◆ set()

template<class K , class V >

bool LMDBAL::Cursor< K, V >::set ( const K & key )

Sets cursors to the defined position.

If exactly the same element wasn't found it sets the cursor to the first element greater then the key and returns false

Parameters

[in] key a key of the element you would like the cursor to be

Returns: true if the exact value was found, false otherwise

Exceptions

LMDBAL::CursorNotReady	thrown if you try to call this method on a closed cursor
LMDBAL::Unknown	thrown if there was some unexpected problem

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

/workspace/blue/lmdbal/src/cursor.h
/workspace/blue/lmdbal/src/cursor.hpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Cursor() [1/2]

◆ Cursor() [2/2]

◆ ~Cursor()

Member Function Documentation

◆ close()

◆ current() [1/2]

◆ current() [2/2]

◆ drop()

◆ empty()

◆ first() [1/2]

◆ first() [2/2]

◆ last() [1/2]

◆ last() [2/2]

◆ next() [1/2]

◆ next() [2/2]

◆ open() [1/2]

◆ open() [2/2]

◆ operator=()

◆ prev() [1/2]

◆ prev() [2/2]

◆ renew() [1/2]

◆ renew() [2/2]

◆ set()