dbsp::trace::cursor

Trait Cursor

pub trait Cursor<K: ?Sized, V: ?Sized, T, R: ?Sized> {
Show 36 methods    // Required methods
    fn weight_factory(&self) -> &'static dyn Factory<R>;
    fn key_valid(&self) -> bool;
    fn val_valid(&self) -> bool;
    fn key(&self) -> &K;
    fn val(&self) -> &V;
    fn map_times(&mut self, logic: &mut dyn FnMut(&T, &R));
    fn map_times_through(&mut self, upper: &T, logic: &mut dyn FnMut(&T, &R));
    fn weight(&mut self) -> &R
       where T: PartialEq<()>;
    fn weight_checked(&mut self) -> &R;
    fn map_values(&mut self, logic: &mut dyn FnMut(&V, &R))
       where T: PartialEq<()>;
    fn step_key(&mut self);
    fn step_key_reverse(&mut self);
    fn seek_key(&mut self, key: &K);
    fn seek_key_exact(&mut self, key: &K, hash: Option<u64>) -> bool;
    fn seek_key_with(&mut self, predicate: &dyn Fn(&K) -> bool);
    fn seek_key_with_reverse(&mut self, predicate: &dyn Fn(&K) -> bool);
    fn seek_key_reverse(&mut self, key: &K);
    fn step_val(&mut self);
    fn step_val_reverse(&mut self);
    fn seek_val(&mut self, val: &V);
    fn seek_val_reverse(&mut self, val: &V);
    fn seek_val_with(&mut self, predicate: &dyn Fn(&V) -> bool);
    fn seek_val_with_reverse(&mut self, predicate: &dyn Fn(&V) -> bool);
    fn rewind_keys(&mut self);
    fn fast_forward_keys(&mut self);
    fn rewind_vals(&mut self);
    fn fast_forward_vals(&mut self);
    fn position(&self) -> Option<Position>;

    // Provided methods
    fn get_key(&self) -> Option<&K> { ... }
    fn get_val(&self) -> Option<&V> { ... }
    fn keyval_valid(&self) -> bool { ... }
    fn keyval(&self) -> (&K, &V) { ... }
    fn step_keyval(&mut self) { ... }
    fn step_keyval_reverse(&mut self) { ... }
    fn seek_keyval(&mut self, key: &K, val: &V)
       where K: PartialEq { ... }
    fn seek_keyval_reverse(&mut self, key: &K, val: &V)
       where K: PartialEq { ... }
}

Expand description

A cursor for (key, val, time, diff) tuples.

A cursor navigates an ordered collection of (key, val, time, diff) tuples in order by key, then by value within each key. In the time-diff pairs associated with each key-value pair, the times may not be ordered or unique and, in particular, CursorList cursors can contain out-of-order and duplicate timestamps. Because duplicate times are possible, it’s possible to have multiple diffs even when T = ().

Cursors are not iterators because they allow navigation on multiple levels (by key and value) and because they support efficient seeking (via seek_key and seek_val).

§Visiting keys

A cursor visits keys in forward or reverse order, which is set as a mode. Initially, a cursor is in the forward mode, positioned on the first key (if the collection is non-empty). A cursor in the forward mode can move and seek forward with, e.g., step_key and seek_key, but not backward. The direction can be reversed using fast_forward_keys, after which the cursor can move and seek backward only, e.g. with step_key_reverse and seek_key_reverse. The client may call rewind_keys and fast_forward_keys as many times as necessary to reposition the cursor to the first or last key in the forward or reverse mode, respectively.

A cursor can have a valid position on a key or an invalid position after the last key (in the forward mode) or before the first key (in the reverse mode). A cursor for an empty collection of tuples does not have any valid key positions.

§Visiting values within a key

A cursor also visits values in a forward or reverse order. Whenever a cursor moves to a new key, its value mode is reset to forward order and its value position is set to the first value in the key. This is true even if the cursor is visiting keys in reverse order. In forward order mode, the cursor can move and seek forward within the values, e.g. with step_val and seek_val, but not backward. The value direction may be reversed with fast_forward_vals, after which the cursor may move and seek only backward within the values, e.g. with step_val_reverse and seek_val_reverse. The client may call rewind_vals and fast_forward_vals as many times as necessary to reposition the cursor to the first or last value in the forward or reverse mode, respectively.

