referrerpolicy=no-referrer-when-downgrade

frame_support/storage/
unhashed.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! Operation on unhashed runtime storage.
19
20use alloc::vec::Vec;
21use codec::{Decode, Encode};
22
23/// Return the value of the item in storage under `key`, or `None` if there is no explicit entry.
24pub fn get<T: Decode + Sized>(key: &[u8]) -> Option<T> {
25	sp_io::storage::get(key).and_then(|val| {
26		Decode::decode(&mut &val[..]).map(Some).unwrap_or_else(|e| {
27			// TODO #3700: error should be handleable.
28			log::error!(
29				target: "runtime::storage",
30				"Corrupted state at `{}`: {:?}",
31				array_bytes::bytes2hex("0x", key),
32				e,
33			);
34			None
35		})
36	})
37}
38
39/// Return the value of the item in storage under `key`, or the type's default if there is no
40/// explicit entry.
41pub fn get_or_default<T: Decode + Sized + Default>(key: &[u8]) -> T {
42	get(key).unwrap_or_default()
43}
44
45/// Return the value of the item in storage under `key`, or `default_value` if there is no
46/// explicit entry.
47pub fn get_or<T: Decode + Sized>(key: &[u8], default_value: T) -> T {
48	get(key).unwrap_or(default_value)
49}
50
51/// Return the value of the item in storage under `key`, or `default_value()` if there is no
52/// explicit entry.
53pub fn get_or_else<T: Decode + Sized, F: FnOnce() -> T>(key: &[u8], default_value: F) -> T {
54	get(key).unwrap_or_else(default_value)
55}
56
57/// Put `value` in storage under `key`.
58pub fn put<T: Encode + ?Sized>(key: &[u8], value: &T) {
59	value.using_encoded(|slice| sp_io::storage::set(key, slice));
60}
61
62/// Remove `key` from storage, returning its value if it had an explicit entry or `None` otherwise.
63pub fn take<T: Decode + Sized>(key: &[u8]) -> Option<T> {
64	let r = get(key);
65	if r.is_some() {
66		kill(key);
67	}
68	r
69}
70
71/// Remove `key` from storage, returning its value, or, if there was no explicit entry in storage,
72/// the default for its type.
73pub fn take_or_default<T: Decode + Sized + Default>(key: &[u8]) -> T {
74	take(key).unwrap_or_default()
75}
76
77/// Return the value of the item in storage under `key`, or `default_value` if there is no
78/// explicit entry. Ensure there is no explicit entry on return.
79pub fn take_or<T: Decode + Sized>(key: &[u8], default_value: T) -> T {
80	take(key).unwrap_or(default_value)
81}
82
83/// Return the value of the item in storage under `key`, or `default_value()` if there is no
84/// explicit entry. Ensure there is no explicit entry on return.
85pub fn take_or_else<T: Decode + Sized, F: FnOnce() -> T>(key: &[u8], default_value: F) -> T {
86	take(key).unwrap_or_else(default_value)
87}
88
89/// Check to see if `key` has an explicit entry in storage.
90pub fn exists(key: &[u8]) -> bool {
91	sp_io::storage::exists(key)
92}
93
94/// Ensure `key` has no explicit entry in storage.
95pub fn kill(key: &[u8]) {
96	sp_io::storage::clear(key);
97}
98
99/// Ensure keys with the given `prefix` have no entries in storage.
100#[deprecated = "Use `clear_prefix` instead"]
101pub fn kill_prefix(prefix: &[u8], limit: Option<u32>) -> sp_io::KillStorageResult {
102	// TODO: Once the network has upgraded to include the new host functions, this code can be
103	// enabled.
104	// clear_prefix(prefix, limit).into()
105	sp_io::storage::clear_prefix(prefix, limit)
106}
107
108/// Partially clear the storage of all keys under a common `prefix`.
109///
110/// # Limit
111///
112/// A *limit* should always be provided through `maybe_limit`. This is one fewer than the
113/// maximum number of backend iterations which may be done by this operation and as such
114/// represents the maximum number of backend deletions which may happen. A *limit* of zero
115/// implies that no keys will be deleted, though there may be a single iteration done.
116///
117/// The limit can be used to partially delete storage items in case it is too large or costly
118/// to delete all in a single operation.
119///
120/// # Cursor
121///
122/// A *cursor* may be passed in to this operation with `maybe_cursor`. `None` should only be
123/// passed once (in the initial call) for any attempt to clear storage. In general, subsequent calls
124/// operating on the same prefix should pass `Some` and this value should be equal to the
125/// previous call result's `maybe_cursor` field. The only exception to this is when you can
126/// guarantee that the subsequent call is in a new block; in this case the previous call's result
127/// cursor need not be passed in and a `None` may be passed instead. This exception may be useful
128/// then making this call solely from a block-hook such as `on_initialize`.
129///
130/// Returns [`MultiRemovalResults`](sp_io::MultiRemovalResults) to inform about the result. Once the
131/// resultant `maybe_cursor` field is `None`, then no further items remain to be deleted.
132///
133/// NOTE: After the initial call for any given child storage, it is important that no keys further
134/// keys are inserted. If so, then they may or may not be deleted by subsequent calls.
135///
136/// # Note
137///
138/// Please note that keys which are residing in the overlay for the child are deleted without
139/// counting towards the `limit`.
140pub fn clear_prefix(
141	prefix: &[u8],
142	maybe_limit: Option<u32>,
143	_maybe_cursor: Option<&[u8]>,
144) -> sp_io::MultiRemovalResults {
145	// TODO: Once the network has upgraded to include the new host functions, this code can be
146	// enabled.
147	// sp_io::storage::clear_prefix(prefix, maybe_limit, maybe_cursor)
148	use sp_io::{KillStorageResult::*, MultiRemovalResults};
149	#[allow(deprecated)]
150	let (maybe_cursor, i) = match kill_prefix(prefix, maybe_limit) {
151		AllRemoved(i) => (None, i),
152		SomeRemaining(i) => (Some(prefix.to_vec()), i),
153	};
154	MultiRemovalResults { maybe_cursor, backend: i, unique: i, loops: i }
155}
156
157/// Returns `true` if the storage contains any key, which starts with a certain prefix,
158/// and is longer than said prefix.
159/// This means that a key which equals the prefix will not be counted.
160pub fn contains_prefixed_key(prefix: &[u8]) -> bool {
161	match sp_io::storage::next_key(prefix) {
162		Some(key) => key.starts_with(prefix),
163		None => false,
164	}
165}
166
167/// Get a Vec of bytes from storage.
168pub fn get_raw(key: &[u8]) -> Option<Vec<u8>> {
169	sp_io::storage::get(key).map(|value| value.to_vec())
170}
171
172/// Put a raw byte slice into storage.
173///
174/// **WARNING**: If you set the storage of the Substrate Wasm (`well_known_keys::CODE`),
175/// you should also call `frame_system::RuntimeUpgraded::put(true)` to trigger the
176/// `on_runtime_upgrade` logic.
177pub fn put_raw(key: &[u8], value: &[u8]) {
178	sp_io::storage::set(key, value)
179}