Difference between revisions of "Modules/ooc2Strings"

From vishap oberon compiler
Jump to navigation Jump to search
Line 4: Line 4:
  
 
== Description ==
 
== Description ==
 +
 
As string manipulation is so common to programming problems, the OOC library provides additional string operations to those built into Oberon-2. The Oberon-2 language defines a string as a character array containing 0X as an embedded terminator. This means that an ARRAY OF CHAR isn't necessarily a string. The module `Strings' provides string manipulation operations for use on terminated character arrays.
 
As string manipulation is so common to programming problems, the OOC library provides additional string operations to those built into Oberon-2. The Oberon-2 language defines a string as a character array containing 0X as an embedded terminator. This means that an ARRAY OF CHAR isn't necessarily a string. The module `Strings' provides string manipulation operations for use on terminated character arrays.
  
Line 17: Line 18:
  
 
Also described are procedures that provide for pre-testing of the operation-completion conditions for the copying and concatenation procedures.
 
Also described are procedures that provide for pre-testing of the operation-completion conditions for the copying and concatenation procedures.
 +
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 
Procedure: Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 
::This procedure copies the string value of source to destination. It is equivalent to the predefined procedure COPY. Unlike COPY, this procedure can be assigned to a procedure variable.  
 
::This procedure copies the string value of source to destination. It is equivalent to the predefined procedure COPY. Unlike COPY, this procedure can be assigned to a procedure variable.  
  
Line 25: Line 28:
 
