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.

This module includes a large number of PROCs for formatted output that aren't individually documented. These take varying numbers of arguments, and have names that end with a "format string" indicating the types of the arguments they support. Several families of PROCs are provided for different purposes:

  • print.* write to a CHAN BYTE;
  • prints.* write to a SHARED CHAN BYTE, claiming it first;
  • format.* return a string as a RESULT MOBILE []BYTE;
  • trace.* write directly to standard error, taking no additional parameters.

The output channel or variable always appears at the end of the argument list.

The formatting characters supported are:

  • s for a string as a VAL []BYTE;
  • i for a decimal integer as a VAL INT;
  • r for a decimal floating-point value as a VAL REAL32;
  • b for a boolean value as a VAL BOOL;
  • n for a newline (taking no parameter).

For example, if you wanted to print a string and an integer followed by a newline to a channel, you could use PROC print.sin (VAL []BYTE s, VAL INT i, CHAN BYTE out!) as follows:

print.sin ("Number of interrupts: ", count, out!)

PROCs are provided for all valid combinations of up to 5 formatting characters, with the restrictions that n is only permitted at the end of a format string, and i, r and b cannot occur next to each other. (For example, trace.sisin is provided, but trace.siin and trace.sinin are not.)

Index

Declarations

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

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

vector.occ:80Function normal3

VECTOR3 FUNCTION normal3 (VAL VECTOR3 a, b)

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

math.occ:29Function abs.int

INT FUNCTION abs.int (VAL INT n)

Remove the sign from an integer.

Parameters:

VAL INT n Input value

Returns:

INT -n if n is negative, else n

math.occ:44Function 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:59Function 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:74Function abs.real32

REAL32 FUNCTION abs.real32 (VAL REAL32 n)

Remove the sign from a real.

Parameters:

VAL REAL32 n Input value

Returns:

REAL32 -n if n is negative, else n

math.occ:89Function 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:104Function 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:121Process 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:137Function 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:156Function 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:168Function deg.to.rad

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

Convert an angle in degrees into radians.

math.occ:172Function rad.to.deg

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

Convert an angle in radians into degrees.

io.occ:29Process fd.read.bytes

PROC fd.read.bytes (VAL INT fd, CHAN BYTE out!)

Read bytes from fd until EOF, then output 0.

io.occ:54Process bytes.to.lines

PROC bytes.to.lines (CHAN BYTE in?, CHAN MOBILE []BYTE out!)

Turn a stream of bytes into a stream of lines. Lines are terminated by *n, which is included in the output. EOF on input is marked by 0, and on output by [].

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, line-feed, form-feed or vertical-tab

string.occ:113Process rstrip.string

PROC rstrip.string (MOBILE []BYTE s)

Remove trailing whitespace from a string.

string.occ:131Function string.char

INT FUNCTION string.char (VAL []BYTE haystack, VAL BYTE needle)

Return the position of needle inside haystack, or [@code -1] if it isn't found.

string.occ:146Process tail.string

PROC tail.string (VAL INT n, VAL []BYTE src, MOBILE []BYTE dest)

Remove n bytes from the start of src, writing the result into dest.

string.occ:155Process split.string

PROC split.string (VAL []BYTE src, VAL BYTE sep, CHAN MOBILE []BYTE out!)

Split src on sep, writing each substring to out, terminated by [].

useful.inc:71Record VECTOR2

DATA TYPE VECTOR2

A two-dimensional vector of REALs.

useful.inc:77Operator + (VECTOR2, VECTOR2)

VECTOR2 INLINE FUNCTION "+" (VAL VECTOR2 a, b)

useful.inc:78Operator - (VECTOR2, VECTOR2)

VECTOR2 INLINE FUNCTION "-" (VAL VECTOR2 a, b)

useful.inc:79Operator - (VECTOR2)

VECTOR2 INLINE FUNCTION "-" (VAL VECTOR2 a)

useful.inc:80Operator * (VECTOR2, REAL32)

VECTOR2 INLINE FUNCTION "**" (VAL VECTOR2 a, VAL REAL32 b)

useful.inc:81Operator / (VECTOR2, REAL32)

