# Module `string`

## Index

- Process `append.char` - Write a byte into a string
- Process `append.hex.int` - Convert an integer into its representation as ASCII hexadecimal characters and write this into a given string
- Process `append.hex.int64` - Convert a 64-bit integer into its representation as ASCII hexadecimal characters and write this into a given string
- Process `append.int` - Convert an integer into its representation as ASCII decimal digits, with leading spaces if desired, and write this into a given string
- Process `append.int64` - Convert a 64-bit integer into its representation as ASCII decimal digits, with leading spaces if desired, and write this into a given string
- Process `append.real32` - Write an ASCII representation of a single precision real number into a given string
- Process `append.real64` - Write an ASCII representation of a double precision real number into a given string
- Process `append.text` - Concatenate two strings
- Function `char.pos` - Determine where the first occurrence of a character is in a given string
- Function `compare.strings` - Determine the lexicographical ordering of two strings
- Process `delete.string` - Remove a substring from a string
- Function `eqstr` - Determine if two strings are identical or not
- Process `insert.string` - Insert a string into another string
- Function `is.digit` - Determine whether the value of a byte lies in the inclusive range that delimits ASCII decimal digits
- Function `is.hex.digit` - Determine whether the value of a byte corresponds to the ASCII value of any hexadecimal digit
- Function `is.id.char` - Determine whether the value of a byte corresponds to the ASCII code of any legal occam identifier character
- Function `is.in.range` - Determine whether the value of a byte lies in the inclusive range between two others
- Function `is.lower` - Determine whether the value of a byte lies in the inclusive range that delimits lower case ASCII characters
- Function `is.upper` - Determine whether the value of a byte lies in the inclusive range that delimits upper case ASCII characters
- Process `next.int.from.line` - Determine the next integer in a given line, skipping leading spaces and tabs
- Process `next.word.from.line` - Determine the next word in a given line, skipping leading spaces and tabs
- Function `search.match` - Search a string for the first occurrence of any one of a given number of characters
- Function `search.no.match` - Search a string for the first occurrence of a character which does not match any of a given number of characters
- Process `str.shift` - Shift a substring
- Function `string.pos` - Determine where the first occurrence is of a string within another string
- Process `to.lower.case` - Convert all upper case alphabetic characters in a given string to lower case
- Process `to.upper.case` - Convert all lower case alphabetic characters in a given string to upper case

## Declarations

### `string1.occ`:42Function `compare.strings`

`INT FUNCTION compare.strings (VAL []BYTE str1, str2)`

Determine the lexicographical ordering of two strings.

Lexicographical ordering is that which uses the ordinal values of the characters for comparison in sequence along the strings. Here the ordinal values are the ASCII values.

#### Parameters:

`VAL []BYTE` | `str1`, `str2` | the strings to be compared

#### Returns:

`INT` |  | 0 for exact equality ( of both length and content ) 1 for str2 is leading substring of str1 -1 for str1 is leading substring of str2 2 for str1 "later" than str2 -2 for str2 "later" than str1

### `string1.occ`:81Function `eqstr`

`BOOL FUNCTION eqstr (VAL []BYTE s1, s2)`

Determine if two strings are identical or not.

#### Parameters:

`VAL []BYTE` | `s1`, `s2` | the strings to be compared

#### Returns:

`BOOL` |  | TRUE if the two strings are identical in length and content; FALSE otherwise

### `string1.occ`:115Process `str.shift`

`PROC str.shift ([]BYTE str, VAL INT start, len, shift, BOOL not.done)`

Shift a substring.

#### Parameters:

`[]BYTE` | `str` | on entry: a string containing the substring to be shifted in positions [str FROM start FOR len]; on exit: the string once the substring has been shifted, the only bytes of string that have changed being those that the substring was shifted into
`VAL INT` | `start` | the index of str of the first character of the substring to be shifted
`VAL INT` | `len` | the number of characters in the substring to be shifted
`VAL INT` | `shift` | the number of places to the right to move the substring by, so that a negative number for shift will move the substring left
`BOOL` | `not.done` | TRUE if any elements of the substring are shifted off either end of str ( though no access is made to invalid locations of str ); FALSE if the shifted substring is entirely within str

### `string1.occ`:223Process `delete.string`

