Andrew Kesterson
342e4c07da
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m2s
akbasic CI Build / sanitizers (push) Successful in 3m52s
akbasic CI Build / coverage (push) Failing after 3m24s
akbasic CI Build / akgl_build (push) Failing after 20s
akbasic CI Build / mutation_test (push) Has been cancelled
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand exactly once, when it was written, which is not a standard that survives a changing interpreter -- and four were already wrong: two transcripts showing a leading space PRINT does not emit, akbasic_TextSink in README.md missing the two members it had grown hours earlier, and FILTER's refusal quoted with wording the code does not use. tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds. BASIC programs and transcripts run and are byte-compared against an `output` block; C snippets compile with -fsyntax-only against the real include path, which CMake writes out because it is transitive through akerror, akstdlib and akgl; shell blocks run in a sandbox. Anything that would reconfigure the build tree, hit the network or re-enter the suite is tagged norun with the reason in MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision. An untagged block is a failure rather than a default, and the pass line reports what it executed by kind. Both exist because the way a harness like this dies is by quietly matching nothing and passing -- which it duly did on the first CTest run, where a generator expression evaluating to nothing still contributed an empty argument that the script read as a filename. The count is what caught it. The excerpt check earns its own mention: a block tagged `c excerpt=include/akbasic/sink.h` must still appear in that header, comments and whitespace ignored. Compiling it would only redefine the type, so a compile check could not have found the stale struct, and did not. Registered as the CTest case docs_examples in both configurations. Fixing the four wrong examples turned up two interpreter defects, fixed in the previous commit and recorded in TODO.md section 8. MAINTENANCE.md is new: the fence-tag reference, what to do when the case fails, and the conventions that until now only existed inside source comments -- the three test lists and how two of them invert "passed", the sorted verb table, that a golden file is never edited to suit this interpreter, and that a fix gets mutation-checked with a file copy rather than git checkout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
# 5. Strings and formatting
|
|
|
|
## The string functions
|
|
|
|
| Function | What it gives you |
|
|
|---|---|
|
|
| `LEN(A$)` | how many characters, or how many elements in an array |
|
|
| `LEFT(A$, N#)` | the leftmost `N#` characters |
|
|
| `RIGHT(A$, N#)` | the rightmost `N#` characters |
|
|
| `MID(A$, START#, LENGTH#)` | a substring, counting from **zero** |
|
|
| `INSTR(A$, B$)` | where `B$` appears in `A$` counting from **zero**, or -1 |
|
|
| `CHR(N#)` | the character for a Unicode code point |
|
|
| `STR(N#)` | a number as a string |
|
|
| `VAL(A$)` | a string as a number |
|
|
| `HEX(N#)` | a number as hexadecimal text |
|
|
| `SPC(N#)` | that many spaces |
|
|
|
|
`LEFT` and `RIGHT` clamp rather than failing, so asking for more characters than the
|
|
string has gives you the whole string.
|
|
|
|
**`MID` and `INSTR` count from zero**, where a C128's `MID$` and `INSTR` count from one.
|
|
`MID("HELLO WORLD", 6, 5)` is `WORLD`, and `INSTR("HELLO WORLD", "WORLD")` is `6`. A
|
|
failed `INSTR` gives -1, not 0, so there is no ambiguity with a match at the start.
|
|
|
|
```basic
|
|
10 A$ = "HELLO WORLD"
|
|
20 PRINT LEN(A$)
|
|
30 PRINT LEFT(A$, 5)
|
|
40 PRINT RIGHT(A$, 5)
|
|
50 PRINT MID(A$, 6, 5)
|
|
60 PRINT INSTR(A$, "WORLD")
|
|
```
|
|
|
|
```output
|
|
11
|
|
HELLO
|
|
WORLD
|
|
WORLD
|
|
6
|
|
```
|
|
|
|
`VAL` refuses text that is not a number rather than quietly returning zero, so a
|
|
program can tell "the user typed 0" from "the user typed nonsense".
|
|
|
|
## PRINT USING
|
|
|
|
`PRINT USING` lays a value out in a fixed field, which is what makes columns line up.
|
|
|
|
```basic
|
|
10 PRINT USING "###.##"; 3.14159
|
|
20 PRINT USING "TOTAL: $#,###.##"; 1234.5
|
|
30 PRINT USING "####-"; -42
|
|
```
|
|
|
|
```output
|
|
3.14
|
|
TOTAL: $1,234.50
|
|
42-
|
|
```
|
|
|
|
The field is built from these characters, and any text around it is printed as it
|
|
stands:
|
|
|
|
| In the field | Means |
|
|
|---|---|
|
|
| `#` | one digit position |
|
|
| `.` | the decimal point |
|
|
| `,` | group the integer part in threes |
|
|
| `$` | a currency sign |
|
|
| `+` or `-` at the front | a sign position before the number |
|
|
| `+` or `-` at the end | a sign position after it |
|
|
| `=` | centre a string in the field |
|
|
| `>` | right-justify a string |
|
|
|
|
**A value too wide for its field fills the field with `*`.** That is deliberate and it
|
|
is loud: printing more digits than the field asked for would push every later column
|
|
out of line.
|
|
|
|
```basic
|
|
10 PRINT USING "###"; 99999
|
|
```
|
|
|
|
```output
|
|
***
|
|
```
|
|
|
|
A negative number in a field with no sign position overflows the same way, because
|
|
printing `-5` as `5` would be worse.
|
|
|
|
String fields centre and right-justify:
|
|
|
|
```basic
|
|
10 PRINT USING "=========="; "MID"
|
|
20 PRINT USING ">>>>>>>>>>"; "RIGHT"
|
|
```
|
|
|
|
```output
|
|
MID
|
|
RIGHT
|
|
```
|
|
|
|
One field per statement. `PRINT USING "### ###"; A, B` is not supported — see
|
|
Chapter 13.
|
|
|
|
## PUDEF
|
|
|
|
`PUDEF` changes the characters a numeric field pads and punctuates with. It takes up
|
|
to four, in this order: the leading blank, the thousands separator, the decimal point,
|
|
and the currency sign.
|
|
|
|
```basic
|
|
10 PUDEF "*"
|
|
20 PRINT USING "#####"; 42
|
|
```
|
|
|
|
```output
|
|
***42
|
|
```
|
|
|
|
Positions you leave out keep what they had, so the one-character form above changes
|
|
only the padding.
|
|
|
|
## CHAR
|
|
|
|
`CHAR` puts text at a character position rather than at the cursor:
|
|
|
|
```basic requires=akgl
|
|
10 CHAR 1, 10, 5, "HERE"
|
|
20 PRINT
|
|
```
|
|
|
|
```output
|
|
HERE
|
|
```
|
|
|
|
The arguments are colour, column, row and the text. `CHAR` writes no newline of its
|
|
own and leaves the cursor after the text, which is why line 20 is there. It needs a text device with a
|
|
cursor, which means the SDL build — a terminal's cursor is not this library's to move,
|
|
and it refuses by name in the default build.
|
|
|
|
The colour argument is accepted and ignored; the sink draws in one colour, chosen by
|
|
whoever built it.
|