VECTOR2 INLINE FUNCTION "/" (VAL VECTOR2 a, VAL REAL32 b)

useful.inc:85Function mag.squared2

REAL32 INLINE FUNCTION mag.squared2 (VAL VECTOR2 v)

Compute the square of the magnitude of a VECTOR2.

useful.inc:88Function dot.product2

REAL32 INLINE FUNCTION dot.product2 (VAL VECTOR2 a, b)

useful.inc:93Record VECTOR2.INT

DATA TYPE VECTOR2.INT

A two-dimensional vector of INTs.

useful.inc:99Operator = (VECTOR2.INT, VECTOR2.INT)

BOOL INLINE FUNCTION "=" (VAL VECTOR2.INT a, b)

useful.inc:100Operator + (VECTOR2.INT, VECTOR2.INT)

VECTOR2.INT INLINE FUNCTION "+" (VAL VECTOR2.INT a, b)

useful.inc:101Operator - (VECTOR2.INT, VECTOR2.INT)

VECTOR2.INT INLINE FUNCTION "-" (VAL VECTOR2.INT a, b)

useful.inc:102Operator - (VECTOR2.INT)

VECTOR2.INT INLINE FUNCTION "-" (VAL VECTOR2.INT a)

useful.inc:103Operator * (VECTOR2.INT, INT)

VECTOR2.INT INLINE FUNCTION "**" (VAL VECTOR2.INT a, VAL INT b)

useful.inc:104Operator / (VECTOR2.INT, INT)

VECTOR2.INT INLINE FUNCTION "/" (VAL VECTOR2.INT a, VAL INT b)

useful.inc:109Record VECTOR3

DATA TYPE VECTOR3

A three-dimensional vector.

useful.inc:115Operator + (VECTOR3, VECTOR3)

VECTOR3 INLINE FUNCTION "+" (VAL VECTOR3 a, b)

useful.inc:116Operator - (VECTOR3, VECTOR3)

VECTOR3 INLINE FUNCTION "-" (VAL VECTOR3 a, b)

useful.inc:117Operator - (VECTOR3)

VECTOR3 INLINE FUNCTION "-" (VAL VECTOR3 a)

useful.inc:118Operator * (VECTOR3, REAL32)

VECTOR3 INLINE FUNCTION "**" (VAL VECTOR3 a, VAL REAL32 b)

useful.inc:119Operator / (VECTOR3, REAL32)

VECTOR3 INLINE FUNCTION "/" (VAL VECTOR3 a, VAL REAL32 b)

useful.inc:123Function mag.squared3

REAL32 INLINE FUNCTION mag.squared3 (VAL VECTOR3 v)

Compute the square of the magnitude of a VECTOR3.

useful.inc:127Function dot.product3

REAL32 INLINE FUNCTION dot.product3 (VAL VECTOR3 a, b)

useful.inc:132Record COMPLEX32

DATA TYPE COMPLEX32

A 2*32-bit complex number.

useful.inc:143Function COMPLEX32ABSSQ

REAL32 INLINE FUNCTION COMPLEX32ABSSQ (VAL COMPLEX32 x)

useful.inc:146Operator - (COMPLEX32)

COMPLEX32 INLINE FUNCTION "-" (VAL COMPLEX32 x)

useful.inc:149Operator ~ (COMPLEX32)

COMPLEX32 INLINE FUNCTION "~" (VAL COMPLEX32 x)

useful.inc:152Operator + (COMPLEX32, COMPLEX32)

COMPLEX32 INLINE FUNCTION "+" (VAL COMPLEX32 x, y)

useful.inc:155Operator - (COMPLEX32, COMPLEX32)

COMPLEX32 INLINE FUNCTION "-" (VAL COMPLEX32 x, y)

useful.inc:158Operator * (COMPLEX32, COMPLEX32)

COMPLEX32 INLINE FUNCTION "**" (VAL COMPLEX32 x, y)

useful.inc:162Operator * (COMPLEX32, REAL32)

COMPLEX32 INLINE FUNCTION "**" (VAL COMPLEX32 x, VAL REAL32 r)