`PROC delete.string (INT len, []BYTE str, VAL INT start, size, BOOL not.done)`

Remove a substring from a string.

#### Parameters:

`INT` | `len` | on entry: the number of significant characters in str; on exit: if not.done is FALSE, the number of significant characters in str, being size subtracted from the entry value of len; otherwise the same as it was on entry

`[]BYTE`

`str`

on entry: the string from which it is desired to delete a substring; on exit: if not.done is FALSE, the original string with substring deleted, where deleted means that the gap created by the deletion is filled from the left with those significant characters left in str that were originally after the end of the deleted substring, and so that the number of significant characters remaining in str is len on exit; otherwise the same as it was on entry

`VAL INT` | `start` | the index of str of the first character of the substring to be deleted
`VAL INT` | `size` | the number of characters in the substring to be deleted
`BOOL` | `not.done` | TRUE if size is less than zero, start is less than zero, or (start + size) is greater than the entry value of len; FALSE otherwise. If TRUE then len and str are unchanged from their original values.

### `string1.occ`:257Process `insert.string`

`PROC insert.string (VAL []BYTE new.str, INT len, []BYTE str, VAL INT start, BOOL not.done)`

Insert a string into another string.

If new.str can be fully inserted from the desired starting position, then any significant characters in str that were originally after str[ start ] are moved to the right by SIZE new.str, with not.done being set to TRUE if any of these characters are moved off the end of str ( though no invalid accesses are made ), FALSE otherwise

#### Parameters:

`VAL []BYTE` | `new.str` | the string to be inserted
`INT` | `len` | on entry: the number of significant characters in str; on exit: the number of significant characters in str
`[]BYTE` | `str` | on entry: the string into which new.str is to be inserted; on exit: the original str with new.str inserted, where any overflow of str at the high index results in truncation at the high index
`VAL INT` | `start` | the index of str at which the first character of new.str should go
`BOOL` | `not.done` | TRUE if start < 0, start > len, len < 0, new.str had to be truncated to fit, or if any significant characters of the original str could not be retained within str after the insertion; otherwise FALSE

### `string1.occ`:308Function `string.pos`

`INT FUNCTION string.pos (VAL []BYTE search, str)`

Determine where the first occurrence is of a string within another string.

The searching is case sensitive.

#### Parameters:

`VAL []BYTE` | `search` | the string to search for in the string str
`VAL []BYTE` | `str` | the string in which to search for the string search

#### Returns:

`INT` |  | the lowest index of str at which begins a substring exactly matching the string search was found, or -1 if no such substring found

### `string1.occ`:373Function `char.pos`

`INT FUNCTION char.pos (VAL BYTE search, VAL []BYTE str)`

Determine where the first occurrence of a character is in a given string.

The searching is case sensitive.

#### Parameters:

`VAL BYTE` | `search` | the character to search for in the string str
`VAL []BYTE` | `str` | the string in which to search for the character search

#### Returns:

`INT` |  | the lowest index of str at which a byte exactly matching search was found, or -1 if no such byte found

### `string1.occ`:397Function `search.match`

`INT, BYTE FUNCTION search.match (VAL []BYTE possibles, str)`

Search a string for the first occurrence of any one of a given number of characters.

#### Parameters:

`VAL []BYTE` | `possibles` | a string each byte of which is to be individually checked for in str
`VAL []BYTE` | `str` | the string in which to search for any of the various bytes contained in possibles

#### Returns:

`INT` |  | if a match found, this gives the lowest index of str at which the match occurs; otherwise -1
`BYTE` |  | if a match found, this gives the byte of possibles which was found; otherwise 255( BYTE )

### `string1.occ`:427Function `search.no.match`

`INT, BYTE FUNCTION search.no.match (VAL []BYTE possibles, str)`

Search a string for the first occurrence of a character which does not match any of a given number of characters.

#### Parameters:

`VAL []BYTE` | `possibles` | a string each byte of which is to be individually checked for non-existence in str
`VAL []BYTE` | `str` | the string in which to search for a byte which is not identical to any of the various bytes contained in possibles

#### Returns:

`INT` |  | if no match found, this gives the lowest index of str at which the lack of a match occurs; otherwise -1
`BYTE` |  | if no match found, this gives the byte of str which was found not to match; otherwise 255( BYTE )

### `string0.occ`:40Function `is.in.range`

