spitewaste 0.1.009 → 0.2.01

data/lib/spitewaste/libspw/fun.spw

@@ -36,6 +36,12 @@ _isop_resume: sub add swap push 128 div jump _isop_loop
 _isop_no: dup jump _isop_resume
 _isop_done: pop ret
 
+$_do_collatz() {
+  dup push 2 mod
+  swap copy 1 push 2 mul $++ mul
+  push 2 copy 2 sub div add
+}
+
 ; returns the elements of the Collatz sequence for integer N as a pseudo-array
 ; ! may run forever on some as-yet-unknown input
 ; [N] => [A]
@@ -48,11 +54,43 @@ _isop_done: pop ret
 collatz: push 1 ; sequence length
 _collatz_loop:
   copy 1 dup push 1 sub jz _collatz_done
-  dup push 2 mod
-  swap copy 1 push 2 mul $++ mul
-  push 2 copy 2 sub div add
-  swap $++ jump _collatz_loop
+  $_do_collatz() swap $++ jump _collatz_loop
 _collatz_done: pop ret
 
+; returns the length L of the Collatz sequence for integer N
+; ! may run forever on some as-yet-unknown input
+; [N] => [L]
+;
+; [1] => [1]
+; [4] => [3]
+; [7] => [17]
+; [189] => [107]
+collatz_len: push 1 swap
+_collatz_len_loop:
+  dup $-- jz _collatz_done
+  $_do_collatz() swap $++ swap jump _collatz_len_loop
+  copy 1 dup push 1 sub jz _collatz_done
+
 ; ruby:
 ;   push "'" :strcat push "ruby -e 'p " swap :strcat shell ret
+
+$_to_roman(r, v) {
+  push `v` :divmod swap push `r` swap :strrep
+  @-2 swap :strcat ^-2
+}
+
+; converts the number N to a string of roman numerals R
+; [N] => [R]
+;
+; [2020] => ["MMXX"]
+; [1666] => ["MDCLXVI"]
+; [1337] => ["MCCCXXXVII"]
+; [94] => ["XCIV"]
+to_roman: push -2,0 store
+  $_to_roman("M", 1000) $_to_roman("CM", 900)
+  $_to_roman("D", 500)  $_to_roman("CD", 400)
+  $_to_roman("C", 100)  $_to_roman("XC", 90)
+  $_to_roman("L", 50)   $_to_roman("XL", 40)
+  $_to_roman("X", 10)   $_to_roman("IX", 9)
+  $_to_roman("V", 5)    $_to_roman("IV", 4)
+  $_to_roman("I", 1) push 2 sub load ret

data/lib/spitewaste/libspw/math.spw

@@ -1,8 +1,7 @@
 import array ; arycat, arydup
 import util  ; eq, inc, range
 
-; returns B raised to the power E
-; ! TODO: support negative exponents (return Rational)
+; returns B raised to the power E; if E must be negative, use ratpow instead
 ; [B E] => [B**E]
 ;
 ; [0 0] => [1],   [0 9] => [0],   [9 0] => [1]
@@ -52,7 +51,7 @@ ilog: push -1,0 store ; accumulator at -1
 _ilog_loop: ; [n b]
   swap copy 1 div dup jz _ilog_done
   push -1 :inc swap jump _ilog_loop
-_ilog_done: push -1 load slide 2 ret
+_ilog_done: @-1 slide 2 ret
 
 ; returns the greatest common divisor of A and B
 ; [A B] => [gcd(A, B)]
@@ -112,10 +111,7 @@ abs: dup :sign mul ret
 ; [42 6] => [7 0]
 ; [ 1 5] => [0 1]
 ; ! [9 0] => [!!] TODO: find a way to expect exceptions
-divmod:
-  push -1 swap store
-  dup push -1 load div
-  swap push -1 load mod ret
+divmod: ^-1 dup @-1 div swap @-1 mod ret
 
 ; returns whether N is greater than 0
 ; [N] => [N > 0]
