spitewaste 0.1.001 → 0.1.006

data/lib/spitewaste/libspw/prime.spw

@@ -1,3 +1,6 @@
+import math ; divmod
+import util ; inc
+
 ; [n] => [0|1]
 prime?: ; [n]
   dup push 3 sub jn _prime_special ; special-case < 3
@@ -40,7 +43,5 @@ _factor_loop: ; [d n]
 _divisor_loop:
   dup copy 2 :divmod jz _divisor_keep
   pop swap :next_prime swap jump _factor_loop
-
 _divisor_keep: push -2 :inc slide 1 copy 1 swap jump _factor_loop
-
 _factor_done: slide 1 push 3 sub load ret

data/lib/spitewaste/libspw/random.spw

@@ -1,3 +1,5 @@
+import math ; pow
+
 srand: push $seed swap store ret
 
 rand:

data/lib/spitewaste/libspw/rational.spw

@@ -0,0 +1,153 @@
+;;; Rational numbers
+
+import math ; abs, divmod, gcd, pow, sign
+import util ; die!, neq
+
+; maximum value of either component of a rational number before behavior is
+; undefined; 2^31 by default to give interpreters without bignums a chance,
+; but customizable from userland.
+$RAT = push 2,31 :pow
+
+; encodes a numerator N and a denominator D as a rational number R with the
+; following structure: ((N × $RAT + D) << 1) + sign (0 for negative, else 1).
+; This representation is nice because, with care, it makes it so that we never
+; have to involve the heap (besides divmod) just to do fairly basic arithmetic.
+; [N D] => [R]
+;
+; [22 7]  => [R(22,7)]
+; [4 8]   => [R(4,8)]  ; no implicit simplification TODO: make it configurable?
+; [5 1]   => [R(5,1)]  ; no conversion to integer (duh)
+; [-3 4]  => [R(-3,4)]
+; [3 -4]  => [R(-3,4)] ; sign always held in the numerator
+; [-1 -3] => [R(1,3)]
+to_r: dup jz _to_r_dbz
+  dup :sign copy 2 :sign mul push -1 :neq
+  copy 2 :abs copy 2 :abs
+  $RAT copy 2 mul add push 2 mul
+  copy 2 add slide 4 ret
+_to_r_dbz: push "0 in denominator!" :die!
+
+; returns the numerator N of the rational number R, which may be negative
+; [R] => [N]
+;
+; [R(22,7)] => [22]
+; [R(-3,4)] => [-3]
+; [R(3,-4)] => [-3]
+ratnum: push 2 :divmod push 2 mul push 1 sub swap $RAT div mul ret
+
+; returns the denominator D of the rational number R; always positive
+; [R] => [D]
+;
+; [R(22,7)] => [7]
+; [R(-3,4)] => [4]
+; [R(3,-4)] => [4]
+ratden: push 2 div $RAT mod ret
+
+; decomposes the rational number R into its numerator N and denominator D
+; [R] => [N D]
+;
+; [R(22,7)] => [22 7]
+; [R(-3,4)] => [-3 4]
+; [R(3,-4)] => [-3 4]
+; [R(4,8)]  => [4 8]  ; no implicit simplification
+from_r: dup :ratnum swap :ratden ret
+
+; fully simplifies the rational number R by dividing both of its components
+; by their greatest common divisor
+; [R] => [R, simplified]
+;
+; [R(4,8)] => [R(1,2)]
+; [R(-3,12)] => [R(-1,4)]
+; [R(17,-51)] => [R(-1,3)]
+ratsimp:
+  push 2 :divmod swap $RAT :divmod dup copy 2 :gcd
+  swap copy 1 div copy 2 copy 2 div swap :to_r
+  slide 2 push 2 div push 2 mul add ret
+
+; helper prologue shared by all but ratmul
+_rathead:
+  copy 1 :ratnum copy 1 :ratden mul
+  copy 2 :ratden copy 2 :ratnum mul ret
+
+; helper epilogue shared by all but ratdiv
+_rattail:
+  copy 2 :ratden copy 2 :ratden mul
+  :to_r :ratsimp slide 2 ret
+
+; returns the simplified sum of the rational numbers Ra and Rb
+; [Ra Rb] => [Ra + Rb]
+;
+; [R(-9,-14) R(-3,19)]  => [R(129,266)]
+; [R(17,30)  R(18,10)]  => [R(71,30)]
+; [R(-27,14) R(15,-23)] => [R(-831,322)]
+; [R(3,-9)   R(8,3)]    => [R(7,3)]
+; [R(-5,27)  R(-2,-27)] => [R(-1,9)]
+; [R(-27,-8) R(-15,22)] => [R(237,88)]
+; [R(-9,-29) R(-27,3)]  => [R(-252,29)]
+; [R(2,-21)  R(4,6)]    => [R(4,7)]
+ratadd: :_rathead add :_rattail ret
+
+; returns the simplified difference of the rational numbers Ra and Rb
+; [Ra Rb] => [Ra - Rb]
+;
+; [R(21,25)  R(-28,27)]  => [R(1267,675)]
+; [R(14,7)   R(13,6)]    => [R(-1,6)]
+; [R(-24,-9) R(-5,-21)]  => [R(17,7)]
+; [R(-27,-2) R(-2,26)]   => [R(353,26)]
+; [R(-27,3)  R(2,-22)]   => [R(-98,11)]
+; [R(-4,23)  R(-9,13)]   => [R(155,299)]
+; [R(-14,19) R(-18,-11)] => [R(-496,209)]
+; [R(-29,21) R(-15,-16)] => [R(-779,336)]
+ratsub: :_rathead sub :_rattail ret
+
+; returns the simplified product of the rational numbers Ra and Rb
+; [Ra Rb] => [Ra × Rb]
+;
+; [R(-24,26) R(-1,-30)]  => [R(-2,65)]
+; [R(19,4)   R(27,2)]    => [R(513,8)]
+; [R(25,27)  R(4,-11)]   => [R(-100,297)]
+; [R(1,18)   R(4,8)]     => [R(1,36)]
+; [R(1,27)   R(-8,29)]   => [R(-8,783)]
+; [R(25,-13) R(-6,24)]   => [R(25,52)]
+; [R(6,-13)  R(9,23)]    => [R(-54,299)]
+; [R(11,8)   R(-19,-19)] => [R(11,8)]
+ratmul: copy 1 :ratnum copy 1 :ratnum mul :_rattail ret
+
+; returns the simplified quotient of the rational numbers Ra and Rb
+; [Ra Rb] => [Ra / Rb]
+;
+; [R(-30,-22) R(15,12)]   => [R(12,11)]
+; [R(13,28)   R(-15,29)]  => [R(-377,420)]
+; [R(7,-30)   R(-22,-12)] => [R(-7,55)]
+; [R(15,4)    R(8,-8)]    => [R(-15,4)]
+; [R(-23,28)  R(-16,-15)] => [R(-345,448)]
+; [R(-18,12)  R(6,18)]    => [R(-9,2)]
+; [R(29,-2)   R(11,-21)]  => [R(609,22)]
+; [R(-23,25)  R(25,-3)]   => [R(69,625)]
+ratdiv: :_rathead :to_r :ratsimp slide 2 ret
+
+; returns the simplified modulus of the rational numbers Ra and Rb
+; [Ra Rb] => [Ra % Rb]
+;
+; [R(-15,-3) R(-16,-10)] => [R(1,5)]
+; [R(4,2)    R(21,21)]   => [R(0,1)]
+; [R(24,10)  R(-18,-3)]  => [R(12,5)]
+; [R(3,-7)   R(-2,16)]   => [R(-3,56)]
+; [R(4,28)   R(-29,7)]   => [R(-4,1)]
+; [R(7,-27)  R(10,23)]   => [R(109,621)]
+; [R(28,-3)  R(30,-12)]  => [R(-11,6)]
+; [R(-29,21) R(19,-23)]  => [R(-268,483)]
+ratmod: :_rathead mod :_rattail ret
+
+; returns the sign of the rational number R
+; [R] => [-1 | 0 | 1]
+;
+; [R(4,3)] => [1]
+; [R(4,-3)] => [-1]
+; [R(0,10)] => [0]
+; [R(-3,4)] => [-1]
+; [R(-3,-4)] => [1]
+ratsign:
+  dup $RAT push 2 mul push 2 add sub jn _ratsign_zero
+  push 2 mod push 2 mul push 1 sub ret
+_ratsign_zero: pop push 0 ret