`BOOL FUNCTION is.in.range (VAL BYTE char, bottom, top)`

Determine whether the value of a byte lies in the inclusive range between two others.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested to see whether it lies in a given range
`VAL BYTE` | `bottom` | the lowermost limit of the test range
`VAL BYTE` | `top` | the uppermost limit of the test range

#### Returns:

`BOOL` |  | TRUE if the value of char lies in the range [value of bottom, value of top]; FALSE otherwise

### `string0.occ`:50Function `is.upper`

`BOOL FUNCTION is.upper (VAL BYTE char)`

Determine whether the value of a byte lies in the inclusive range that delimits upper case ASCII characters.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested

#### Returns:

`BOOL` |  | TRUE if the value of char corresponds to an upper case ASCII character; FALSE otherwise

### `string0.occ`:59Function `is.lower`

`BOOL FUNCTION is.lower (VAL BYTE char)`

Determine whether the value of a byte lies in the inclusive range that delimits lower case ASCII characters.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested

#### Returns:

`BOOL` |  | TRUE if the value of char corresponds to a lower case ASCII character; FALSE otherwise

### `string0.occ`:68Function `is.digit`

`BOOL FUNCTION is.digit (VAL BYTE char)`

Determine whether the value of a byte lies in the inclusive range that delimits ASCII decimal digits.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested

#### Returns:

`BOOL` |  | TRUE if the value of char corresponds to a decimal digit according to the ASCII code; FALSE otherwise

### `string0.occ`:78Function `is.hex.digit`

`BOOL FUNCTION is.hex.digit (VAL BYTE char)`

Determine whether the value of a byte corresponds to the ASCII value of any hexadecimal digit.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested

#### Returns:

`BOOL` |  | TRUE if the value of char corresponds to a hexadecimal digit according to the ASCII code, where upper or lower case letters are allowed; FALSE otherwise

### `string0.occ`:90Function `is.id.char`

`BOOL FUNCTION is.id.char (VAL BYTE char)`

Determine whether the value of a byte corresponds to the ASCII code of any legal occam identifier character.

#### Parameters:

`VAL BYTE` | `char` | the byte the value of which is to be tested

#### Returns:

`BOOL` |  | TRUE if the value of char corresponds to the ASCII code of any legal occam identifier character

### `string0.occ`:105Process `to.upper.case`

`PROC to.upper.case ([]BYTE str)`

Convert all lower case alphabetic characters in a given string to upper case.

Assumes the ASCII character set. Characters which are not lower case letters remain unchanged.

#### Parameters:

`[]BYTE` | `str` | the string the lower case characters of which are to be converted to upper case

### `string0.occ`:125Process `to.lower.case`

`PROC to.lower.case ([]BYTE str)`

Convert all upper case alphabetic characters in a given string to lower case.

Assumes the ASCII character set. Characters which are not upper case letters remain unchanged.

#### Parameters:

`[]BYTE` | `str` | the string the upper case characters of which are to be converted to lower case

### `string3.occ`:47Process `append.real32`

`PROC append.real32 (INT len, []BYTE str, VAL REAL32 number, VAL INT Ip, Dp)`

Write an ASCII representation of a single precision real number into a given string.

If str overflows this routine acts as an invalid process.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the representation of number is to be placed; on exit: the index of str of the byte immediately following the last character in str of the representation of number, or (SIZE str) if the last character of the representation was placed into the last byte of str
`[]BYTE` | `str` | the string into which to place the ASCII representation of number
`VAL REAL32` | `number` | a single precision real number in IEEE format
`VAL INT` | `Ip`, `Dp` | formatting values for the real number; see REAL32TOSTRING for their effect

### `string3.occ`:73Process `append.real64`

`PROC append.real64 (INT len, []BYTE str, VAL REAL64 number, VAL INT Ip, Dp)`

Write an ASCII representation of a double precision real number into a given string.

If str overflows this routine acts as an invalid process.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the representation of number is to be placed; on exit: the index of str of the byte immediately following the last character in str of the representation of number, or (SIZE str) if the last character of the representation was placed into the last byte of str
`[]BYTE` | `str` | the string into which to place the ASCII representation of number
`VAL REAL64` | `number` | a double precision real number in IEEE format
`VAL INT` | `Ip`, `Dp` | formatting values for the real number; see REAL64TOSTRING for their effect

