Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add examples on how to import storage types to the book #6051

Merged
merged 3 commits into from
May 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/book/src/advanced/advanced_storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<T>` in a `StorageMap<K, V>`

The following demonstrates how to write to a `StorageVec<T>` that is nested in a `StorageMap<T, V>`:
Expand Down
30 changes: 30 additions & 0 deletions docs/book/src/blockchain-development/storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<K, V>` 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<K, V>`.

**Warning** While the `StorageMap<K, V>` 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
Expand All @@ -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<T>` 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<T>`.

The following demonstrates how to import `StorageVec<T>`:

```sway
{{#include ../../../../examples/advanced_storage_variables/src/main.sw:storage_vec_import}}
```

> **NOTE**: When importing the `StorageVec<T>`, please be sure to use the glob operator: `use std::storage::storage_vec::*`.

The following demonstrates how to write to a `StorageVec<T>`:

```sway
Expand All @@ -102,6 +116,14 @@ The following demonstrates how to read from a `StorageVec<T>`:

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<T>` or `StorageMap<K, V>` 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<u8>` 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
Expand All @@ -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<T>` or `StorageMap<K, V>`. 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
Expand Down
27 changes: 17 additions & 10 deletions examples/advanced_storage_variables/src/main.sw
Original file line number Diff line number Diff line change
@@ -1,15 +1,22 @@
contract;

use std::{
bytes::Bytes,
hash::Hash,
storage::{
storage_bytes::*,
storage_string::*,
storage_vec::*,
},
string::String,
};
use std::{bytes::Bytes, string::String,};
bitzoic marked this conversation as resolved.
Show resolved Hide resolved

// 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 {
Expand Down
Loading