From fd04fb417bbc7429e5d054c15991cebb5788072f Mon Sep 17 00:00:00 2001
From: Aaron Taylor <ataylor@subgeniuskitty.com>
Date: Mon, 15 Jul 2019 16:05:54 -0700
Subject: [PATCH] Added memsrch function to VVS stdlib.

---
 stdlib/README.md |  4 +++
 stdlib/heap.pvvs | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/stdlib/README.md b/stdlib/README.md
index 8babbde..925c82c 100644
--- a/stdlib/README.md
+++ b/stdlib/README.md
@@ -38,6 +38,7 @@ header comment for each function to learn the call and return stack.
           11001 ----- memcpy                        (heap.pvvs)
           11010 ----- memrand                       (heap.pvvs)
           11011 ----- memcmp                        (heap.pvvs)
+          11100 ----- memsrch                       (heap.pvvs)
          100xxx - unassigned
          101xxx - unassigned
          110xxx - conversion functions
@@ -55,3 +56,6 @@ private label space associated with it, formed as follows:
     00001000 xxxxxxxx - for use by 1000
     00001001 xxxxxxxx - for use by 1001
     ...etc
+
+Also by convention, functions which return a pointer will use the value `0` to
+represent a `NULL` pointer.
diff --git a/stdlib/heap.pvvs b/stdlib/heap.pvvs
index aef5527..7a3ddc3 100644
--- a/stdlib/heap.pvvs
+++ b/stdlib/heap.pvvs
@@ -217,6 +217,71 @@ SNN                     | DROP
 SSSSN                   | PUSH 0
 NTN                     | RTS
 
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Description:
+@   This function searches the heap from address to address+count.
+@   If pattern is found, the return value is a pointer to the matching word.
+@   If not found, the return value is a null pointer.
+@ Call Stack:
+@   pattern
+@   count
+@   address <-- TOS
+@ Return Stack:
+@   pointer <-- TOS
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+NSSVTTTSSN              | Mark: 11100 (memsrch)
+
+@ Prepare the stack for computation.
+@ Stack:
+@   offset  <-- TOS
+@ Addr | Contents
+@    0 | address
+@    1 | count
+@    2 | pattern
+
+SSSSN                   | PUSH 0 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+SSSTN                   | PUSH 1 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+SSSTSN                  | PUSH 2 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+
+@ Compare one word on each pass through this loop.
+NSSVSSSTTTSSSSSSSSSSN   | Mark: 00011100 00000000
+SNS                     | DUP
+SSSSN                   | PUSH 0 (ptr)
+TTT                     | LOAD
+TSSS                    | ADD
+TTT                     | LOAD
+SSSTSN                  | PUSH 2 (ptr)
+TTT                     | LOAD
+TSST                    | SUBTRACT
+NTSSSSTTTSSSSSSSSSTN    | BRZ > 00011100 00000001
+SNS                     | DUP
+SSSTN                   | PUSH 1 (ptr)
+TTT                     | LOAD
+TSST                    | SUBTRACT
+NTSSSSTTTSSSSSSSSTSN    | BRZ > 00011100 00000010
+SSSTN                   | PUSH 1
+TSSS                    | ADD
+NSNSSSTTTSSSSSSSSSSN    | JMP > 00011100 00000000
+
+@ Found a match. Clean up and return.
+NSSVSSSTTTSSSSSSSSSTN   | Mark: 00011100 00000001
+SSSSN                   | PUSH 0 (ptr)
+TTT                     | LOAD
+TSSS                    | ADD
+NTN                     | RTS
+
+@ No match found. Clean up and return.
+NSSVSSSTTTSSSSSSSSTSN   | Mark: 00011100 00000010
+SNN                     | DROP
+SSSSN                   | PUSH 0
+NTN                     | RTS
+
 #include <math.pvvs>
 
 #endif
-- 
2.20.1