First draft of a real README for the VVS stdlib.

[vvhitespace] / stdlib / stack.pvvs

diff --git a/stdlib/stack.pvvs b/stdlib/stack.pvvs
index c543d98..8ed5e9d 100644 (file)
--- a/stdlib/stack.pvvs
+++ b/stdlib/stack.pvvs
@@ -1,3 +1,6 @@
+@ (c) 2020 Aaron Taylor <ataylor at subgeniuskitty dot com>
+@ See LICENSE.txt file for copyright and license details.
+

 #ifndef VVS_STDLIB_STACK
 #define VVS_STDLIB_STACK
 
 #ifndef VVS_STDLIB_STACK
 #define VVS_STDLIB_STACK
 


@@ -6,6 +9,7 @@
 @   stackrotate
 @ Description:
 @   Maximum rotation depth is 14. Stomps on heap[1]-heap[15].
 @   stackrotate
 @ Description:
 @   Maximum rotation depth is 14. Stomps on heap[1]-heap[15].

+@   Assumes rotation depth is at least 2.

 @ Call Stack:
 @   stack word n
 @   ...
 @ Call Stack:
 @   stack word n
 @   ...


@@ -22,10 +26,11 @@ NSSVTSTSN               | Mark: 1010 (stackrotate)
 
 @ For the convenience of other functions, modulo the
 @ rotation depth by the available registers.
 
 @ For the convenience of other functions, modulo the
 @ rotation depth by the available registers.

-SSSTTTSN                | PUSH 14
+SSSTTTTN                | PUSH 15

 TSTT                    | MODULO
 
 @ Use heap[15] for generating register addresses.
 TSTT                    | MODULO
 
 @ Use heap[15] for generating register addresses.

+@ TODO: Switch to using heap[1] so number of registers is limited only by user.

 SSSTTTTN                | PUSH 15 (ptr)
 SSSSN                   | PUSH 0
 TTS                     | STORE
 SSSTTTTN                | PUSH 15 (ptr)
 SSSSN                   | PUSH 0
 TTS                     | STORE


@@ -109,6 +114,7 @@ NTN                     | RTS
 @   stackrotatereverse
 @ Description:
 @   Maximum rotation depth is 14. Stomps on heap[1]-heap[15].
 @   stackrotatereverse
 @ Description:
 @   Maximum rotation depth is 14. Stomps on heap[1]-heap[15].

+@   Assumes rotation depth is at least 2.

 @ Call Stack:
 @   stack word n
 @   ...
 @ Call Stack:
 @   stack word n
 @   ...


@@ -125,10 +131,11 @@ NSSVTSTTN               | Mark: 1011 (stackrotatereverse)
 
 @ For the convenience of other functions, modulo the
 @ rotation depth by the available registers.
 
 @ For the convenience of other functions, modulo the
 @ rotation depth by the available registers.

-SSSTTTSN                | PUSH 14
+SSSTTTTN                | PUSH 15

 TSTT                    | MODULO
 
 @ Use heap[15] for generating register addresses.
 TSTT                    | MODULO
 
 @ Use heap[15] for generating register addresses.

+@ TODO: Switch to using heap[1] so number of registers is limited only by user.

 SSSTTTTN                | PUSH 15 (ptr)
 SSSSN                   | PUSH 0
 TTS                     | STORE
 SSSTTTTN                | PUSH 15 (ptr)
 SSSSN                   | PUSH 0
 TTS                     | STORE


@@ -213,14 +220,14 @@ NTN                     | RTS
 @   deepdup
 @ Description:
 @   Duplicates an item deep on the stack, placing the duplicate on TOS.
 @   deepdup
 @ Description:
 @   Duplicates an item deep on the stack, placing the duplicate on TOS.

-@   By default, maximum depth is 11.
-@   True maximum depth is (max depth of stackrotate & stackrotatereverse)-3.
+@   By default, maximum depth is 13.
+@   True maximum depth is (max depth of stackrotate & stackrotatereverse)-1.

 @ Call Stack:
 @   stack word n
 @   ...
 @   stack word 1
 @ Call Stack:
 @   stack word n
 @   ...
 @   stack word 1

-@   dupdepth  <-- TOS
-@ Return Stack:
+@   dupdepth   <-- TOS
+@ Return Stack: (dupdepth=3)

 @   stack word n
 @   ...
 @   stack word 1
 @   stack word n
 @   ...
 @   stack word 1