C# Class Upscaledb.Cursor

A Database Cursor class
Inheritance: IDisposable
Show file Open project: cruppstahl/upscaledb Class Usage Examples

Public Methods

Method Description
Clone ( ) : Cursor

Clones a Database Cursor

This method wraps the native ups_cursor_clone function.
Clones an existing Cursor. The new Cursor will point to exactly the same item as the old Cursor. If the old Cursor did not point to any item, so will the new Cursor. If the old Cursor is bound to a Transaction, then the new Cursor will also be bound to this Transaction.

Close ( ) : void

Closes the Cursor

This method wraps the native ups_cursor_close function.
Closes this Cursor and frees allocated memory. All Cursors should be closed before closing the Database.

Create ( Database db ) : void

Creates a new Cursor
Create ( Database db, Transaction txn ) : void

Creates a new Cursor in a Transaction

This method wraps the native ups_cursor_create function.
Creates a new Database Cursor. Cursors can be used to traverse the Database from start to end or vice versa. Cursors can also be used to insert, delete or search Database items. A newly created Cursor does not point to any item in the Database. The application should close all Database Cursors before closing the Database.

Cursor ( Database db ) : System

Constructor which creates a new Cursor
Cursor ( Database db, Transaction txn ) : System

Constructor which creates a new Cursor in a Transaction
Dispose ( ) : void

Closes the Cursor
Erase ( ) : void

Erases the current key

This method wraps the native ups_cursor_erase function.
Erases a key from the Database. If the erase was successfull, the Cursor is invalidated, and does no longer point to any item. In case of an error, the Cursor is not modified.
If the Database was opened with the flag UpsConst.UPS_ENABLE_DUPLICATE_KEYS, this function erases only the duplicate item to which the Cursor refers.

Find ( byte key ) : byte[]

Searches a key and points the Cursor to this key; returns the record of the key
Find ( byte &key, int flags ) : byte[]

Searches a key and points the Cursor to this key

This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.

GetDuplicateCount ( ) : int

Returns the number of duplicate keys

This method wraps the native ups_cursor_get_duplicate_count function.
Returns the number of duplicate keys of the item to which the Cursor currently refers.
Returns 1 if the key has no duplicates.

GetHandle ( ) : IntPtr

Returns the internal cursor handle.
GetKey ( ) : byte[]

Retrieves the Key of the current item

This method wraps the native ups_cursor_move function.
Returns the key of the current Database item. Throws UpsConst.UPS_CURSOR_IS_NIL if the Cursor does not point to any item.

GetRecord ( ) : byte[]

Retrieves the Record of the current item

This method wraps the native ups_cursor_move function.
Returns the record of the current Database item. Throws UpsConst.UPS_CURSOR_IS_NIL if the Cursor does not point to any item.

Insert ( byte key, byte record ) : void

Inserts a Database item and points the Cursor to the new item

This is an overloaded function for Insert(key, record, 0).

Insert ( byte key, byte record, int flags ) : void

Inserts a Database item and points the Cursor to the new item

This method wraps the native ups_cursor_insert function.
This function inserts a key/record pair as a new Database item. If the key already exists in the Database, error UpsConst.UPS_DUPLICATE_KEY is thrown.
If you wish to overwrite an existing entry specify the flag UpsConst.UPS_OVERWRITE
If you wish to insert a duplicate key specify the flag UpsConst.UPS_DUPLICATE. (Note that the Database has to be created with the flag UpsConst.UPS_ENABLE_DUPLICATE_KEYS in order to use duplicate keys.) By default, the duplicate key is inserted after all other duplicate keys (UpsConst.UPS_DUPLICATE_INSERT_LAST). This behaviour can be overwritten by specifying UpsConst.UPS_DUPLICATE_INSERT_FIRST, UpsConst.UPS_DUPLICATE_INSERT_BEFORE or UpsConst.UPS_DUPLICATE_INSERT_AFTER.
Specify the flag UpsConst.UPS_HINT_APPEND if you insert sequential data and the current key is higher than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the highest; if not, it will perform a normal insert. This is the default for Record Number Databases.
Specify the flag UpsConst.UPS_HINT_PREPEND if you insert sequential data and the current key is lower than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the lowest; if not, it will perform a normal insert.
After inserting, the Cursor will point to the new item. If inserting the item failed, the Cursor is not modified.

Move ( int flags ) : void

Moves the Cursor to the direction specified in the flags

This method wraps the native ups_cursor_move function. Moves the Cursor. Use the flags to specify the direction. After the move, use Cursor.GetKey and Cursor.GetRecord to retrieve key and record of the item. If the direction is not specified, the Cursor will not move.

MoveFirst ( ) : void

Moves the Cursor to the first Database element
MoveLast ( ) : void

Moves the Cursor to the last Database element
MoveNext ( ) : void

Moves the Cursor to the next Database element
MoveNext ( int flags ) : void

Moves the Cursor to the next Database element
MovePrevious ( ) : void

Moves the Cursor to the previous Database element
MovePrevious ( int flags ) : void

Moves the Cursor to the previous Database element
Overwrite ( byte record ) : void

