Skip to main content

ic_storage/adapter/
set.rs

1//! Governed set collection implementation.
2use super::{Memory, SetIter, Storable};
3use crate::{DefaultMemoryImpl, RuntimeMemory, substrate};
4use std::ops::RangeBounds;
5
6/// Governed upstream `BTreeSet`; initialization and failures follow upstream contracts.
7pub struct StableBTreeSet<K: Storable + Ord + Clone, M: Memory = DefaultMemoryImpl> {
8    inner: substrate::BTreeSet<K, RuntimeMemory<M>>,
9}
10
11impl<K: Storable + Ord + Clone, M: Memory> StableBTreeSet<K, M> {
12    /// Create a collection only in zero-page memory.
13    ///
14    /// # Panics
15    /// Refuses nonempty memory before writing. Growth and codec failures retain
16    /// upstream behavior.
17    #[must_use]
18    pub fn create(memory: RuntimeMemory<M>) -> Self {
19        assert_eq!(memory.size(), 0, "collection memory is not empty");
20        Self::reset(memory)
21    }
22
23    /// Deliberately replace any contents in this admitted allocation.
24    ///
25    /// # Panics
26    /// Growth and codec failures retain upstream behavior.
27    #[must_use]
28    pub fn reset(memory: RuntimeMemory<M>) -> Self {
29        Self {
30            inner: substrate::BTreeSet::new(memory),
31        }
32    }
33
34    /// Load retained collection state without initializing a replacement.
35    ///
36    /// # Panics
37    /// Refuses empty or foreign memory and incompatible layouts/bounds without
38    /// writing. Record decoding and backing failures retain upstream behavior.
39    #[must_use]
40    pub fn load(memory: RuntimeMemory<M>) -> Self {
41        Self {
42            inner: substrate::BTreeSet::load(memory),
43        }
44    }
45
46    /// Delegates to upstream `BTreeSet::insert` with the governed allocation.
47    pub fn insert(&mut self, key: K) -> bool {
48        self.inner.insert(key)
49    }
50
51    /// Delegates to upstream `BTreeSet::contains` with the governed allocation.
52    pub fn contains(&self, key: &K) -> bool {
53        self.inner.contains(key)
54    }
55
56    /// Delegates to upstream `BTreeSet::is_empty` with the governed allocation.
57    #[must_use]
58    pub fn is_empty(&self) -> bool {
59        self.inner.is_empty()
60    }
61
62    /// Delegates to upstream `BTreeSet::len` with the governed allocation.
63    #[must_use]
64    pub fn len(&self) -> u64 {
65        self.inner.len()
66    }
67
68    /// Delegates to upstream `BTreeSet::remove` with the governed allocation.
69    pub fn remove(&mut self, key: &K) -> bool {
70        self.inner.remove(key)
71    }
72
73    /// Delegates to upstream `BTreeSet::first` with the governed allocation.
74    #[must_use]
75    pub fn first(&self) -> Option<K> {
76        self.inner.first()
77    }
78
79    /// Delegates to upstream `BTreeSet::last` with the governed allocation.
80    #[must_use]
81    pub fn last(&self) -> Option<K> {
82        self.inner.last()
83    }
84
85    /// Delegates to upstream `BTreeSet::pop_first` with the governed allocation.
86    pub fn pop_first(&mut self) -> Option<K> {
87        self.inner.pop_first()
88    }
89
90    /// Delegates to upstream `BTreeSet::pop_last` with the governed allocation.
91    pub fn pop_last(&mut self) -> Option<K> {
92        self.inner.pop_last()
93    }
94
95    /// Delegates to upstream `BTreeSet::iter` with the governed allocation.
96    #[must_use]
97    pub fn iter(&self) -> SetIter<'_, K, M> {
98        self.inner.iter()
99    }
100
101    /// Delegates to upstream `BTreeSet::range` with the governed allocation.
102    pub fn range(&self, key_range: impl RangeBounds<K>) -> SetIter<'_, K, M> {
103        self.inner.range(key_range)
104    }
105
106    /// Delegates to upstream `BTreeSet::clear` with the governed allocation.
107    pub fn clear(&mut self) {
108        self.inner.clear();
109    }
110}
111
112impl<'a, K: Storable + Ord + Clone, M: Memory> IntoIterator for &'a StableBTreeSet<K, M> {
113    type Item = K;
114    type IntoIter = SetIter<'a, K, M>;
115    fn into_iter(self) -> Self::IntoIter {
116        self.iter()
117    }
118}