From a5b8aa4e7aba9c9253f3ca1099195397dfb8a3a4 Mon Sep 17 00:00:00 2001 From: bitzoic Date: Thu, 23 May 2024 16:31:15 +0800 Subject: [PATCH 1/2] Add examples on how to import storage types to the book --- docs/book/src/advanced/advanced_storage.md | 2 ++ .../src/blockchain-development/storage.md | 30 +++++++++++++++++++ .../advanced_storage_variables/src/main.sw | 22 ++++++++++---- 3 files changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/book/src/advanced/advanced_storage.md b/docs/book/src/advanced/advanced_storage.md index aa2d0acf1c5..77d41e47270 100644 --- a/docs/book/src/advanced/advanced_storage.md +++ b/docs/book/src/advanced/advanced_storage.md @@ -12,6 +12,8 @@ For example, here we have a few common nested storage types declared in a `stora Please note that storage initialization is needed to do this. +> **NOTE**: When importing a storage type, please be sure to use the glob operator i.e. `use std::storage::storage_vec::*`. + ### Storing a `StorageVec` in a `StorageMap` The following demonstrates how to write to a `StorageVec` that is nested in a `StorageMap`: diff --git a/docs/book/src/blockchain-development/storage.md b/docs/book/src/blockchain-development/storage.md index 1f780aff7e8..809cd7492c8 100644 --- a/docs/book/src/blockchain-development/storage.md +++ b/docs/book/src/blockchain-development/storage.md @@ -70,6 +70,12 @@ Declaring these variables in storage requires a `storage` block as follows: Generic storage maps are available in the standard library as `StorageMap` which have to be defined inside a `storage` block and allow you to call `insert()` and `get()` to insert values at specific keys and get those values respectively. Refer to [Storage Maps](../common-collections/storage_map.md) for more information about `StorageMap`. +**Warning** While the `StorageMap` is currently included in the prelude, to use it the `Hash` trait must still be imported. This is a known issue and will be resolved. + +```sway +{{#include ../../../../examples/advanced_storage_variables/src/main.sw:temp_hash_import}} +``` + To write to a storage map, call either the `insert()` or `try_insert()` functions as follows: ```sway @@ -86,6 +92,14 @@ The following demonstrates how to read from a storage map: Generic storage vectors are available in the standard library as `StorageVec` which have to be defined inside a `storage` block and allow you to call `push()` and `pop()` to push and pop values from a vector respectively. Refer to [Storage Vector](../common-collections/storage_vec.md) for more information about `StorageVec`. +The following demonstrates how to import `StorageVec`: + +```sway +{{#include ../../../../examples/advanced_storage_variables/src/main.sw:storage_vec_import}} +``` + +> **NOTE**: When importing the `StorageVec`, please be sure to use the glob operator: `use std::storage::storage_vec::*`. + The following demonstrates how to write to a `StorageVec`: ```sway @@ -102,6 +116,14 @@ The following demonstrates how to read from a `StorageVec`: Storage of `Bytes` is available in the standard library as `StorageBytes` which have to be defined inside a `storage` block. `StorageBytes` cannot be manipulated in the same way a `StorageVec` or `StorageMap` can but stores bytes more efficiently thus reducing gas. Only the entirety of a `Bytes` may be read/written to storage. This means any changes would require loading the entire `Bytes` to the heap, making changes, and then storing it once again. If frequent changes are needed, a `StorageVec` is recommended. +The following demonstrates how to import `StorageBytes`: + +```sway +{{#include ../../../../examples/advanced_storage_variables/src/main.sw:storage_bytes_import}} +``` + +> **NOTE**: When importing the `StorageBytes`, please be sure to use the glob operator: `use std::storage::storage_bytes::*`. + The following demonstrates how to write to a `StorageBytes`: ```sway @@ -118,6 +140,14 @@ The following demonstrates how to read from a `StorageBytes`: Storage of `String` is available in the standard library as `StorageString` which have to be defined inside a `storage` block. `StorageString` cannot be manipulated in the same way a `StorageVec` or `StorageMap`. Only the entirety of a `String` may be read/written to storage. +The following demonstrates how to import `StorageString`: + +```sway +{{#include ../../../../examples/advanced_storage_variables/src/main.sw:storage_string_import}} +``` + +> **NOTE**: When importing the `StorageString`, please be sure to use the glob operator: `use std::storage::storage_string::*`. + The following demonstrates how to write to a `StorageString`: ```sway diff --git a/examples/advanced_storage_variables/src/main.sw b/examples/advanced_storage_variables/src/main.sw index a13ef0a9ed2..32f9e0003ea 100644 --- a/examples/advanced_storage_variables/src/main.sw +++ b/examples/advanced_storage_variables/src/main.sw @@ -2,15 +2,25 @@ contract; use std::{ bytes::Bytes, - hash::Hash, - storage::{ - storage_bytes::*, - storage_string::*, - storage_vec::*, - }, string::String, }; +// ANCHOR: temp_hash_import +use std::hash::Hash; +// ANCHOR: temp_hash_import + +// ANCHOR: storage_vec_import +use std::storage::storage_vec::*; +// ANCHOR: storage_vec_import + +// ANCHOR: storage_bytes_import +use std::storage::storage_bytes::*; +// ANCHOR: storage_bytes_import + +// ANCHOR: storage_bytes_import +use std::storage::storage_string::*; +// ANCHOR: storage_bytes_import + // ANCHOR: advanced_storage_declaration storage { storage_map: StorageMap = StorageMap {}, From 4db28b73d91cff87354c3ad330350fb9811bb72e Mon Sep 17 00:00:00 2001 From: bitzoic Date: Thu, 23 May 2024 16:37:14 +0800 Subject: [PATCH 2/2] Run formatter --- examples/advanced_storage_variables/src/main.sw | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/examples/advanced_storage_variables/src/main.sw b/examples/advanced_storage_variables/src/main.sw index 32f9e0003ea..ac955c6e45c 100644 --- a/examples/advanced_storage_variables/src/main.sw +++ b/examples/advanced_storage_variables/src/main.sw @@ -1,9 +1,6 @@ contract; -use std::{ - bytes::Bytes, - string::String, -}; +use std::{bytes::Bytes, string::String,}; // ANCHOR: temp_hash_import use std::hash::Hash;