nimiq_database/traits/
cursor.rs

1use super::{DupSubKey, DupTable, DupTableValue, Row, Table};
2
3/// A cursor is used for navigating the entries within a table.
4/// The read-only version cannot modify entries.
5///
6/// Closely follows `libmdbx`'s [cursor API](https://docs.rs/libmdbx/latest/libmdbx/struct.Cursor.html).
7pub trait ReadCursor<'txn, T: Table>: Clone {
8    type IntoIter: Iterator<Item = Row<T>>;
9
10    /// Positions the cursor at the first entry in the table.
11    fn first(&mut self) -> Option<Row<T>>;
12
13    /// Positions the cursor at the last entry in the table.
14    fn last(&mut self) -> Option<Row<T>>;
15
16    /// Positions the cursor at the next entry in the table.
17    /// For a `DupTable`, this can be either the next duplicate for the current key
18    /// or the first duplicate for the next key.
19    fn next(&mut self) -> Option<Row<T>>;
20
21    /// Positions the cursor at the previous entry in the table.
22    /// For a `DupTable`, this can be either the next duplicate for the current key
23    /// or the first duplicate for the next key.
24    fn prev(&mut self) -> Option<Row<T>>;
25
26    /// Returns the current entry at the cursor position.
27    fn get_current(&mut self) -> Option<Row<T>>;
28
29    /// Positions the cursor at the entry that has a key == `key`.
30    /// Previously `seek_key`.
31    fn set_key(&mut self, key: &T::Key) -> Option<T::Value>;
32
33    /// Positions the cursor at the first entry that has a key >= `key`.
34    /// Previously `seek_range_key`.
35    fn set_lowerbound_key(&mut self, key: &T::Key) -> Option<Row<T>>;
36
37    /// Iterates over all entries in the table.
38    fn into_iter_start(self) -> Self::IntoIter;
39
40    /// Iterates over all entries in the table starting from a given key.
41    fn into_iter_from(self, key: &T::Key) -> Self::IntoIter;
42}
43
44pub trait DupReadCursor<'txn, T: DupTable>: ReadCursor<'txn, T> {
45    /// Positions the cursor at the first duplicate value for the current key.
46    fn first_duplicate(&mut self) -> Option<T::Value>;
47
48    /// Positions the cursor at the last duplicate value for the current key.
49    fn last_duplicate(&mut self) -> Option<T::Value>;
50
51    /// Positions the cursor at the next duplicate value for the current key.
52    /// This does not jump keys.
53    fn next_duplicate(&mut self) -> Option<Row<T>>;
54
55    /// Positions the cursor at the first duplicate of the next key.
56    fn next_no_duplicate(&mut self) -> Option<Row<T>>;
57
58    /// Positions the cursor at the previous duplicate value for the current key.
59    fn prev_duplicate(&mut self) -> Option<Row<T>>;
60
61    /// Positions the cursor at the last duplicate of the previous key.
62    fn prev_no_duplicate(&mut self) -> Option<Row<T>>;
63
64    /// Positions the cursor at the entry with a given key and subkey.
65    fn set_subkey(&mut self, key: &T::Key, subkey: &DupSubKey<T>) -> Option<T::Value>
66    where
67        T::Value: DupTableValue;
68
69    /// Positions the cursor at the first duplicate entry that has a key >= `key` && subkey >= `subkey`.
70    fn set_lowerbound_both(&mut self, key: &T::Key, subkey: &DupSubKey<T>) -> Option<Row<T>>
71    where
72        T::Value: DupTableValue;
73
74    /// Positions the cursor at the first duplicate entry that has a key == `key` && subkey >= `subkey`.
75    fn set_lowerbound_subkey(&mut self, key: &T::Key, subkey: &DupSubKey<T>) -> Option<T::Value>
76    where
77        T::Value: DupTableValue;
78
79    /// Counts the number of duplicates (linear operation!).
80    fn count_duplicates(&mut self) -> usize;
81
82    /// Iterates over all duplicates of the given key.
83    fn into_iter_dup_of(self, key: &T::Key) -> Self::IntoIter;
84}
85
86/// A cursor is used for navigating the entries within a table.
87/// The read-write version can also delete entries.
88///
89/// Closely follows `libmdbx`'s [cursor API](https://docs.rs/libmdbx/0.3.3/libmdbx/struct.Cursor.html).
90pub trait WriteCursor<'txn, T: Table>: ReadCursor<'txn, T> {
91    /// Puts a new entry into the database.
92    /// The cursor will be positioned on the new entry.
93    fn put(&mut self, key: &T::Key, value: &T::Value);
94
95    /// Appends a key/value pair to the end of the database.
96    /// This operation fails if the key is less than the last key.
97    fn append(&mut self, key: &T::Key, value: &T::Value);
98
99    /// Removes the current entry from the database.
100    /// For a `DupTable`, this removes the current duplicate value.
101    fn remove(&mut self);
102}
103
104pub trait DupWriteCursor<'txn, T: DupTable>: WriteCursor<'txn, T> + DupReadCursor<'txn, T> {
105    /// Appends a key/value pair to the end of the database.
106    /// This operation fails if the key is less than the last key.
107    fn append_dup(&mut self, key: &T::Key, value: &T::Value);
108
109    /// Removes all duplicate values for the current key.
110    fn remove_all_dup(&mut self);
111}
nimiq_database/traits/cursor.rs

nimiq_database/traits/
cursor.rs