### `string4.occ`:59Process `append.int64`

`PROC append.int64 (INT len, []BYTE str, VAL INT64 number, VAL INT width)`

Convert a 64-bit integer into its representation as ASCII decimal digits, with leading spaces if desired, and write this into a given string.

If str overflows then this routine acts as an invalid process. The conversion of number will include a minus sign if applicable.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the ASCII conversion of number is to be written; on exit: the index of str immediately after where the last character of the ASCII conversion of number was written, or SIZE str if this last character was written into the last positon of str
`[]BYTE` | `str` | the string into which the ASCII conversion of number is to be written
`VAL INT64` | `number` | the 64-bit integer to be converted to an ASCII representation and then written into str
`VAL INT` | `width` | the field width of the ASCII representation of number: if number cannot be represented in width characters then the representation is widened as necessary; if width is larger than necessary then padding spaces are added on the left; it is an error for width to be negative

### `string4.occ`:104Process `append.hex.int64`

`PROC append.hex.int64 (INT len, []BYTE str, VAL INT64 number, VAL INT width)`

Convert a 64-bit integer into its representation as ASCII hexadecimal characters and write this into a given string.

If str overflows then this routine acts as an invalid process. The conversion of number includes a # as the first character, so that the representation is always ( width + 1 ) characters. Any hexadecimal characters which are letters will be in upper case.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the ASCII hexadecimal of number is to be written; on exit: the index of str immediately after where the last character of the ASCII hexadecimal of number was written, or SIZE str if this last character was written into the last positon of str
`[]BYTE` | `str` | the string into which the hexadecimal ASCII form of number is to be written
`VAL INT64` | `number` | the 64-bit integer to be converted to an ASCII hexadecimal representation and then written into str
`VAL INT` | `width` | the field width of the ASCII hexadecimal representation of number: if number cannot be represented in width characters then the representation is truncated at the left as necessary; otherwise the representation is padded on the left with 0's or F's to make up width characters; a negative value for width is an error

### `string5.occ`:63Process `next.word.from.line`

`PROC next.word.from.line (VAL []BYTE line, INT ptr, len, []BYTE word, BOOL ok)`

Determine the next word in a given line, skipping leading spaces and tabs.

Leading spaces and ( horizontal ) tabs ( from line[ ptr ], ptr on entry ) are skipped. A word continues until a space or tab or the end of the string is encountered.

#### Parameters:

`VAL []BYTE` | `line` | a string containing the line from which a word is desired to be noted. The string is considered to be of length (SIZE line).

`INT`

`ptr`

on entry: the index of line from which to start the search for a word, i.e. the search begins at line[ ptr ] with ptr increasing. On exit: if ok is FALSE on entry, then unchanged; if ok is TRUE on entry, then is either the index of the space or tab immediately after the found word or is >= (SIZE line) ( where it is only ever greater than if it was passed in as such ), whether ok is subsequently set to FALSE or not.

`INT` | `len` | if ok is FALSE on entry, then 0; if ok is TRUE on entry then gives the length of the first word found after the given starting position ( whether ok is subsequently set to FALSE or not ), which in the case of no word found is 0
`[]BYTE` | `word` | if ok is FALSE on entry, then undefined; if ok is TRUE on entry, then this contains the found word from line in the first len bytes, the remaining bytes being undefined, or if not large enough to contain the word or no word found it is undefined and ok is set to FALSE, though len gives the correct length of the word found
`BOOL` | `ok` | on entry: if FALSE, then len is set to 0, ptr and ok remain unchanged, and word is undefined; otherwise a search for a word is carried out. On exit: if FALSE on entry then FALSE; if TRUE on entry: FALSE if no word found; FALSE if a word found that was too large to fit into word; otherwise TRUE

### `string5.occ`:131Process `next.int.from.line`

`PROC next.int.from.line (VAL []BYTE line, INT ptr, number, BOOL ok)`

Determine the next integer in a given line, skipping leading spaces and tabs.

Leading spaces and ( horizontal ) tabs ( from line[ ptr ], ptr on entry ) are skipped. The first sequence of characters found after skipping spaces and tabs is taken to be the integer desired; the integer continues until a space or tab or the end of the string is encountered. A + or - are permissible as the first character of the integer.

