Itzam Core

C API Documentation (Index Iterators)



 

Itzam/Core 4.0.7 Download: (tar.gz) (bzip2) (zip) Open Source License (GPL) Non-free, Closed-Source License: $749 Itzam/Java 2.1.1 Download: (source) (extension) Open Source License (GPL) Non-free, Closed-Source License: $749 Documents Itzam Home Page C API Documentation Java Class Documentation

Index

General Types & Functions
Datafiles
About Keys
B-tree Indexes
B-tree Index Cursors
Hash Indexes
Sparse Matrix Indexes
 

An itzam_btree_iterator is a list of the records in a database, and can be traversed in key order. It does not store records; instead, it is a forward and backward traversable list of records in order (as defined by the database's key comparison function.)

When you create an itzam_btree_iterator, it represents the current state of the itzam_btree. Changes to the index, especially adding or removing keys, will not be reflected in existing iterators. As with threading, you need to ensure that you either prevent index changes during the lifetime of an iterator, or that you get a new iterator after changes have been made. Higher-level abstractions in C++ or Python will automatically track iterators and provide index locking; Itzam Core is, however, a low-level tool, and should be treated like memory allocation in terms of caution.

Philosophically, an itzam_btree_iterator is similar to a traditional database cursor. You can also treat it like a query, filtering records as your traverse the list.

All functions that directly manipulate b-tree iterators follow the naming pattern itzam_btree_iterator_*.

Types and Structures

itzam_btree_iterator

This structure maintains a linked list of key and record pairs. It contains a pointer to the btree for which it was created, so that it can retrieve records via the convenience functions described below.

typedef struct
{
    // No externally useful members
}
itzam_btree_iterator;

itzam_key_selector

An index iterator uses a selector to choose the indexes it will include in its list. The user defines and supplies a selector function pointer when opening or creating an iterator; the function's signature must match this type definition.

typedef bool itzam_key_selector(const void * key);

Parameters
btree - a pointer to the target itzam_btree structure
filename - the platform-specific name of the file to be created
key_comparator - a function that compares two index keys

Return Value
true, if key should be included in the iterator list
false, if key should not be included in the iterator list

Functions

itzam_btree_iterator_create

Creates a new iterator for the given index. When created, an iterator points to the first record in its sequence. The caller is responsible for calling itzam_btree_iterator_free for every iterator created.

With version 1.1, Itzam supports the concepts of a "selector" function that returns true or false to determine whether or not a key is included in the iterator. The selector acts as a filter to define a subset of the keys in an index; for example, a selector function could return true only for string-keys that begin with "S". The stress_btree test program includes a selector that selects all odd numeric keys.

void itzam_btree_iterator_create(itzam_btree * btree,
                                 itzam_btree_iterator * iterator,
                                 itzam_key_selector * selector);

Parameters
btree - a pointer to the target itzam_btree structure
iterator - a pointer to the target itzam_btree_iterator structure
selector - a pointer to a itzam_key_selector function, or NULL is all keys are to be included in the iterator

Return Value
None

itzam_btree_iterator_count

Returns the number of records listed in the given iterator.

itzam_int itzam_btree_iterator_count(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
The number of records referenced by this iterator.

itzam_btree_iterator_read_rec

Reads the record associated with the current value of the iterator.

itzam_state itzam_btree_iterator_read_rec(itzam_btree_iterator * iterator,
                                          void * record,
                                          itzam_ref max_rec_len);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure
record - a buffer of at least max_rec_len bytes
max_rec_len - the number of bytes that can be stored in record

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_btree_iterator_get_data_ref

Returns the file pointer for the record at the current iterator position.

itzam_ref itzam_btree_iterator_get_data_ref(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
A file pointer for the data record currently referenced by iterator.

itzam_btree_iterator_get_key_ref

Returns the file pointer for the key data at the current iterator position.

itzam_ref itzam_btree_iterator_get_key_ref(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
A pointer to the key record currently referenced by iterator.

itzam_btree_iterator_move_prev

Move to the previous record in sequence. If the position is at the beginning of the list, it returns ITZAM_AT_BEGIN.

itzam_state itzam_btree_iterator_move_prev(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_AT_BEGIN if the iterator is already at the beginning of the list
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_btree_iterator_move_next

Move to the previous record in sequence. If the position is at the beginning of the list, it returns ITZAM_AT_END.

itzam_state itzam_btree_iterator_move_next(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_AT_BEGIN if the iterator is already at the end of the list
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_btree_iterator_move_first

Move the iterator to the first record in the list.

void itzam_btree_iterator_move_first(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
None

itzam_btree_iterator_move_last

Move the iterator to the last record in the list.

void itzam_btree_iterator_move_last(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
None

itzam_btree_iterator_free

Free memory allocated to this iterator. You must do this for every iterator created, or memory will be wasted.

void itzam_btree_iterator_free(itzam_btree_iterator * iterator);

Parameters
iterator - a pointer to the target itzam_btree_iterator structure

Return Value
None