data/lib/spitewaste/libspw/stack.spw

@@ -1,77 +1,101 @@
+;;; Heavy-handed stack manipulation
+
+; These subrtouines do some pretty intricate stack-based operations, relying
+; heavily on clobbering the heap in order to maintain their "bookkeeping".
+; Many of them use heap addresses -10 and lower, unbounded, so they're only
+; meant to be used in a pinch or when there just isn't much of an alternative.
+
+import util ; dec
+
+; rolls the Ith element (counting from 0) to the top of the stack,
+; shifting the elements above it down by 1.
+; [I]
+;
+; [1 2 3 2] => [2 3 1]
+; [1 2 3 4 1] => [1 2 4 3]
+; [1 2 3 4 5 3] => [1 3 4 5 2]
 roll:
   push -10 dup store ; current heap index kept at -10
-
 _roll_keep: ; [n]
   dup jz _roll_remove
   push -10 :dec
   swap push -10 load swap store
   push 1 sub jump _roll_keep
-
 _roll_remove:
   push 10 sub load
   swap push -10 swap store
-
 _roll_restore: ; i
   dup load swap push 1 add
   dup push 10 add jz _roll_done
   jump _roll_restore
-
 _roll_done: load ret
 
-;;;
-
+; "buries" X in the stack at index I, counting from 0
+; [X I]
+;
+; [1 2 3 4 2] => [1 4 2 3] ; 2nd element of stack now 4
+; [1 2 3 4 5 8 5] => [8 1 2 3 4 5]
 bury:
   push -10 dup store ; current heap index kept at -10
   swap push -9 swap store ; preserve element to bury
