# Module `useful` - General utilities

General utilities.

This module contains miscellaneous utilities for occam-pi programs. The aim is to provide somewhere to collect code that should obviously be in the standard library (that is: it's been needed by more than one occam-pi program), but where there isn't an existing module that it should obviously go into.

## Index

- Record `COMPLEX32` - A 2*32-bit complex number
- Record `COMPLEX64` - A 2*64-bit complex number
- Record `VECTOR2` - A two-dimensional vector
- Record `VECTOR3` - A three-dimensional vector
- Process `append.int` - Append a number to a string
- Process `append.string` - Append a string to a string
- Function `clamp.int` - Limit an integer to a particular range
- Function `cross.product3` - Compute the cross product of two s
- Function `deg.to.rad` - Convert an angle in degrees into radians
- Process `delay` - Wait for a period of time
- Function `is.whitespace` - Is a character whitespace?
- Function `mag.squared2` - Compute the square of the magnitude of a
- Function `mag.squared3` - Compute the square of the magnitude of a
- Process `matrix.add` - Add two matrices
- Process `matrix.multiply` - Compute the ordinary product of two matrices
- Function `max.int` - Find the greater of two integers
- Function `max.real32` - Find the greater of two reals
- Function `min.int` - Find the lesser of two integers
- Function `min.real32` - Find the lesser of two reals
- Function `normal3` - Compute the normal to the plane defined by the two given vectors
- Function `normalise2` - Normalise a
- Function `normalise3` - Normalise a
- Operator `* (VECTOR2, [2][2]REAL32)` - Multiply a by a transformation matrix
- Operator `* (VECTOR3, [3][3]REAL32)` - Multiply a by a transformation matrix
- Process `out.vector2` - Print a
- Process `out.vector3` - Print a
- Function `rad.to.deg` - Convert an angle in radians into degrees
- Function `random.real32` - Generate a random REAL32
- Process `resize.string` - Resize a string, keeping its contents intact
- Function `rotate2` - Generate a transformation matrix that rotates a 2D point around the origin
- Function `rotate3.x` - Generate a transformation matrix that rotates a 3D point around the X axis
- Function `rotate3.y` - Generate a transformation matrix that rotates a 3D point around the Y axis
- Function `rotate3.z` - Generate a transformation matrix that rotates a 3D point around the Z axis
- Process `rstrip.string` - Remove trailing whitespace from a string
- Function `same.string` - Compare two strings for equality
- Process `seed.from.timer` - Initialise a random number generator's seed using a timer
- Process `update.max.int` - Update a running maximum value
- Function `wrap.int` - Wrap array indexes around

## Declarations

### `time.occ`:25Process `delay`

`PROC delay (VAL INT us)`

Wait for a period of time.

#### Parameters:

`VAL INT` | `us` | The delay in microseconds

### `random.occ`:26Process `seed.from.timer`

`PROC seed.from.timer (TIMER tim, RESULT INT seed)`

Initialise a random number generator's seed using a timer.

### `random.occ`:35Function `random.real32`

`REAL32, INT FUNCTION random.real32 (VAL REAL32 range, VAL INT seed)`

Generate a random `REAL32`. The resulting value will be selected from the range `0.0 .. range`.

### `vector.occ`:28Process `out.vector2`

`PROC out.vector2 (VAL VECTOR2 v, CHAN BYTE out!)`

Print a `VECTOR2`.

### `vector.occ`:42Function `normalise2`

`VECTOR2 FUNCTION normalise2 (VAL VECTOR2 v)`

Normalise a `VECTOR2`.

#### Parameters:

`VAL VECTOR2` | `v` | Input vector

#### Returns:

`VECTOR2` |  | Unit vector parallel to `v`

### `vector.occ`:47Process `out.vector3`

`PROC out.vector3 (VAL VECTOR3 v, CHAN BYTE out!)`

Print a `VECTOR3`.

### `vector.occ`:64Function `normalise3`

`VECTOR3 FUNCTION normalise3 (VAL VECTOR3 v)`

Normalise a `VECTOR3`.

#### Parameters:

`VAL VECTOR3` | `v` | Input vector

#### Returns:

`VECTOR3` |  | Unit vector parallel to `v`

### `vector.occ`:68Function `cross.product3`

`VECTOR3 FUNCTION cross.product3 (VAL VECTOR3 a, b)`

Compute the cross product of two `VECTOR3`s.

### `vector.occ`:80Function `normal3`

`VECTOR3 FUNCTION normal3 (VAL VECTOR3 a, b)`

Compute the normal to the plane defined by the two given vectors.

### `matrix.occ`:33Process `matrix.multiply`

`PROC matrix.multiply (VAL [][]REAL32 a, b, [][]REAL32 result)`

Compute the ordinary product of two matrices. The number of columns in `a` must be the same as the number of rows in `b`. `result` must have the same number of rows as `a` and the same number of columns as `b`.

#### Parameters:

`VAL [][]REAL32` | `a` | First matrix
`VAL [][]REAL32` | `b` | Second matrix
`[][]REAL32` | `result` | Product

### `matrix.occ`:53Process `matrix.add`

`PROC matrix.add (VAL [][]REAL32 a, b, [][]REAL32 result)`

Add two matrices. `a`, `b` and `result` must all be the same size.

#### Parameters:

`VAL [][]REAL32` | `a` | First matrix
`VAL [][]REAL32` | `b` | Second matrix
`[][]REAL32` | `result` | Product

### `matrix.occ`:67Operator `* (VECTOR2, [2][2]REAL32)`

`VECTOR2 FUNCTION "**" (VAL VECTOR2 v, VAL [2][2]REAL32 m)`

Multiply a `VECTOR2` by a transformation matrix.

### `matrix.occ`:77Operator `* (VECTOR3, [3][3]REAL32)`

`VECTOR3 FUNCTION "**" (VAL VECTOR3 v, VAL [3][3]REAL32 m)`

Multiply a `VECTOR3` by a transformation matrix.

### `matrix.occ`:90Function `rotate2`

`[2][2]REAL32 FUNCTION rotate2 (VAL REAL32 theta)`

Generate a transformation matrix that rotates a 2D point around the origin.

#### Parameters:

`VAL REAL32` | `theta` | Angle (in radians)

#### Returns:

`[2][2]REAL32` |  | Transformation matrix

### `matrix.occ`:98Function `rotate3.x`

`[3][3]REAL32 FUNCTION rotate3.x (VAL REAL32 theta)`

Generate a transformation matrix that rotates a 3D point around the X axis.

#### Parameters:

`VAL REAL32` | `theta` | Angle (in radians)

#### Returns:

`[3][3]REAL32` |  | Transformation matrix

### `matrix.occ`:107Function `rotate3.y`

`[3][3]REAL32 FUNCTION rotate3.y (VAL REAL32 theta)`

Generate a transformation matrix that rotates a 3D point around the Y axis.

#### Parameters:

`VAL REAL32` | `theta` | Angle (in radians)

#### Returns:

`[3][3]REAL32` |  | Transformation matrix

### `matrix.occ`:116Function `rotate3.z`

`[3][3]REAL32 FUNCTION rotate3.z (VAL REAL32 theta)`

Generate a transformation matrix that rotates a 3D point around the Z axis.

#### Parameters:

`VAL REAL32` | `theta` | Angle (in radians)

#### Returns:

`[3][3]REAL32` |  | Transformation matrix

### `string.occ`:29Process `resize.string`

`PROC resize.string (MOBILE []BYTE s, VAL INT new.size)`

Resize a string, keeping its contents intact.

#### Parameters:

`MOBILE []BYTE` | `s` | String to resize
`VAL INT` | `new.size` | New length

### `string.occ`:37Process `append.string`

`PROC append.string (MOBILE []BYTE out, VAL []BYTE in)`

Append a string to a string.

#### Parameters:

`MOBILE []BYTE` | `out` | String to append to
`VAL []BYTE` | `in` | String that will be appended to `out`

### `string.occ`:48Process `append.int`

`PROC append.int (MOBILE []BYTE out, VAL INT n)`

Append a number to a string.

#### Parameters:

`MOBILE []BYTE` | `out` | String to which the decimal representation of `n` will be appended
`VAL INT` | `n` | Integer to format

### `string.occ`:82Function `same.string`

`BOOL FUNCTION same.string (VAL []BYTE a, b)`

Compare two strings for equality.

#### Parameters:

`VAL []BYTE` | `a`, `b` | Strings to compare

#### Returns:

`BOOL` |  | `TRUE` if the strings are the same, `FALSE` otherwise

### `string.occ`:100Function `is.whitespace`

`BOOL FUNCTION is.whitespace (VAL BYTE ch)`

Is a character whitespace?

#### Parameters:

`VAL BYTE` | `ch` | Character to examine

#### Returns:

`BOOL` |  | `TRUE` if `ch` is a space, tab, carriage-return or line-feed

### `string.occ`:113Process `rstrip.string`

`PROC rstrip.string (MOBILE []BYTE s)`

Remove trailing whitespace from a string.

### `useful.inc`:33Record `VECTOR2`

`DATA TYPE VECTOR2`

A two-dimensional vector.

### `useful.inc`:47Function `mag.squared2`

`REAL32 INLINE FUNCTION mag.squared2 (VAL VECTOR2 v)`

Compute the square of the magnitude of a `VECTOR2`.

### `useful.inc`:55Record `VECTOR3`

`DATA TYPE VECTOR3`

A three-dimensional vector.

### `useful.inc`:69Function `mag.squared3`

`REAL32 INLINE FUNCTION mag.squared3 (VAL VECTOR3 v)`

Compute the square of the magnitude of a `VECTOR3`.

### `useful.inc`:78Record `COMPLEX32`

`DATA TYPE COMPLEX32`

A 2*32-bit complex number.

### `useful.inc`:135Record `COMPLEX64`

`DATA TYPE COMPLEX64`

A 2*64-bit complex number.

### `math.occ`:28Function `min.int`

`INT FUNCTION min.int (VAL INT a, b)`

Find the lesser of two integers.

#### Parameters:

`VAL INT` | `a`, `b` | Integers to compare

#### Returns:

`INT` |  | The lesser of `a` and `b`

### `math.occ`:43Function `max.int`

`INT FUNCTION max.int (VAL INT a, b)`

Find the greater of two integers.

#### Parameters:

`VAL INT` | `a`, `b` | Integers to compare

#### Returns:

`INT` |  | The greater of `a` and `b`

### `math.occ`:58Function `min.real32`

`REAL32 FUNCTION min.real32 (VAL REAL32 a, b)`

Find the lesser of two reals.

#### Parameters:

`VAL REAL32` | `a`, `b` | Reals to compare

#### Returns:

`REAL32` |  | The lesser of `a` and `b`

### `math.occ`:73Function `max.real32`

`REAL32 FUNCTION max.real32 (VAL REAL32 a, b)`

Find the greater of two reals.

#### Parameters:

`VAL REAL32` | `a`, `b` | Reals to compare

#### Returns:

`REAL32` |  | The greater of `a` and `b`

### `math.occ`:90Process `update.max.int`

`PROC update.max.int (INT max, VAL INT value)`

Update a running maximum value. If `value` is greater than `max`, `max` will be set to `value`.

#### Parameters:

`INT` | `max` | The running maximum
`VAL INT` | `value` | The input value

### `math.occ`:106Function `clamp.int`

`INT FUNCTION clamp.int (VAL INT in, left, width)`

Limit an integer to a particular range. For example, if you call this with `left = 3` and `width = 3`, then the output value will be in the range `3 .. 5`.

#### Parameters:

`VAL INT` | `in` | Input value
`VAL INT` | `left` | The lowest value in the range
`VAL INT` | `width` | The width of the range

#### Returns:

`INT` |  | A value in the range `left .. (left + width - 1)`

### `math.occ`:125Function `wrap.int`

`INT FUNCTION wrap.int (VAL INT i, max)`

Wrap array indexes around. If given `-1`, this will return `max - 1`; if given `max + 1`, this will return `1`. This is not quite the same thing as `\ max`, since that doesn't do the right thing for negative numbers.

### `math.occ`:137Function `deg.to.rad`

`REAL32 FUNCTION deg.to.rad (VAL REAL32 deg)`

Convert an angle in degrees into radians.

### `math.occ`:141Function `rad.to.deg`

`REAL32 FUNCTION rad.to.deg (VAL REAL32 rad)`

Convert an angle in radians into degrees.