From a67867aead6a33ba7271feb4aaf85a0857cd0bba Mon Sep 17 00:00:00 2001
From: Aaron Taylor <ataylor@subgeniuskitty.com>
Date: Sat, 20 Jul 2019 13:07:29 -0700
Subject: [PATCH] Added stackrotatereverse function to VVS stdlib to complement
 stackrotate.

---
 stdlib/README.md  |   1 +
 stdlib/stack.pvvs | 106 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+)

diff --git a/stdlib/README.md b/stdlib/README.md
index 3c92dde..7508410 100644
--- a/stdlib/README.md
+++ b/stdlib/README.md
@@ -36,6 +36,7 @@ header comment for each function to learn the call and return stack.
            1000 ----- printf                        (stdio.pvvs)
            1001 ----- print number from stack       (stdio.pvvs)
            1010 ----- stackrotate                   (stack.pvvs)
+           1011 ----- stackrotatereverse            (stack.pvvs)
          010xxx - math functions
           10000 ----- random                        (math.pvvs)
           10001 ----- absolute value                (math.pvvs)
diff --git a/stdlib/stack.pvvs b/stdlib/stack.pvvs
index a5115ac..0ef72bf 100644
--- a/stdlib/stack.pvvs
+++ b/stdlib/stack.pvvs
@@ -105,4 +105,110 @@ NSNSSSSTSTSSSSSSSTSN    | JMP > 00001010 00000010
 NSSVSSSSTSTSSSSSSSTTN   | Mark: 00001010 00000011
 NTN                     | RTS
 
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@   stackrotatereverse
+@ Description:
+@   Maximum rotation depth is five. Stomps on heap[9]-heap[14].
+@   Assumes rotation depth greater than two, otherwise use SWAP.
+@ Call Stack:
+@   stack word n
+@   ...
+@   stack word 1
+@   rotation depth (rd)  <-- TOS
+@ Return Stack (n>rd=3):
+@   stack word n
+@   ...
+@   stack word 2
+@   stack word 1
+@   stack word 3   <-- TOS
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+NSSVTSTTN               | Mark: 1011 (stackrotatereverse)
+
+@ For the convenience of other functions, modulo the
+@ rotation depth by the available registers.
+SSSTSTN                 | PUSH 5
+TSTT                    | MODULO
+
+@ Use heap[14] for generating register addresses.
+SSSTTTSN                | PUSH 14 (ptr)
+SSSSN                   | PUSH 0
+TTS                     | STORE
+
+@ Dump one word from stack to heap each pass through the loop.
+NSSVSSSSTSTTSSSSSSSSN   | Mark: 00001011 00000000
+SNT                     | SWAP
+SSSTSSTN                | PUSH 9 (starting register)
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+TSSS                    | ADD
+SNT                     | SWAP
+TTS                     | STORE
+
+@ See if the loop is complete.
+SNS                     | DUP
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+SSSTN                   | PUSH 1
+TSSS                    | ADD
+TSST                    | SUBTRACT
+NTSSSSSTSTTSSSSSSSTN    | BRZ > 00001011 00000001
+
+@ Increment the loop counter
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+SSSTN                   | PUSH 1
+TSSS                    | ADD
+SSSTTTSN                | PUSH 14 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+NSNSSSSTSTTSSSSSSSSN    | JMP > 00001011 00000000
+
+@ The correct number of words have been stored to registers.
+@ Time to read them back in rotated order.
+
+@ First, prepare the counter in heap[14] again.
+NSSVSSSSTSTTSSSSSSSTN   | Mark: 00001011 00000001
+SSSTN                   | PUSH 1
+TSST                    | SUBTRACT
+SNS                     | DUP
+SSSTN                   | PUSH 1
+TSST                    | SUBTRACT
+SSSTTTSN                | PUSH 14 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+
+@ Read one word per pass through this loop.
+@ Store it behind 'rd' on the stack.
+NSSVSSSSTSTTSSSSSSTSN   | Mark: 00001011 00000010
+SSSTSSTN                | PUSH 9 (starting register)
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+TSSS                    | ADD
+TTT                     | LOAD
+SNT                     | SWAP
+
+@ See if the loop is complete.
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+NTSSSSSTSTTSSSSSSTTN    | BRZ > 00001011 00000011
+
+@ Decrement the loop counter and loop again.
+SSSTTTSN                | PUSH 14 (ptr)
+TTT                     | LOAD
+SSSTN                   | PUSH 1
+TSST                    | SUBTRACT
+SSSTTTSN                | PUSH 14 (ptr)
+SNT                     | SWAP
+TTS                     | STORE
+NSNSSSSTSTTSSSSSSTSN    | JMP > 00001011 00000010
+
+@ Read in the final value manually and return.
+NSSVSSSSTSTTSSSSSSTTN   | Mark: 00001011 00000011
+SSSTSSTN                | PUSH 9 (starting register)
+TSSS                    | ADD
+TTT                     | LOAD
+NTN                     | RTS
+
 #endif
+
-- 
2.20.1