#### Parameters:

`VAL []BYTE` | `line` | a string containing the line from which an integer is desired to be noted. The string is considered to be of length (SIZE line).

`INT`

`ptr`

on entry: the index of line from which to start the search for an integer, i.e. the search begins at line[ ptr ] with ptr increasing. On exit: if ok is FALSE on entry, then unchanged; if ok is TRUE on entry, then is either the index of the space or tab immediately after the found integer or is >= (SIZE line) ( where it is only ever greater than if it was passed in as such ), whether ok is subsequently set to FALSE or not.

`INT` | `number` | if ok is FALSE on entry, then undefined; if ok is TRUE on entry: if ok TRUE on exit, the integer read, otherwise, undefined

`BOOL`

`ok`

on entry: if FALSE, ptr and ok remain unchanged, and number is undefined; otherwise a search for an integer is carried out. On exit: if FALSE on entry then FALSE; if TRUE on entry: FALSE if there were no non-space or non-tab characters before the end of the string; FALSE if the first sequence of non-space, non-tab characters do not form an integer; FALSE if an integer found that overflowed the range of INT; otherwise TRUE

### `string2.occ`:46Process `append.char`

`PROC append.char (INT len, []BYTE str, VAL BYTE char)`

Write a byte into a string.

If accessing str[ len ], for len on entry, is invalid then this routine acts as an invalid process.

#### Parameters:

`INT` | `len` | on entry: the byte char will be written at str[ len ]; on exit: len will be one greater than it was on entry
`[]BYTE` | `str` | the string to write char to
`VAL BYTE` | `char` | the byte which is to be written into str

### `string2.occ`:67Process `append.text`

`PROC append.text (INT len, []BYTE str, VAL []BYTE text)`

Concatenate two strings.

If str is not long enough to hold the concatenation then this routine acts as an invalid process.

#### Parameters:

`INT` | `len` | on entry: the index of str where the first character of text is to go; on exit: the index of str immediately after the last character of text inserted, or SIZE str if the last character of text was placed in the last position of str
`[]BYTE` | `str` | the concatenation of what str was on entry with text, where text is placed in positions str[ len ] to str[ len + (SIZE text) - 1 ] inclusive, where len here is that on entry
`VAL []BYTE` | `text` | the string to be concatenated with str, text being the second string

### `string2.occ`:95Process `append.int`

`PROC append.int (INT len, []BYTE str, VAL INT number, width)`

Convert an integer into its representation as ASCII decimal digits, with leading spaces if desired, and write this into a given string.

If str overflows then this routine acts as an invalid process. The conversion of number will include a minus sign if applicable.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the ASCII conversion of number is to be written; on exit: the index of str immediately after where the last character of the ASCII conversion of number was written, or SIZE str if this last character was written into the last positon of str
`[]BYTE` | `str` | the string into which the ASCII conversion of number is to be written
`VAL INT` | `number` | the integer to be converted to an ASCII representation and then written into str
`VAL INT` | `width` | the field width of the ASCII representation of number: if number cannot be represented in width characters then the representation is widened as necessary; if width is larger than necessary then padding spaces are added on the left; it is an error if width is negative

### `string2.occ`:139Process `append.hex.int`

`PROC append.hex.int (INT len, []BYTE str, VAL INT number, width)`

Convert an integer into its representation as ASCII hexadecimal characters and write this into a given string.

If str overflows then this routine acts as an invalid process. The conversion of number includes a # as the first character, so that the representation is always ( width + 1 ) characters. Any hexadecimal characters which are letters will be in upper case.

#### Parameters:

`INT` | `len` | on entry: the index of str at which the first character of the ASCII hexadecimal of number is to be written; on exit: the index of str immediately after where the last character of the ASCII hexadecimal of number was written, or SIZE str if this last character was written into the last positon of str
`[]BYTE` | `str` | the string into which the hexadecimal ASCII form of number is to be written
`VAL INT` | `number` | the integer to be converted to an ASCII hexadecimal representation and then written into str
`VAL INT` | `width` | the field width of the ASCII hexadecimal representation of number: if number cannot be represented in width characters then the representation is truncated at the left as necessary; otherwise the representation is padded on the left with 0's or F's to make up width characters; it is an error if width is negative