@@ -139,11 +135,11 @@ neg?: :sign push -1 :eq ret
 ; [25] => [1 5 25 3] ; no duplicate for perfect squares
 ; [60] => [1 2 3 4 5 6 60 30 20 15 12 10 12]
 divisors: ; [n]
-  dup push -1 swap store ; preserve N because array operations
+  dup ^-1 ; preserve N because array operations
   :isqrt push 1 swap :range dup ; 1..isqrt(N)
-  reject (push -1 load swap mod) :arydup ; get first half of divisors
-  map (push -1 load swap div) :arycat ; map first half to second half
-  push -1 load copy 2 dup mul sub jz _divisors_square ret
+  reject (@-1 swap mod) :arydup ; get first half of divisors
+  map (@-1 swap div) :arycat ; map first half to second half
+  @-1 copy 2 dup mul sub jz _divisors_square ret
 _divisors_square: slide 1 $-- ret ; de-duplicate when N is a perfect square
 
 ; returns the number of ways to choose K elements from a set of N

data/lib/spitewaste/libspw/random.spw

@@ -1,12 +1,34 @@
-import math ; pow
+import math   ; pow
+import string ; strtoa
 
-srand: push $seed swap store ret
+; seeds the random number generator with integer S
+; [S] => []
+srand: ^$seed ret
 
+; returns the next number N in the linear congruential generator (better MINSTD)
+; [] => [N]
 rand:
   push $seed dup dup load
-  push 3,13,10244807 mul mul mul
-  push 2,32 :pow mod
+  push 48271 mul
+  push 2,31 :pow $-- mod
   store load ret
 
