gcc/m2/gm2-libs/StringConvert.def

   1 (* StringConvert.def provides functions to convert numbers to and from strings.
   2
   3 Copyright (C) 2001-2024 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 StringConvert ;
  28
  29 FROM DynamicStrings IMPORT String ;
  30 EXPORT QUALIFIED IntegerToString, StringToInteger,
  31                  StringToLongInteger, LongIntegerToString,
  32                  StringToCardinal, CardinalToString,
  33                  StringToLongCardinal, LongCardinalToString,
  34                  StringToShortCardinal, ShortCardinalToString,
  35                  StringToLongreal, LongrealToString,
  36                  ToSigFig,
  37                  stoi, itos, ctos, stoc, hstoi, ostoi, bstoi,
  38                  hstoc, ostoc, bstoc,
  39                  stor, stolr ;
  40
  41
  42 (*
  43    IntegerToString - converts INTEGER, i, into a String. The field with
  44                      can be specified if non zero. Leading characters
  45                      are defined by padding and this function will
  46                      prepend a + if sign is set to TRUE.
  47                      The base allows the caller to generate binary,
  48                      octal, decimal, hexidecimal numbers.
  49                      The value of lower is only used when hexidecimal
  50                      numbers are generated and if TRUE then digits
  51                      abcdef are used, and if FALSE then ABCDEF are used.
  52 *)
  53
  54 PROCEDURE IntegerToString (i: INTEGER; width: CARDINAL; padding: CHAR; sign: BOOLEAN;
  55                            base: CARDINAL; lower: BOOLEAN) : String ;
  56
  57
  58 (*
  59    CardinalToString - converts CARDINAL, c, into a String. The field
  60                       width can be specified if non zero. Leading
  61                       characters are defined by padding.
  62                       The base allows the caller to generate binary,
  63                       octal, decimal, hexidecimal numbers.
  64                       The value of lower is only used when hexidecimal
  65                       numbers are generated and if TRUE then digits
  66                       abcdef are used, and if FALSE then ABCDEF are used.
  67 *)
  68
  69 PROCEDURE CardinalToString (c: CARDINAL; width: CARDINAL; padding: CHAR;
  70                             base: CARDINAL; lower: BOOLEAN) : String ;
  71
  72
  73 (*
  74    StringToInteger - converts a string, s, of, base, into an INTEGER.
  75                      Leading white space is ignored. It stops converting
  76                      when either the string is exhausted or if an illegal
  77                      numeral is found.
  78                      The parameter found is set TRUE if a number was found.
  79 *)
  80
  81 PROCEDURE StringToInteger (s: String; base: CARDINAL; VAR found: BOOLEAN) : INTEGER ;
  82
  83
  84 (*
  85    StringToCardinal - converts a string, s, of, base, into a CARDINAL.
  86                       Leading white space is ignored. It stops converting
  87                       when either the string is exhausted or if an illegal
  88                       numeral is found.
  89                       The parameter found is set TRUE if a number was found.
  90 *)
  91
  92 PROCEDURE StringToCardinal (s: String; base: CARDINAL; VAR found: BOOLEAN) : CARDINAL ;
  93
  94
  95 (*
  96    LongIntegerToString - converts LONGINT, i, into a String. The field with
  97                          can be specified if non zero. Leading characters
  98                          are defined by padding and this function will
  99                          prepend a + if sign is set to TRUE.
 100                          The base allows the caller to generate binary,
 101                          octal, decimal, hexidecimal numbers.
 102                          The value of lower is only used when hexidecimal
 103                          numbers are generated and if TRUE then digits
 104                          abcdef are used, and if FALSE then ABCDEF are used.
 105 *)
 106
 107 PROCEDURE LongIntegerToString (i: LONGINT; width: CARDINAL; padding: CHAR;
 108                                sign: BOOLEAN; base: CARDINAL; lower: BOOLEAN) : String ;
 109
 110
 111
 112 (*
 113    StringToLongInteger - converts a string, s, of, base, into an LONGINT.
 114                          Leading white space is ignored. It stops converting
 115                          when either the string is exhausted or if an illegal
 116                          numeral is found.
 117                          The parameter found is set TRUE if a number was found.
 118 *)
 119
 120 PROCEDURE StringToLongInteger (s: String; base: CARDINAL; VAR found: BOOLEAN) : LONGINT ;
 121
 122
 123 (*
 124    LongCardinalToString - converts LONGCARD, c, into a String. The field
 125                           width can be specified if non zero. Leading
 126                           characters are defined by padding.
 127                           The base allows the caller to generate binary,
 128                           octal, decimal, hexidecimal numbers.
 129                           The value of lower is only used when hexidecimal
 130                           numbers are generated and if TRUE then digits
 131                           abcdef are used, and if FALSE then ABCDEF are used.
 132 *)
 133
 134 PROCEDURE LongCardinalToString (c: LONGCARD; width: CARDINAL; padding: CHAR;
 135                                 base: CARDINAL; lower: BOOLEAN) : String ;
 136
 137
 138 (*
 139    StringToLongCardinal - converts a string, s, of, base, into a LONGCARD.
 140                           Leading white space is ignored. It stops converting
 141                           when either the string is exhausted or if an illegal
 142                           numeral is found.
 143                           The parameter found is set TRUE if a number was found.
 144 *)
 145
 146 PROCEDURE StringToLongCardinal (s: String; base: CARDINAL; VAR found: BOOLEAN) : LONGCARD ;
 147
 148
 149 (*
 150    ShortCardinalToString - converts SHORTCARD, c, into a String. The field
 151                            width can be specified if non zero. Leading
 152                            characters are defined by padding.
 153                            The base allows the caller to generate binary,
 154                            octal, decimal, hexidecimal numbers.
 155                            The value of lower is only used when hexidecimal
 156                            numbers are generated and if TRUE then digits
 157                            abcdef are used, and if FALSE then ABCDEF are used.
 158 *)
 159
 160 PROCEDURE ShortCardinalToString (c: SHORTCARD; width: CARDINAL; padding: CHAR;
 161                                  base: CARDINAL; lower: BOOLEAN) : String ;
 162
 163
 164 (*
 165    StringToShortCardinal - converts a string, s, of, base, into a SHORTCARD.
 166                            Leading white space is ignored. It stops converting
 167                            when either the string is exhausted or if an illegal
 168                            numeral is found.
 169                            The parameter found is set TRUE if a number was found.
 170 *)
 171
 172 PROCEDURE StringToShortCardinal (s: String; base: CARDINAL;
 173                                  VAR found: BOOLEAN) : SHORTCARD ;
 174
 175
 176 (*
 177    stoi - decimal string to INTEGER
 178 *)
 179
 180 PROCEDURE stoi (s: String) : INTEGER ;
 181
 182
 183 (*
 184    itos - integer to decimal string.
 185 *)
 186
 187 PROCEDURE itos (i: INTEGER; width: CARDINAL; padding: CHAR; sign: BOOLEAN) : String ;
 188
 189
 190 (*
 191    ctos - cardinal to decimal string.
 192 *)
 193
 194 PROCEDURE ctos (c: CARDINAL; width: CARDINAL; padding: CHAR) : String ;
 195
 196
 197 (*
 198    stoc - decimal string to CARDINAL
 199 *)
 200
 201 PROCEDURE stoc (s: String) : CARDINAL ;
 202
 203
 204 (*
 205    hstoi - hexidecimal string to INTEGER
 206 *)
 207
 208 PROCEDURE hstoi (s: String) : INTEGER ;
 209
 210
 211 (*
 212    ostoi - octal string to INTEGER
 213 *)
 214
 215 PROCEDURE ostoi (s: String) : INTEGER ;
 216
 217
 218 (*
 219    bstoi - binary string to INTEGER
 220 *)
 221
 222 PROCEDURE bstoi (s: String) : INTEGER ;
 223
 224
 225 (*
 226    hstoc - hexidecimal string to CARDINAL
 227 *)
 228
 229 PROCEDURE hstoc (s: String) : CARDINAL ;
 230
 231
 232 (*
 233    ostoc - octal string to CARDINAL
 234 *)
 235
 236 PROCEDURE ostoc (s: String) : CARDINAL ;
 237
 238
 239 (*
 240    bstoc - binary string to CARDINAL
 241 *)
 242
 243 PROCEDURE bstoc (s: String) : CARDINAL ;
 244
 245
 246 (*
 247    StringToLongreal - returns a LONGREAL and sets found to TRUE
 248                       if a legal number is seen.
 249 *)
 250
 251 PROCEDURE StringToLongreal (s: String; VAR found: BOOLEAN) : LONGREAL ;
 252
 253
 254 (*
 255    LongrealToString - converts a LONGREAL number, Real, which has,
 256                       TotalWidth, and FractionWidth into a string.
 257
 258                       So for example:
 259
 260                       LongrealToString(1.0, 4, 2)  -> '1.00'
 261                       LongrealToString(12.3, 5, 2) -> '12.30'
 262                       LongrealToString(12.3, 6, 2) -> ' 12.30'
 263                       LongrealToString(12.3, 6, 3) -> '12.300'
 264
 265                       if total width is too small then the fraction
 266                       becomes truncated.
 267
 268                       LongrealToString(12.3, 5, 3) -> '12.30'
 269
 270                       If TotalWidth is 0 then the function
 271                       will return the value of x which is converted
 272                       into as a fixed point number with exhaustive
 273                       precision.
 274 *)
 275
 276 PROCEDURE LongrealToString (x: LONGREAL;
 277                             TotalWidth, FractionWidth: CARDINAL) : String ;
 278
 279
 280 (*
 281    stor - returns a REAL given a string.
 282 *)
 283
 284 PROCEDURE stor (s: String) : REAL ;
 285
 286
 287 (*
 288    stolr - returns a LONGREAL given a string.
 289 *)
 290
 291 PROCEDURE stolr (s: String) : LONGREAL ;
 292
 293
 294 (*
 295    ToSigFig - returns a floating point or base 10 integer
 296               string which is accurate to, n, significant
 297               figures.  It will return a new String
 298               and, s, will be destroyed.
 299
 300
 301               So:  12.345
 302
 303               rounded to the following significant figures yields
 304
 305               5      12.345
 306               4      12.34
 307               3      12.3
 308               2      12
 309               1      10
 310 *)
 311
 312 PROCEDURE ToSigFig (s: String; n: CARDINAL) : String ;
 313
 314
 315 (*
 316    ToDecimalPlaces - returns a floating point or base 10 integer
 317                      string which is accurate to, n, decimal
 318                      places.  It will return a new String
 319                      and, s, will be destroyed.
 320                      Decimal places yields, n, digits after
 321                      the .
 322
 323                      So:  12.345
 324
 325                      rounded to the following decimal places yields
 326
 327                      5      12.34500
 328                      4      12.3450
 329                      3      12.345
 330                      2      12.34
 331                      1      12.3
 332 *)
 333
 334 PROCEDURE ToDecimalPlaces (s: String; n: CARDINAL) : String ;
 335
 336
 337 END StringConvert.