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.