-rand_range: ; [a b]
-  copy 1 sub :rand swap mod add ret
+; returns a random integer I between A and B (inclusive)
+; [A B] => [I]
+rand_range:
+  $++ copy 1 sub :rand swap mod add ret
+
+; returns an array A of N random integers between 1 and D (inclusive)
+; [N D] => [A]
+dice: ^-2 dup ^-1 times (push 1 @-2 :rand_range) @-1 ret
+
+; shuffles the array A in-place using the modern Fisher-Yates algorithm
+; [A] => [A']
+shuffle: dup $-- ^-3
+_shuffle_loop:
+  push 0 @-3 :rand_range @-3 :aryswap
+  push -3 :dec @-3 push -1 mul jn _shuffle_loop ret
+
+; shuffles the characters of the string S, producing a random anagram
+; [S] => [S']
+strfry: :strtoa :shuffle pop :strpack ret

data/lib/spitewaste/libspw/rational.spw

@@ -169,8 +169,37 @@ ratinv:
 ; [R(4,2) 5] => [R(32,1)]
 ; [R(-3,7) 0] => [R(1,1)]
 ; [R(-3,14) 2] => [R(9,196)]
-ratpow:
+; [R(5,1) -1] => [R(1,5)]
+; [R(2,5) -2] => [R(25,4)]
+; [R(-3,14) -3] => [R(-2744,27)]
+ratpow: dup jn _ratpow_neg
   swap push 2 :divmod push 2 mul $--
   swap $RAT :divmod copy 2 mul
   copy 3 :pow swap copy 3 :pow
   swap :to_r :ratsimp slide 2 ret
+_ratpow_neg: push -1 mul swap :ratinv swap :ratpow ret
+
+; converts the rational number R to a "pseudo-float" with a whole (W) part
+; and a fractional (F) part composed of P digits after the decimal point
+; [R P] => [W F]
+;
+; [R(22,7) 2] => [3 14]
+; [R(355,113) 6] => [3 141592]
+; [R(8675,309) 10] => [28 744336569] TODO: leading 0 is lost (bug)
+; [R(2,4) 3] => [0 500]
+to_f: ^-2 :from_r :divmod push 0 swap
+_to_f_loop:
+  @-1 :divmod  swap
+  copy 2 push 10 mul add
+  swap push 10 mul
+  push 2 :dig
+  push -2 dup :dec load :neg? jz _to_f_loop pop ret
+
+; converts the rational number R to a string S of the form
+; "<simplified numerator>/<simplified denominator>"
+; [R] => [S]
+;
+; [R(22,7)] => ["22/7"]
+; [R(2,4)] => ["1/2"]
+; [R(99,9)] => ["11/1"]
+ratstr: :ratsimp :from_r push 2 map (:to_s) push '/' :strjoinc ret

data/lib/spitewaste/libspw/stack.spw

@@ -16,15 +16,13 @@ import util ; dec
 ; [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]
+_roll_keep:
   dup jz _roll_remove
   push -10 :dec
-  swap push -10 load swap store
+  swap @-10 swap store
   push 1 sub jump _roll_keep
-_roll_remove:
-  push 10 sub load
-  swap push -10 swap store
-_roll_restore: ; i
+_roll_remove: push 10 sub load swap ^-10
+_roll_restore:
   dup load swap push 1 add
   dup push 10 add jz _roll_done
   jump _roll_restore
@@ -37,15 +35,15 @@ _roll_done: load ret
 ; [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
+  swap ^-9 ; preserve element to bury
 _bury_keep: ; [n]
   dup jz _bury_restore
   push -10 :dec
-  swap push -10 load swap store
+  swap @-10 swap store
   push 1 sub jump _bury_keep
 _bury_restore:
   push 9 sub load
-  push -10 load :_roll_restore pop ret
+  @-10 :_roll_restore pop ret
 
 
 ; "digs" out the Ith element of the stack and discards it
@@ -63,14 +61,14 @@ dig: :roll pop ret
 ;
 ; [-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: ^-1 push -10 dup store
 _to_a_loop:
-  dup push -1 load sub jz _to_a_sentinel
+  dup @-1 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
+  dup @-10 sub jz _to_a_done
   push 1 sub dup load swap
   jump _to_a_restore
 _to_a_done: push -10 swap sub ret
@@ -88,7 +86,7 @@ _npop_done: pop ret
 ;
 ; [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
+nslide: swap ^-1 :npop @-1 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

data/lib/spitewaste/libspw/string.spw

@@ -207,8 +207,10 @@ center: push ' ' :centerc ret
 ; ["foobar"] => ["fooba"]
 ; ["abc"] => ["ab"]
 ; ["a"] => [""]
-; ! [""] => ERROR TODO: Should just be a no-op.
-strchop: dup :strlen push 1 sub push 0 swap :strslice ret
+; [""] => [""]
+strchop: dup jz _strchop_empty
+  dup :strlen push 1 sub push 0 swap :strslice ret
+_strchop_empty: ret
 
 ; splits string S on delimiting character C, leaving the resultant substrings
 ; on the stack as a pseudo-array (length at top of stack)
@@ -222,13 +224,13 @@ strchop: dup :strlen push 1 sub push 0 swap :strslice ret
 ; ["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
+  push -3,1 store ; number of found substrings
+  ^-2 ; stash delimiter to allow some stack juggling
 _strsplit_loop:
-  dup dup push -2 load
+  dup dup @-2
   :strindex dup jn _strsplit_done ; done when index of delimiter is -1
   push 0 swap :strslice
-  swap copy 1 push -3 load
+  swap copy 1 @-3
   swap :strlen
   swap push -3 swap push 1 add store ; update number of found
   push 1 add push 128 swap :pow div ; shrink haystack
@@ -246,11 +248,10 @@ lines: push 10 :strsplit ret
 ; ["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
+  dup :strlen pop ^-2 ; get delimiter length into -1
+  map (@-2 :strcat) ; add delimiter to all elements
   swap push 128 copy 1 :strlen
-  push -2 load :strlen
+  @-2 :strlen
   sub :pow mod swap ; remove delimiter from last and flow into strjoin
 
 ; concatenates the pseudo-array of strings A into string S
@@ -287,13 +288,12 @@ _strcountc_done: swap slide 2 ret
 ; ["eunoia" "aeiou"] => [5]
 ; ["why" "aeiou"] => [0]
 strcount:
-  swap push -2 swap store
-  :strunpack push 0 :to_a
-  map (push -2 load swap :strcountc)
+  swap ^-2 :strunpack push 0 :to_a
+  map (@-2 swap :strcountc)
   reduce (add) ret
 
 ; 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
+; in string 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
 ; [S A B] => [S']
@@ -301,16 +301,13 @@ strcount:
 ; ["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
+strtrans: ^-3 ^-2
+  dup :strlen ^-1 :strunpack @-1
   map (:_strtrans) pop :strpack ret
 _strtrans:
-  dup push -2 load swap :strindex
+  dup @-2 swap :strindex
   dup jn _strtrans_no
-  push -3 load swap :charat
+  @-3 swap :charat
   slide 1 ret
 _strtrans_no: pop ret
 
@@ -343,17 +340,38 @@ _strsqueeze_loop: ; [s]
 _strsqueeze_skip: pop jump _strsqueeze_loop
 _strsqueeze_done: pop :strpack :strrev ret
 
+$_strdel(cmp) {
+  :strunpack @-1 :strlen
+  select (@-2 swap :strindex `cmp`)
+  pop :strpack ret
+}
+
+; returns the string S with all characters in string T removed, like `tr -d`.
+; If the first character of T is '^', instead only those characters are kept.
+; [S T] => [S']
+;
+; ["abc123" "abc"] => ["123"]
+; ["abc123" "123"] => ["abc"]
+; ["abcba12321" "abc"] => ["12321"]
+; ["abc12321cba" "^2ac"] => ["ac22ca"]
+; ["facetious" "^aeiou"] => ["aeiou"]
+strdel: push -1 copy 2 store push -2 copy 1 store
+  push 0 :charat push '^' :neq jz _strdel_comp $_strdel(:neg?)
+_strdel_comp: $_strdel(:pos?)
+
 ; 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
+; [""] => [0]
+strsum: dup jz _strsum_empty
+  :strunpack push 0 :to_a reduce (add) ret
+_strsum_empty: ret
 
 ; rotates the string S to the left N times, wrapping
-; [S N]
+; [S N] => [S']
 ;
 ; ["abc" 0] => ["abc"]
 ; ["abcd" 1] => ["bcda"]
@@ -362,9 +380,22 @@ strsum: :strunpack push 0 :to_a reduce (add) ret
 strrotl: push 128 swap copy 2 :strlen mod :pow :divmod :strcat ret
 
 ; rotates the string S to the right N times, wrapping
-; [S N]
+; [S N] => [S']
 ;
 ; ["abcd" 1] => ["dabc"]
 ; ["abcd" 5] => ["dabc"]
 ; ["foodbar" 3] => ["barfood"]
-strrotr: push 0 swap sub :strrotl ret
+strrotr: push -1 mul :strrotl ret
+
+; gets the characters of the string S onto the stack as a pseudo-array, but
+; with a leading 0 on the assumption that it'll eventually be repacked
+;
+; ["abc"] => [0 99 98 97 3]
+strtoa: dup :strlen pop :strunpack @-1 $++ ret
+
+; frobnicates the string S by XORing all its bytes with 42
+; [S] => [S']
+;
+; ["foobar"] => ["LEEHKX"]
+; ["LEEHKX"] => ["foobar"]
+memfrob: :strtoa map (push 42 :bxor) pop :strpack ret

data/lib/spitewaste/libspw/terminal.spw

@@ -0,0 +1,14 @@
+;;; Miscellaneous terminal-based functionality
+
+import util ; hex2rgb
+
+$_setg(code) {
+  push 91,27 ochr ochr
+  push `code` onum push 50,59 ochr ochr
+  :hex2rgb each (push 59 ochr onum)
+  push 109 ochr ret
+}
+
+setfg: $_setg(38)
+setbg: $_setg(48)
+reset: push 109,91,27 ochr ochr ochr ret

data/lib/spitewaste/libspw/test.spw

@@ -8,3 +8,6 @@ assert_eq:
   push ", got " :print onum
   push " for test " swap :strcat :die!
 _assert_eq_yes: pop pop pop ret
+
+assert_nz: jz _assert_nz_no pop ret
+_assert_nz_no: push "expected nonzero for test " swap :strcat :die!

data/lib/spitewaste/libspw/util.spw

@@ -15,22 +15,24 @@ import string ; charat, strcat, strindex, strlen
 ; [0 -2] => [0 -1 -2]
 ; [-3 3] => [-3 -2 -1 0 1 2 3]
 ; [3 -3] => [3 2 1 0 -1 -2 -3]
-; [4 4] => [4 5] TODO: bug
-range: dup copy 2 sub jn _range_down
+; [4 4] => [4]
+range: dup copy 2 sub jz _range_one dup copy 2 sub jn _range_down
   copy 1 push 1 add swap
   copy 1 copy 1 sub jn range pop ret
+_range_one: pop ret
 _range_down:
   copy 1 push 1 sub swap
   dup copy 2 sub jn _range_down pop ret
 
 $range_loop(fn, cmp) {
 `fn`:
-  copy 1 copy 1 add swap dup
-  copy 2 add push -1 load `cmp` jz `fn` pop ret
+  dup copy 2 add @-1 `cmp` jz _`fn`_done
+  copy 1 copy 1 add swap jump `fn`
+_`fn`_done: pop ret
 }
 
-; inserts between the top two stack values the intervening consecutive elements,
-; counting by `step` up/down to (but never beyond) J
+; inserts between I and J the intervening consecutive elements, counting by
+; step S up/down to (but never beyond) J
 ; [I J S] => [I I±S ... ~J]
 ;
 ; [1 4 1] => [1 2 3 4]
@@ -39,12 +41,19 @@ $range_loop(fn, cmp) {
 ; [10 2 -3] => [10 7 4]
 ; [-5 25 10] => [-5 5 15 25]
 ; [25 -5 -10] => [25 15 5 -5]
-steprange: swap push -1 swap store dup copy 2 sub jn _steprange_down_loop
-$range_loop(_steprange_loop, :gt)
-$range_loop(_steprange_down_loop, :lt)
-
-; prints the string at the top of the stack and halts execution
-die!: :println exit
+; [4 20 3] => [4 7 10 13 16 19]
+; [20 4 -3] => [20 17 14 11 8 5]
+; [3 9 7] => [3]
+; [9 3 -7] => [9]
+steprange: swap push -1 copy 1 store copy 2 sub
+  jn _steprange_down_loop jump _steprange_loop ; prevent DCE
+$range_loop(_steprange_loop, :lte)
+$range_loop(_steprange_down_loop, :gte)
+
+; prints the string at the top of the stack and halts execution after pushing
+; something onto the stack to signal abnormal termination/unclean exit
+; [...] => [... 1]
+die!: :println push 1 exit
 
 ; for stoi and itos
 alpha: push "0123456789abcdefghijklmnopqrstuvwxyz" ret
@@ -65,7 +74,7 @@ alpha: push "0123456789abcdefghijklmnopqrstuvwxyz" ret
 ; ["-123" 10] => [-123]
 ; ["-ff" 16] => [-255]
 stoi: swap dup :_stoi_sign swap copy 1 :eq
-  push 2 mul $-- push -2 swap store push 0
+  push 2 mul $-- ^-2 push 0
 _stoi_loop: ; [b s a]
   swap dup jz _stoi_done
   swap copy 2 copy 2
@@ -76,10 +85,11 @@ _stoi_loop: ; [b s a]
   mul add swap push 128 div swap
   jump _stoi_loop
 _stoi_sign: dup push 0 :charat push '-' :eq copy 1 :strlen :strslice ret
-_stoi_invalid: pop pop slide 1 swap div push -2 load mul ret
-_stoi_done: swap slide 2 push -2 load mul ret
+_stoi_invalid: pop pop slide 1 swap div @-2 mul ret
+_stoi_done: swap slide 2 @-2 mul ret
 
 ; creature comforts
+
 bin:  push  2 :stoi ret
 oct:  push  8 :stoi ret
 to_i: push 10 :stoi ret
@@ -89,11 +99,13 @@ hex:  push 16 :stoi ret
 ; [N B]
 ;
 ; [42 2] => ["101010"]
+; [-42 2] => ["-101010"]
 ; [511 8] => ["777"]
 ; [12345 10] => ["12345"]
+; [-54321 10] => ["-54321"]
 ; [57005 16] => ["dead"]
 ; [81699 17] => ["gabe"]
-itos: swap push 0 ; accumulator
+itos: swap push -2 copy 1 :neg? store :abs push 0
 _itos_loop:
   swap dup jz _itos_done
   swap copy 1 copy 3 mod
@@ -101,9 +113,10 @@ _itos_loop:
   swap :strcat
   swap copy 2 div
   swap jump _itos_loop
-_itos_done: swap slide 2 ret
+_itos_done: swap slide 2 push 45 @-2 mul swap :strcat ret
 
 ; creature comforts
+
 to_bin: push  2 :itos ret
 to_oct: push  8 :itos ret
 to_s:   push 10 :itos ret
@@ -118,12 +131,10 @@ to_hex: push 16 :itos ret
 ; [256 16] => [1 0 0 3]
 digits:
   copy 1 jz _digits_zero ; special case
-  push -1 swap store
-  push -1 swap ; sentinel value
+  ^-1 push -1 swap ; sentinel value
 _digits_loop:
   dup jz _digits_done
-  push -1 load :divmod
-  swap jump _digits_loop
+  @-1 :divmod swap jump _digits_loop
 _digits_zero: dup div ret
 _digits_done: push 1 sub :to_a ret
 
@@ -187,6 +198,18 @@ lte: swap ; intentionally flow into gte
 gte: sub jn _gte_no push 1 ret
 _gte_no: push 0 ret
 
+; returns 1 if the number N is between A and B (inclusive), 0 otherwise
+; ! A must be <= B for sensible results TODO: bug?
+; [N A B]
+;
+; [5 0 10] => [1]
+; [11 0 10] => [0]
+; [4 0 4] => [1]
+; [-1 0 4] => [0]
+; [-5 -10 0] => [1]
+; [3 4 2] => [0]
+between?: copy 2 :gte swap copy 2 :lte mul slide 1 ret
+
 ; Though extremely rare, it's possible that we know a particular value is
 ; stored in the heap at some key, just not which one. This subroutine takes
 ; a value V to search for and a starting index I, and either returns the first
@@ -195,3 +218,31 @@ _gte_no: push 0 ret
 heap_seeking_missile:
   $++ dup load copy 2 :eq jz heap_search
   slide 1 ret
+
+; converts the #RRGGBB (leading '#' optional) color string S to
+; its individual RGB components as integers in the range 0-255
+; [S] => [R G B]
+;
+; ["#000000"] => [0 0 0]
+; ["ffffff"]  => [255 255 255]
+; ["#102030"] => [16 32 48]
+; ["c0ffee"] => [192 255 238]
+hex2rgb:
+  dup push 0 :charat push '#' :eq push 127 mul $++ div
+  push 128,2 :pow :divmod :hex swap
+  push 128,2 :pow :divmod :hex swap :hex ret
+
+; converts R, G, and B components to length-6 hexadecimal string S
+; ! dies if any of the values to convert aren't between 0 and 255
+; [R G B] => [S]
+;
+; [0 0 0] => ["000000"]
+; [255 255 255] => ["ffffff"]
+; [16 32 48] => ["102030"]
+; [192 255 238] => ["c0ffee"]
+rgb2hex:
+  push 3 :arydup all (push 0,255 :between?) jz _rgb2hex_invalid
+  pop copy 2 push 256,2 :pow mul
+  copy 2 push 256 mul add add
+  slide 2 :to_hex push 6,48 :rjustc ret
+_rgb2hex_invalid: push "(rgb2hex) invalid RGB" :die!