[sui-framework] Added swap and swap_remove function to the table_vec.move (#13644)

## Description 

Added `swap_remove` function to `table_vec.move` since we have a
situation to remove an certain element in the `TableVec` and both
`table` and `vector` have similar functionality implemented.

## Test Plan

New unit tests for `sui::table_vec`.

---
If your changes are not user-facing and not a breaking change, you can
skip the following section. Otherwise, please indicate what changed, and
then add to the Release Notes section as highlighted during the release
process.

### Type of Change (Check all that apply)

- [x] protocol change
- [x] user-visible impact
- [ ] breaking change for a client SDKs
- [x] breaking change for FNs (FN binary must upgrade)
- [x] breaking change for validators or node operators (must upgrade
binaries)
- [ ] breaking change for on-chain data layout
- [ ] necessitate either a data wipe or data migration

### Release notes
Introduces protocol version 25 which adds `sui::table_vec::swap` and
`sui::table_vec::swap_remove` to system packages. Use these functions to
swap two positions in a single `TableVec<T>` or swap an element to the
end and remove it in `O(1)` time, analogous to `std::vector::swap` and
`std::vector::swap_remove`.

---------

Co-authored-by: Ashok Menon <[email protected]>

Author: WayneAl

crates/sui-framework/packages/sui-framework/sources/table_vec.move

@@ -81,4 +81,25 @@ module sui::table_vec {
         table::drop(contents)
     }
 
+    /// Swaps the elements at the `i`th and `j`th indices in the TableVec `t`.
+    /// Aborts if `i` or `j` is out of bounds.
+    public fun swap<Element: store>(t: &mut TableVec<Element>, i: u64, j: u64) {
+        assert!(length(t) > i, EIndexOutOfBound);
+        assert!(length(t) > j, EIndexOutOfBound);
+        if (i == j) { return };
+        let element_i = table::remove(&mut t.contents, i);
+        let element_j = table::remove(&mut t.contents, j);
+        table::add(&mut t.contents, j, element_i);
+        table::add(&mut t.contents, i, element_j);
+    }
+
+    /// Swap the `i`th element of the TableVec `t` with the last element and then pop the TableVec.
+    /// This is O(1), but does not preserve ordering of elements in the TableVec.
+    /// Aborts if `i` is out of bounds.
+    public fun swap_remove<Element: store>(t: &mut TableVec<Element>, i: u64): Element {
+        assert!(length(t) > i, EIndexOutOfBound);
+        let last_idx = length(t) - 1;
+        swap(t, i, last_idx);
+        pop_back(t)
+    }
 }

crates/sui-framework/packages/sui-framework/tests/table_vec_tests.move

@@ -10,7 +10,7 @@ module sui::table_vec_tests {
 
     #[test]
     fun simple_all_functions() {
-        let scenario = ts::begin(TEST_SENDER_ADDR);    
+        let scenario = ts::begin(TEST_SENDER_ADDR);
 
         let table_vec = table_vec::empty<u64>(ts::ctx(&mut scenario));
         assert!(table_vec::length(&table_vec) == 0, 0);
@@ -21,7 +21,14 @@ module sui::table_vec_tests {
         let value = table_vec::borrow(&table_vec, 0);
         assert!(*value == 8, 0);
 
-        table_vec::pop_back(&mut table_vec);
+        table_vec::push_back(&mut table_vec, 5);
+        table_vec::swap(&mut table_vec, 0, 1);
+
+        let value = table_vec::swap_remove(&mut table_vec, 0);
+        assert!(value == 5, 0);
+
+        let value = table_vec::pop_back(&mut table_vec);
+        assert!(value == 8, 0);
         table_vec::destroy_empty(table_vec);
         ts::end(scenario);
     }
@@ -41,7 +48,7 @@ module sui::table_vec_tests {
         let scenario = ts::begin(TEST_SENDER_ADDR);
         let table_vec = table_vec::empty<u64>(ts::ctx(&mut scenario));
         table_vec::pop_back(&mut table_vec);
-        table_vec::destroy_empty(table_vec);    
+        table_vec::destroy_empty(table_vec);
         ts::end(scenario);
     }
 
@@ -64,4 +71,34 @@ module sui::table_vec_tests {
         table_vec::destroy_empty(table_vec);
         ts::end(scenario);
     }
+
+    #[test]
+    #[expected_failure(abort_code = sui::table_vec::EIndexOutOfBound)]
+    fun swap_out_of_bounds_aborts() {
+        let scenario = ts::begin(TEST_SENDER_ADDR);
+        let table_vec = table_vec::singleton(1, ts::ctx(&mut scenario));
+        table_vec::swap(&mut table_vec, 0, 77);
+        table_vec::destroy_empty(table_vec);
+        ts::end(scenario);
+    }
+
+    #[test]
+    fun swap_same_index_succeeds() {
+        let scenario = ts::begin(TEST_SENDER_ADDR);
+        let table_vec = table_vec::singleton(1, ts::ctx(&mut scenario));
+        table_vec::swap(&mut table_vec, 0, 0);
+        table_vec::pop_back(&mut table_vec);
+        table_vec::destroy_empty(table_vec);
+        ts::end(scenario);
+    }
+
+    #[test]
+    #[expected_failure(abort_code = sui::table_vec::EIndexOutOfBound)]
+    fun swap_same_index_out_of_bounds_aborts() {
+        let scenario = ts::begin(TEST_SENDER_ADDR);
+        let table_vec = table_vec::singleton(1, ts::ctx(&mut scenario));
+        table_vec::swap(&mut table_vec, 77, 77);
+        table_vec::destroy_empty(table_vec);
+        ts::end(scenario);
+    }
 }