From 0d455a6c1355988535144a33fd0a9deeee5793d2 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Sun, 19 Apr 2020 08:20:54 -0700 Subject: [PATCH] Addres @thiolliere PR comments * Deemphasize redudancy with Rust docs by collapsing sections about Storage Item APIs * Distinguish APIs for StorageMap and StorageDoubleMap * Clarify StorageMap implementation --- current/runtime/storage.md | 93 ++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 53 deletions(-) diff --git a/current/runtime/storage.md b/current/runtime/storage.md index 45315e9..31d04b5 100644 --- a/current/runtime/storage.md +++ b/current/runtime/storage.md @@ -48,50 +48,40 @@ Refer to the Storage Value documentation for [a comprehensive list of the methods that Storage Values expose](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageValue.html#required-methods). Some of the most important methods are summarized here: -##### `get()` - -Load the value from storage. - -##### `put(val)` - -Store the provided value. - -##### `mutate(fn)` - -Mutate the value with the provided function. - -##### `take()` - -Remove the value from storage. +* [`get()`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageValue.html#tymethod.get) - Load + the value from storage. +* [`put(val)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageValue.html#tymethod.put) - Store + the provided value. +* [`mutate(fn)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageValue.html#tymethod.mutate) - + Mutate the value with the provided function. +* [`take()`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageValue.html#tymethod.take) - Remove + the value from storage. ### Storage Maps -Storage Maps are implemented as hash maps, which is a pattern that should be familiar to most developers. In order to -give blockchain engineers increased control over the way in which these data structures are stored, Substrate allows -developers to select the hashing algorithm that is used to generate map keys. Map data structures are ideal for managing -sets of items whose elements will be accessed randomly, as opposed to iterating over them sequentially in their entirety. +Storage Maps are implemented as maps with hashed keys, which is a pattern that should be familiar to most developers. +In order to give blockchain engineers increased control over the way in which these data structures are stored, +Substrate allows developers to select the hashing algorithm that is used to generate map keys. Map data structures are +ideal for managing sets of items whose elements will be accessed randomly, as opposed to iterating over them +sequentially in their entirety. #### Methods [Storage Maps expose an API](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageMap.html#required-methods) -that is similar to that of Storage Values. The selected methods referenced below all use a single key; use two keys for -[Storage Double Maps](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageDoubleMap.html#required-methods): - -##### `get(key)` - -Load the value associated with the provided key from storage. - -##### `store(key, val)` - -Store the provided value by associating it with the given key. - -##### `mutate(key, fn)` - -Use the provided function to mutate the value associated with the given key. - -##### `take(key)` - -Remove the value associated with the given key from storage. +that is similar to that of Storage Values. + +* `get` - Load the value associated with the provided key from storage. Docs: + [`StorageMap#get(key)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageMap.html#tymethod.get), + [`StorageDoubleMap#get(key1, key2)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageDoubleMap.html#tymethod.get) +* `insert` - Store the provided value by associating it with the given key. Docs: + [`StorageMap#insert(key, val)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageMap.html#tymethod.insert), + [`StorageDoubleMap#insert(key1, key2, val)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageDoubleMap.html#tymethod.insert) +* `mutate` - Use the provided function to mutate the value associated with the given key. Docs: + [`StorageMap#mutate(key, fn)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageMap.html#tymethod.mutate), + [`StorageDoubleMap#mutate(key1, key2, fn)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageDoubleMap.html#tymethod.mutate) +* `take` - Remove the value associated with the given key from storage. Docs: + [`StorageMap#take(key)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageMap.html#tymethod.take), + [`StorageDoubleMap#take(key1, key2)`](https://substrate.dev/rustdocs/master/frame_support/storage/trait.StorageDoubleMap.html#tymethod.take) ### Iterable Storage Maps @@ -105,22 +95,19 @@ iterate across its keys as well as its values. #### Methods [Iterable Storage Maps expose the following methods](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageMap.html#required-methods) -in addition to the other map methods: - -##### `iter()` - -Enumerate all elements in the map in no particular order. If you alter the map while doing this, you'll get undefined -results. - -##### `drain()` - -Remove all elements from the map and iterate through them in no particular order. If you add elements to the map while -doing this, you'll get undefined results. - -##### `translate(fn)` - -Use the provided function to translate all elements of the map, in no particular order. To remove an element from the -map, return `None` from the translation function. +in addition to the other map methods. Note that for Iterable Storage Double Maps, the `iter` and `drain` methods require a parameter, i.e. the first key: + +* `iter` - Enumerate all elements in the map in no particular order. If you alter the map while doing this, you'll get undefined + results. Docs: + [IterableStorageMap#iter()](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageMap.html#tymethod.iter), + [IterableStorageDoubleMap#iter(key1)](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageDoubleMap.html#tymethod.iter) +* `drain` - Remove all elements from the map and iterate through them in no particular order. If you add elements to the map while + doing this, you'll get undefined results. Docs: + [IterableStorageMap#drain()](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageMap.html#tymethod.drain), [IterableStorageDoubleMap#drain(key1)](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageDoubleMap.html#tymethod.drain) +* `translate` - Use the provided function to translate all elements of the map, in no particular order. To remove an element from the + map, return `None` from the translation function. Docs: + [IterableStorageMap#translate(fn)](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageMap.html#tymethod.translate), + [IterableStorageDoubleMap#translate(fn)](https://substrate.dev/rustdocs/master/frame_support/storage/trait.IterableStorageDoubleMap.html#tymethod.translate) ## Declaring Storage Items