Overwrites the record of the current item

This method wraps the native ups_cursor_overwrite function.
This function overwrites the record of the current item.

TryFind ( byte key ) : byte[]

Searches for a key and points the Cursor to this key

This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified and the return value is null.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.

TryFind ( byte &key, int flags ) : byte[]

Searches for a key and points the Cursor to this key

This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified and the return value is null.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.

TryMove ( byte &key, byte &record, int flags ) : bool

Like Cursor.Move, but returns false only if cursor points to the first (or last) item, and a move to the previous (or next) item was requested (i.e., when ups_cursor_move returns UpsConst.UPS_KEY_NOT_FOUND).

Private Methods

Method Description
Cursor ( Database db, IntPtr handle ) : System

Constructor which creates a new Cursor

Method Details

Clone() public method

Clones a Database Cursor
This method wraps the native ups_cursor_clone function.
Clones an existing Cursor. The new Cursor will point to exactly the same item as the old Cursor. If the old Cursor did not point to any item, so will the new Cursor. If the old Cursor is bound to a Transaction, then the new Cursor will also be bound to this Transaction.
/// /// /// if the new structure could not be allocated /// ///
public Clone ( ) : Cursor
return Cursor

Close() public method

Closes the Cursor
This method wraps the native ups_cursor_close function.
Closes this Cursor and frees allocated memory. All Cursors should be closed before closing the Database.
public Close ( ) : void
return void

Create() public method

Creates a new Cursor
public Create ( Database db ) : void
db Database
return void

Create() public method

Creates a new Cursor in a Transaction
This method wraps the native ups_cursor_create function.
Creates a new Database Cursor. Cursors can be used to traverse the Database from start to end or vice versa. Cursors can also be used to insert, delete or search Database items. A newly created Cursor does not point to any item in the Database. The application should close all Database Cursors before closing the Database.
/// /// /// if the new structure could not be allocated /// ///
public Create ( Database db, Transaction txn ) : void
db Database The Database object
txn Transaction The optional Transaction
return void

Cursor() public method

Constructor which creates a new Cursor
public Cursor ( Database db ) : System
db Database The Database of this Cursor
return System

Cursor() public method

Constructor which creates a new Cursor in a Transaction
public Cursor ( Database db, Transaction txn ) : System
db Database
txn Transaction
return System

Dispose() public method

Closes the Cursor
public Dispose ( ) : void
return void

Erase() public method

Erases the current key
This method wraps the native ups_cursor_erase function.
Erases a key from the Database. If the erase was successfull, the Cursor is invalidated, and does no longer point to any item. In case of an error, the Cursor is not modified.
If the Database was opened with the flag UpsConst.UPS_ENABLE_DUPLICATE_KEYS, this function erases only the duplicate item to which the Cursor refers.
/// /// /// if the Cursor does not point to any item /// /// if you tried to erase a key from a read-only Database /// ///
public Erase ( ) : void
return void

Find() public method

Searches a key and points the Cursor to this key; returns the record of the key
public Find ( byte key ) : byte[]
key byte
return byte[]

Find() public method

Searches a key and points the Cursor to this key
This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.
/// /// /// if the requested key was not found /// ///
public Find ( byte &key, int flags ) : byte[]
key byte The key to search for
flags int The flags, can be zero
return byte[]

GetDuplicateCount() public method

Returns the number of duplicate keys
This method wraps the native ups_cursor_get_duplicate_count function.
Returns the number of duplicate keys of the item to which the Cursor currently refers.
Returns 1 if the key has no duplicates.
/// /// /// if the Cursor does not point to any item /// ///
public GetDuplicateCount ( ) : int
return int

GetHandle() public method

Returns the internal cursor handle.
public GetHandle ( ) : IntPtr
return System.IntPtr

GetKey() public method

Retrieves the Key of the current item
This method wraps the native ups_cursor_move function.
Returns the key of the current Database item. Throws UpsConst.UPS_CURSOR_IS_NIL if the Cursor does not point to any item.
/// /// /// if the Cursor does not point to any item /// ///
public GetKey ( ) : byte[]
return byte[]

GetRecord() public method

Retrieves the Record of the current item
This method wraps the native ups_cursor_move function.
Returns the record of the current Database item. Throws UpsConst.UPS_CURSOR_IS_NIL if the Cursor does not point to any item.
/// /// /// if the Cursor does not point to any item /// ///
public GetRecord ( ) : byte[]
return byte[]

Insert() public method

Inserts a Database item and points the Cursor to the new item
This is an overloaded function for Insert(key, record, 0).
public Insert ( byte key, byte record ) : void
key byte The key of the new item
record byte The record of the new item
return void

Insert() public method