-
 _bury_keep: ; [n]
   dup jz _bury_restore
   push -10 :dec
   swap push -10 load swap store
   push 1 sub jump _bury_keep
-
 _bury_restore:
   push 9 sub load
   push -10 load :_roll_restore pop ret
 
-;;;
 
+; "digs" out the Ith element of the stack and discards it
+; [I]
+;
+; [1 2 3 4 5 2] => [1 2 4 5]
+; [1 2 3 4 5 4] => [2 3 4 5]
 dig: :roll pop ret
 
-;;;
-
-to_a:
-  push -1 swap store
-  push -10 dup store
-
+; pops elements off the stack until it hits the specified sentinel value S,
+; pushing them to the resulting pseudo-array. It's often more convenient to
+; build up a collection in reverse order, and we often don't know in advance
+; how many elements we'll meet, but we do know to stop at the sentinel.
+; [S En ... E1 S] => [E1 ... En n]
+;
+; [-1 9 8 7 -1] => [7 8 9 3]
+; [0 'c' 'b' 'a' 0] => ['a' 'b' 'c' 3]
+to_a: push -1 swap store push -10 dup store
 _to_a_loop:
   dup push -1 load sub jz _to_a_sentinel
   push -10 dup :dec load
   swap store jump _to_a_loop
-
 _to_a_sentinel: pop push -10
-
 _to_a_restore:
   dup push -10 load sub jz _to_a_done
   push 1 sub dup load swap
   jump _to_a_restore
-
 _to_a_done: push -10 swap sub ret
 
-;;;
-
-; dynamic pop ; [n]
-npop:
-  dup jz _npop_done
-  swap pop push 1 sub jump npop
-
+; pops N elements off the top of the stack
+; [N]
+;
+; [1 2 3 4 5 3] => [1 2]
+; [1 2 3 4 0] => [1 2 3 4]
+npop: dup jz _npop_done swap pop push 1 sub jump npop
 _npop_done: pop ret
 
-; dynamic slide ; [n]
-nslide:
-  swap push -1 swap store
-  :npop push -1 load ret
-
+; slides N elements off the stack, as if the `slide` operator took an argument
+; [N]
+;
+; [1 2 3 4 5 2] => [1 2 5]
+; [1 2 3 4 1] => [1 2 4]
+nslide: swap push -1 swap store :npop push -1 load ret
+
+; copies the Nth element to the top of the stack; this does exactly what
+; a `copy N` instruction would do, but we don't always know N in advance
+; [N]
+;
+; [1 2 3 4 0] => [1 2 3 4 4] ; `copy 0` is just dup
+; [1 2 3 4 3] => [1 2 3 4 1]
 ncopy: push -10 dup store
 _ncopy_loop:
   dup jz _ncopy_save swap

