An object to iterate storages. More...

#include <cursor.hpp>

Inheritance diagram for LMDBAL::Cursor< K, V >:

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 this cursor.

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

Cursor &	operator= (Cursor &&other)
	Move assignment operator.

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.

Public Member Functions inherited from LMDBAL::CursorCommon
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.

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

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

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

Friends
class	Storage< K, V >

Additional Inherited Members
Protected Types inherited from LMDBAL::CursorCommon
enum	State { closed , openedPublic , openedPrivate }

Protected Member Functions inherited from LMDBAL::CursorCommon
	CursorCommon ()
	Creates a empty class.

	CursorCommon (StorageCommon *storage)
	Creates a cursor.

	CursorCommon (const CursorCommon &other)=delete

	CursorCommon (CursorCommon &&other)
	Moves other cursor into this class.

virtual	~CursorCommon () noexcept
	Destroys this cursor.

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

CursorCommon &	operator= (CursorCommon &&other)
	Move assignment operator.

void	terminated ()
	A private function called to inform the cursor he has been terminated.

void	dropped ()
	A private method that turns cursor into an empty one.

void	reset ()
	A private method that turns cursor into an empty one.

Protected Attributes inherited from LMDBAL::CursorCommon
uint32_t	id

State	state

MDB_cursor *	handle

StorageCommon *	storage

Static Protected Attributes inherited from LMDBAL::CursorCommon
static const std::string	firstMethodName = "first"
	member function name, just for exceptions in heir

static const std::string	lastMethodName = "last"
	member function name, just for exceptions in heir

static const std::string	nextMethodName = "next"
	member function name, just for exceptions in heir

static const std::string	prevMethodName = "prev"
	member function name, just for exceptions in heir

static const std::string	currentMethodName = "current"
	member function name, just for exceptions in heir

static const std::string	setMethodName = "set"
	member function name, just for exceptions in heir

static const std::string	firstOperationName = "Cursor::first"
	member function name, just for exceptions in heir

static const std::string	lastOperationName = "Cursor::last"
	member function name, just for exceptions in heir

static const std::string	nextOperationName = "Cursor::next"
	member function name, just for exceptions in heir

static const std::string	prevOperationName = "Cursor::prev"
	member function name, just for exceptions in heir

static const std::string	currentOperationName = "Cursor::current"
	member function name, just for exceptions in heir

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 this cursor.

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

Member Function Documentation

◆ 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

◆ 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

◆ operator=()

template<class K, class V>

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

Move assignment operator.

Transfers other cursor into this one

◆ 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

◆ 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

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Cursor() [1/2]

◆ Cursor() [2/2]

◆ ~Cursor()

Member Function Documentation

◆ current() [1/2]

◆ current() [2/2]

◆ drop()

◆ first() [1/2]

◆ first() [2/2]

◆ last() [1/2]

◆ last() [2/2]

◆ next() [1/2]

◆ next() [2/2]

◆ operator=()

◆ prev() [1/2]

◆ prev() [2/2]

◆ set()