# 12. Function reference

Every function, alphabetically, generated from the interpreter's own dispatch table.

A function is called with parentheses and yields a value; it cannot stand alone as a
statement. The arity column is how many arguments it takes — the interpreter checks it,
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. |
| `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. |
| `COS` | 1 | `COS(n)` | Cosine, in radians. |
| `ERR` | 1 | `ERR(n)` | The message text for an error code. `ERR(ER#)` names the last one. |
| `HEX` | 1 | `HEX(n)` | An integer as hexadecimal text. |
| `INSTR` | 2 | `INSTR(A$, B$)` | Where `B$` appears in `A$`, counting from zero, or -1. |
| `LEFT` | 2 | `LEFT(A$, n)` | The leftmost `n` characters. Clamped to the string's length. |
| `LEN` | 1 | `LEN(x)` | The length of a string, or the element count of an array. |
| `LOG` | 1 | `LOG(n)` | Natural logarithm. |
| `MID` | 3 | `MID(A$, start, len)` | A substring, counting from zero. |
| `MOD` | 2 | `MOD(a, b)` | The remainder of `a / b`. Integers only. |
| `PEEK` | 1 | `PEEK(addr)` | The byte at a real address. |
| `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
| `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
| `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
| `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. |
| `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. |
| `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
| `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |
| `SGN` | 1 | `SGN(n)` | -1, 0 or 1 according to the sign. |
| `SHL` | 2 | `SHL(n, bits)` | Shift left. |
| `SHR` | 2 | `SHR(n, bits)` | Shift right. |
| `SIN` | 1 | `SIN(n)` | Sine, in radians. |
| `SPC` | 1 | `SPC(n)` | A string of `n` spaces. |
| `STR` | 1 | `STR(n)` | A number as a string. |
| `TAN` | 1 | `TAN(n)` | Tangent, in radians. |
| `VAL` | 1 | `VAL(A$)` | A string as a number. Refuses text that is not one. |
| `XOR` | 2 | `XOR(a, b)` | Bitwise exclusive or. |

## Reserved variables

Two things a C128 exposes as bare names are ordinary global variables here, because
this dialect has no variable name without a type suffix:

| Here | On a C128 | Holds |
|---|---|---|
| `ER#` | `ER` | the code of the last trapped error |
| `EL#` | `EL` | the line it happened on |
| `TI#` | `TI` | jiffies — sixtieths of a second — since the host's clock started |
| `TI$` | `TI$` | the same time as `HHMMSS` |

`ER#` carries this interpreter's error code, not a Commodore error number. There is no
correspondence to reproduce — the errors raised here are not the errors a 1985 ROM
raised — so print `ERR(ER#)` rather than the number. **[Chapter 15](15-error-codes.md)
lists every value it can hold.**