gcc/m2/gm2-libs-iso/Strings.def

   1 (* Library module defined by the International Standard
   2    Information technology - programming languages
   3    BS ISO/IEC 10514-1:1996E Part 1: Modula-2, Base Language.
   4
   5    Copyright ISO/IEC (International Organization for Standardization
   6    and International Electrotechnical Commission) 1996-2021.
   7
   8    It may be freely copied for the purpose of implementation (see page
   9    707 of the Information technology - Programming languages Part 1:
  10    Modula-2, Base Language.  BS ISO/IEC 10514-1:1996).  *)
  11
  12 DEFINITION MODULE Strings;
  13
  14   (* Facilities for manipulating strings *)
  15
  16 TYPE
  17   String1 = ARRAY [0..0] OF CHAR;
  18     (* String1 is provided for constructing a value of a single-character string type from a
  19        single character value in order to pass CHAR values to ARRAY OF CHAR parameters.
  20     *)
  21
  22 PROCEDURE Length (stringVal: ARRAY OF CHAR): CARDINAL;
  23   (* Returns the length of stringVal (the same value as would be returned by the
  24      pervasive function LENGTH).
  25   *)
  26
  27
  28 (* The following seven procedures construct a string value, and attempt to assign it to a
  29    variable parameter.  They all have the property that if the length of the constructed string
  30    value exceeds the capacity of the variable parameter, a truncated value is assigned, while
  31    if the length of the constructed string value is less than the capacity of the variable
  32    parameter, a string terminator is appended before assignment is performed.
  33 *)
  34
  35 PROCEDURE Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  36   (* Copies source to destination *)
  37
  38 PROCEDURE Extract (source: ARRAY OF CHAR; startIndex, numberToExtract: CARDINAL;
  39                    VAR destination: ARRAY OF CHAR);
  40   (* Copies at most numberToExtract characters from source to destination, starting at position
  41      startIndex in source.
  42   *)
  43
  44 PROCEDURE Delete (VAR stringVar: ARRAY OF CHAR; startIndex, numberToDelete:
  45 CARDINAL);
  46   (* Deletes at most numberToDelete characters from stringVar, starting at position
  47      startIndex.
  48   *)
  49
  50 PROCEDURE Insert (source: ARRAY OF CHAR; startIndex: CARDINAL;
  51                   VAR destination: ARRAY OF CHAR);
  52   (* Inserts source into destination at position startIndex *)
  53
  54 PROCEDURE Replace (source: ARRAY OF CHAR; startIndex: CARDINAL;
  55                    VAR destination: ARRAY OF CHAR);
  56   (* Copies source into destination, starting at position startIndex. Copying stops when
  57      all of source has been copied, or when the last character of the string value in
  58      destination has been replaced.
  59   *)
  60
  61 PROCEDURE Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  62   (* Appends source to destination. *)
  63
  64 PROCEDURE Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  65   (* Concatenates source2 onto source1 and copies the result into destination. *)
  66
  67 (* The following predicates provide for pre-testing of the operation-completion
  68    conditions for the procedures above.
  69 *)
  70
  71 PROCEDURE CanAssignAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  72   (* Returns TRUE if a number of characters, indicated by sourceLength, will fit into
  73      destination; otherwise returns FALSE.
  74   *)
  75
  76 PROCEDURE CanExtractAll (sourceLength, startIndex, numberToExtract: CARDINAL;
  77                          VAR destination: ARRAY OF CHAR): BOOLEAN;
  78   (* Returns TRUE if there are numberToExtract characters starting at startIndex and
  79      within the sourceLength of some string, and if the capacity of destination is
  80      sufficient to hold numberToExtract characters; otherwise returns FALSE.
  81   *)
  82
  83 PROCEDURE CanDeleteAll (stringLength, startIndex, numberToDelete: CARDINAL): BOOLEAN;
  84   (* Returns TRUE if there are numberToDelete characters starting at startIndex and
  85      within the stringLength of some string; otherwise returns FALSE.
  86   *)
  87
  88 PROCEDURE CanInsertAll (sourceLength, startIndex: CARDINAL;
  89                         VAR destination: ARRAY OF CHAR): BOOLEAN;
  90   (* Returns TRUE if there is room for the insertion of sourceLength characters from
  91      some string into destination starting at startIndex; otherwise returns FALSE.
  92   *)
  93
  94 PROCEDURE CanReplaceAll (sourceLength, startIndex: CARDINAL;
  95                          VAR destination: ARRAY OF CHAR): BOOLEAN;
  96   (* Returns TRUE if there is room for the replacement of sourceLength characters in
  97      destination starting at startIndex; otherwise returns FALSE.
  98   *)
  99
 100 PROCEDURE CanAppendAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
 101   (* Returns TRUE if there is sufficient room in destination to append a string of
 102      length sourceLength to the string in destination; otherwise returns FALSE.
 103   *)
 104
 105 PROCEDURE CanConcatAll (source1Length, source2Length: CARDINAL;
 106                         VAR destination: ARRAY OF CHAR): BOOLEAN;
 107   (* Returns TRUE if there is sufficient room in destination for a two strings of
 108      lengths source1Length and source2Length; otherwise returns FALSE.
 109   *)
 110
 111 (* The following type and procedures provide for the comparison of string values, and for the
 112    location of substrings within strings.
 113 *)
 114
 115 TYPE
 116   CompareResults = (less, equal, greater);
 117
 118 PROCEDURE Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults;
 119   (* Returns less, equal, or greater, according as stringVal1 is lexically less than,
 120      equal to, or greater than stringVal2.
 121   *)
 122
 123 PROCEDURE Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN;
 124   (* Returns Strings.Compare(stringVal1, stringVal2) = Strings.equal *)
 125
 126 PROCEDURE FindNext (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL;
 127                     VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
 128   (* Looks forward for next occurrence of pattern in stringToSearch, starting the search at
 129      position startIndex. If startIndex < LENGTH(stringToSearch) and pattern is found,
 130      patternFound is returned as TRUE, and posOfPattern contains the start position in
 131      stringToSearch of pattern. Otherwise patternFound is returned as FALSE, and posOfPattern
 132      is unchanged.
 133   *)
 134
 135 PROCEDURE FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL;
 136                     VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
 137   (* Looks backward for the previous occurrence of pattern in stringToSearch and returns the
 138      position of the first character of the pattern if found. The search for the pattern
 139      begins at startIndex. If pattern is found, patternFound is returned as TRUE, and
 140      posOfPattern contains the start position in stringToSearch of pattern in the range
 141      [0..startIndex]. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged.
 142   *)
 143
 144 PROCEDURE FindDiff (stringVal1, stringVal2: ARRAY OF CHAR;
 145                     VAR differenceFound: BOOLEAN; VAR posOfDifference: CARDINAL);
 146   (* Compares the string values in stringVal1 and stringVal2 for differences. If they
 147      are equal, differenceFound is returned as FALSE, and TRUE otherwise. If
 148      differenceFound is TRUE, posOfDifference is set to the position of the first
 149      difference; otherwise posOfDifference is unchanged.
 150   *)
 151
 152 PROCEDURE Capitalize (VAR stringVar: ARRAY OF CHAR);
 153   (* Applies the function CAP to each character of the string value in stringVar. *)
 154
 155
 156 END Strings.
 157