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}