canic-memory 0.27.3

Canic — a canister orchestration and management toolkit for the Internet Computer
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Derive `ic-stable-structures` storage traits using CBOR serialization.
//!
//! The helper macros below wire types into the Canister Development Kit's
//! `Storable` trait by delegating to Canic's CBOR helpers. The bounded
//! variant requires callers to specify a maximum serialized size and whether
//! the size is fixed; the unbounded variant is suitable for archival data
//! that can grow, at the cost of larger metadata cells.

/// Implement [`Storable`](ic_stable_structures::storable::Storable) with a
/// bounded size guarantee.
#[macro_export]
macro_rules! impl_storable_bounded {
    ($ident:ident, $max_size:expr, $is_fixed_size:expr) => {
        impl $crate::cdk::structures::storable::Storable for $ident {
            const BOUND: $crate::cdk::structures::storable::Bound =
                $crate::cdk::structures::storable::Bound::Bounded {
                    max_size: $max_size,
                    is_fixed_size: $is_fixed_size,
                };

            fn to_bytes(&self) -> ::std::borrow::Cow<'_, [u8]> {
                let bytes = $crate::serialize::serialize(self).unwrap_or_else(|e| {
                    panic!("impl_storable_bounded: serialize failed: {e}");
                });

                ::std::borrow::Cow::Owned(bytes)
            }

            fn into_bytes(self) -> Vec<u8> {
                $crate::serialize::serialize(&self).unwrap_or_else(|e| {
                    panic!("impl_storable_bounded: serialize failed: {e}");
                })
            }

            fn from_bytes(bytes: ::std::borrow::Cow<'_, [u8]>) -> Self {
                $crate::serialize::deserialize(&bytes).unwrap_or_else(|e| {
                    panic!("impl_storable_bounded: deserialize failed: {e}");
                })
            }
        }
    };
}

/// Implement [`Storable`](ic_stable_structures::storable::Storable) without a
/// size bound.
#[macro_export]
macro_rules! impl_storable_unbounded {
    ($ident:ident) => {
        impl $crate::cdk::structures::storable::Storable for $ident {
            const BOUND: $crate::cdk::structures::storable::Bound =
                $crate::cdk::structures::storable::Bound::Unbounded;

            fn to_bytes(&self) -> ::std::borrow::Cow<'_, [u8]> {
                let bytes = $crate::serialize::serialize(self).unwrap_or_else(|e| {
                    panic!("impl_storable_unbounded: serialize failed: {e}");
                });

                ::std::borrow::Cow::Owned(bytes)
            }

            fn into_bytes(self) -> Vec<u8> {
                $crate::serialize::serialize(&self).unwrap_or_else(|e| {
                    panic!("impl_storable_unbounded: serialize failed: {e}");
                })
            }

            fn from_bytes(bytes: ::std::borrow::Cow<'_, [u8]>) -> Self {
                $crate::serialize::deserialize(&bytes).unwrap_or_else(|e| {
                    panic!("impl_storable_unbounded: deserialize failed: {e}");
                })
            }
        }
    };
}

///
/// TESTS
///

#[cfg(test)]
mod tests {
    use canic_cdk::structures::storable::Storable;
    use serde::{Deserialize, Serialize};
    use std::borrow::Cow;

    ///
    /// Sample
    ///

    #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
    struct Sample {
        v: u32,
    }

    impl_storable_bounded!(Sample, 32, false);

    #[test]
    fn bounded_round_trip() {
        let s = Sample { v: 42 };
        let bytes = s.to_bytes();
        let decoded = Sample::from_bytes(bytes);

        assert_eq!(decoded, s);
    }

    #[test]
    #[should_panic(expected = "impl_storable_bounded: deserialize failed")]
    fn bounded_deserialize_panics_with_context() {
        let bytes = Cow::Owned(vec![0xFF]); // invalid CBOR
        let _ = Sample::from_bytes(bytes);
    }
}