Add native RND and ASC functions

Implement bounded random integers with lazy clock seeding and add ASC as the inverse of CHR. Cover dispatch, validation, deterministic LCG output, UTF-8 round trips, function reference, and the breakout tutorial.

Closes #16.

Co-authored-by: andrew <andrew@aklabs.net>

docs/12-function-reference.md

@@ -9,6 +9,7 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | Function | Args | Form | What it gives |
 |---|---|---|---|
 | `ABS` | 1 | `ABS(n)` | The absolute value of an integer or float. |
+| `ASC` | 1 | `ASC(A$)` | The Unicode code point of a string's first character. |
 | `ATN` | 1 | `ATN(n)` | Arctangent, in radians. |
 | `BUMP` | 1 | `BUMP(1)` | Which sprites have collided, as a bitmask. **Reading clears it.** |
 | `CHR` | 1 | `CHR(n)` | The character for a Unicode code point, as a string. |
@@ -29,6 +30,7 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
 | `RMENU` | 2 | `RMENU(n, f)` | A menu's state: field 0 the highlighted entry, field 1 whether it has been confirmed. **Reading field 1 clears it.** |
+| `RND` | 1 | `RND(n)` | A random integer from 0 up to but not including `n`. |
 | `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |

docs/17-tutorial-breakout.md

@@ -1005,20 +1005,48 @@ IF NUDGE# = 1 THEN GOSUB UNSTICK
 LABEL UNSTICK
 NUDGE# = 0
 STALL# = 0
-RMAX# = 4
+BVX# = (RND(4) * 3) - 6
-GOSUB RANDOM
-BVX# = (RND# * 3) - 6
 IF BVX# = 0 THEN BVX# = 3
 RETURN
 ```
 
-### You have to write your own random numbers
+### Random numbers are built in
 
-**There is no `RND` in this dialect**, and no `INT`, `SQR`, `ASC` or `TIMER` either. A
+There is no `INT`, `SQR` or `TIMER` in this dialect, but
-linear congruential generator is nine tokens and does the job. Put the number of possible
+`RND(n)` returns an integer from zero through `n - 1`. It seeds itself
-answers in `RMAX#` and read the result from `RND#`:
+from the host clock the first time it is called, so a program only needs the bound:
 
 ```basic
+I# = 0
+FOR I# = 1 TO 5
+  PRINT "ROLL " + (RND(6) + 1)
+NEXT I#
+END
+```
+
+Use `RND` for the serve, too, so the ball does not always leave in the same direction:
+
+```basic norun
+LABEL SERVE
+PX# = (SCW# - PW#) / 2
+HELD# = 1
+BX# = PX# + ((PW# / 2) - 4)
+BY# = PY# - 10
+BVX# = BSPD#
+IF RND(2) = 0 THEN BVX# = 0 - BSPD#
+BVY# = 0 - BSPD#
+PDEC# = 0
+GOSUB SHOWSPR
+RETURN
+```
+
+<details>
+<summary>Historical aside: the LCG this chapter used to teach</summary>
+
+Before `RND` existed, this nine-token linear congruential generator was copied into
+every program. It remains a useful from-scratch PRNG example:
+
+```basic norun
 SEED# = 12345
 RMAX# = 6
 RND# = 0
@@ -1035,43 +1063,11 @@ RND# = MOD((SEED# / 65536), RMAX#)
 RETURN
 ```
 
-```output
+The multiplication stays inside a 64-bit integer for any seed below 2147483648. The
-ROLL 1
+answer is taken from the middle bits because the low bits of a power-of-two modulus
-ROLL 5
+barely change from one call to the next. This used to be required; it is now built in.
-ROLL 2
-ROLL 1
-ROLL 2
-```
 
-The multiplication stays inside a 64-bit integer for any seed below 2147483648, which is
+</details>
-why the modulus is that number. The answer is taken from the middle bits — `SEED# / 65536`
-— because the low bits of a power-of-two modulus barely change from one call to the next.
-Integer division truncating for free is the `INT` you do not have.
-
-Seed it from the clock at startup. `TI#` is the host's uptime in sixtieths of a second,
-which is different every time the game is run:
-
-```basic norun
-SEED# = TI#
-```
-
-Use `RANDOM` for the serve, too, so the ball does not always leave in the same direction:
-
-```basic norun
-LABEL SERVE
-PX# = (SCW# - PW#) / 2
-HELD# = 1
-BX# = PX# + ((PW# / 2) - 4)
-BY# = PY# - 10
-RMAX# = 2
-GOSUB RANDOM
-BVX# = BSPD#
-IF RND# = 0 THEN BVX# = 0 - BSPD#
-BVY# = 0 - BSPD#
-PDEC# = 0
-GOSUB SHOWSPR
-RETURN
-```
 
 `HELD#` is the flag Step 6's loop tests: while it is 1 the ball sits on the paddle, and
 `HOLDBAL` keeps it there:
@@ -1422,9 +1418,7 @@ PX# = PX# + D#
 RETURN
 
 LABEL DEMOAIM
-RMAX# = 81
+DOFF# = RND(81) - 40
-GOSUB RANDOM
-DOFF# = RND# - 40
 RETURN
 ```
 
@@ -1501,7 +1495,7 @@ This is the shape of the whole file:
 LABEL SETUP           the geometry from Step 2
                       the declaration block from Step 3
                       the brick faces from Step 5
-                      SEED# = TI#
+                      RND(n) seeds itself from the host clock
                       the ceiling from Step 9
                       GOSUB MKSPR       Step 4
                       GOSUB SNDPROBE    Step 14
@@ -1576,10 +1570,7 @@ BB# = 0
 RX# = 0