data/lib/spitewaste/libspw/string.spw

@@ -1,104 +1,134 @@
-import math
 import case
+import math  ; divmod, ilog, max, pow
+import stack ; to_a
+import util  ; gt, lt, neq, range
 
 ;;; String packing and unpacking
 
 ; convert a 0-terminated string on the stack to a single base-128 integer
-strpack: push 0 ; tally
+; [0 ... c b a] => ["abc..."]
+;
+; [0 99 98 97] => ["abc"]
+; [0 99 98 97] => [1634657]
+; [0] => [0]
+strpack: push 0 ; accumulator
 _strpack_loop:
   swap dup jz _strpack_done
-  copy 1 push 128 mul add
-  slide 1
+  copy 1 push 128 mul add slide 1
   jump _strpack_loop
-
 _strpack_done: pop :strrev ret
 
 ; convert a single base-128 integer to a 0-terminated string on the stack
-strunpack:
-  :strrev push 0 swap ; terminator
-
+; ["abc..."] => [0 ... c b a]
+;
+; ["abc"] => [0 99 98 97]
+; [1634657] => [0 99 98 97]
+; [0] => [0]
+strunpack: :strrev push 0 swap ; terminator
 _strunpack_loop:
   dup jz _strunpack_done
   dup push 128 mod swap push 128 div
   jump _strunpack_loop
-
 _strunpack_done: pop ret
 
-;;;
-
-; takes a packed string and just returns it log128 to give the length
-strlen: push 128 :ilog ret
-
-;;;
+; returns the length of a packed string, which is just the
+; value itself log-128, +1 if the integer logarithm isn't exact.
+; [S] => [len(S)]
+;
+; [""] => [0]
+; ["abc"] => [3]
+; ["foobar"] => [6]
+strlen: dup push 128 :ilog swap push 128 mod push 0 :neq add ret
 
 ; takes two packed strings and returns their concatenation (as a packed string)
