# Strings

Unlike Modula-2, the behaviour of a procedure is undefined, if one of its input parameters is an unterminated character array. All of the following procedures expect to get 0X terminated strings, and will return likewise terminated strings.

All input parameters that represent an array index or a length are expected to be non-negative. In the descriptions below these restrictions are stated as pre-conditions of the procedures, but they aren't checked explicitly. If this module is compiled with run-time index enabled, checks some illegal input values may be caught. By default it is installed without index checks.

Type Summary
CompareResults = SHORTINT Result type of Compare.

Procedure Summary
Append(ARRAY OF CHAR, VAR ARRAY OF CHAR) Appends source to destination.
Assign(ARRAY OF CHAR, VAR ARRAY OF CHAR) Copies source to destination.
CanAppendAll(INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if there is sufficient room in destination to append a string of length sourceLength to the string in destination; otherwise returns FALSE.
CanAssignAll(INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if a number of characters, indicated by sourceLength, will fit into destination; otherwise returns FALSE.
CanConcatAll(INTEGER, INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if there is sufficient room in destination for a two strings of lengths source1Length and source2Length; otherwise returns FALSE.
CanDeleteAll(INTEGER, INTEGER, INTEGER): BOOLEAN Returns TRUE if there are numberToDelete characters starting at startPos and within the stringLength of some string; otherwise returns FALSE.
CanExtractAll(INTEGER, INTEGER, INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if there are numberToExtract characters starting at startPos and within the sourceLength of some string, and if the capacity of destination is sufficient to hold numberToExtract characters; otherwise returns FALSE.
CanInsertAll(INTEGER, INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if there is room for the insertion of sourceLength characters from some string into destination starting at startPos; otherwise returns FALSE.
CanReplaceAll(INTEGER, INTEGER, VAR ARRAY OF CHAR): BOOLEAN Returns TRUE if there is room for the replacement of sourceLength characters in destination starting at startPos; otherwise returns FALSE.
Capitalize(VAR ARRAY OF CHAR) Applies the function CAP to each character of the string value in stringVar.
Compare(ARRAY OF CHAR, ARRAY OF CHAR): CompareResults Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2.
Concat(ARRAY OF CHAR, ARRAY OF CHAR, VAR ARRAY OF CHAR) Concatenates source2 onto source1 and copies the result into destination.
Delete(VAR ARRAY OF CHAR, INTEGER, INTEGER) Deletes at most numberToDelete characters from stringVar, starting at position startPos.
Equal(ARRAY OF CHAR, ARRAY OF CHAR): BOOLEAN Returns ``stringVal1 = stringVal2`'.
Extract(ARRAY OF CHAR, INTEGER, INTEGER, VAR ARRAY OF CHAR) Copies at most numberToExtract characters from source to destination, starting at position startPos in source.
FindDiff(ARRAY OF CHAR, ARRAY OF CHAR, VAR BOOLEAN, VAR INTEGER) Compares the string values in stringVal1 and stringVal2 for differences.
FindNext(ARRAY OF CHAR, ARRAY OF CHAR, INTEGER, VAR BOOLEAN, VAR INTEGER) Looks forward for next occurrence of pattern in stringToSearch, starting the search at position startPos.
FindPrev(ARRAY OF CHAR, ARRAY OF CHAR, INTEGER, VAR BOOLEAN, VAR INTEGER) Looks backward for the previous occurrence of pattern in stringToSearch and returns the position of the first character of the pattern if found.
Insert(ARRAY OF CHAR, INTEGER, VAR ARRAY OF CHAR) Inserts source into destination at position startPos.
Length(ARRAY OF CHAR): INTEGER Returns the length of stringVal.
Replace(ARRAY OF CHAR, INTEGER, VAR ARRAY OF CHAR) Copies source into destination, starting at position startPos.

Constant Summary
equal Result of Compare if the first argument is equal to the second one.
greater Result of Compare if the first argument is lexically greater than the second one.
less Result of Compare if the first argument is lexically less than the second one.

Type Detail

### CompareResults

    TYPE CompareResults = SHORTINT

> Result type of Compare.

Procedure Detail

### Append

    PROCEDURE Append(source: ARRAY OF CHAR;
                     VAR destination: ARRAY OF CHAR)

> Appends source to destination.

### Assign

    PROCEDURE Assign(source: ARRAY OF CHAR;
                     VAR destination: ARRAY OF CHAR)

> Copies source to destination. Equivalent to the predefined procedure COPY. Unlike COPY, this procedure can be assigned to a procedure variable.

### CanAppendAll

    PROCEDURE CanAppendAll(sourceLength: INTEGER;
                           VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if there is sufficient room in destination to append a string of length sourceLength to the string in destination; otherwise returns FALSE.

> Pre-condition: sourceLength is not negative.

### CanAssignAll

    PROCEDURE CanAssignAll(sourceLength: INTEGER;
                           VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if a number of characters, indicated by sourceLength, will fit into destination; otherwise returns FALSE.

> Pre-condition: sourceLength is not negative.

### CanConcatAll

    PROCEDURE CanConcatAll(source1Length: INTEGER;
                           source2Length: INTEGER;
                           VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if there is sufficient room in destination for a two strings of lengths source1Length and source2Length; otherwise returns FALSE.

> Pre-condition: source1Length and source2Length are not negative.

### CanDeleteAll

    PROCEDURE CanDeleteAll(stringLength: INTEGER;
                           startPos: INTEGER;
                           numberToDelete: INTEGER): BOOLEAN

> Returns TRUE if there are numberToDelete characters starting at startPos and within the stringLength of some string; otherwise returns FALSE.

> Pre-condition: stringLength, startPos and numberToDelete are not negative.

### CanExtractAll

    PROCEDURE CanExtractAll(sourceLength: INTEGER;
                            startPos: INTEGER;
                            numberToExtract: INTEGER;
                            VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if there are numberToExtract characters starting at startPos and within the sourceLength of some string, and if the capacity of destination is sufficient to hold numberToExtract characters; otherwise returns FALSE.

> Pre-condition: sourceLength, startPos, and numberToExtract are not negative.

### CanInsertAll

    PROCEDURE CanInsertAll(sourceLength: INTEGER;
                           startPos: INTEGER;
                           VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if there is room for the insertion of sourceLength characters from some string into destination starting at startPos; otherwise returns FALSE.

> Pre-condition: sourceLength and startPos are not negative.

### CanReplaceAll

    PROCEDURE CanReplaceAll(sourceLength: INTEGER;
                            startPos: INTEGER;
                            VAR destination: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if there is room for the replacement of sourceLength characters in destination starting at startPos; otherwise returns FALSE.

> Pre-condition: sourceLength and startPos are not negative.

### Capitalize

    PROCEDURE Capitalize(VAR stringVar: ARRAY OF CHAR)

> Applies the function CAP to each character of the string value in stringVar.

### Compare

    PROCEDURE Compare(stringVal1: ARRAY OF CHAR;
                      stringVal2: ARRAY OF CHAR): CompareResults

> Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2. Note that Oberon-2 already contains predefined comparison operators on strings.

### Concat

    PROCEDURE Concat(source1: ARRAY OF CHAR;
                     source2: ARRAY OF CHAR;
                     VAR destination: ARRAY OF CHAR)

> Concatenates source2 onto source1 and copies the result into destination.

### Delete

    PROCEDURE Delete(VAR stringVar: ARRAY OF CHAR;
                     startPos: INTEGER;
                     numberToDelete: INTEGER)

> Deletes at most numberToDelete characters from stringVar, starting at position startPos. The string value in stringVar is not altered if startPos is greater than or equal to ``Length(stringVar)`'.

> Pre-condition: startPos and numberToDelete are not negative.

### Equal

    PROCEDURE Equal(stringVal1: ARRAY OF CHAR;
                    stringVal2: ARRAY OF CHAR): BOOLEAN

> Returns ``stringVal1 = stringVal2`'. Unlike the predefined operator ``=`', this procedure can be assigned to a procedure variable.

### Extract

    PROCEDURE Extract(source: ARRAY OF CHAR;
                      startPos: INTEGER;
                      numberToExtract: INTEGER;
                      VAR destination: ARRAY OF CHAR)

> Copies at most numberToExtract characters from source to destination, starting at position startPos in source. An empty string value will be extracted if startPos is greater than or equal to ``Length(source)`'.

> Pre-condition: startPos and numberToExtract are not negative.

### FindDiff

    PROCEDURE FindDiff(stringVal1: ARRAY OF CHAR;
                       stringVal2: ARRAY OF CHAR;
                       VAR differenceFound: BOOLEAN;
                       VAR posOfDifference: INTEGER)

> Compares the string values in stringVal1 and stringVal2 for differences. If they are equal, differenceFound is returned as FALSE, and TRUE otherwise. If differenceFound is TRUE, posOfDifference is set to the position of the first difference; otherwise posOfDifference is unchanged.

### FindNext

    PROCEDURE FindNext(pattern: ARRAY OF CHAR;
                       stringToSearch: ARRAY OF CHAR;
                       startPos: INTEGER;
                       VAR patternFound: BOOLEAN;
                       VAR posOfPattern: INTEGER)

> Looks forward for next occurrence of pattern in stringToSearch, starting the search at position startPos. If ``startPos < Length(stringToSearch)`' and pattern is found, patternFound is returned as TRUE, and posOfPattern contains the start position in stringToSearch of pattern. The position is a value in the range [startPos..Length(stringToSearch)-1]. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged. If ``startPos > Length(stringToSearch)-Length(Pattern)`' then patternFound is returned as FALSE.

> Pre-condition: startPos is not negative.

### FindPrev

    PROCEDURE FindPrev(pattern: ARRAY OF CHAR;
                       stringToSearch: ARRAY OF CHAR;
                       startPos: INTEGER;
                       VAR patternFound: BOOLEAN;
                       VAR posOfPattern: INTEGER)

> Looks backward for the previous occurrence of pattern in stringToSearch and returns the position of the first character of the pattern if found. The search for the pattern begins at startPos. If pattern is found, patternFound is returned as TRUE, and posOfPattern contains the start position in stringToSearch of pattern in the range [0..startPos]. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged. The pattern might be found at the given value of startPos. The search will fail if startPos is negative. If ``startPos > Length(stringToSearch)-Length(pattern)`' the whole string value is searched.

### Insert

    PROCEDURE Insert(source: ARRAY OF CHAR;
                     startPos: INTEGER;
                     VAR destination: ARRAY OF CHAR)

> Inserts source into destination at position startPos. After the call destination contains the string that is contructed by first splitting destination at the position startPos and then concatenating the first half, source, and the second half. The string value in destination is not altered if startPos is greater than ``Length(source)`'. If ``startPos = Length(source)`', then source is appended to destination.

> Pre-condition: startPos is not negative.

### Length

    PROCEDURE Length(stringVal: ARRAY OF CHAR): INTEGER

> Returns the length of stringVal. This is equal to the number of characters in stringVal up to and excluding the first 0X.

### Replace

    PROCEDURE Replace(source: ARRAY OF CHAR;
                      startPos: INTEGER;
                      VAR destination: ARRAY OF CHAR)

> Copies source into destination, starting at position startPos. Copying stops when all of source has been copied, or when the last character of the string value in destination has been replaced. The string value in destination is not altered if startPos is greater than or equal to ``Length(source)`'.

> Pre-condition: startPos is not negative.

Constant Detail

### equal

    CONST equal

> Result of Compare if the first argument is equal to the second one.

### greater

    CONST greater

> Result of Compare if the first argument is lexically greater than the second one.

### less

    CONST less

> Result of Compare if the first argument is lexically less than the second one.