useful.inc:165Operator * (REAL32, COMPLEX32)

COMPLEX32 INLINE FUNCTION "**" (VAL REAL32 r, VAL COMPLEX32 x)

useful.inc:168Operator / (COMPLEX32, REAL32)

COMPLEX32 INLINE FUNCTION "/" (VAL COMPLEX32 x, VAL REAL32 r)

useful.inc:171Function REAL32TOCOMPLEX32

COMPLEX32 INLINE FUNCTION REAL32TOCOMPLEX32 (VAL REAL32 x)

useful.inc:174Operator = (COMPLEX32, COMPLEX32)

BOOL INLINE FUNCTION "=" (VAL COMPLEX32 x, y)

useful.inc:177Operator <> (COMPLEX32, COMPLEX32)

BOOL INLINE FUNCTION "<>" (VAL COMPLEX32 x, y)

useful.inc:180Function COMPLEX32TOREAL32

REAL32, REAL32 INLINE FUNCTION COMPLEX32TOREAL32 (VAL COMPLEX32 x)

useful.inc:183Function COMPLEX32SQR

COMPLEX32 INLINE FUNCTION COMPLEX32SQR (VAL COMPLEX32 z)

useful.inc:189Record COMPLEX64

DATA TYPE COMPLEX64

A 2*64-bit complex number.

useful.inc:200Function COMPLEX64ABSSQ

REAL64 INLINE FUNCTION COMPLEX64ABSSQ (VAL COMPLEX64 x)

useful.inc:203Operator - (COMPLEX64)

COMPLEX64 INLINE FUNCTION "-" (VAL COMPLEX64 x)

useful.inc:206Operator ~ (COMPLEX64)

COMPLEX64 INLINE FUNCTION "~" (VAL COMPLEX64 x)

useful.inc:209Operator + (COMPLEX64, COMPLEX64)

COMPLEX64 INLINE FUNCTION "+" (VAL COMPLEX64 x, y)

useful.inc:212Operator - (COMPLEX64, COMPLEX64)

COMPLEX64 INLINE FUNCTION "-" (VAL COMPLEX64 x, y)

useful.inc:215Operator * (COMPLEX64, COMPLEX64)

COMPLEX64 INLINE FUNCTION "**" (VAL COMPLEX64 x, y)

useful.inc:219Operator * (COMPLEX64, REAL64)

COMPLEX64 INLINE FUNCTION "**" (VAL COMPLEX64 x, VAL REAL64 r)

useful.inc:222Operator * (REAL64, COMPLEX64)

COMPLEX64 INLINE FUNCTION "**" (VAL REAL64 r, VAL COMPLEX64 x)

useful.inc:225Operator / (COMPLEX64, REAL64)

COMPLEX64 INLINE FUNCTION "/" (VAL COMPLEX64 x, VAL REAL64 r)

useful.inc:228Function REAL64TOCOMPLEX64

COMPLEX64 INLINE FUNCTION REAL64TOCOMPLEX64 (VAL REAL64 x)

useful.inc:231Operator = (COMPLEX64, COMPLEX64)

BOOL INLINE FUNCTION "=" (VAL COMPLEX64 x, y)

useful.inc:234Operator <> (COMPLEX64, COMPLEX64)

BOOL INLINE FUNCTION "<>" (VAL COMPLEX64 x, y)

useful.inc:237Function COMPLEX64TOREAL64

REAL64, REAL64 INLINE FUNCTION COMPLEX64TOREAL64 (VAL COMPLEX64 x)

useful.inc:240Function COMPLEX32TO64

COMPLEX64 INLINE FUNCTION COMPLEX32TO64 (VAL COMPLEX32 x)

useful.inc:243Function COMPLEX64ROUND

COMPLEX32 INLINE FUNCTION COMPLEX64ROUND (VAL COMPLEX64 x)

useful.inc:246Function COMPLEX64TRUNC

COMPLEX32 INLINE FUNCTION COMPLEX64TRUNC (VAL COMPLEX64 x)

useful.inc:249Function COMPLEX64SQR

COMPLEX64 INLINE FUNCTION COMPLEX64SQR (VAL COMPLEX64 z)