ink_storage_traits/
storage.rs

1// Copyright (C) Use Ink (UK) Ltd.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use ink_primitives::Key;
16
17/// Trait for representing types which can be read and written to storage.
18///
19/// This trait is not the same as the [`scale::Codec`]. Each type that implements
20/// [`scale::Codec`] are storable by default and transferable between contracts.
21/// But not each storable type is transferable.
22pub trait Storable: Sized {
23    /// Convert self to a slice and append it to the destination.
24    fn encode<T: scale::Output + ?Sized>(&self, dest: &mut T);
25
26    /// Attempt to deserialize the value from input.
27    fn decode<I: scale::Input>(input: &mut I) -> Result<Self, scale::Error>;
28
29    /// The exact number of bytes this type consumes in the encoded form.
30    fn encoded_size(&self) -> usize;
31}
32
33/// Types which implement `scale::Encode` and `scale::Decode` are `Storable` by default
34/// because they can be written directly into the storage cell.
35impl<P> Storable for P
36where
37    P: scale::Codec,
38{
39    #[inline]
40    fn encode<T: scale::Output + ?Sized>(&self, dest: &mut T) {
41        scale::Encode::encode_to(self, dest)
42    }
43
44    #[inline]
45    fn decode<I: scale::Input>(input: &mut I) -> Result<Self, scale::Error> {
46        scale::Decode::decode(input)
47    }
48
49    #[inline]
50    fn encoded_size(&self) -> usize {
51        <P as scale::Encode>::encoded_size(self)
52    }
53}
54
55/// Decode and consume all of the given input data.
56///
57/// If not all data is consumed, an error is returned.
58pub fn decode_all<T: Storable>(input: &mut &[u8]) -> Result<T, scale::Error> {
59    let res = <T as Storable>::decode(input)?;
60
61    if input.is_empty() {
62        Ok(res)
63    } else {
64        Err("Input buffer has still data left after decoding!".into())
65    }
66}
67
68pub(crate) mod private {
69    /// Seals the implementation of `Packed`.
70    pub trait Sealed {}
71}
72
73/// Trait for describing types that can be read and written to storage while all fields
74/// occupy only a single storage cell.
75///
76/// If at least one of the fields in the type occupies its own storage cell, this type
77/// is considered non-packed.
78///
79/// # Note
80///
81/// The trait is automatically implemented for types that implement [`scale::Codec`]
82/// via blanket implementation.
83pub trait Packed: Storable + scale::Codec + private::Sealed {}
84
85/// Holds storage key for the type.
86///
87/// # Note
88///
89/// The trait is automatically implemented for [`Packed`] types
90/// via blanket implementation.
91pub trait StorageKey {
92    /// Storage key of the type.
93    const KEY: Key;
94
95    /// Returns the storage key.
96    fn key(&self) -> Key {
97        Self::KEY
98    }
99}
100
101/// Describes the type that should be used for storing the value and preferred storage
102/// key.
103///
104/// # Note
105///
106/// The trait is automatically implemented for [`Packed`] types
107/// via blanket implementation.
108pub trait StorableHint<Key: StorageKey> {
109    /// Storable type with storage key inside.
110    type Type: Storable;
111    /// The storage key that the type prefers. It can be overwritten by an auto-generated
112    /// storage key.
113    type PreferredKey: StorageKey;
114}
115
116/// Automatically returns the type that should be used for storing the value.
117///
118/// The trait is used by codegen to determine which storage key the type should have.
119pub trait AutoStorableHint<Key: StorageKey> {
120    /// Storable type with storage key inside.
121    type Type: Storable;
122}
ink_storage_traits/storage.rs

ink_storage_traits/
storage.rs
