Skip to content

Commit

Permalink
Add examples on how to import storage types to the book (#6051)
Browse files Browse the repository at this point in the history
## Description

A [recent issue on the
forum](https://forum.fuel.network/t/no-method-push-found/5342)
demonstrated the lack of examples on how to import storage types to the
book. Specifically, they require the glob operator to be used properly.
A note on this has been added.

## Checklist

- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
  • Loading branch information
bitzoic committed May 27, 2024
1 parent d93bb91 commit 5389aa8
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 10 deletions.
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,};

// 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

0 comments on commit 5389aa8

Please sign in to comment.