From 4e44645dc47194ee18f1a60049cbf7c5e50bd7b7 Mon Sep 17 00:00:00 2001
From: frisitano <francesco.risitano95@gmail.com>
Date: Mon, 16 Oct 2023 16:19:11 +0800
Subject: [PATCH] feat: introduce std::utils asm module

---
 CHANGELOG.md                      |  4 ++++
 stdlib/asm/collections/smt.masm   |  7 +++----
 stdlib/asm/collections/smt64.masm |  7 +++----
 stdlib/asm/utils.masm             | 15 +++++++++++++++
 stdlib/docs/utils.md              |  5 +++++
 5 files changed, 30 insertions(+), 8 deletions(-)
 create mode 100644 stdlib/asm/utils.masm
 create mode 100644 stdlib/docs/utils.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e5f913c0a..d67481f7c0 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/stdlib/asm/collections/smt.masm b/stdlib/asm/collections/smt.masm
index 9bb402e426..ad80b5ee4a 100644
--- a/stdlib/asm/collections/smt.masm
+++ b/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
diff --git a/stdlib/asm/collections/smt64.masm b/stdlib/asm/collections/smt64.masm
index 295950ddfa..26aaf4c591 100644
--- a/stdlib/asm/collections/smt64.masm
+++ b/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
diff --git a/stdlib/asm/utils.masm b/stdlib/asm/utils.masm
new file mode 100644
index 0000000000..b3184b729f
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/stdlib/docs/utils.md b/stdlib/docs/utils.md
new file mode 100644
index 0000000000..cb6f11ff72
--- /dev/null
+++ b/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. |