#define HAM_CURSOR_FIRST 0x0001 |
Flag for ham_cursor_move
Definition at line 2309 of file hamsterdb.h.
Referenced by copy_db(), main(), and ham::cursor::move_first().
#define HAM_CURSOR_LAST 0x0002 |
Flag for ham_cursor_move
Definition at line 2312 of file hamsterdb.h.
Referenced by ham::cursor::move_last().
#define HAM_CURSOR_NEXT 0x0004 |
Flag for ham_cursor_move
Definition at line 2315 of file hamsterdb.h.
Referenced by copy_db(), main(), ham::cursor::move_next(), and run_demo().
#define HAM_CURSOR_PREVIOUS 0x0008 |
Flag for ham_cursor_move
Definition at line 2318 of file hamsterdb.h.
Referenced by ham::cursor::move_previous().
#define HAM_FIND_EXACT_MATCH 0x4000 |
Cursor 'find' flag: return an exact match (default).
Note: For backwards compatibility, you can specify zero (0) as an alternative when this flag is used alone.
Definition at line 2631 of file hamsterdb.h.
#define HAM_FIND_GEQ_MATCH (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH) |
Cursor 'find' flag 'Greater or Equal': return the nearest match above the given key, when an exact match does not exist.
May be combined with HAM_FIND_LEQ_MATCH to accept any 'near' key, or you can use the HAM_FIND_NEAR_MATCH constant as a shorthand for that.
Definition at line 2661 of file hamsterdb.h.
#define HAM_FIND_GT_MATCH 0x2000 |
Cursor 'find' flag 'Greater Than': return the nearest match above the given key, whether an exact match exists or not.
Definition at line 2643 of file hamsterdb.h.
#define HAM_FIND_LEQ_MATCH (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH) |
Cursor 'find' flag 'Less or EQual': return the nearest match below the given key, when an exact match does not exist.
May be combined with HAM_FIND_GEQ_MATCH to accept any 'near' key, or you can use the HAM_FIND_NEAR_MATCH constant as a shorthand for that.
Definition at line 2652 of file hamsterdb.h.
#define HAM_FIND_LT_MATCH 0x1000 |
Cursor 'find' flag 'Less Than': return the nearest match below the given key, whether an exact match exists or not.
Definition at line 2637 of file hamsterdb.h.
#define HAM_FIND_NEAR_MATCH |
Cursor 'find' flag 'Any Near Or Equal': return a match directly below or above the given key, when an exact match does not exist.
Be aware that the returned match will either match the key exactly or is either the first key available above or below the given key when an exact match could not be found; 'find' does NOT spend any effort, in the sense of determining which of both is the 'nearest' to the given key, when both a key above and a key below the one given exist; 'find' will simply return the first of both found. As such, this flag is the simplest possible combination of the combined HAM_FIND_LEQ_MATCH and HAM_FIND_GEQ_MATCH flags.
Definition at line 2676 of file hamsterdb.h.
#define HAM_ONLY_DUPLICATES 0x0020 |
Flag for ham_cursor_move
Definition at line 2324 of file hamsterdb.h.
Referenced by main(), and run_demo().
#define HAM_SKIP_DUPLICATES 0x0010 |
Flag for ham_cursor_move and ham_get_key_count
Definition at line 2321 of file hamsterdb.h.
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_clone | ( | ham_cursor_t * | src, | |
ham_cursor_t ** | dest | |||
) |
Clones a Database Cursor
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.
src | The existing Cursor | |
dest | A pointer to a pointer, which is allocated for the cloned Cursor handle |
Referenced by ham::cursor::clone().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_close | ( | ham_cursor_t * | cursor | ) |
Closes a Database Cursor
Closes a Cursor and frees allocated memory. All Cursors should be closed before closing the Database (see ham_close).
cursor | A valid Cursor handle |
Referenced by ham::cursor::close(), copy_db(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_create | ( | ham_db_t * | db, | |
ham_txn_t * | txn, | |||
ham_u32_t | flags, | |||
ham_cursor_t ** | cursor | |||
) |
Creates a Database Cursor
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.
db | A valid Database handle | |
txn | A Transaction handle, or NULL | |
flags | Optional flags for creating the Cursor; unused, set to 0 | |
cursor | A pointer to a pointer which is allocated for the new Cursor handle |
Referenced by copy_db(), ham::cursor::create(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_erase | ( | ham_cursor_t * | cursor, | |
ham_u32_t | flags | |||
) |
Erases the current key
Erases a key from the Database. If the erase was successful, 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 HAM_ENABLE_DUPLICATES, this function erases only the duplicate item to which the Cursor refers.
cursor | A valid Cursor handle | |
flags | Unused, set to 0 |
Referenced by ham::cursor::erase().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_find | ( | ham_cursor_t * | cursor, | |
ham_key_t * | key, | |||
ham_u32_t | flags | |||
) |
Searches a key and points the Cursor to this key
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.
Note that ham_cursor_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.
When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.
When either or both HAM_FIND_LT_MATCH and/or HAM_FIND_GT_MATCH have been specified as flags, the key structure will be overwritten when an approximate match was found: the key and record structures will then point at the located key (and record). In this case the caller should ensure key points at a structure which must adhere to the same restrictions and conditions as specified for ham_cursor_move(...,HAM_CURSOR_*): key->data will point to temporary data upon return. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour.
Further note that the key structure must be non-const at all times as its internal flag bits may be written to. This is done for your benefit, as you may pass the returned key structure to ham_key_get_approximate_match_type() to retrieve additional info about the precise nature of the returned key: the sign value produced by ham_key_get_approximate_match_type() tells you which kind of match (equal, less than, greater than) occurred. This is very useful to discern between the various possible successful answers produced by the combinations of HAM_FIND_LT_MATCH, HAM_FIND_GT_MATCH and/or HAM_FIND_EXACT_MATCH.
cursor | A valid Cursor handle | |
key | A pointer to a ham_key_t structure. If this pointer is not NULL, the key of the new item is returned. Note that key->data will point to temporary data. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour. | |
flags | Optional flags for searching, which can be combined with bitwise OR. Possible flags are:
|
Remark For Approximate Matching the returned match will either match the key exactly or is either the first key available above or below the given key when an exact match could not be found; 'find' does NOT spend any effort, in the sense of determining which of both is the 'nearest' to the given key, when both a key above and a key below the one given exist; 'find' will simply return the first of both found. As such, this flag is the simplest possible combination of the combined HAM_FIND_LEQ_MATCH and HAM_FIND_GEQ_MATCH flags.
Note that these flags may be bitwise OR-ed to form functional combinations.
HAM_FIND_LEQ_MATCH, HAM_FIND_GEQ_MATCH and HAM_FIND_NEAR_MATCH are themselves shorthands created using the bitwise OR operation like this:
Referenced by ham::cursor::find(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_find_ex | ( | ham_cursor_t * | cursor, | |
ham_key_t * | key, | |||
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Searches with a key and points the Cursor to the key found, retrieves the located record
This function is identical to ham_cursor_find, but it immediately retrieves the located record if the lookup operation was successful.
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.
Note that ham_cursor_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.
When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.
You can read only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will read record->partial_size bytes of the record data at offset record->partial_offset. If necessary, the record data will be limited to the original record size. The number of actually read bytes is returned in record->size.
When either or both HAM_FIND_LT_MATCH and/or HAM_FIND_GT_MATCH have been specified as flags, the key structure will be overwritten when an approximate match was found: the key and record structures will then point at the located key (and record). In this case the caller should ensure key points at a structure which must adhere to the same restrictions and conditions as specified for ham_cursor_move(...,HAM_CURSOR_*): key->data will point to temporary data upon return. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour.
Further note that the key structure must be non-const at all times as its internal flag bits may be written to. This is done for your benefit, as you may pass the returned key structure to ham_key_get_approximate_match_type() to retrieve additional info about the precise nature of the returned key: the sign value produced by ham_key_get_approximate_match_type() tells you which kind of match (equal, less than, greater than) occurred. This is very useful to discern between the various possible successful answers produced by the combinations of HAM_FIND_LT_MATCH, HAM_FIND_GT_MATCH and/or HAM_FIND_EXACT_MATCH.
cursor | A valid Cursor handle | |
key | A pointer to a ham_key_t structure. If this pointer is not NULL, the key of the new item is returned. Note that key->data will point to temporary data. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour. | |
record | A pointer to a ham_record_t structure. If this pointer is not NULL, the record of the new item is returned. Note that record->data will point to temporary data. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_RECORD_USER_ALLOC on how to change this behaviour. | |
flags | Optional flags for searching, which can be combined with bitwise OR. Possible flags are:
|
Remark For Approximate Matching the returned match will either match the key exactly or is either the first key available above or below the given key when an exact match could not be found; 'find' does NOT spend any effort, in the sense of determining which of both is the 'nearest' to the given key, when both a key above and a key below the one given exist; 'find' will simply return the first of both found. As such, this flag is the simplest possible combination of the combined HAM_FIND_LEQ_MATCH and HAM_FIND_GEQ_MATCH flags.
Note that these flags may be bitwise OR-ed to form functional combinations.
HAM_FIND_LEQ_MATCH, HAM_FIND_GEQ_MATCH and HAM_FIND_NEAR_MATCH are themselves shorthands created using the bitwise OR operation like this:
Referenced by ham::cursor::find_ex().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_get_duplicate_count | ( | ham_cursor_t * | cursor, | |
ham_size_t * | count, | |||
ham_u32_t | flags | |||
) |
Gets the number of duplicate keys
Returns the number of duplicate keys of the item to which the Cursor currently refers. Returns 1 if the key has no duplicates.
cursor | A valid Cursor handle | |
count | Returns the number of duplicate keys | |
flags | Optional flags; unused, set to 0. |
Referenced by ham::cursor::get_duplicate_count().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_insert | ( | ham_cursor_t * | cursor, | |
ham_key_t * | key, | |||
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Inserts a Database item and points the Cursor to the inserted item
This function inserts a key/record pair as a new Database item. If the key already exists in the Database, error HAM_DUPLICATE_KEY is returned.
If you wish to overwrite an existing entry specify the flag HAM_OVERWRITE. The use of this flag is not allowed in combination with HAM_DUPLICATE.
If you wish to insert a duplicate key specify the flag HAM_DUPLICATE. (Note that the Database has to be created with HAM_ENABLE_DUPLICATES, in order to use duplicate keys.) By default, the duplicate key is inserted after all other duplicate keys (see HAM_DUPLICATE_INSERT_LAST). This behaviour can be overwritten by specifying HAM_DUPLICATE_INSERT_FIRST, HAM_DUPLICATE_INSERT_BEFORE or HAM_DUPLICATE_INSERT_AFTER.
You can write only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will write partial_size bytes of the record data at offset partial_offset. If necessary, the record data will grow. Gaps will be filled with null-bytes, if the record did not yet exist. Using HAM_PARTIAL is not allowed in combination with sorted duplicates (HAM_SORT_DUPLICATES).
However, if a sort order is specified (see HAM_SORT_DUPLICATES) then the key is inserted in sorted order. In this case, the use of HAM_DUPLICATE_INSERT_FIRST, HAM_DUPLICATE_INSERT_LAST, HAM_DUPLICATE_INSERT_BEFORE and HAM_DUPLICATE_INSERT_AFTER is not allowed and will return HAM_INV_PARAMETER.
Specify the flag HAM_HINT_APPEND if you insert sequential data and the current key is higher than any other key in this Database. In this case hamsterdb will optimize the insert algorithm. hamsterdb 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 HAM_HINT_PREPEND if you insert sequential data and the current key is lower than any other key in this Database. In this case hamsterdb will optimize the insert algorithm. hamsterdb 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.
Record Number Databases (created with HAM_RECORD_NUMBER) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag HAM_KEY_USER_ALLOC, a size of 8 and a valid data pointer). If key.size is 0 and key.data is NULL, hamsterdb will temporarily allocate memory for key->data, which will then point to an 8-byte unsigned integer in host-endian.
cursor | A valid Cursor handle | |
key | A valid key structure | |
record | A valid record structure | |
flags | Optional flags for inserting the item, combined with bitwise OR. Possible flags are:
|
Referenced by ham::cursor::insert().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_move | ( | ham_cursor_t * | cursor, | |
ham_key_t * | key, | |||
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Moves the Cursor
Moves the Cursor. Use the flags to specify the direction. After the move, key and record of the item are returned, if key and/or record are valid pointers.
If the direction is not specified, the Cursor will not move. Do not specify a direction if you want to fetch the key and/or record of the current item.
When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.
You can write only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will write partial_size bytes of the record data at offset partial_offset. The full record size will always be given in record->size! If partial_size+partial_offset exceed record->size then partial_size will be limited. To shrink or grow the record, adjust record->size. HAM_PARTIAL automatically overwrites existing records. Gaps will be filled with null-bytes if the record did not yet exist. Using HAM_PARTIAL is not allowed in combination with sorted duplicates (HAM_SORT_DUPLICATES).
cursor | A valid Cursor handle | |
key | An optional pointer to a ham_key_t structure. If this pointer is not NULL, the key of the new item is returned. Note that key->data will point to temporary data. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour. | |
record | An optional pointer to a ham_record_t structure. If this pointer is not NULL, the record of the new item is returned. Note that record->data will point to temporary data. This pointer will be invalidated by subsequent hamsterdb API calls. See HAM_RECORD_USER_ALLOC on how to change this behaviour. | |
flags | The flags for this operation. They are used to specify the direction for the "move". If you do not specify a direction, the Cursor will remain on the current position.
|
Referenced by copy_db(), main(), and ham::cursor::move().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_overwrite | ( | ham_cursor_t * | cursor, | |
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Overwrites the current record
This function overwrites the record of the current item.
The use of this function is not allowed if the item has duplicate keys and the duplicate sorting is enabled (see HAM_SORT_DUPLICATES). In this case, HAM_INV_PARAMETER is returned.
cursor | A valid Cursor handle | |
record | A valid record structure | |
flags | Optional flags for overwriting the item; unused, set to 0 |
Referenced by ham::cursor::overwrite().