composable-indexes 0.9.0

In-memory collections with composable indexes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

pub use super::Key;

/// Seal type to restrict modification of indexes outside
/// of the [`crate::Collection`] API.
///
/// If you are writing tests and need to create a seal,
/// you can use the `unsafe_mk_seal` function under the
/// `testutils` feature flag.
#[derive(Clone, Copy)]
pub struct Seal {
    _seal: (),
}

pub(crate) const SEAL: Seal = Seal { _seal: () };

impl Seal {
    #[cfg(feature = "testutils")]
    pub fn unsafe_mk_seal() -> Self {
        Seal { _seal: () }
    }
}

/// Types that can be used as indexes in a [`crate::Collection`].
///
/// An index processes items of type `T` - and can be accessed through the
/// [`crate::Collection::query`]-family of methods to expose queries over the
/// indexed data.
///
/// You should only need to know about this trait if you are implementing a
/// custom index.
///
/// # Implementing an Index
///
/// An [`Index`] receives insertions, removals, and updates of items of type `T`,
/// and maintains some internal state to answer queries about the indexed data.
///
/// Indexes must (minimally) handle insertion and removal of items. (Update
/// operation has a default implementation that calls remove followed by insert;
/// override it if a more efficient implementation is possible.)
///
/// All trait functions receive a `Seal` parameter that prevents external code
/// from calling them directly. You can safely ignore this parameter.
///
/// All operations receive an operation struct (`Insert`, `Remove`, or `Update`)
/// [`Insert`] guarantees that the key did not previously exists, [`Remove`] and
/// [`Update`] guarantee carry a pointer to the existing value. This usually
/// allows for more efficient implementations.
///
/// The queries themselves are not part of this trait - they are implemented
/// as inherent on the index type itself.
pub trait Index<T> {
    fn insert(&mut self, seal: Seal, op: &Insert<T>);

    fn remove(&mut self, seal: Seal, op: &Remove<T>);

    #[inline]
    fn update(&mut self, seal: Seal, op: &Update<T>) {
        self.remove(
            seal,
            &Remove {
                key: op.key,
                existing: op.existing,
            },
        );
        self.insert(
            seal,
            &Insert {
                key: op.key,
                new: op.new,
            },
        );
    }
}

#[derive(Clone)]
pub struct Insert<'t, In> {
    pub key: Key,
    pub new: &'t In,
}

#[derive(Clone)]
pub struct Update<'t, In> {
    pub key: Key,
    pub new: &'t In,
    pub existing: &'t In,
}

#[derive(Clone)]
pub struct Remove<'t, In> {
    pub key: Key,
    pub existing: &'t In,
}