akbasic/docs/05-strings-and-formatting.md

# 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.

```
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")
```

`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.

```
10 PRINT USING "###.##"; 3.14159
20 PRINT USING "TOTAL: $#,###.##"; 1234.5
30 PRINT USING "####-"; -42
```

```
  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.

```
10 PRINT USING "###"; 99999
```

```
***
```

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:

```
10 PRINT USING "=========="; "MID"
20 PRINT USING ">>>>>>>>>>"; "RIGHT"
```

```
   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.

```
10 PUDEF "*"
20 PRINT USING "#####"; 42
```

```
***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:

```
10 CHAR 1, 10, 5, "HERE"
```

The arguments are colour, column, row and the text. 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.