Add native RND and ASC functions
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 40s
akbasic CI Build / sanitizers (push) Failing after 45s
akbasic CI Build / coverage (push) Failing after 48s
akbasic CI Build / akgl_build (push) Failing after 49s
akbasic CI Build / mutation_test (push) Failing after 45s

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>
This commit is contained in:
2026-08-05 06:40:53 -04:00
parent fac84acdaa
commit 699ac9ab93
9 changed files with 141 additions and 50 deletions

View File

@@ -1005,20 +1005,48 @@ IF NUDGE# = 1 THEN GOSUB UNSTICK
LABEL UNSTICK
NUDGE# = 0
STALL# = 0
RMAX# = 4
GOSUB RANDOM
BVX# = (RND# * 3) - 6
BVX# = (RND(4) * 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
linear congruential generator is nine tokens and does the job. Put the number of possible
answers in `RMAX#` and read the result from `RND#`:
There is no `INT`, `SQR` or `TIMER` in this dialect, but
`RND(n)` returns an integer from zero through `n - 1`. It seeds itself
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
ROLL 1
ROLL 5
ROLL 2
ROLL 1
ROLL 2
```
The multiplication stays inside a 64-bit integer for any seed below 2147483648. The
answer is taken from the middle bits because the low bits of a power-of-two modulus
barely change from one call to the next. This used to be required; it is now built in.
The multiplication stays inside a 64-bit integer for any seed below 2147483648, which is
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
```
</details>
`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
GOSUB RANDOM
DOFF# = RND# - 40
DOFF# = RND(81) - 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
N# = 0
MROW# = 0
RMAX# = 2
RND# = 0
SND# = 0
SEED# = 0
P$ = ""
H$ = ""
S$ = ""