unc_sdk/store/
mod.rs

1//! Collections and types used when interacting with storage.
2//!
3//! These collections are more scalable versions of [`std::collections`] when used as contract
4//! state because it allows values to be lazily loaded and stored based on what is actually
5//! interacted with.
6//!
7//! Fundamentally, a contract's storage is a key/value store where both keys and values are just
8//! [`Vec<u8>`]. If you want to store some structured data, for example, [`Vec<Account>`], one way
9//! to achieve that would be to serialize the Vec to bytes and store that. This has a drawback in
10//! that accessing or modifying a single element would require reading the whole `Vec` from the
11//! storage.
12//!
13//! That's where `store` module helps. Its collections are backed by a key value store.
14//! For example, a store::Vector is stored as several key-value pairs, where indices are the keys.
15//! So, accessing a single element would only load this specific element.
16//!
17//! It can be expensive to load all values into memory, and because of this, `serde`
18//! [`Serialize`](serde::Serialize) and [`Deserialize`](serde::Deserialize) traits are
19//! intentionally not implemented. If you want to return all values from a storage collection from
20//! a function, consider using pagination with the collection iterators.
21//!
22//! All of the collections implement [`BorshSerialize`](borsh::BorshSerialize) and
23//! [`BorshDeserialize`](borsh::BorshDeserialize) to be able to store the metadata of the
24//! collections to be able to access all values. Because only metadata is serialized, these
25//! structures should not be used as a borsh return value from a function.
26//!
27//! The collections are as follows:
28//!
29//! Sequences:
30//!
31//! - [`Vector`]: Analogous to [`Vec`] but not contiguous and persisted to storage.
32//!
33//! Maps:
34//!
35//! - [`LookupMap`]: Wrapper around key-value storage interactions, similar to
36//! [`UnorderedMap`]/[`std::collections::HashMap`] except that keys are not persisted and cannot be
37//! iterated over.
38//!
39//! - [`UnorderedMap`]: Storage version of [`std::collections::HashMap`]. No ordering
40//! guarantees.
41//!
42//! - [`TreeMap`](TreeMap) (`unstable`): Storage version of [`std::collections::BTreeMap`]. Ordered by key,
43//! which comes at the cost of more expensive lookups and iteration.
44//!
45//! Sets:
46//!
47//! - [`LookupSet`]: Non-iterable storage version of [`std::collections::HashSet`].
48//!
49//! - [`UnorderedSet`]: Analogous to [`std::collections::HashSet`], and is an iterable
50//! version of [`LookupSet`] and persisted to storage.
51//!
52//! Basic Types:
53//!
54//! - [`Lazy<T>`](Lazy): Lazily loaded type that can be used in place of a type `T`.
55//! Will only be loaded when interacted with and will persist on [`Drop`].
56//!
57//! - [`LazyOption<T>`](LazyOption): Lazily loaded, optional type that can be used in
58//! place of a type [`Option<T>`](Option). Will only be loaded when interacted with and will
59//! persist on [`Drop`].
60
61#[cfg(feature = "unstable")]
62mod lazy;
63#[cfg(feature = "unstable")]
64pub use lazy::Lazy;
65
66#[cfg(feature = "unstable")]
67mod lazy_option;
68#[cfg(feature = "unstable")]
69pub use lazy_option::LazyOption;
70
71pub mod vec;
72pub use vec::Vector;
73
74pub mod lookup_map;
75pub use self::lookup_map::LookupMap;
76
77mod lookup_set;
78pub use self::lookup_set::LookupSet;
79
80pub mod iterable_map;
81pub use self::iterable_map::IterableMap;
82pub mod iterable_set;
83pub use self::iterable_set::IterableSet;
84pub mod unordered_map;
85#[allow(deprecated)]
86pub use self::unordered_map::UnorderedMap;
87
88pub mod unordered_set;
89#[allow(deprecated)]
90pub use self::unordered_set::UnorderedSet;
91
92#[cfg(feature = "unstable")]
93pub mod tree_map;
94#[cfg(feature = "unstable")]
95pub use self::tree_map::TreeMap;
96
97mod index_map;
98pub(crate) use self::index_map::IndexMap;
99
100pub(crate) mod free_list;
101pub(crate) use self::free_list::FreeList;
102
103/// Storage key hash function types and trait to override map hash functions.
104pub mod key;
105
106pub(crate) const ERR_INCONSISTENT_STATE: &str =
107    "The collection is in an inconsistent state. Did previous smart \
108        contract execution terminate unexpectedly?";
109
110pub(crate) const ERR_NOT_EXIST: &str = "Key does not exist in map";
unc_sdk/store/mod.rs

unc_sdk/store/
mod.rs
