Skip to content

Commit

Permalink
Storage Vector Method and Dev-Doc Enhancements (FuelLabs#4172)
Browse files Browse the repository at this point in the history
## Description

> Note:
> Part 2 of 3 breakout of PR FuelLabs#3935
> Blocked by PR FuelLabs#4171

This PR enhances existing `StorageVec` methods and introduces a new
documentation section for each `StorageVec` method titled "Number of
Storage Accesses".

### Number of Storage Accesses

This section is meant to indicate the number of storage read, write, and
clear operations for a given method. Methods that do not use a constant
number of storage operations (such as `StorageVec::insert`) will use a
sway expression in its documentation to indicate the amount.

## Checklist

- [✅] I have linked to any relevant issues.
- [✅] I have commented my code, particularly in hard-to-understand
areas.
- [✅] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [✅] I have added tests that prove my fix is effective or that my
feature works.
- [✅] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [✅] 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).
- [✅] I have requested a review from the relevant team or maintainers.

---------

Co-authored-by: João Matos <[email protected]>
  • Loading branch information
jtriley-eth and tritao authored Mar 13, 2023
1 parent 205c6c5 commit 2099b9a
Showing 1 changed file with 58 additions and 15 deletions.
73 changes: 58 additions & 15 deletions sway-lib-std/src/storage.sw
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,11 @@ impl<V> StorageVec<V> {
///
/// * `value` - The item being added to the end of the vector.
///
/// ### Number of Number of Storage Accesses
///
/// * Reads: `1`
/// * Writes: `2`
///
/// ### Examples
///
/// ```sway
Expand All @@ -252,8 +257,7 @@ impl<V> StorageVec<V> {
/// fn foo() {
/// let five = 5_u64;
/// storage.vec.push(five);
/// let retrieved_value = storage.vec.get(0).unwrap();
/// assert(five == retrieved_value);
/// assert(five == storage.vec.get(0).unwrap());
/// }
/// ```
#[storage(read, write)]
Expand All @@ -271,6 +275,11 @@ impl<V> StorageVec<V> {

/// Removes the last element of the vector and returns it, `None` if empty.
///
/// ### Number of Storage Accesses
///
/// * Reads: `2`
/// * Writes: `1`
///
/// ### Examples
///
/// ```sway
Expand Down Expand Up @@ -302,7 +311,7 @@ impl<V> StorageVec<V> {
store(__get_storage_key(), len - 1);

let key = sha256((len - 1, __get_storage_key()));
Option::Some::<V>(get::<V>(key).unwrap())
get::<V>(key)
}

/// Gets the value in the given index, `None` if index is out of bounds.
Expand All @@ -311,6 +320,10 @@ impl<V> StorageVec<V> {
///
/// * `index` - The index of the vec to retrieve the item from.
///
/// ### Number of Storage Accesses
///
/// * Reads: `2`
///
/// ### Examples
///
/// ```sway
Expand All @@ -323,10 +336,8 @@ impl<V> StorageVec<V> {
/// fn foo() {
/// let five = 5_u64;
/// storage.vec.push(five);
/// let retrieved_value = storage.vec.get(0).unwrap();
/// assert(five == retrieved_value);
/// let none_value = storage.vec.get(1);
/// assert(none_value.is_none())
/// assert(five == storage.vec.get(0).unwrap());
/// assert(storage.vec.get(1).is_none())
/// }
/// ```
#[storage(read)]
Expand All @@ -338,8 +349,7 @@ impl<V> StorageVec<V> {
return Option::None;
}

let key = sha256((index, __get_storage_key()));
Option::Some::<V>(get::<V>(key).unwrap())
get::<V>(sha256((index, __get_storage_key())))
}

/// Removes the element in the given index and moves all the elements in the following indexes
Expand All @@ -355,6 +365,11 @@ impl<V> StorageVec<V> {
///
/// Reverts if index is larger or equal to length of the vec.
///
/// ### Number of Storage Accesses
///
/// * Reads: `2 + self.len() - index`
/// * Writes: `self.len() - index`
///
/// ### Examples
///
/// ```sway
Expand Down Expand Up @@ -412,6 +427,11 @@ impl<V> StorageVec<V> {
///
/// Reverts if index is larger or equal to length of the vec.
///
/// ### Number of Storage Accesses
///
/// * Reads: `3`
/// * Writes: `2`
///
/// ### Examples
///
/// ```sway
Expand All @@ -427,7 +447,7 @@ impl<V> StorageVec<V> {
/// storage.vec.push(15);
/// let removed_value = storage.vec.swap_remove(0);
/// assert(5 == removed_value);
/// let swapped_value = storage.vec.get(0);
/// let swapped_value = storage.vec.get(0).unwrap();
/// assert(15 == swapped_value);
/// }
/// ```
Expand All @@ -450,6 +470,7 @@ impl<V> StorageVec<V> {

element_to_be_removed
}

/// Sets or mutates the value at the given index.
///
/// ### Arguments
Expand All @@ -461,6 +482,11 @@ impl<V> StorageVec<V> {
///
/// Reverts if index is larger than or equal to the length of the vec.
///
/// ### Number of Storage Accesses
///
/// * Reads: `1`
/// * Writes: `1`
///
/// ### Examples
///
/// ```sway
Expand All @@ -476,7 +502,7 @@ impl<V> StorageVec<V> {
/// storage.vec.push(15);
///
/// storage.vec.set(0, 20);
/// let set_value = storage.vec.get(0);
/// let set_value = storage.vec.get(0).unwrap();
/// assert(20 == set_value);
/// }
/// ```
Expand Down Expand Up @@ -505,6 +531,11 @@ impl<V> StorageVec<V> {
///
/// Reverts if index is larger than the length of the vec.
///
/// ### Number of Storage Accesses
///
/// * Reads: `if self.len() == index { 1 } else { 1 + self.len() - index }`
/// * Writes: `if self.len() == index { 2 } else { 2 + self.len() - index }`
///
/// ### Examples
///
/// ```sway
Expand All @@ -520,9 +551,9 @@ impl<V> StorageVec<V> {
///
/// storage.vec.insert(1, 10);
///
/// assert(5 == storage.vec.get(0));
/// assert(10 == storage.vec.get(1))
/// assert(15 == storage.vec.get(2));
/// assert(5 == storage.vec.get(0).unwrap());
/// assert(10 == storage.vec.get(1).unwrap());
/// assert(15 == storage.vec.get(2).unwrap());
/// }
/// ```
#[storage(read, write)]
Expand Down Expand Up @@ -565,6 +596,10 @@ impl<V> StorageVec<V> {

/// Returns the length of the vector.
///
/// ### Number of Storage Accesses
///
/// * Reads: `1`
///
/// ### Examples
///
/// ```sway
Expand All @@ -589,6 +624,10 @@ impl<V> StorageVec<V> {

/// Checks whether the len is zero or not.
///
/// ### Number of Storage Accesses
///
/// * Reads: `1`
///
/// ### Examples
///
/// ```sway
Expand Down Expand Up @@ -617,6 +656,10 @@ impl<V> StorageVec<V> {

/// Sets the len to zero.
///
/// ### Number of Storage Accesses
///
/// * Clears: `1`
///
/// ### Examples
///
/// ```sway
Expand All @@ -636,7 +679,7 @@ impl<V> StorageVec<V> {
/// ```
#[storage(write)]
pub fn clear(self) {
store(__get_storage_key(), 0);
let _ = clear::<u64>(__get_storage_key());
}
}

Expand Down

0 comments on commit 2099b9a

Please sign in to comment.