A cursor with a valid key position can have a valid value position on a value or an invalid value position after the last value (in forward mode) or before the first value (in reverse mode).

Every key in a nonempty collection has at least one value.

§Example

The following is typical code for iterating through all of the key-value pairs navigated by a cursor:

let cursor = ...obtain cursor...;
while cursor.key_valid() {
    while cursor.val_valid() {
        /// Do something with the current key-value pair.
        cursor.step_val();
    }
    cursor.step_key();
}

Required Methods§

Source

fn weight_factory(&self) -> &'static dyn Factory<R>

Source

fn key_valid(&self) -> bool

Indicates if the current key is valid.

A value of false indicates that the cursor has exhausted all keys.

Source

fn val_valid(&self) -> bool

Indicates if the current value is valid.

A value of false indicates that the cursor has exhausted all values for this key.

Source

fn key(&self) -> &K

A reference to the current key. Panics if invalid.

Source

fn val(&self) -> &V

A reference to the current value. Panics if invalid.

Source

fn map_times(&mut self, logic: &mut dyn FnMut(&T, &R))

Applies logic to each pair of time and difference. Intended for mutation of the closure’s scope.

Source

fn map_times_through(&mut self, upper: &T, logic: &mut dyn FnMut(&T, &R))

Applies logic to each pair of time and difference, restricted to times t <= upper.

Source

fn weight(&mut self) -> &R
where T: PartialEq<()>,

Returns the weight associated with the current key/value pair. This concept only makes sense for cursors with unit timestamp type (T=()), since otherwise there is no singular definition of weight. This method is more convenient, and may be more efficient, than the equivalent call to Self::map_times.

If the current key and value are not valid, behavior is unspecified.

Source

fn weight_checked(&mut self) -> &R

Returns the weight associated with the current key/value pair is T is (); panics otherwise.

Can be used in contexts where the weight is known to be () at runtime, but not at compile time. This is more efficient and ergonomic than using Self::map_times to compute the weight.

§Panics

Panics if the T is not ().

Source

fn map_values(&mut self, logic: &mut dyn FnMut(&V, &R))
where T: PartialEq<()>,

Apply a function to all values associated with the current key.

Source

fn step_key(&mut self)

Advances the cursor to the next key.

Source

fn step_key_reverse(&mut self)

Moves the cursor to the previous key.

Source

fn seek_key(&mut self, key: &K)

Advances the cursor to the specified key. If key itself is not present, advances to the first key greater than key; if there is no such key, the cursor becomes invalid.

This has no effect if the cursor is already positioned past key, so it might be desirable to call rewind_keys first.

Source

fn seek_key_exact(&mut self, key: &K, hash: Option<u64>) -> bool

Looks up the specified key and returns true if it is present.

The implementation can be more efficient than seek_key.

This method has several constraints.

It cannot be mixed with other seek and step methods, specifically, you cannot call seek_key, seek_key_with, seek_key_with_reverse, seek_key_reverse, step_key, step_key_reverse on the cursor if you also use seek_key_exact on it without first resetting this cursor using rewind_keys or fast_forward_keys.
When calling seek_key_exact multiple times on the cursor, every next call must be for a key that is greater than the previous key.

Source

fn seek_key_with(&mut self, predicate: &dyn Fn(&K) -> bool)

Advances the cursor to the first key that satisfies predicate. Assumes that predicate remains true once it turns true.

Source

fn seek_key_with_reverse(&mut self, predicate: &dyn Fn(&K) -> bool)

Move the cursor backward to the first key that satisfies predicate. Assumes that predicate remains true once it turns true.

Source

fn seek_key_reverse(&mut self, key: &K)

Moves the cursor backward to the specified key. If key itself is not present, moves backward to the first key less than key; if there is no such key, the cursor becomes invalid.

Source