Merge pull request #1107 from 0xPolygonMiden/frisitano-std-asm-utils

Introduce `std::utils` assembly module

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.8.0 (TBD)
 
+#### Stdlib
+- Introduced `std::utils` module with `is_empty_word` procedure.  Refactored `std::collections::smt` 
+  and `std::collections::smt64` to use the procedure (#1107).
+
 ## 0.7.0 (2023-10-11)
 
 #### Assembly

stdlib/asm/collections/smt.masm

@@ -1,3 +1,5 @@
+use.std::utils
+
 # Constant value for empty sub-tree root at depth 16
 const.EMPTY_16_0=17483286922353768131
 const.EMPTY_16_1=353378057542380712
@@ -1142,10 +1144,7 @@ end
 #!   - Depth 32 -> 48: 255
 export.insert
     # make sure the value is not [ZERO; 4] (17 cycles)
-    repeat.4
-        dup.3 eq.0
-    end
-    and and and assertz
+    exec.utils::is_empty_word assertz
     # => [V, K, R, ...]
 
     # arrange the data needed for the insert procedure on the advice stack and move the

stdlib/asm/collections/smt64.masm

@@ -3,6 +3,8 @@
 #! Current implementation is a thin wrapper over a simple Sparse Merkle Tree of depth 64. In the
 #! future, this will be replaced with a compact Sparse Merkle Tree implementation.
 
+use.std::utils
+
 #! Returns the value located under the specified key in the Sparse Merkle Tree defined by the
 #! specified root.
 #!
@@ -38,10 +40,7 @@ end
 #! - The provided value is an empty word.
 export.insert
     # make sure the value is not [ZERO; 4] (17 cycles)
-    repeat.4
-        dup.3 eq.0
-    end
-    and and and assertz
+    exec.utils::is_empty_word assertz
 
     # prepare the stack for mtree_set operation
     movup.4 movdn.8 swapw movup.8 push.64

stdlib/asm/utils.masm

@@ -0,0 +1,15 @@
+#! Returns a boolean indicating whether the input word is an empty word.
+#!
+#! Inputs: [INPUT_WORD]
+#! Outputs: [is_empty_word, INPUT_WORD]
+#!
+#! - INPUT_WORD is the word whose emptiness is to be determined.
+#! - is_empty_word is a boolean indicating whether INPUT_WORD is empty.
+#!
+#! Cycles: 11
+export.is_empty_word
+    repeat.4
+        dup.3 eq.0
+    end
+    and and and
+end

stdlib/docs/utils.md

@@ -0,0 +1,5 @@
+
+## std::utils
+| Procedure | Description |
+| ----------- | ------------- |
+| is_empty_word | Returns a boolean indicating whether the input word is an empty word.<br /><br />Inputs: [INPUT_WORD]<br /><br />Outputs: [is_empty_word, INPUT_WORD]<br /><br />- INPUT_WORD is the word whose emptiness is to be determined.<br /><br />- is_empty_word is a boolean indicating whether INPUT_WORD is empty. |