gcc/m2/gm2-libs/DynamicStrings.def

   1 (* DynamicStrings.def provides a dynamic string type and procedures.
   2
   3 Copyright (C) 2001-2023 Free Software Foundation, Inc.
   4 Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.
   5
   6 This file is part of GNU Modula-2.
   7
   8 GNU Modula-2 is free software; you can redistribute it and/or modify
   9 it under the terms of the GNU General Public License as published by
  10 the Free Software Foundation; either version 3, or (at your option)
  11 any later version.
  12
  13 GNU Modula-2 is distributed in the hope that it will be useful, but
  14 WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 General Public License for more details.
  17
  18 Under Section 7 of GPL version 3, you are granted additional
  19 permissions described in the GCC Runtime Library Exception, version
  20 3.1, as published by the Free Software Foundation.
  21
  22 You should have received a copy of the GNU General Public License and
  23 a copy of the GCC Runtime Library Exception along with this program;
  24 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  25 <http://www.gnu.org/licenses/>.  *)
  26
  27 DEFINITION MODULE DynamicStrings ;
  28
  29 FROM SYSTEM IMPORT ADDRESS ;
  30 EXPORT QUALIFIED String,
  31                  InitString, KillString, Fin, InitStringCharStar,
  32                  InitStringChar, Index, RIndex,
  33                  Mark, Length, ConCat, ConCatChar, Assign, Dup, Add,
  34                  Equal, EqualCharStar, EqualArray, ToUpper, ToLower,
  35                  CopyOut, Mult, Slice, ReplaceChar,
  36                  RemoveWhitePrefix, RemoveWhitePostfix, RemoveComment,
  37                  char, string,
  38                  InitStringDB, InitStringCharStarDB, InitStringCharDB,
  39                  MultDB, DupDB, SliceDB,
  40                  PushAllocation, PopAllocation, PopAllocationExemption ;
  41
  42 TYPE
  43    String ;
  44
  45
  46 (*
  47    InitString - creates and returns a String type object.
  48                 Initial contents are, a.
  49 *)
  50
  51 PROCEDURE InitString (a: ARRAY OF CHAR) : String ;
  52
  53
  54 (*
  55    KillString - frees String, s, and its contents.
  56                 NIL is returned.
  57 *)
  58
  59 PROCEDURE KillString (s: String) : String ;
  60
  61
  62 (*
  63    Fin - finishes with a string, it calls KillString with, s.
  64          The purpose of the procedure is to provide a short cut
  65          to calling KillString and then testing the return result.
  66 *)
  67
  68 PROCEDURE Fin (s: String) ;
  69
  70
  71 (*
  72    InitStringCharStar - initializes and returns a String to contain
  73                         the C string.
  74 *)
  75
  76 PROCEDURE InitStringCharStar (a: ADDRESS) : String ;
  77
  78
  79 (*
  80    InitStringChar - initializes and returns a String to contain the
  81                     single character, ch.
  82 *)
  83
  84 PROCEDURE InitStringChar (ch: CHAR) : String ;
  85
  86
  87 (*
  88    Mark - marks String, s, ready for garbage collection.
  89 *)
  90
  91 PROCEDURE Mark (s: String) : String ;
  92
  93
  94 (*
  95    Length - returns the length of the String, s.
  96 *)
  97
  98 PROCEDURE Length (s: String) : CARDINAL ;
  99
 100
 101 (*
 102    ConCat - returns String, a, after the contents of, b,
 103             have been appended.
 104 *)
 105
 106 PROCEDURE ConCat (a, b: String) : String ;
 107
 108
 109 (*
 110    ConCatChar - returns String, a, after character, ch,
 111                 has been appended.
 112 *)
 113
 114 PROCEDURE ConCatChar (a: String; ch: CHAR) : String ;
 115
 116
 117 (*
 118    Assign - assigns the contents of, b, into, a.
 119             String, a, is returned.
 120 *)
 121
 122 PROCEDURE Assign (a, b: String) : String ;
 123
 124
 125 (*
 126    ReplaceChar - returns string s after it has changed all
 127                  occurances of from to to.
 128 *)
 129
 130 PROCEDURE ReplaceChar (s: String; from, to: CHAR) : String ;
 131
 132
 133 (*
 134    Dup - duplicate a String, s, returning the copy of s.
 135 *)
 136
 137 PROCEDURE Dup (s: String) : String ;
 138
 139
 140 (*
 141    Add - returns a new String which contains the contents of a and b.
 142 *)
 143
 144 PROCEDURE Add (a, b: String) : String ;
 145
 146
 147 (*
 148    Equal - returns TRUE if String, a, and, b, are equal.
 149 *)
 150
 151 PROCEDURE Equal (a, b: String) : BOOLEAN ;
 152
 153
 154 (*
 155    EqualCharStar - returns TRUE if contents of String, s, is
 156                    the same as the string, a.
 157 *)
 158
 159 PROCEDURE EqualCharStar (s: String; a: ADDRESS) : BOOLEAN ;
 160
 161
 162 (*
 163    EqualArray - returns TRUE if contents of String, s, is the
 164                 same as the string, a.
 165 *)
 166
 167 PROCEDURE EqualArray (s: String; a: ARRAY OF CHAR) : BOOLEAN ;
 168
 169
 170 (*
 171    Mult - returns a new string which is n concatenations of String, s.
 172           If n<=0 then an empty string is returned.
 173 *)
 174
 175 PROCEDURE Mult (s: String; n: CARDINAL) : String ;
 176
 177
 178 (*
 179    Slice - returns a new string which contains the elements
 180            low..high-1
 181
 182            strings start at element 0
 183            Slice(s, 0, 2)  will return elements 0, 1 but not 2
 184            Slice(s, 1, 3)  will return elements 1, 2 but not 3
 185            Slice(s, 2, 0)  will return elements 2..max
 186            Slice(s, 3, -1) will return elements 3..max-1
 187            Slice(s, 4, -2) will return elements 4..max-2
 188 *)
 189
 190 PROCEDURE Slice (s: String; low, high: INTEGER) : String ;
 191
 192
 193 (*
 194    Index - returns the indice of the first occurance of, ch, in
 195            String, s. -1 is returned if, ch, does not exist.
 196            The search starts at position, o.
 197 *)
 198
 199 PROCEDURE Index (s: String; ch: CHAR; o: CARDINAL) : INTEGER ;
 200
 201
 202 (*
 203    RIndex - returns the indice of the last occurance of, ch,
 204             in String, s. The search starts at position, o.
 205             -1 is returned if, ch, is not found.
 206 *)
 207
 208 PROCEDURE RIndex (s: String; ch: CHAR; o: CARDINAL) : INTEGER ;
 209
 210
 211 (*
 212    RemoveComment - assuming that, comment, is a comment delimiter
 213                    which indicates anything to its right is a comment
 214                    then strip off the comment and also any white space
 215                    on the remaining right hand side.
 216                    It leaves any white space on the left hand side
 217                    alone.
 218 *)
 219
 220 PROCEDURE RemoveComment (s: String; comment: CHAR) : String ;
 221
 222
 223 (*
 224    RemoveWhitePrefix - removes any leading white space from String, s.
 225                        A new string is returned.
 226 *)
 227
 228 PROCEDURE RemoveWhitePrefix (s: String) : String ;
 229
 230
 231 (*
 232    RemoveWhitePostfix - removes any leading white space from String, s.
 233                         A new string is returned.
 234 *)
 235
 236 PROCEDURE RemoveWhitePostfix (s: String) : String ;
 237
 238
 239 (*
 240    ToUpper - returns string, s, after it has had its lower case
 241              characters replaced by upper case characters.
 242              The string, s, is not duplicated.
 243 *)
 244
 245 PROCEDURE ToUpper (s: String) : String ;
 246
 247
 248 (*
 249    ToLower - returns string, s, after it has had its upper case
 250              characters replaced by lower case characters.
 251              The string, s, is not duplicated.
 252 *)
 253
 254 PROCEDURE ToLower (s: String) : String ;
 255
 256
 257 (*
 258    CopyOut - copies string, s, to a.
 259 *)
 260
 261 PROCEDURE CopyOut (VAR a: ARRAY OF CHAR; s: String) ;
 262
 263
 264 (*
 265    char - returns the character, ch, at position, i, in String, s.
 266           As Slice the index can be negative so:
 267
 268           char(s, 0) will return the first character
 269           char(s, 1) will return the second character
 270           char(s, -1) will return the last character
 271           char(s, -2) will return the penultimate character
 272
 273           a nul character is returned if the index is out of range.
 274 *)
 275
 276 PROCEDURE char (s: String; i: INTEGER) : CHAR ;
 277
 278
 279 (*
 280    string - returns the C style char * of String, s.
 281 *)
 282
 283 PROCEDURE string (s: String) : ADDRESS ;
 284
 285
 286 (*
 287    to easily debug an application using this library one could use
 288    use the following macro processing defines:
 289
 290    #define InitString(X) InitStringDB(X, __FILE__, __LINE__)
 291    #define InitStringCharStar(X) InitStringCharStarDB(X, \
 292      __FILE__, __LINE__)
 293    #define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__)
 294    #define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__)
 295    #define Dup(X) DupDB(X, __FILE__, __LINE__)
 296    #define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__)
 297
 298    and then invoke gm2 with the -fcpp flag.
 299 *)
 300
 301
 302 (*
 303    InitStringDB - the debug version of InitString.
 304 *)
 305
 306 PROCEDURE InitStringDB (a: ARRAY OF CHAR;
 307                         file: ARRAY OF CHAR; line: CARDINAL) : String ;
 308
 309
 310 (*
 311    InitStringCharStarDB - the debug version of InitStringCharStar.
 312 *)
 313
 314 PROCEDURE InitStringCharStarDB (a: ADDRESS;
 315                                 file: ARRAY OF CHAR;
 316                                 line: CARDINAL) : String ;
 317
 318
 319 (*
 320    InitStringCharDB - the debug version of InitStringChar.
 321 *)
 322
 323 PROCEDURE InitStringCharDB (ch: CHAR;
 324                             file: ARRAY OF CHAR;
 325                             line: CARDINAL) : String ;
 326
 327
 328 (*
 329    MultDB - the debug version of MultDB.
 330 *)
 331
 332 PROCEDURE MultDB (s: String; n: CARDINAL;
 333                   file: ARRAY OF CHAR; line: CARDINAL) : String ;
 334
 335
 336 (*
 337    DupDB - the debug version of Dup.
 338 *)
 339
 340 PROCEDURE DupDB (s: String;
 341                  file: ARRAY OF CHAR; line: CARDINAL) : String ;
 342
 343
 344 (*
 345    SliceDB - debug version of Slice.
 346 *)
 347
 348 PROCEDURE SliceDB (s: String; low, high: INTEGER;
 349                    file: ARRAY OF CHAR; line: CARDINAL) : String ;
 350
 351 (*
 352    PushAllocation - pushes the current allocation/deallocation lists.
 353 *)
 354
 355 PROCEDURE PushAllocation ;
 356
 357
 358 (*
 359    PopAllocation - test to see that all strings are deallocated since
 360                    the last push.  Then it pops to the previous
 361                    allocation/deallocation lists.
 362
 363                    If halt is true then the application terminates
 364                    with an exit code of 1.
 365 *)
 366
 367 PROCEDURE PopAllocation (halt: BOOLEAN) ;
 368
 369
 370 (*
 371    PopAllocationExemption - test to see that all strings are
 372                             deallocated, except string e since
 373                             the last push.
 374                             Post-condition: it pops to the previous
 375                             allocation/deallocation lists.
 376
 377                             If halt is true then the application
 378                             terminates with an exit code of 1.
 379
 380                             The string, e, is returned unmodified,
 381 *)
 382
 383 PROCEDURE PopAllocationExemption (halt: BOOLEAN; e: String) : String ;
 384
 385
 386 END DynamicStrings.