-strcat:
-  push 128 copy 2 :strlen :pow
-  mul add ret
-
-;;;
-
-; reverses a packed string in-place (heapless) [s] => [s.reverse]
-strrev: push 0 swap ; [tally string]
-
-_strrev_loop: ; [t s]
+; [S T] => [S+T]
+;
+; ["foo" ""] => ["foo"]
+; ["" "foo"] => ["foo"]
+; ["foo" "bar"] => ["foobar"]
+strcat: push 128 copy 2 :strlen :pow mul add ret
+
+; reverses a packed string "in-place"
+; [S] => [S']
+;
+; ["foo"] => ["oof"]
+; ["bark"] => ["krab"]
+; ["ab"] => ["ba"]   ['a'] => ['a']   [""] => [""]
+strrev: push 0 swap
+_strrev_loop:
   dup jz _strrev_done
-  swap push 128 mul ; [s t]
+  swap push 128 mul
   copy 1 push 128 mod add
   swap push 128 div
   jump _strrev_loop
-
 _strrev_done: pop ret
 
-;;;
-
-; takes a packed string, a start index, and a length and returns the
+; takes a packed string S, a start index I, and a length L and returns the
 ; corresponding substring (simply by doing division with powers of 128; neat)
+; [S I L] => [S']
+;
+; ["foobar" 0  6] => ["foobar"]
+; ["foobar" 1  4] => ["ooba"]
+; ["foobar" 1 10] => ["oobar"]
+; ["foobar" 5  1] => ['r']
+; ["foobar" 6  0] => [""]
 strslice:
   swap push 128 swap :pow
   copy 2 swap div
   swap push 128 swap :pow
   mod slide 1 ret
 
-;;;
-
-; index of substring t in string s ; [s t]
+; returns the index I of substring T in string S (or -1 if not found)
+; [S T] => [I]
+;
+; ["foobar" 'o'] => [1]
+; ["foobar" "ob"] => [2]
+; ["foobar" ""] => [0]
+; ["foobar" "bar"] => [3]
+; ["foobar" "bark"] => [-1]
 strindex: swap push 0
-
 _strindex_loop: ; [t s i]
   copy 1 copy 3 :strlen push 0 swap :strslice
   copy 3 sub jz _strindex_found
-  push 1 add ; increment index
-  swap push 128 div dup jz _strindex_no
+  push 1 add swap push 128 div dup jz _strindex_no
   swap jump _strindex_loop
-
 _strindex_no: push -1 slide 3 ret
-
 _strindex_found: slide 2 ret
 
-;;;
-
+; returns the character C at index I in string S
+; [S I] => [C]
+;
+; ["foobar" 1] => ['o']
+; ["foobar" 3] => ['b']
+; ["foobar" 5] => ['r']
+; ["foobar" 6] => [""]
 charat: push 1 :strslice ret
 
-;;;
-
-; 1 if the character at the top of the stack is alphabetical, 0 otherwise
+; returns 1 if the character at the top of the stack is
+; alphabetical (ASCII 65-90 or 97-122), 0 otherwise
+; [C] => [0 | 1]
+;
+; ['@'] => [0]   ['a'] => [1]
+; ['z'] => [1]   ['['] => [0]
+; ['`'] => [0]   ['A'] => [1]
+; ['Z'] => [1]   ['{'] => [0]
 isalpha:
   dup push 123 :lt jz _isalpha_no
   dup push 64 :gt jz _isalpha_no
   push 32 mod $-- push 32 mod push 26 :lt ret
 _isalpha_no: dup sub ret
 
-;;;
-
-; repeat a string s n times [s n]
+; returns string S replicated N times
+; [S N] => [S']
+;
+; ["abc" 1] => ["abc"]
+; ["abc" 2] => ["abcabc"]
+; ["abc" 0] => [""]
 strrep: push 0 swap
-_strrep_loop: ; [s t n]
+_strrep_loop:
   dup jz _strrep_done
   swap copy 2 :strcat
-  swap push 1 sub
-  jump _strrep_loop
-
+  swap push 1 sub jump _strrep_loop
 _strrep_done: swap slide 2 ret
 
 ;;; String alignment
@@ -107,19 +137,48 @@ _strrep_done: swap slide 2 ret
 ; we swap before calling strcat.
 _justc: swap copy 2 :strlen sub push 0 :max :strrep ret
 
-; Left-justify string s to width w with character c. [s w c]
+; left-justifies string S to width W with character C
+; [S W C] => [S']
+;
+; ["foo" 5 'x'] => ["fooxx"]
+; ["foobar" 4 'x'] => ["foobar"]
+; ["" 3 'x'] => ["xxx"]
 ljustc: :_justc :strcat ret
 
-; Left-justify string s to width w with spaces. [s w]
+; left-justifies string S to width W with spaces
+; [S W] => [S']
+;
+; ["foo" 5] => ["foo  "]
+; ["foobar" 4] => ["foobar"]
+; ["" 3] => [528416]
 ljust: push ' ' :ljustc ret
 
-; Right-justify string s to width w with character c. [s w c]
+; right-justifies string S to width W with character C
+; [S W C] => [S']
+;
+; ["foo" 5 'x'] => ["xxfoo"]
+; ["foobar" 4 'x'] => ["foobar"]
+; ["" 3 'x'] => ["xxx"]
 rjustc: :_justc swap :strcat ret
 
-; Right-justify string s to width w with spaces. [s w]
+; right-justifies string S to width W with spaces
+; [S W C] => [S']
+;
+; ["foo" 5] => ["  foo"]
+; ["foobar" 4] => ["foobar"]
+; ["" 3] => [528416]
 rjust: push ' ' :rjustc ret
 
-; Center string s to width w with character c. [s w c]
+; centers string S to width W with character C, favoring left alignment when
+; there's a parity mismatch (even-length string to odd width or vice versa)
+; ! TODO: This seems unnecessarily intricate, but perhaps just its nature.
+; [S W C] => [S']
+;
+; ["abc" 7 'x']  => ["xxabcxx"]
+; ["abc" 6 'x']  => ["xabcxx"]
+; ["abcd" 6 'o'] => ["oabcdo"]
+; ["abcd" 7 'o'] => ["oabcdoo"]
+; ["abcd" 3 '!'] => ["abcd"]
 centerc:
   swap dup copy 3 :strlen sub
   push 0 :max push 2 div
@@ -130,22 +189,42 @@ centerc:
   copy 2 swap :strrep :strcat
   slide 2 ret
 
-; Center string s to width w with spaces. [s w]
+; centers string S to width W with spaces
+; [S W] => [S']
+;
+; ["abc" 7] => ["  abc  "]
+; ["abc" 6] => [" abc  "]
+; ["abcd" 6] => [" abcd "]
+; ["abcd" 7] => [" abcd  "]
+; ["abcd" 3] => ["abcd"]
 center: push ' ' :centerc ret
 
 ;;;
 
-; remove the last character of a string
-strchop:
-  dup :strlen push 1 sub
-  push 0 swap :strslice ret
-
-; Split string s on delimiting character d.
-; ! clobbers heap addresses -1 and -2
-strsplit: ; [s d]
+; removes the last character of a string
+; [S] => [S']
+;
+; ["foobar"] => ["fooba"]
+; ["abc"] => ["ab"]
+; ["a"] => [""]
+; ! [""] => ERROR TODO: Should just be a no-op.
+strchop: dup :strlen push 1 sub push 0 swap :strslice ret
+
+; splits string S on delimiting character C, leaving the resultant substrings
+; on the stack as a pseudo-array (length at top of stack)
+; ! TODO: permit string delimiter
+; ! clobbers heap addresses -1 (strlen), -2, and -3
+; [S C] => [A]
+;
+; ["fooxbar" 'x'] => ["foo" "bar" 2]
+; ["foobar" 'x'] => ["foobar" 1]
+; ["foo|bar|baz" '|'] => ["foo" "bar" "baz" 3]
+; ["foo,,bar" ','] => ["foo" "" "bar" 3]
+; ["/foo/bar/" '/'] => ["" "foo" "bar" "" 4]
+strsplit:
   push -3 push 1 store ; number of found substrings
   push -2 swap store ; stash delimiter to allow some stack juggling
-_strsplit_loop: ; [s]
+_strsplit_loop:
   dup dup push -2 load
   :strindex dup jn _strsplit_done ; done when index of delimiter is -1
   push 0 swap :strslice
@@ -154,80 +233,137 @@ _strsplit_loop: ; [s]
   swap push -3 swap push 1 add store ; update number of found
   push 1 add push 128 swap :pow div ; shrink haystack
   jump _strsplit_loop
-
 _strsplit_done: push 2 sub slide 1 load ret
 
-;;;
+; splits the string S on newlines
+lines: push 10 :strsplit ret
 
-; [...strs n delim]
-; ! clobbers heap address -2 (strlen uses -1)
+; joins the pseudo-array of strings A into string S with delimiter string D
+; ! clobbers heap address -2 (and strlen uses -1)
+; [A D] => [S]
+;
+; ["foo" "bar" 2 'x'] => ["fooxbar"]
+; ["foo" "bar" "baz" 3 '--'] => ["foo--bar--baz"]
+; ["foo" 1 "?!"] => ["foo"]
 strjoinc:
   dup :strlen pop ; get delimiter length into -1
   push -2 swap store
   map (push -2 load :strcat) ; add delimiter to all elements
   swap push 128 copy 1 :strlen
   push -2 load :strlen
-  sub :pow mod swap ; remove delimiter from last and flow
+  sub :pow mod swap ; remove delimiter from last and flow into strjoin
+
+; concatenates the pseudo-array of strings A into string S
+; [A] => [S]
+;
+; ["foo" 1] => ["foo"]
+; ["foo" "bar" 2] => ["foobar"]
+; ["foo" 'x' "bar" 'x' "baz" 5] => ["fooxbarxbaz"]
 strjoin: reduce (:strcat) ret
 
-;;;
-
-; return the number of ocurrences of character c in string s [s c]
+; returns the number of ocurrences of character C in string S
+; [S C] => [N]
+;
+; ["foobar" 'a'] => [1]
+; ["foobar" 'o'] => [2]
+; ["foobar" 'c'] => [0]
 strcountc: swap push 0 swap
-
-_strcountc_loop: ; c t s
+_strcountc_loop:
   dup jz _strcountc_done
   dup push 128 mod copy 3 sub jz _strcountc_yes
   push 128 div jump _strcountc_loop
-
 _strcountc_yes:
   swap push 1 add swap push 128 div
   jump _strcountc_loop
-
 _strcountc_done: swap slide 2 ret
 
-; number of ocurrences of all characters in string c [s c]
+; returns the total number of ocurrences of all characters in string T in string S
+; [S T] => [N]
 ; ! clobbers heap address -2
+;
+; ["foobar" 'o'] => [2]
+; ["foobar" "ob"] => [3]
+; ["foxboar" "box"] => [4]
+; ["eunoia" "aeiou"] => [5]
+; ["why" "aeiou"] => [0]
 strcount:
   swap push -2 swap store
   :strunpack push 0 :to_a
   map (push -2 load swap :strcountc)
   reduce (add) ret
 
-;;;
-
-; Convert all characters in src to the corresponding characters in dest.
+; translates all characters in A to the corresponding characters in B
+; in stirng S, ; similar to the `tr` utility in Unix. A and B must be
+; of the same length. TODO: make this smarter (ranges, length mismatch)
 ; ! clobbers heap addresses -1, -2, and -3
-strtrans: ; [string src dest]
+; [S A B] => [S']
+;
+; ["abcd" "abc" "xyz"] => ["xyzd"]
+; ["foobar" "oba" "ele"] => ["feeler"]
+; ["abcdcba" "abcd" "xyz|"] => ["xyz|zyx"]
+strtrans:
   push -3 swap store
   push -2 swap store
   dup :strlen push -1 swap store
   :strunpack push -1 load
-  map (:_strtrans) pop
-  :strpack ret
-
+  map (:_strtrans) pop :strpack ret
 _strtrans:
   dup push -2 load swap :strindex
   dup jn _strtrans_no
   push -3 load swap :charat
   slide 1 ret
-
 _strtrans_no: pop ret
 
+; expands the length-2 string S to contain the intervening ASCII characters
+; ! TODO: make this smarter; multiple ranges in one string
+; [S] => [S']
+;
+; ["CJ"] => ["CDEFGHIJ"]
+; ["DA"] => ["DE"] TODO: bug
+; ["af"] => ["abcdef"]
+; ["09"] => ["0123456789"]
+; ["(1"] => ["()*+,-./01"]
 strexpand:
   push 0 swap push 128 :divmod
   swap :range :strpack :strrev ret
 
-strsqueeze: push 0 swap ; [sentinel s]
+; "squeezes" runs of the same character in string S to just one occurrence
+; [S] => [S']
+;
+; ["abc"] => ["abc"]
+; ["foobar"] => ["fobar"]
+; ["bookkeeper"] => ["bokeper"]
+; ["xxxxxxx"] => ["x"]
+strsqueeze: push 0 swap
 _strsqueeze_loop: ; [s]
   dup jz _strsqueeze_done
   push 128 :divmod dup copy 3 sub jz _strsqueeze_skip
   swap jump _strsqueeze_loop
-
 _strsqueeze_skip: pop jump _strsqueeze_loop
-
 _strsqueeze_done: pop :strpack :strrev ret
 
-strsum: :strunpack push 0 :to_a :arysum ret
-
-lines: push 10 :strsplit ret
+; returns the sum of the ordinal values of the characters in string S
+; [S] => [N]
+;
+; ["ABC"] => [198]
+; ["012"] => [147]
+; ["a"] => [97]
+; [""] => [] TODO: bug, should be 0
+strsum: :strunpack push 0 :to_a reduce (add) ret
+
+; rotates the string S to the left N times, wrapping
+; [S N]
+;
+; ["abc" 0] => ["abc"]
+; ["abcd" 1] => ["bcda"]
+; ["abcd" 5] => ["bcda"]
+; ["foodbar" 4] => ["barfood"]
+strrotl: push 128 swap copy 2 :strlen mod :pow :divmod :strcat ret
+
+; rotates the string S to the right N times, wrapping
+; [S N]
+;
+; ["abcd" 1] => ["dabc"]
+; ["abcd" 5] => ["dabc"]
+; ["foodbar" 3] => ["barfood"]
+strrotr: push 0 swap sub :strrotl ret