feat: Allow store collection iterators to be cloned (this enables sta…

…ndard Iterator methods like `cycle()`) (#1224)

near-sdk/src/store/free_list/iter.rs

@@ -34,6 +34,7 @@ fn decrement_count(count: &mut u32) {
 }
 
 /// An iterator over elements in the storage bucket. This only yields the occupied entries.
+#[derive(Clone)]
 pub struct Iter<'a, T>
 where
     T: BorshDeserialize + BorshSerialize,

near-sdk/src/store/free_list/mod.rs

@@ -34,7 +34,7 @@ where
 }
 
 #[near(inside_nearsdk)]
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 enum Slot<T> {
     /// Represents a filled cell of a value in the collection.
     Occupied(T),

near-sdk/src/store/iterable_map/iter.rs

@@ -37,6 +37,7 @@ where
 /// An iterator over elements of a [`IterableMap`].
 ///
 /// This `struct` is created by the `iter` method on [`IterableMap`].
+#[derive(Clone)]
 pub struct Iter<'a, K, V, H>
 where
     K: BorshSerialize + Ord + BorshDeserialize,

near-sdk/src/store/iterable_set/iter.rs

@@ -24,6 +24,7 @@ where
 /// See its documentation for more.
 ///
 /// [`iter`]: IterableSet::iter
+#[derive(Clone)]
 pub struct Iter<'a, T>
 where
     T: BorshSerialize + Ord + BorshDeserialize,

near-sdk/src/store/tree_map/iter.rs

@@ -40,6 +40,7 @@ where
 /// An iterator over elements of a [`TreeMap`], in sorted order.
 ///
 /// This `struct` is created by the `iter` method on [`TreeMap`].
+#[derive(Clone)]
 pub struct Iter<'a, K, V, H>
 where
     K: BorshSerialize + Ord + BorshDeserialize,
@@ -408,6 +409,7 @@ where
 /// An iterator over the keys of a [`TreeMap`], in sorted order.
 ///
 /// This `struct` is created by the `keys` method on [`TreeMap`].
+#[derive(Clone)]
 pub struct Keys<'a, K: 'a>
 where
     K: BorshSerialize + BorshDeserialize + Ord,
@@ -676,6 +678,7 @@ where
 /// An iterator over the values of a [`TreeMap`], in order by key.
 ///
 /// This `struct` is created by the `values` method on [`TreeMap`].
+#[derive(Clone)]
 pub struct Values<'a, K, V, H>
 where
     K: BorshSerialize + Ord + BorshDeserialize,

near-sdk/src/store/unordered_map/iter.rs

@@ -36,6 +36,7 @@ where
 /// An iterator over elements of a [`UnorderedMap`].
 ///
 /// This `struct` is created by the `iter` method on [`UnorderedMap`].
+#[derive(Clone)]
 pub struct Iter<'a, K, V, H>
 where
     K: BorshSerialize + Ord + BorshDeserialize,
@@ -222,6 +223,7 @@ where
 /// An iterator over the keys of a [`UnorderedMap`].
 ///
 /// This `struct` is created by the `keys` method on [`UnorderedMap`].
+#[derive(Clone)]
 pub struct Keys<'a, K: 'a>
 where
     K: BorshSerialize + BorshDeserialize,
@@ -277,6 +279,7 @@ where
 /// An iterator over the values of a [`UnorderedMap`].
 ///
 /// This `struct` is created by the `values` method on [`UnorderedMap`].
+#[derive(Clone)]
 pub struct Values<'a, K, V, H>
 where
     K: BorshSerialize + Ord + BorshDeserialize,
@@ -521,3 +524,47 @@ where
         Some(self.remove_value(key))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use borsh::{BorshDeserialize, BorshSerialize};
+
+    #[derive(BorshSerialize, BorshDeserialize, Ord, PartialOrd, Eq, PartialEq, Debug, Clone)]
+    struct Key(i32);
+
+    #[derive(BorshSerialize, BorshDeserialize, Debug, Clone, PartialEq)]
+    struct Value(String);
+
+    #[test]
+    fn test_unordered_map_iter_clone() {
+        let mut store = UnorderedMap::new(b'a');
+
+        store.insert(Key(1), Value("one".to_string()));
+        store.insert(Key(2), Value("two".to_string()));
+        store.insert(Key(3), Value("three".to_string()));
+
+        let mut iter = store.iter().cycle();
+
+        let mut collected = vec![];
+        for _ in 0..9 {
+            if let Some((key, value)) = iter.next() {
+                collected.push((key.clone(), value.clone()));
+            }
+        }
+
+        let expected = vec![
+            (Key(1), Value("one".to_string())),
+            (Key(2), Value("two".to_string())),
+            (Key(3), Value("three".to_string())),
+            (Key(1), Value("one".to_string())),
+            (Key(2), Value("two".to_string())),
+            (Key(3), Value("three".to_string())),
+            (Key(1), Value("one".to_string())),
+            (Key(2), Value("two".to_string())),
+            (Key(3), Value("three".to_string())),
+        ];
+
+        assert_eq!(collected, expected);
+    }
+}

near-sdk/src/store/unordered_set/iter.rs

@@ -24,6 +24,7 @@ where
 /// See its documentation for more.
 ///
 /// [`iter`]: UnorderedSet::iter
+#[derive(Clone)]
 pub struct Iter<'a, T>
 where
     T: BorshSerialize + Ord + BorshDeserialize,

near-sdk/src/store/vec/iter.rs

@@ -5,7 +5,7 @@ use super::{Vector, ERR_INDEX_OUT_OF_BOUNDS};
 use crate::env;
 
 /// An iterator over references to each element in the stored vector.
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct Iter<'a, T>
 where
     T: BorshSerialize + BorshDeserialize,