Function: CanAssignAll (sourceLength: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanAssignAll (sourceLength: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 
::Returns TRUE if a number of characters, indicated by sourceLength, will fit into destination; otherwise returns FALSE.
 
::Returns TRUE if a number of characters, indicated by sourceLength, will fit into destination; otherwise returns FALSE.
 +
  
 
::Pre-condition: sourceLength is not negative.  
 
::Pre-condition: sourceLength is not negative.  
  
 
Example:
 
Example:
 +
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR source:      ARRAY 6 OF CHAR;  
 
VAR source:      ARRAY 6 OF CHAR;  
Line 38: Line 45:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
:=> TRUE
 
:=> TRUE
 +
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Assign (source, destination);
 
Strings.Assign (source, destination);
Line 51: Line 59:
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Assign (source, destination);
 
Strings.Assign (source, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> destination = "abc"
 
:=> destination = "abc"
  
Line 57: Line 65:
 
source := "abcd";  
 
source := "abcd";  
 
Strings.CanAssignAll (Strings.Length (source), destination);
 
Strings.CanAssignAll (Strings.Length (source), destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> FALSE
 
:=> FALSE
  
Line 64: Line 72:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
:=> destination = "abc"
 
:=> destination = "abc"
 +
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Extract (source: ARRAY OF CHAR; startPos, numberToExtract: INTEGER; VAR destination: ARRAY OF CHAR)
 
Procedure: Extract (source: ARRAY OF CHAR; startPos, numberToExtract: INTEGER; VAR destination: ARRAY OF CHAR)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
::This procedure 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).
 
::This procedure 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.  
 
::Pre-condition: startPos and numberToExtract are not negative.  
Line 76: Line 88:
 
Function: CanExtractAll (sourceLength, startPos, numberToExtract: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanExtractAll (sourceLength, startPos, numberToExtract: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
::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.
 
::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.
Line 82: Line 95:
  
 
Example:
 
Example:
 +
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR source:      ARRAY 6 OF CHAR;  
 
VAR source:      ARRAY 6 OF CHAR;  
Line 109: Line 123:
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.CanExtractAll (Strings.Length (source), 0, 4, destination);
 
Strings.CanExtractAll (Strings.Length (source), 0, 4, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> FALSE
 
:=> FALSE
  
Line 119: Line 133:
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.CanExtractAll (Strings.Length (source), 2, 4, destination);
 
Strings.CanExtractAll (Strings.Length (source), 2, 4, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> FALSE
 
:=> FALSE
  
Line 139: Line 153:
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.CanExtractAll (Strings.Length (source), 4, 0, destination);
 
Strings.CanExtractAll (Strings.Length (source), 4, 0, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> TRUE
 
:=> TRUE
  
Line 150: Line 164:
 
Procedure: Delete (VAR stringVar: ARRAY OF CHAR; startPos, numberToDelete: INTEGER)
 
Procedure: Delete (VAR stringVar: ARRAY OF CHAR; startPos, numberToDelete: INTEGER)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
::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).
 
::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.  
 
::Pre-condition: startPos and numberToDelete are not negative.  
Line 158: Line 174:
 
Function: CanDeleteAll (stringLength, startPos, numberToDelete: INTEGER): BOOLEAN
 
Function: CanDeleteAll (stringLength, startPos, numberToDelete: INTEGER): BOOLEAN
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
::Returns TRUE if there are numberToDelete characters starting at startPos and within the stringLength of some string; otherwise returns FALSE.
 
::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.  
 
::Pre-condition: stringLength, startPos and numberToDelete are not negative.  
Line 172: Line 190:
 
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 4);
 
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 4);
 
</syntaxhighlight>   
 
</syntaxhighlight>   
::=> TRUE
+
:=> TRUE
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Delete (stringVar, 0, 4);
 
Strings.Delete (stringVar, 0, 4);
 
</syntaxhighlight>
 
</syntaxhighlight>
::=> stringVar = ""
+
:=> stringVar = ""
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">  
Line 183: Line 201:
 
Strings.CanDeleteAll (Strings.Length (stringVar), 1, 2);
 
Strings.CanDeleteAll (Strings.Length (stringVar), 1, 2);
 
</syntaxhighlight>   
 
</syntaxhighlight>   
::=> TRUE
+
:=> TRUE
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Delete (stringVar, 1, 2);
 
Strings.Delete (stringVar, 1, 2);
 
</syntaxhighlight>
 
</syntaxhighlight>
::=> stringVar = "ad"
+
 
 +
:</syntaxhighlight>
 +
:=> stringVar = "ad"
 
   
 
   
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
Line 194: Line 214:
 
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 5);
 
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 5);
 
</syntaxhighlight>   
 
</syntaxhighlight>   
::=> FALSE
+
 
 +
:</syntaxhighlight>
 +
:=> FALSE
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Delete (stringVar, 0, 5);
 
Strings.Delete (stringVar, 0, 5);
 
</syntaxhighlight>
 
</syntaxhighlight>
::=> stringVar = ""
+
 
 +
:</syntaxhighlight>
 +
:=> stringVar = ""
  
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Insert (source: ARRAY OF CHAR; startPos: INTEGER; VAR destination: ARRAY OF CHAR)
 
Procedure: Insert (source: ARRAY OF CHAR; startPos: INTEGER; VAR destination: ARRAY OF CHAR)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
::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.
 
::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.  
 
::Pre-condition: startPos is not negative.  
Line 212: Line 238:
 
Function: CanInsertAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanInsertAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
</syntaxhighlighting>
 
</syntaxhighlighting>
 +
  
 
::Returns TRUE if there is room for the insertion of sourceLength characters from some string into destination starting at startPos; otherwise returns FALSE.
 
::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.  
 
::Pre-condition: sourceLength and startPos are not negative.  
Line 237: Line 265:
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.CanInsertAll (Strings.Length (source), 3, destination);
 
Strings.CanInsertAll (Strings.Length (source), 3, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> TRUE
 
:=> TRUE
  
Line 260: Line 288:
  
 
Strings.CanInsertAll (Strings.Length (source), 0, destination);
 
Strings.CanInsertAll (Strings.Length (source), 0, destination);
</syntaxhighlight>
+
</syntaxhighlight>
 
:=> FALSE
 
:=> FALSE
  
Line 268: Line 296:
 
:=> destination = "abcde01"
 
:=> destination = "abcde01"
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.CanInsertAll (Strings.Length (source), 4, destination);   
 
Strings.CanInsertAll (Strings.Length (source), 4, destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Insert (source, 4, destination);   
 
Strings.Insert (source, 4, destination);   
  => destination = "0123abc"
+
</syntaxhighlight>
 +
:=> destination = "0123abc"
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Replace (source: ARRAY OF CHAR; startPos: INTEGER; VAR destination: ARRAY OF CHAR)
 
Procedure: Replace (source: ARRAY OF CHAR; startPos: INTEGER; VAR destination: ARRAY OF CHAR)
 +
</syntaxhighlight>
 +
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
  
Procedure: Replace (source: ARRAY OF LONGCHAR; startPos: INTEGER; VAR destination: ARRAY OF LONGCHAR)
 
 
::Copies source into destination starting at position startPos. The existing character values of destination are overwritten (i.e., replaced by) source's values. 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).
 
::Copies source into destination starting at position startPos. The existing character values of destination are overwritten (i.e., replaced by) source's values. 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).
  
    Notice that Replace does not continue past the string terminator 0X in destination. That is, Length(destination) will never be changed by Replace.
+
::Notice that Replace does not continue past the string terminator 0X in destination. That is, Length(destination) will never be changed by Replace.
  
    Pre-condition: startPos is not negative.
 
  
 +
::Pre-condition: startPos is not negative.
 +
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Function: CanReplaceAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanReplaceAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 +
</syntaxhighlight>
  
Function: CanReplaceAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF LONGCHAR): BOOLEAN
+
::Returns TRUE if there is room for the replacement of sourceLength characters in destination starting at startPos; otherwise returns FALSE.
    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.  
+
 
 +
::Pre-condition: sourceLength and startPos are not negative.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR source, destination: ARRAY 6 OF CHAR;  
 
VAR source, destination: ARRAY 6 OF CHAR;  
  
 
source := "ab"; destination := "1234";  
 
source := "ab"; destination := "1234";  
 
Strings.CanReplaceAll (Strings.Length (source), 0, destination);   
 
Strings.CanReplaceAll (Strings.Length (source), 0, destination);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Replace (source, 0, destination);   
 
Strings.Replace (source, 0, destination);   
  => destination = "ab34"
+
</syntaxhighlight>
 +
:=> destination = "ab34"
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source := "abc"; destination := "1234";  
 
source := "abc"; destination := "1234";  
 
Strings.CanReplaceAll (Strings.Length (source), 2, destination);   
 
Strings.CanReplaceAll (Strings.Length (source), 2, destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Replace (source, 2, destination);   
 
Strings.Replace (source, 2, destination);   
  => destination = "12ab"
+
</syntaxhighlight>
 +
:=> destination = "12ab"
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source := ""; destination := "1234";  
 
source := ""; destination := "1234";  
 
Strings.CanReplaceAll (Strings.Length (source), 4, destination);   
 
Strings.CanReplaceAll (Strings.Length (source), 4, destination);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Replace (source, 4, destination);   
 
Strings.Replace (source, 4, destination);   
  => destination = "1234"
+
</syntaxhighlight>
 +
:=> destination = "1234"
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source := ""; destination := "1234";  
 
source := ""; destination := "1234";  
 
Strings.CanReplaceAll (Strings.Length (source), 5, destination);   
 
Strings.CanReplaceAll (Strings.Length (source), 5, destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Replace (source, 5, destination);   
 
Strings.Replace (source, 5, destination);   
  => destination = "1234"
+
</syntaxhighlight>
 +
:=> destination = "1234"
  
 +
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 
Procedure: Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 +
</syntaxhighlight>
  
Procedure: Append (source: ARRAY OF LONGCHAR; VAR destination: ARRAY OF LONGCHAR)
+
::Appends source to destination.  
    Appends source to destination.  
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Function: CanAppendAll (sourceLength: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanAppendAll (sourceLength: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 +
</syntaxhighlight>
  
Function: CanAppendAll (sourceLength: INTEGER; VAR destination: ARRAY OF LONGCHAR): 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.
    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.  
+
 
 +
::Pre-condition: sourceLength is not negative.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR source, destination: ARRAY 6 OF CHAR;  
 
VAR source, destination: ARRAY 6 OF CHAR;  
  
 
source := "12"; destination := "abc";  
 
source := "12"; destination := "abc";  
 
Strings.CanAppendAll (Strings.Length (source), destination);   
 
Strings.CanAppendAll (Strings.Length (source), destination);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Append (source, destination);   
 
Strings.Append (source, destination);   
  => destination = "abc12"
+
</syntaxhighlight>
 +
:=> destination = "abc12"
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source := "123"; destination := "abc";  
 
source := "123"; destination := "abc";  
 
Strings.CanAppendAll (Strings.Length (source), destination);   
 
Strings.CanAppendAll (Strings.Length (source), destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 
Strings.Append (source, destination);   
 
Strings.Append (source, destination);   
  => destination = "abc12"
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 +
</syntaxhighlight>
 +
:=> destination = "abc12"
 +
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source := "123"; destination := "abcde";  
 
source := "123"; destination := "abcde";  
 
Strings.CanAppendAll (Strings.Length (source), destination);   
 
Strings.CanAppendAll (Strings.Length (source), destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Append (source, destination);   
 
Strings.Append (source, destination);   
  => destination = "abcde"
+
</syntaxhighlight>
 +
:=> destination = "abcde"
 +
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 
Procedure: Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
 +
</syntaxhighlight>
  
Procedure: Concat (source1, source2: ARRAY OF LONGCHAR; VAR destination: ARRAY OF LONGCHAR)
+
::Concatenates source2 onto source1 and copies the result into destination. Note that any previous contents of destination are destroyed by Concat.  
    Concatenates source2 onto source1 and copies the result into destination. Note that any previous contents of destination are destroyed by Concat.  
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Function: CanConcatAll (source1Length, source2Length: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 
Function: CanConcatAll (source1Length, source2Length: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
 +
</syntaxhighlight>
 +
::Returns TRUE if there is sufficient room in destination for a two strings of lengths source1Length and source2Length; otherwise returns FALSE.
  
Function: CanConcatAll (source1Length, source2Length: INTEGER; VAR destination: ARRAY OF LONGCHAR): 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.  
+
::Pre-condition: source1Length and source2Length are not negative.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR source1, source2: ARRAY 5 OF CHAR;  
 
VAR source1, source2: ARRAY 5 OF CHAR;  
    destination: ARRAY 6 OF CHAR;  
+
::destination: ARRAY 6 OF CHAR;  
  
 
source1 := "12"; source2 := "abc";  
 
source1 := "12"; source2 := "abc";  
 
Strings.CanConcatAll (Strings.Length (source1),  
 
Strings.CanConcatAll (Strings.Length (source1),  
                      Strings.Length (source2), destination);   
+
::                  Strings.Length (source2), destination);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 
Strings.Concat (source1, source2, destination);   
 
Strings.Concat (source1, source2, destination);   
  => destination = "12abc"
+
</syntaxhighlight>
 +
:=> destination = "12abc"
 
   
 
   
 
source1 := "123"; source2 := "abc";  
 
source1 := "123"; source2 := "abc";  
 
Strings.CanConcatAll (Strings.Length (source1),  
 
Strings.CanConcatAll (Strings.Length (source1),  
 
                       Strings.Length (source2), destination);   
 
                       Strings.Length (source2), destination);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 
Strings.Concat (source1, source2, destination);   
 
Strings.Concat (source1, source2, destination);   
  => destination = "123ab"
+
</syntaxhighlight>
 +
:=> destination = "123ab"
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
source1 := ""; source2 := "abc";  
 
source1 := ""; source2 := "abc";  
 
Strings.CanConcatAll (Strings.Length (source1),  
 
Strings.CanConcatAll (Strings.Length (source1),  
 
                       Strings.Length (source2), destination);   
 
                       Strings.Length (source2), destination);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 
Strings.Concat (source1, source2, destination);   
 
Strings.Concat (source1, source2, destination);   
  => destination = "abc"
+
</syntaxhighlight>
 +
:=> destination = "abc"
  
 
== Comparing & Searching Strings ==
 
== Comparing & Searching Strings ==
Line 395: Line 484:
 
Function: Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults
 
Function: Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults
  
Function: Compare (stringVal1, stringVal2: ARRAY OF LONGCHAR): CompareResults
+
::Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2.
    Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2.
 
  
    Please note: Oberon-2 already contains predefined comparison operators on strings.
+
::Please note: Oberon-2 already contains predefined comparison operators on strings.
  
    Data type: CompareResults = SHORTINT
+
::Data type: CompareResults = SHORTINT
        CompareResults and its related constants are used with procedure Compare. The following constants are defined for its value:
+
::    CompareResults and its related constants are used with procedure Compare. The following constants are defined for its value:
  
        Constant: less
+
::    Constant: less
  
        Constant: equal
+
::    Constant: equal
  
        Constant: greater
+
::    Constant: greater
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
  
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
Strings.Compare (stringVal1, stringVal2);   
 
Strings.Compare (stringVal1, stringVal2);   
  => equal
+
</syntaxhighlight>
 +
:=> equal
 
   
 
   
 
stringVal1 := "abc"; stringVal2 := "abd";  
 
stringVal1 := "abc"; stringVal2 := "abd";  
 
Strings.Compare (stringVal1, stringVal2);   
 
Strings.Compare (stringVal1, stringVal2);   
  => less
+
</syntaxhighlight>
 +
:=> less
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "ab"; stringVal2 := "abc";  
 
stringVal1 := "ab"; stringVal2 := "abc";  
 
Strings.Compare (stringVal1, stringVal2);   
 
Strings.Compare (stringVal1, stringVal2);   
  => less
+
</syntaxhighlight>
 +
:=> less
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "abd"; stringVal2 := "abc";  
 
stringVal1 := "abd"; stringVal2 := "abc";  
 
Strings.Compare (stringVal1, stringVal2);   
 
Strings.Compare (stringVal1, stringVal2);   
  => greater
+
</syntaxhighlight>
 +
:=> greater
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Function: Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN
 
Function: Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN
 
+
</syntaxhighlight>
Function: Equal (stringVal1, stringVal2: ARRAY OF LONGCHAR): BOOLEAN
+
::Returns stringVal1=stringVal2. That is, Equal returns TRUE if the string value of stringVal1 is the same as the string value of stringVal2; otherwise, it returns FALSE. Unlike the predefined operator =, this procedure can be assigned to a procedure variable.  
    Returns stringVal1=stringVal2. That is, Equal returns TRUE if the string value of stringVal1 is the same as the string value of stringVal2; otherwise, it returns FALSE. Unlike the predefined operator =, this procedure can be assigned to a procedure variable.  
 
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
 
   
 
   
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
Strings.Equal (stringVal1, stringVal2);   
 
Strings.Equal (stringVal1, stringVal2);   
  => TRUE
+
</syntaxhighlight>
 +
:=> TRUE
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "abc"; stringVal2 := "abd";  
 
stringVal1 := "abc"; stringVal2 := "abd";  
 
Strings.Equal (stringVal1, stringVal2);   
 
Strings.Equal (stringVal1, stringVal2);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "ab"; stringVal2 := "abc";  
 
stringVal1 := "ab"; stringVal2 := "abc";  
 
Strings.Equal (stringVal1, stringVal2);   
 
Strings.Equal (stringVal1, stringVal2);   
  => FALSE
+
</syntaxhighlight>
 +
:=> FALSE
 +
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: FindNext (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
 
Procedure: FindNext (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
 +
</syntaxhighlight>
  
Procedure: FindNext (pattern, stringToSearch: ARRAY OF LONGCHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
+
::This procedure is used to locate a pattern string within another string. It searches forward through stringToSearch for next occurrence of pattern; startPos is the starting position of the search (within stringToSearch).
    This procedure is used to locate a pattern string within another string. It searches forward through stringToSearch for next occurrence of pattern; startPos is the starting position of the search (within stringToSearch).
 
  
    If startPos<Length(stringToSearch) and pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is in the range
+
::If startPos<Length(stringToSearch) and pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is in the range
  
    [startPos..Length(stringToSearch)-1])
+
::[startPos..Length(stringToSearch)-1])
  
    Otherwise, patternFound is returned as FALSE and posOfPattern is unchanged.
+
::Otherwise, patternFound is returned as FALSE and posOfPattern is unchanged.
  
    If startPos>Length(stringToSearch)-Length(pattern), then patternFound is returned as FALSE.
+
::If startPos>Length(stringToSearch)-Length(pattern), then patternFound is returned as FALSE.
  
    Pre-condition: startPos is not negative.  
+
 
 +
::Pre-condition: startPos is not negative.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR pattern:        ARRAY 4 OF CHAR;  
 
VAR pattern:        ARRAY 4 OF CHAR;  
    stringToSearch: ARRAY 9 OF CHAR;  
+
::stringToSearch: ARRAY 9 OF CHAR;  
    found: BOOLEAN;  
+
::found: BOOLEAN;  
    posOfPattern: INTEGER;  
+
::posOfPattern: INTEGER;  
  
 
pattern := "ab"; stringToSearch := "ababcaba";  
 
pattern := "ab"; stringToSearch := "ababcaba";  
 
Strings.FindNext (pattern, stringToSearch, 0, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 0, found, posOfPattern);   
  => TRUE, posOfPattern = 0
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 0
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindNext (pattern, stringToSearch, 1, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 1, found, posOfPattern);   
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 +
:=> TRUE, posOfPattern = 2
 
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);   
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 +
:=> TRUE, posOfPattern = 2
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern);   
  => TRUE, posOfPattern = 5
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 5
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindNext (pattern, stringToSearch, 4, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 4, found, posOfPattern);   
  => TRUE, posOfPattern = 5
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 5
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindNext (pattern, stringToSearch, 5, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 5, found, posOfPattern);   
  => TRUE, posOfPattern = 5
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 5
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindNext (pattern, stringToSearch, 6, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 6, found, posOfPattern);   
  => FALSE, posOfPattern unchanged
+
</syntaxhighlight>
 +
:=> FALSE, posOfPattern unchanged
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
pattern := ""; stringToSearch := "abc";  
 
pattern := ""; stringToSearch := "abc";  
 
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);   
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 
Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern);   
 
Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern);   
  => FALSE, posOfPattern unchanged
+
</syntaxhighlight>
 +
:=> FALSE, posOfPattern unchanged
 +
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
 
Procedure: FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
 +
</syntaxhighlight>
  
Procedure: FindPrev (pattern, stringToSearch: ARRAY OF LONGCHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
+
<syntaxhighlight lang="oberon2" style="font-size:10pt">
    This procedure is used to locate a pattern string within another string. It searches backward through stringToSearch for a previous occurrence of pattern; startPos is the starting position of the search (within stringToSearch).
+
::This procedure is used to locate a pattern string within another string. It searches backward through stringToSearch for a previous occurrence of pattern; startPos is the starting position of the search (within stringToSearch).
  
    If pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is in the range [0..startPos]).
+
::If pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is in the range [0..startPos]).
  
    Otherwise, patternFound is returned as FALSE and posOfPattern is unchanged (in this case, the pattern might be found at startPos).
+
::Otherwise, patternFound is returned as FALSE and posOfPattern is unchanged (in this case, the pattern might be found at startPos).
  
    The search will fail if startPos is negative.
+
::The search will fail if startPos is negative.
  
    If startPos>Length(stringToSearch)-Length(pattern) the whole string value is searched.  
+
::If startPos>Length(stringToSearch)-Length(pattern) the whole string value is searched.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR pattern:        ARRAY 4 OF CHAR;  
 
VAR pattern:        ARRAY 4 OF CHAR;  
    stringToSearch: ARRAY 9 OF CHAR;  
+
::stringToSearch: ARRAY 9 OF CHAR;  
    found: BOOLEAN;  
+
::found: BOOLEAN;  
    posOfPattern: INTEGER;  
+
::posOfPattern: INTEGER;  
  
 
pattern := "abc"; stringToSearch := "ababcaba";  
 
pattern := "abc"; stringToSearch := "ababcaba";  
 
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
  => FALSE, posOfPattern unchanged
+
</syntaxhighlight>
 +
:=> FALSE, posOfPattern unchanged
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
pattern := "ab"; stringToSearch := "ababcaba";  
 
pattern := "ab"; stringToSearch := "ababcaba";  
 
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
  => TRUE, posOfPattern = 0
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 0
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
  => TRUE, posOfPattern = 0
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 0
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
  => TRUE, posOfPattern = 2
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 2
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 5, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 5, found, posOfPattern);
  => TRUE, posOfPattern = 5
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 5
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
pattern := ""; stringToSearch := "abc";  
 
pattern := ""; stringToSearch := "abc";  
 
Strings.FindPrev(pattern, stringToSearch, -1, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, -1, found, posOfPattern);
  => FALSE, posOfPattern unchanged
+
</syntaxhighlight>
 +
:=> FALSE, posOfPattern unchanged
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
  => TRUE, posOfPattern = 0
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 0
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
 
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
  => TRUE, posOfPattern = 3
+
</syntaxhighlight>
 +
:=> TRUE, posOfPattern = 3
 +
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: FindDiff (stringVal1, stringVal2: ARRAY OF CHAR; VAR differenceFound: BOOLEAN; VAR posOfDifference: INTEGER)
 
Procedure: FindDiff (stringVal1, stringVal2: ARRAY OF CHAR; VAR differenceFound: BOOLEAN; VAR posOfDifference: INTEGER)
 +
</syntaxhighlight>
 +
 +
::Compares the string values in stringVal1 and stringVal2 for differences. If they are equal, differenceFound is returned as FALSE; and TRUE otherwise.
  
Procedure: FindDiff (stringVal1, stringVal2: ARRAY OF LONGCHAR; 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.  
+
::If differenceFound is TRUE, posOfDifference is set to the position of the first difference; otherwise posOfDifference is unchanged.  
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
 
VAR stringVal1, stringVal2: ARRAY 4 OF CHAR;  
    diffFound: BOOLEAN;
+
::diffFound: BOOLEAN;
    posOfDiff: INTEGER;  
+
::posOfDiff: INTEGER;  
  
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
stringVal1 := "abc"; stringVal2 := "abc";  
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
  => FALSE, posOfDifference unchanged
+
</syntaxhighlight>
 +
:=> FALSE, posOfDifference unchanged
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "ab"; stringVal2 := "ac";  
 
stringVal1 := "ab"; stringVal2 := "ac";  
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
  => TRUE, posOfDifference = 1
+
</syntaxhighlight>
 +
:=> TRUE, posOfDifference = 1
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal1 := "ab"; stringVal2 := "a";  
 
stringVal1 := "ab"; stringVal2 := "a";  
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
  => TRUE, posOfDifference = 1
+
</syntaxhighlight>
 +
:=> TRUE, posOfDifference = 1
  
 
== Miscellaneous Strings Procedures ==
 
== Miscellaneous Strings Procedures ==
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Function: Length (stringVal: ARRAY OF CHAR): INTEGER
 
Function: Length (stringVal: ARRAY OF CHAR): INTEGER
 
+
</syntaxhighlight>
Function: Length (stringVal: ARRAY OF LONGCHAR): INTEGER
+
::Returns the string length of stringVal. This is equal to the number of characters in stringVal up to and excluding the first 0X.  
    Returns the string length of stringVal. This is equal to the number of characters in stringVal up to and excluding the first 0X.  
 
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Strings.Length("Hello, world");  
 
Strings.Length("Hello, world");  
    => 12
+
:</syntaxhighlight>
 +
:=> 12
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR stringVal: ARRAY 6 OF CHAR;  
 
VAR stringVal: ARRAY 6 OF CHAR;  
 
stringVal := "";  
 
stringVal := "";  
 
Strings.Length(stringVal);
 
Strings.Length(stringVal);
    => 0
+
</syntaxhighlight>
 +
:=> 0
 +
 
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVal := "12";  
 
stringVal := "12";  
 
Strings.Length(stringVal);
 
Strings.Length(stringVal);
    => 2
+
:</syntaxhighlight>
 +
:=> 2
  
 
Recall that if you instead need the total size of the character array, you should use the standard Oberon-2 function procedure LEN:
 
Recall that if you instead need the total size of the character array, you should use the standard Oberon-2 function procedure LEN:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR aString: ARRAY 32 OF CHAR;
 
VAR aString: ARRAY 32 OF CHAR;
 
aString := "Hello, world";
 
aString := "Hello, world";
 
LEN(aString)
 
LEN(aString)
    => 32
+
</syntaxhighlight>
 +
:=> 32
 +
 
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
Procedure: Capitalize (VAR stringVar: ARRAY OF CHAR)
 
Procedure: Capitalize (VAR stringVar: ARRAY OF CHAR)
 +
</syntaxhighlight>
  
Procedure: Capitalize (VAR stringVar: ARRAY OF LONGCHAR)
+
::Applies the function CAP to each character of the string value in stringVar.  
    Applies the function CAP to each character of the string value in stringVar.  
 
  
 
Example:
 
Example:
  
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
VAR stringVar: ARRAY 6 OF CHAR;  
 
VAR stringVar: ARRAY 6 OF CHAR;  
  
 
stringVar := "abc";  
 
stringVar := "abc";  
 
Strings.Capitalize (stringVar);   
 
Strings.Capitalize (stringVar);   
  => stringVar = "ABC"
+
</syntaxhighlight>
 +
:=> stringVar = "ABC"
 
   
 
   
 +
<syntaxhighlight lang="oberon2" style="font-size:10pt">
 
stringVar := "0aB";
 
stringVar := "0aB";
 
Strings.Capitalize (stringVar);   
 
Strings.Capitalize (stringVar);   
  => stringVar = "0AB"
+
</syntaxhighlight>
 +
:=> stringVar = "0AB"
  
  

Revision as of 19:24, 5 February 2016

Deutsch (de) | English (en) | հայերեն (hy)

Module ooc2Strings

Description

As string manipulation is so common to programming problems, the OOC library provides additional string operations to those built into Oberon-2. The Oberon-2 language defines a string as a character array containing 0X as an embedded terminator. This means that an ARRAY OF CHAR isn't necessarily a string. The module `Strings' provides string manipulation operations for use on terminated character arrays.

Recall that string literals are sequences of characters enclosed in single (') or double (") quote marks. The opening quote must be the same as the closing quote and must not occur within the string. Passing a string literal of length n as an argument to a procedure expecting an ARRAY OF CHAR delivers n+1 characters to the parameter.

The number of characters in a string (up to the terminating 0X) is called its length. A string literal of length 1 can be used wherever a character constant is allowed and vice versa.

Please note: All procedures reading and producing strings expect termination with 0X. The behaviour of a procedure is undefined if one of its input parameters is an unterminated character array. Behavior is also undefined if a negative value is used as an input parameter that represents an array position or a string length.

Copying and Concatenation

This section describes procedures that construct a string value, and attempt to assign it to a variable parameter. All of these procedures have the property that if the length of the constructed string value exceeds the capacity of the variable parameter, a truncated value is assigned. The constructed string always ends with a string terminator 0X.

Also described are procedures that provide for pre-testing of the operation-completion conditions for the copying and concatenation procedures.

Procedure: Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
This procedure copies the string value of source to destination. It is equivalent to the predefined procedure COPY. Unlike COPY, this procedure can be assigned to a procedure variable.
Function: 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.

Example:

VAR source:      ARRAY 6 OF CHAR; 
    destination: ARRAY 4 OF CHAR; 

source := ""; 
Strings.CanAssignAll (Strings.Length (source), destination);
=> TRUE
Strings.Assign (source, destination);
=> destination = ""
source := "abc"; 
Strings.CanAssignAll (Strings.Length (source), destination);
=> TRUE
Strings.Assign (source, destination);
=> destination = "abc"
source := "abcd"; 
Strings.CanAssignAll (Strings.Length (source), destination);
=> FALSE
Strings.Assign (source, destination);
=> destination = "abc"
<syntaxhighlight lang="oberon2" style="font-size:10pt">
Procedure: Extract (source: ARRAY OF CHAR; startPos, numberToExtract: INTEGER; VAR destination: ARRAY OF CHAR)


This procedure 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.
Function: CanExtractAll (sourceLength, startPos, 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.

Example:

VAR source:      ARRAY 6 OF CHAR; 
    destination: ARRAY 4 OF CHAR; 

source := "abcde"; 

Strings.CanExtractAll (Strings.Length (source), 0, 3, destination);
=> TRUE
Strings.Extract (source, 0, 3, destination);
=> destination = "abc"
 
Strings.CanExtractAll (Strings.Length (source), 3, 2, destination);
=> TRUE
Strings.Extract (source, 3, 2, destination);
=> destination = "de"
Strings.CanExtractAll (Strings.Length (source), 0, 4, destination);
=> FALSE
Strings.Extract (source, 0, 4, destination);
=> destination = "abc"
Strings.CanExtractAll (Strings.Length (source), 2, 4, destination);
=> FALSE
Strings.Extract (source, 2, 4, destination);
=> destination = "cde"
Strings.CanExtractAll (Strings.Length (source), 5, 1, destination);
=> FALSE
Strings.Extract (source, 5, 1, destination);
=> destination = ""
Strings.CanExtractAll (Strings.Length (source), 4, 0, destination);
=> TRUE
Strings.Extract (source, 4, 0, destination);
=> destination = ""
Procedure: Delete (VAR stringVar: ARRAY OF CHAR; startPos, 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.
Function: CanDeleteAll (stringLength, startPos, 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.

Example:

VAR stringVar: ARRAY 6 OF CHAR; 
    startPos:  INTEGER; 
 
stringVar := "abcd";
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 4);
=> TRUE
Strings.Delete (stringVar, 0, 4);
=> stringVar = ""
 
stringVar := "abcd";
Strings.CanDeleteAll (Strings.Length (stringVar), 1, 2);
=> TRUE
Strings.Delete (stringVar, 1, 2);
</syntaxhighlight>
=> stringVar = "ad"
stringVar := "abcd";
Strings.CanDeleteAll (Strings.Length (stringVar), 0, 5);
</syntaxhighlight>
=> FALSE
Strings.Delete (stringVar, 0, 5);
</syntaxhighlight>
=> stringVar = ""
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.
Function: CanInsertAll (sourceLength, startPos: INTEGER; VAR destination: ARRAY OF CHAR): BOOLEAN
</syntaxhighlighting>


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

Example:

<syntaxhighlight lang="oberon2" style="font-size:10pt">
VAR source:      ARRAY 6 OF CHAR; 
    destination: ARRAY 8 OF CHAR; 

source := "abc";
destination := "012"; 

Strings.CanInsertAll (Strings.Length (source), 1, destination);
=> TRUE
Strings.Insert (source, 1, destination);
=> destination = "0abc12"
Strings.CanInsertAll (Strings.Length (source), 3, destination);
=> TRUE
Strings.Insert (source, 3, destination);
=> destination = "012abc"
Strings.CanInsertAll (Strings.Length (source, 4, destination);
=> FALSE
Strings.Insert (source, 4, destination);
=> destination = "012"
source := "abcde"; 
destination := "012356"; 

Strings.CanInsertAll (Strings.Length (source), 0, destination);
=> FALSE
Strings.Insert (source, 0, destination);
=> destination = "abcde01"
Strings.CanInsertAll (Strings.Length (source), 4, destination);
=> FALSE
Strings.Insert (source, 4, destination);
=> destination = "0123abc"
Procedure: Replace (source: ARRAY OF CHAR; startPos: INTEGER; VAR destination: ARRAY OF CHAR)
::Copies source into destination starting at position startPos. The existing character values of destination are overwritten (i.e., replaced by) source's values. 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).

::Notice that Replace does not continue past the string terminator 0X in destination. That is, Length(destination) will never be changed by Replace.


::Pre-condition: startPos is not negative. 

<syntaxhighlight lang="oberon2" style="font-size:10pt">
Function: CanReplaceAll (sourceLength, 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.

Example:

VAR source, destination: ARRAY 6 OF CHAR; 

source := "ab"; destination := "1234"; 
Strings.CanReplaceAll (Strings.Length (source), 0, destination);
=> TRUE
Strings.Replace (source, 0, destination);
=> destination = "ab34"
source := "abc"; destination := "1234"; 
Strings.CanReplaceAll (Strings.Length (source), 2, destination);
=> FALSE
Strings.Replace (source, 2, destination);
=> destination = "12ab"
source := ""; destination := "1234"; 
Strings.CanReplaceAll (Strings.Length (source), 4, destination);
=> TRUE
Strings.Replace (source, 4, destination);
=> destination = "1234"
source := ""; destination := "1234"; 
Strings.CanReplaceAll (Strings.Length (source), 5, destination);
=> FALSE
Strings.Replace (source, 5, destination);
=> destination = "1234"


Procedure: Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
Appends source to destination.
Function: 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.

Example:

VAR source, destination: ARRAY 6 OF CHAR; 

source := "12"; destination := "abc"; 
Strings.CanAppendAll (Strings.Length (source), destination);
=> TRUE
Strings.Append (source, destination);
=> destination = "abc12"
source := "123"; destination := "abc"; 
Strings.CanAppendAll (Strings.Length (source), destination);
=> FALSE

Strings.Append (source, destination);

=> destination = "abc12"
source := "123"; destination := "abcde"; 
Strings.CanAppendAll (Strings.Length (source), destination);
=> FALSE
Strings.Append (source, destination);
=> destination = "abcde"


Procedure: Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR)
Concatenates source2 onto source1 and copies the result into destination. Note that any previous contents of destination are destroyed by Concat.
Function: CanConcatAll (source1Length, 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.

Example:

VAR source1, source2: ARRAY 5 OF CHAR; 
::destination: ARRAY 6 OF CHAR; 

source1 := "12"; source2 := "abc"; 
Strings.CanConcatAll (Strings.Length (source1), 
::                  Strings.Length (source2), destination);
=> TRUE

Strings.Concat (source1, source2, destination); </syntaxhighlight>

=> destination = "12abc"

source1 := "123"; source2 := "abc"; Strings.CanConcatAll (Strings.Length (source1),

                     Strings.Length (source2), destination);  

</syntaxhighlight>

=> FALSE

Strings.Concat (source1, source2, destination); </syntaxhighlight>

=> destination = "123ab"
source1 := ""; source2 := "abc"; 
Strings.CanConcatAll (Strings.Length (source1), 
                      Strings.Length (source2), destination);
=> TRUE

Strings.Concat (source1, source2, destination); </syntaxhighlight>

=> destination = "abc"

Comparing & Searching Strings

These procedures provide for the comparison of string values, and for the location of substrings within strings.

Function: Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults

Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2.
Please note: Oberon-2 already contains predefined comparison operators on strings.
Data type: CompareResults = SHORTINT
CompareResults and its related constants are used with procedure Compare. The following constants are defined for its value:
Constant: less
Constant: equal
Constant: greater

Example:

VAR stringVal1, stringVal2: ARRAY 4 OF CHAR; 

stringVal1 := "abc"; stringVal2 := "abc"; 
Strings.Compare (stringVal1, stringVal2);
=> equal

stringVal1 := "abc"; stringVal2 := "abd"; Strings.Compare (stringVal1, stringVal2); </syntaxhighlight>

=> less
stringVal1 := "ab"; stringVal2 := "abc"; 
Strings.Compare (stringVal1, stringVal2);
=> less
stringVal1 := "abd"; stringVal2 := "abc"; 
Strings.Compare (stringVal1, stringVal2);
=> greater
Function: Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN
Returns stringVal1=stringVal2. That is, Equal returns TRUE if the string value of stringVal1 is the same as the string value of stringVal2; otherwise, it returns FALSE. Unlike the predefined operator =, this procedure can be assigned to a procedure variable.

Example:

VAR stringVal1, stringVal2: ARRAY 4 OF CHAR; 
 
stringVal1 := "abc"; stringVal2 := "abc"; 
Strings.Equal (stringVal1, stringVal2);
=> TRUE
stringVal1 := "abc"; stringVal2 := "abd"; 
Strings.Equal (stringVal1, stringVal2);
=> FALSE
stringVal1 := "ab"; stringVal2 := "abc"; 
Strings.Equal (stringVal1, stringVal2);
=> FALSE


Procedure: FindNext (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
This procedure is used to locate a pattern string within another string. It searches forward through stringToSearch for next occurrence of pattern; startPos is the starting position of the search (within stringToSearch).
If startPos<Length(stringToSearch) and pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is 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.

Example:

VAR pattern:        ARRAY 4 OF CHAR; 
::stringToSearch: ARRAY 9 OF CHAR; 
::found: BOOLEAN; 
::posOfPattern: INTEGER; 

pattern := "ab"; stringToSearch := "ababcaba"; 
Strings.FindNext (pattern, stringToSearch, 0, found, posOfPattern);
=> TRUE, posOfPattern = 0
Strings.FindNext (pattern, stringToSearch, 1, found, posOfPattern);
:=> TRUE, posOfPattern = 2
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);
:=> TRUE, posOfPattern = 2

<syntaxhighlight lang="oberon2" style="font-size:10pt">
Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern);
=> TRUE, posOfPattern = 5
Strings.FindNext (pattern, stringToSearch, 4, found, posOfPattern);
=> TRUE, posOfPattern = 5
Strings.FindNext (pattern, stringToSearch, 5, found, posOfPattern);
=> TRUE, posOfPattern = 5
Strings.FindNext (pattern, stringToSearch, 6, found, posOfPattern);
=> FALSE, posOfPattern unchanged
pattern := ""; stringToSearch := "abc"; 
Strings.FindNext (pattern, stringToSearch, 2, found, posOfPattern);
=> TRUE, posOfPattern = 2

Strings.FindNext (pattern, stringToSearch, 3, found, posOfPattern); </syntaxhighlight>

=> FALSE, posOfPattern unchanged


Procedure: FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startPos: INTEGER; VAR patternFound: BOOLEAN; VAR posOfPattern: INTEGER)
::This procedure is used to locate a pattern string within another string. It searches backward through stringToSearch for a previous occurrence of pattern; startPos is the starting position of the search (within stringToSearch).

::If pattern is found, patternFound is returned as TRUE and posOfPattern contains the start position in stringToSearch of pattern (i.e., posOfPattern is in the range [0..startPos]).

::Otherwise, patternFound is returned as FALSE and posOfPattern is unchanged (in this case, the pattern might be found at startPos).

::The search will fail if startPos is negative.

::If startPos>Length(stringToSearch)-Length(pattern) the whole string value is searched. 

Example:

<syntaxhighlight lang="oberon2" style="font-size:10pt">
VAR pattern:        ARRAY 4 OF CHAR; 
::stringToSearch: ARRAY 9 OF CHAR; 
::found: BOOLEAN; 
::posOfPattern: INTEGER; 

pattern := "abc"; stringToSearch := "ababcaba"; 
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
=> FALSE, posOfPattern unchanged
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
=> TRUE, posOfPattern = 2
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
=> TRUE, posOfPattern = 2
pattern := "ab"; stringToSearch := "ababcaba"; 
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
=> TRUE, posOfPattern = 0
Strings.FindPrev(pattern, stringToSearch, 1, found, posOfPattern);
=> TRUE, posOfPattern = 0
Strings.FindPrev(pattern, stringToSearch, 2, found, posOfPattern);
=> TRUE, posOfPattern = 2
Strings.FindPrev(pattern, stringToSearch, 3, found, posOfPattern);
=> TRUE, posOfPattern = 2
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
=> TRUE, posOfPattern = 2
Strings.FindPrev(pattern, stringToSearch, 5, found, posOfPattern);
=> TRUE, posOfPattern = 5
pattern := ""; stringToSearch := "abc"; 
Strings.FindPrev(pattern, stringToSearch, -1, found, posOfPattern);
=> FALSE, posOfPattern unchanged
Strings.FindPrev(pattern, stringToSearch, 0, found, posOfPattern);
=> TRUE, posOfPattern = 0
Strings.FindPrev(pattern, stringToSearch, 4, found, posOfPattern);
=> TRUE, posOfPattern = 3


Procedure: FindDiff (stringVal1, 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.

Example:

VAR stringVal1, stringVal2: ARRAY 4 OF CHAR; 
::diffFound: BOOLEAN;
::posOfDiff: INTEGER; 

stringVal1 := "abc"; stringVal2 := "abc"; 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
=> FALSE, posOfDifference unchanged
stringVal1 := "ab"; stringVal2 := "ac"; 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
=> TRUE, posOfDifference = 1
stringVal1 := "ab"; stringVal2 := "a"; 
Strings.FindDiff(stringVal1, stringVal2, diffFound, posOfDiff);
=> TRUE, posOfDifference = 1

Miscellaneous Strings Procedures

Function: Length (stringVal: ARRAY OF CHAR): INTEGER
Returns the string length of stringVal. This is equal to the number of characters in stringVal up to and excluding the first 0X.

Example:

Strings.Length("Hello, world"); 
:
=> 12
VAR stringVal: ARRAY 6 OF CHAR; 
stringVal := ""; 
Strings.Length(stringVal);
=> 0
stringVal := "12"; 
Strings.Length(stringVal);
:
=> 2

Recall that if you instead need the total size of the character array, you should use the standard Oberon-2 function procedure LEN:

VAR aString: ARRAY 32 OF CHAR;
aString := "Hello, world";
LEN(aString)
=> 32


Procedure: Capitalize (VAR stringVar: ARRAY OF CHAR)
Applies the function CAP to each character of the string value in stringVar.

Example:

VAR stringVar: ARRAY 6 OF CHAR; 

stringVar := "abc"; 
Strings.Capitalize (stringVar);
=> stringVar = "ABC"
stringVar := "0aB";
Strings.Capitalize (stringVar);
=> stringVar = "0AB"


Origin

This module have been ported from the Optimizing Oberon Compiler's standard library.

This article was created by using Optimizing Oberon Compiler's Reference Manual as a source.