Inserts a Database item and points the Cursor to the new item
This method wraps the native ups_cursor_insert function.
This function inserts a key/record pair as a new Database item. If the key already exists in the Database, error UpsConst.UPS_DUPLICATE_KEY is thrown.
If you wish to overwrite an existing entry specify the flag UpsConst.UPS_OVERWRITE
If you wish to insert a duplicate key specify the flag UpsConst.UPS_DUPLICATE. (Note that the Database has to be created with the flag UpsConst.UPS_ENABLE_DUPLICATE_KEYS in order to use duplicate keys.) By default, the duplicate key is inserted after all other duplicate keys (UpsConst.UPS_DUPLICATE_INSERT_LAST). This behaviour can be overwritten by specifying UpsConst.UPS_DUPLICATE_INSERT_FIRST, UpsConst.UPS_DUPLICATE_INSERT_BEFORE or UpsConst.UPS_DUPLICATE_INSERT_AFTER.
Specify the flag UpsConst.UPS_HINT_APPEND if you insert sequential data and the current key is higher than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the highest; if not, it will perform a normal insert. This is the default for Record Number Databases.
Specify the flag UpsConst.UPS_HINT_PREPEND if you insert sequential data and the current key is lower than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the lowest; if not, it will perform a normal insert.
After inserting, the Cursor will point to the new item. If inserting the item failed, the Cursor is not modified.
/// /// /// if the flags UpsConst.UPS_DUPLICATE AND /// UpsConst.UPS_OVERWRITE were specified, or if /// UpsConst.UPS_DUPLICATE was specified but the Database /// was not created with UpsConst.UPS_ENABLE_DUPLICATE_KEYS /// /// if you tried to insert a key in a read-only Database /// /// if key size is different than than the key size parameter /// specified for Database.Create. /// ///
public Insert ( byte key, byte record, int flags ) : void
key byte The key of the new item
record byte The record of the new item
flags int Optional flags for this operation, combined /// with bitwise OR. Possible flags are: /// /// /// If the key already exists, the record is overwritten. /// Otherwise, the key is inserted. /// /// If the key already exists, a duplicate key is inserted. /// The key is inserted after the already existing duplicates. /// Same as . /// /// /// If the key already exists, a duplicate key is inserted before /// the duplicate pointed to by this Cursor. /// /// If the key already exists, a duplicate key is inserted after /// the duplicate pointed to by this Cursor. /// /// If the key already exists, a duplicate key is inserted as /// the first duplicate of the current key. /// /// If the key already exists, a duplicate key is inserted as /// the last duplicate of the current key. ///
return void

Move() public method

Moves the Cursor to the direction specified in the flags
This method wraps the native ups_cursor_move function. Moves the Cursor. Use the flags to specify the direction. After the move, use Cursor.GetKey and Cursor.GetRecord to retrieve key and record of the item. If the direction is not specified, the Cursor will not move.
/// /// /// if the Cursor points to the first (or last) item, and a /// move to the previous (or next) item was requested /// ///
public Move ( int flags ) : void
flags int The direction for the move. If no direction /// is specified, the Cursor will remain on the current position. /// Possible flags are: /// /// positions /// the Cursor to the first item in the Database /// positions /// the Cursor to the last item in the Database /// positions /// the Cursor to the next item in the Database; if the Cursor /// does not point to any item, the function behaves as if /// direction was . /// positions /// the Cursor to the previous item in the Database; if the Cursor /// does not point to any item, the function behaves as if /// direction was . /// skips /// duplicate keys of the current key. Not allowed in combination /// with . /// only /// moves through duplicate keys of the current key. Not allowed /// in combination with /// . /// ///
return void

MoveFirst() public method

Moves the Cursor to the first Database element
public MoveFirst ( ) : void
return void

MoveLast() public method

Moves the Cursor to the last Database element
public MoveLast ( ) : void
return void

MoveNext() public method

Moves the Cursor to the next Database element
public MoveNext ( ) : void
return void

MoveNext() public method

Moves the Cursor to the next Database element
public MoveNext ( int flags ) : void
flags int Additional flags for the movement
return void

MovePrevious() public method

Moves the Cursor to the previous Database element
public MovePrevious ( ) : void
return void

MovePrevious() public method

Moves the Cursor to the previous Database element
public MovePrevious ( int flags ) : void
flags int Additional flags for the movement
return void

Overwrite() public method

Overwrites the record of the current item
This method wraps the native ups_cursor_overwrite function.
This function overwrites the record of the current item.
/// /// /// if the Cursor does not point to any item /// ///
public Overwrite ( byte record ) : void
record byte
return void

TryFind() public method

Searches for a key and points the Cursor to this key
This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified and the return value is null.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.
public TryFind ( byte key ) : byte[]
key byte The key to search for
return byte[]

TryFind() public method

Searches for a key and points the Cursor to this key
This method wraps the native ups_cursor_find function.
Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified and the return value is null.
If the key has multiple duplicates, the Cursor is positioned on the first duplicate.
public TryFind ( byte &key, int flags ) : byte[]
key byte The key to search for
flags int The flags, can be zero
return byte[]

TryMove() public method

Like Cursor.Move, but returns false only if cursor points to the first (or last) item, and a move to the previous (or next) item was requested (i.e., when ups_cursor_move returns UpsConst.UPS_KEY_NOT_FOUND).
public TryMove ( byte &key, byte &record, int flags ) : bool
key byte
record byte
flags int
return bool