src/PCollection/PCollection_HAsciiString.cdl

   1 -- Created on: 1993-02-10
   2 -- Created by: Mireille MERCIEN
   3 -- Copyright (c) 1993-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 class HAsciiString from PCollection
  18
  19          inherits Persistent
  20
  21          ---Purpose: Describes a persistent ASCII character string of variable length.
  22
  23     uses   VArrayOfCharacter from DBC,
  24            HExtendedString from PCollection,
  25            AsciiString from TCollection
  26
  27     raises OutOfRange from Standard,
  28            NegativeValue from Standard,
  29            NumericError from Standard
  30 is
  31
  32
  33         Create(S : CString)
  34             returns HAsciiString from PCollection;
  35         ---Purpose: Creation and initialization with the string S.
  36
  37         Create(S : AsciiString from TCollection)
  38             returns HAsciiString from PCollection;
  39         ---Purpose: Creation and initialization with the string S from TCollection.
  40
  41         Create(C : Character from Standard)
  42             returns HAsciiString from PCollection;
  43         ---Purpose: Creation and initialization with the character C.
  44
  45         Create(S : HAsciiString from PCollection;
  46                FromIndex, ToIndex : Integer from Standard)
  47             returns HAsciiString from PCollection
  48             raises NegativeValue from Standard;
  49         ---Purpose: Creation of a sub-string of the string S.
  50         -- The sub-string starts at the index FromIndex and ends
  51         -- at the index ToIndex
  52         ---Trigger: Raises an exception if ToIndex is less than FromIndex .
  53         ---Example: before
  54         -- S = "abcdefg", FromIndex=3, ToIndex=6
  55         -- after
  56         -- S = "abcdefg"
  57         -- returns
  58         -- "cdef"
  59
  60         Create(S : HExtendedString from PCollection)
  61             returns HAsciiString from PCollection
  62             raises OutOfRange from Standard;
  63         ---Purpose: Creation by converting an extended string to a normal
  64         -- string. Raises OutOfRange if the String is not in the "Ascii range".
  65
  66         Create(R : Real from Standard ; F : CString = "%f")
  67             returns HAsciiString from PCollection;
  68         ---Purpose: Creation and initialization by converting the real
  69         -- value into a string.
  70         -- F describes a format using "C" conventions.
  71
  72         Create(I : Integer from Standard ; F : CString = "%d")
  73             returns HAsciiString from PCollection;
  74         ---Purpose: Creation and initialization by converting the Integer
  75         -- value into a string.
  76         -- F describes a format using "C" conventions.
  77
  78         Append(me : mutable; S : HAsciiString from PCollection);
  79         ---Level: Public
  80         ---Purpose: Pushing a string at the end of the string me
  81         ---Example:
  82         -- before
  83         --   me = "abcd" , S = "ef"
  84         -- after
  85         --   me = "abcdef" , S = "ef"
  86
  87         Capitalize(me : mutable);
  88         ---Level: Public
  89         ---Purpose: Converts the first character into its corresponding
  90         -- upper-case character and the other characters into lowercase
  91         ---Example: before
  92         --   me = "hellO "
  93         -- after
  94         --   me = "Hello "
  95
  96         Center(me : mutable;
  97                Width : Integer from Standard;
  98                Filler : Character from Standard)
  99         raises NegativeValue from Standard;
 100         ---Level: Public
 101         ---Purpose: center
 102         -- Length becomes equal to Width and the new characters are
 103         -- equal to Filler
 104         -- Raises an exception if Width is less than zero
 105         -- if Width < Length nothing happens
 106         ---Example: before
 107         -- me = "abcdef" , Width = 9 , Filler = ' '
 108         -- after
 109         -- me = "  abcdef "
 110
 111         ChangeAll(me : mutable;
 112                   C, NewC : Character from Standard;
 113                   CaseSensitive : Boolean from Standard);
 114         ---Level: Public
 115         ---Purpose: Substitutes all the characters equal to C by NewC in the
 116         -- string <me>.The substition can be case sensitive.
 117         ---Example: before
 118         -- me = "HetTo" , C = 't' , NewC = 'l' ,
 119         -- CaseSensitive = True
 120         -- after
 121         -- me = "HelTo"
 122
 123         Clear(me : mutable);
 124         ---Level: Public
 125         ---Purpose: Remove all characters in the string <me>.
 126         -- Length is equal to zero now.
 127
 128         Convert(me) returns AsciiString from TCollection;
 129         ---Level: Public
 130         ---Purpose: Converts a persistent HAsciiString to a non
 131         -- persistent AsciiString.
 132
 133         FirstLocationInSet(me; Set : HAsciiString from PCollection;
 134                                  FromIndex : Integer from Standard;
 135                                  ToIndex   : Integer from Standard)
 136                 returns Integer
 137                 raises OutOfRange from Standard;
 138         ---Level: Public
 139         ---Purpose: Returns the index of the first character of <Set> founded in <me>.
 140         -- The search begins to the index FromIndex and ends to the
 141         -- the index ToIndex.
 142         -- Returns zero if failure.
 143         -- Raises an exception if FromIndex or ToIndex is out of range.
 144         ---Example: before
 145         --   me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
 146         -- after
 147         --   me = "aabAcAa"
 148         -- returns
 149         --   4
 150
 151         FirstLocationNotInSet(me; Set : HAsciiString from PCollection;
 152                                      FromIndex : Integer;
 153                                      ToIndex   : Integer) returns Integer
 154                 raises OutOfRange from Standard;
 155         ---Level: Public
 156         ---Purpose: Returns the index of the first character of <me>
 157         -- that is not present in the set <Set>.
 158         -- The search begins to the index FromIndex and ends to the
 159         -- the index ToIndex in <me>.
 160         -- Returns zero if failure.
 161         -- Raises an exception if FromIndex or ToIndex is out of range.
 162         ---Example: before
 163         --  me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
 164         -- after
 165         --   me = "aabAcAa"
 166         -- returns
 167         --   3
 168
 169         InsertAfter(me : mutable; Index : Integer;
 170                     S : HAsciiString from PCollection)
 171         raises OutOfRange from Standard;
 172         ---Level: Public
 173         ---Purpose: Pushing a string after a specific index in the string <me>.
 174         -- Raises an exception if Index is out of bounds.
 175         ---Example: before
 176         -- me = "cde" , Index = 0 , S = "ab"
 177         -- after
 178         -- me = "abcde" , S = "ab"
 179
 180         InsertBefore(me : mutable; Index : Integer;
 181                      S : HAsciiString from PCollection)
 182         raises OutOfRange from Standard;
 183         ---Level: Public
 184         ---Purpose: Pushing a string before a specific index in the string <me>
 185         -- Raises an exception if Index is out of bounds
 186         ---Example: before
 187         -- me = "cde" , Index = 1 , S = "ab"
 188         -- after
 189         -- me = "abcde" , S = "ab"
 190
 191         IntegerValue(me) returns Integer
 192         raises NumericError from Standard;
 193         ---Level: Public
 194         ---Purpose: Returns the integer value corresponding to the string <me>
 195         -- Raises an exception if the string does not correspond to
 196         -- an integer value.
 197         ---Example: me = "   10       " -> 10
 198
 199         IsDifferent (me ; other : HAsciiString) returns Boolean;
 200         ---Level: Public
 201         ---Purpose: Test if characters are different
 202         -- between <me> and <other>.
 203
 204         IsEmpty(me) returns Boolean from Standard;
 205         ---Level: Public
 206         ---Purpose:  Returns True if the string <me> contains zero character
 207
 208         IsGreater (me ; other : HAsciiString) returns Boolean;
 209         ---Level: Public
 210         ---Purpose: Returns TRUE if <me> is 'ASCII' greater than <other>.
 211
 212         IsIntegerValue(me) returns Boolean from Standard;
 213         ---Level: Public
 214         ---Purpose: Returns True if the string contains an integer value.
 215         ---Example: me = "3.14 " -> False
 216         -- me = "123"   -> True
 217
 218         IsLess (me ; other : HAsciiString) returns Boolean;
 219         ---Level: Public
 220         ---Purpose: Returns TRUE if <me> is 'ASCII' less than <other>.
 221
 222         IsRealValue(me) returns Boolean from Standard;
 223         ---Level: Public
 224         ---Purpose: Returns True if the string contains an Real value.
 225         ---Example: me = "3.14 " -> True
 226         -- me = "123"   -> True
 227         -- me = "3.14a" -> False
 228
 229         IsSameString(me ; S : HAsciiString from PCollection)
 230         ---Level: Public
 231         ---Purpose: Returns True if two strings are equal.
 232         -- The comparison is case sensitive.
 233         returns Boolean from Standard;
 234
 235         IsSameString(me; S : HAsciiString from PCollection;
 236                      CaseSensitive : Boolean from Standard)
 237         returns Boolean from Standard;
 238         ---Level: Public
 239         ---Purpose: Returns True if two strings are equal.
 240         -- The comparison is case sensitive if the flag is set.
 241
 242         LeftAdjust(me : mutable);
 243         ---Level: Public
 244         ---Purpose: Removes all space characters in the begining of the
 245         -- string.
 246
 247         LeftJustify(me : mutable; Width : Integer;
 248                     Filler : Character from Standard)
 249         raises NegativeValue from Standard;
 250         ---Level: Public
 251         ---Purpose: Left justify.
 252         -- Length becomes equal to Width and the new characters are
 253         -- equal to Filler.
 254         -- If Width < Length nothing happens.
 255         -- Raises an exception if Width is less than zero.
 256         ---Example: before
 257         --   me = "abcdef" , Width = 9 , Filler = ' '
 258         -- after
 259         --   me = "abcdef   "
 260
 261         Length(me) returns Integer;
 262         ---Level: Public
 263         ---Purpose: Number of characters of the String.
 264
 265         Location(me; N : Integer; C : Character from Standard;
 266                     FromIndex : Integer;
 267                     ToIndex   : Integer)
 268         returns Integer
 269         raises OutOfRange from Standard;
 270         ---Level: Public
 271         ---Purpose: Returns the index of the nth occurence of the character C
 272         -- in the string <me> from the starting index FromIndex to the
 273         -- ending index ToIndex.
 274         -- Returns zero if failure.
 275         -- Raises an exception if FromIndex or ToIndex is out of range.
 276         ---Example: before
 277         --   me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
 278         -- after
 279         --   me = "aabAa"
 280         -- returns
 281         --   5
 282
 283         Location(me; S : HAsciiString from PCollection;
 284                     FromIndex : Integer;
 285                     ToIndex   : Integer)
 286         returns Integer
 287         raises OutOfRange from Standard;
 288         ---Level: Public
 289         ---Purpose: Returns an index in the string <me> of the first occurence
 290         -- of the string S in the string <me> from the starting index
 291         -- FromIndex to the ending index ToIndex
 292         -- returns zero if failure
 293         -- Raises an exception if FromIndex or ToIndex is out of range.
 294         ---Example: before
 295         --   me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
 296         -- after
 297         --   me = "aabAaAa"
 298         -- returns
 299         --   4
 300
 301         Lowercase(me : mutable);
 302         ---Level: Public
 303         ---Purpose: Converts any upper-case character to its corresponding
 304         -- lower-case character in the string <me>. If there is no
 305         -- corresponding lower-case character, the character is
 306         -- unchanged
 307         -- before
 308         -- me = "aBAcd123"
 309         -- after
 310         -- me = "abacd123"
 311
 312         Prepend(me : mutable; S : HAsciiString from PCollection);
 313         ---Level: Public
 314         ---Purpose: Pushing a string at the begining of the string <me>
 315         -- before
 316         --  me = "cde" , S = "ab"
 317         -- after
 318         --  me = "abcde" , S = "ab"
 319
 320         Print(me ; S : in out OStream);
 321         ---Level: Public
 322         ---Purpose: Prints the content of <me> on the stream S.
 323
 324         RealValue(me) returns Real from Standard
 325         raises NumericError from Standard;
 326         ---Level: Public
 327         ---Purpose: Returns the real value corresponding to the string <me>.
 328         -- Raises an exception if the string does not correspond to a real value.
 329         ---Example: me = "   10       " returns 10.0
 330
 331         Remove(me : mutable; Index : Integer)
 332         ---Level: Public
 333         ---Purpose: Removes the character located at the index Index in the string.
 334         -- Raises an exception if Index is out of bounds.
 335         raises OutOfRange from Standard;
 336
 337         Remove(me : mutable; FromIndex, ToIndex : Integer)
 338         ---Level: Public
 339         ---Purpose: Removes all the characters from the index FromIndex to the
 340         -- index ToIndex.
 341         -- Raises an exception if FromIndex or ToIndex is out of bounds.
 342         raises OutOfRange from Standard;
 343
 344         RemoveAll(me : mutable; C : Character from Standard;
 345                   CaseSensitive : Boolean from Standard);
 346         ---Level: Public
 347         ---Purpose: Removes all the occurences of the character C in the string
 348         ---Example: before
 349         --  me = "HellLLo", C = 'L' , CaseSensitive = True
 350         -- after
 351         --  me = "Hello"
 352
 353         RightAdjust(me : mutable);
 354         ---Level: Public
 355         ---Purpose: Removes all space characters at the end of the string.
 356
 357         RightJustify(me : mutable;
 358                      Width : Integer;
 359                      Filler : Character from Standard)
 360         raises NegativeValue from Standard;
 361         ---Level: Public
 362         ---Purpose: Right justify.
 363         -- Length becomes equal to Width and the new characters are
 364         -- equal to Filler.
 365         -- If Width < Length nothing happens.
 366         -- Raises an exception if Width is less than zero.
 367         ---Example: before
 368         --  me = "abcdef" , Width = 9 , Filler = ' '
 369         -- after
 370         --  me = "   abcdef"
 371
 372         SetValue(me : mutable; Index : Integer; C : Character from Standard)
 373         raises OutOfRange from Standard;
 374         ---Level: Public
 375         ---Purpose: Substitutes the character located to the position Index
 376         -- by the character C.
 377         -- Raises an exception if the Index is out of bounds.
 378         ---Example: before
 379         --  me = "Helll" , Index = 5 , C = 'o'
 380         -- after
 381         --  me = "Hello"
 382
 383         SetValue(me : mutable; Index : Integer;
 384                  S : HAsciiString from PCollection)
 385         raises OutOfRange from Standard;
 386         ---Level: Public
 387         ---Purpose: Substitutes from the index Index to the end by the string S.
 388         -- Raises an exception if Index is out of bounds.
 389         ---Example: before
 390         --  me = "abcde" , Index = 3 , S = "wxyz"
 391         --  after
 392         -- me = "abwxyz" , S = "wxyz"
 393
 394         Split(me : mutable; Index  : Integer)
 395         ---Level: Public
 396         ---Purpose: Splits a string of characters into two sub-strings.
 397         returns HAsciiString from PCollection
 398         raises OutOfRange from Standard;
 399
 400         SubString(me; FromIndex, ToIndex : Integer)
 401         ---Level: Public
 402         ---Purpose: Creation of a sub-string of the string <me>.
 403         -- The sub-string starts to the index Fromindex and ends
 404         -- to the index ToIndex.
 405         -- Raises an exception if ToIndex or FromIndex is out of bounds.
 406         ---Example: before
 407         --   me = "abcdefg", ToIndex=3, FromIndex=6
 408         -- after
 409         --   me = "abcdefg"
 410         -- returns
 411         --   "cdef"
 412         returns HAsciiString from PCollection
 413         raises OutOfRange from Standard;
 414
 415         Token (me ; separators : CString=" \t" ; whichone : Integer=1)
 416                  returns HAsciiString from PCollection;
 417         ---Level: Public
 418         ---Purpose: Extracts <aString> token from <me>.
 419         -- The token extracted is the indice number <num>.
 420
 421         Uppercase(me : mutable);
 422         ---Level: Public
 423         ---Purpose: Transforms all the characters into upper-case.
 424         -- If there is no corresponding upper-case character, the
 425         -- character is unchanged.
 426         ---Example: before
 427         --  me = "aBAcd"
 428         -- after
 429         --  me = "ABACD"
 430
 431         UsefullLength(me) returns Integer;
 432         ---Level: Public
 433         ---Purpose: Length of the string ignoring all spaces (' ') and the
 434         -- control character at the end.
 435
 436         Value(me ; Index : Integer) returns Character from Standard
 437         raises OutOfRange from Standard;
 438         ---Level: Public
 439         ---Purpose: Returns the character of index Index of the string
 440         ---Example: me = "abcd", Index = 2, Value returns 'b'.
 441
 442         Assign(me : mutable ;TheData : VArrayOfCharacter) is private;
 443                 ---Level: Internal
 444                 ---Purpose : Assigns the field of the current structure with
 445                 -- the given value.Private method.
 446
 447
 448 fields
 449    Data : VArrayOfCharacter from DBC;
 450 end HAsciiString;
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472