src/TCollection/TCollection_AsciiString.cdl

   1 -- Created on: 1993-02-22
   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 AsciiString from TCollection
  18         ---Purpose: A variable-length sequence of ASCII characters
  19         -- (normal 8-bit character type). It provides editing
  20         -- operations with built-in memory management to
  21         -- make AsciiString objects easier to use than
  22         -- ordinary character arrays.
  23         -- AsciiString objects follow value semantics; in
  24         -- other words, they are the actual strings, not
  25         -- handles to strings, and are copied through
  26         -- assignment. You may use HAsciiString objects
  27         -- to get handles to strings.
  28
  29 uses   ExtendedString from TCollection
  30
  31 raises
  32     NullObject,
  33     OutOfRange,
  34     NumericError,
  35     NegativeValue
  36
  37 is
  38     Create returns AsciiString from TCollection;
  39     ---Purpose: Initializes a AsciiString to an empty AsciiString.
  40
  41     Create ( message : CString ) returns AsciiString from TCollection
  42     ---Purpose: Initializes a AsciiString with a CString.
  43     raises NullObject;
  44
  45     Create ( message : CString ; aLen : Integer )
  46          returns AsciiString from TCollection
  47     ---Purpose: Initializes a AsciiString with a CString.
  48     raises NullObject;
  49
  50     Create ( aChar : Character) returns AsciiString from TCollection;
  51     ---Purpose: Initializes a AsciiString with a single character.
  52
  53     Create ( length : Integer; filler : Character)
  54               returns AsciiString from TCollection;
  55     ---Purpose: Initializes an AsciiString with <length> space allocated.
  56     -- and filled with <filler>. This is usefull for buffers.
  57
  58     Create ( value : Integer ) returns AsciiString from TCollection
  59     ---Purpose: Initializes an AsciiString with an integer value
  60     raises NullObject;
  61
  62     Create ( value : Real ) returns AsciiString from TCollection
  63     ---Purpose: Initializes an AsciiString with a real value
  64     raises NullObject;
  65
  66     Create ( astring : AsciiString from TCollection )
  67             returns AsciiString from TCollection;
  68     ---Purpose: Initializes a AsciiString with another AsciiString.
  69
  70     Create ( astring : AsciiString from TCollection ; message : Character )
  71             returns AsciiString from TCollection;
  72     ---Purpose: Initializes a AsciiString with copy of another AsciiString
  73     --          concatenated with the message character.
  74
  75     Create ( astring : AsciiString from TCollection ; message : CString )
  76             returns AsciiString from TCollection;
  77     ---Purpose: Initializes a AsciiString with copy of another AsciiString
  78     --          concatenated with the message string.
  79
  80     Create ( astring : AsciiString from TCollection ; message : AsciiString )
  81             returns AsciiString from TCollection;
  82     ---Purpose: Initializes a AsciiString with copy of another AsciiString
  83     --          concatenated with the message string.
  84
  85     Create(astring : ExtendedString from TCollection;
  86            replaceNonAscii: Character from Standard = 0)
  87     ---Purpose: Creation by converting an extended string to an ascii string.
  88     --          If replaceNonAscii is non-null charecter, it will be used
  89     --          in place of any non-ascii character found in the source string.
  90     --          Otherwise, creates UTF-8 unicode string.
  91     returns AsciiString from TCollection
  92     raises OutOfRange from Standard;
  93
  94    AssignCat (me : out ; other : Character )
  95    ---Level: Public
  96    ---Purpose: Appends <other>  to me. This is an unary operator.
  97    ---C++: alias operator +=
  98    raises NullObject from Standard
  99    is static;
 100
 101    AssignCat (me : out ; other : Integer from Standard )
 102    ---Level: Public
 103    ---Purpose: Appends <other>  to me. This is an unary operator.
 104    ---C++: alias operator +=
 105    raises NullObject from Standard
 106    is static;
 107
 108    AssignCat (me : out ; other : Real from Standard )
 109    ---Level: Public
 110    ---Purpose: Appends <other>  to me. This is an unary operator.
 111    ---C++: alias operator +=
 112    raises NullObject from Standard
 113    is static;
 114
 115    AssignCat (me : out ; other : CString)
 116    ---Level: Public
 117    ---Purpose: Appends <other>  to me. This is an unary operator.
 118    -- ex: aString += "Dummy"
 119    -- To catenate more than one CString, you must put a
 120    -- AsciiString before.
 121    --  Example: aString += "Hello " + "Dolly"  IS NOT VALID !
 122    -- But astring += anotherString + "Hello " + "Dolly" is valid.
 123    ---C++: alias operator +=
 124    raises NullObject from Standard
 125    is static;
 126
 127    AssignCat (me : out ; other : AsciiString from TCollection)
 128    ---Level: Public
 129    ---Purpose: Appends <other> to me. This is an unary operator.
 130    --  Example: aString += anotherString
 131    ---C++: alias operator +=
 132     is static;
 133
 134    Capitalize(me : out)
 135    ---Level: Public
 136    ---Purpose: Converts the first character into its corresponding
 137    -- upper-case character and the other characters into lowercase
 138    --  Example: before
 139    --   me = "hellO "
 140    -- after
 141    --   me = "Hello "
 142     is static;
 143
 144 --   Cat(me; other : CString from Standard; result : out AsciiString from TCollection )
 145 --      is private;
 146
 147    Cat (me ; other : Character from Standard) returns AsciiString from TCollection
 148    ---Level: Public
 149    ---Purpose: Appends <other>  to me.
 150    -- Syntax:
 151    -- aString = aString + "Dummy"
 152    --  Example: aString contains "I say "
 153    -- aString = aString + "Hello " + "Dolly"
 154    -- gives "I say Hello Dolly"
 155    -- To catenate more than one CString, you must put a String before.
 156    -- So the following example is WRONG !
 157    --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 158    -- This rule is applicable to AssignCat (operator +=) too.
 159    ---C++: alias operator +
 160    ---C++: inline
 161    raises NullObject from Standard
 162    is static;
 163
 164    Cat (me ; other : Integer from Standard) returns AsciiString from TCollection
 165    ---Level: Public
 166    ---Purpose: Appends <other>  to me.
 167    -- Syntax:
 168    -- aString = aString + 15;
 169    --  Example: aString contains "I say "
 170    -- gives "I say 15"
 171    -- To catenate more than one CString, you must put a String before.
 172    -- So the following example is WRONG !
 173    --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 174    -- This rule is applicable to AssignCat (operator +=) too.
 175    ---C++: alias operator +
 176    ---C++: inline
 177    raises NullObject from Standard
 178    is static;
 179
 180    Cat (me ; other : Real from Standard) returns AsciiString from TCollection
 181    ---Level: Public
 182    ---Purpose: Appends <other>  to me.
 183    -- Syntax:
 184    -- aString = aString + 15.15;
 185    --  Example: aString contains "I say "
 186    -- gives "I say 15.15"
 187    -- To catenate more than one CString, you must put a String before.
 188    -- So the following example is WRONG !
 189    --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 190    -- This rule is applicable to AssignCat (operator +=) too.
 191    ---C++: alias operator +
 192    ---C++: inline
 193    raises NullObject from Standard
 194    is static;
 195
 196     Cat (me ; other : CString from Standard)
 197            returns AsciiString from TCollection
 198     ---Level: Public
 199     ---Purpose: Appends <other>  to me.
 200     -- Syntax:
 201     -- aString = aString + "Dummy"
 202     --  Example: aString contains "I say "
 203     -- aString = aString + "Hello " + "Dolly"
 204     -- gives "I say Hello Dolly"
 205     -- To catenate more than one CString, you must put a String before.
 206     -- So the following example is WRONG !
 207     --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 208     -- This rule is applicable to AssignCat (operator +=) too.
 209     ---C++: alias operator +
 210     ---C++: inline
 211     is static;
 212
 213 --   Cat(me; other : AsciiString from TCollection;
 214 --           result : out AsciiString from TCollection )
 215 --      is private;
 216
 217    Cat (me ; other : AsciiString from TCollection)
 218    returns AsciiString from TCollection
 219    ---Level: Public
 220    ---Purpose: Appends <other> to me.
 221    --  Example: aString = aString + anotherString
 222    ---C++: alias operator +
 223    ---C++: inline
 224    is static;
 225
 226    Center(me : out;
 227           Width : Integer from Standard;
 228           Filler : Character from Standard)
 229    raises NegativeValue from Standard
 230    ---Purpose: Modifies this ASCII string so that its length
 231    -- becomes equal to Width and the new characters
 232    -- are equal to Filler. New characters are added
 233    -- both at the beginning and at the end of this string.
 234    -- If Width is less than the length of this ASCII string, nothing happens.
 235    -- Example
 236    -- TCollection_AsciiString
 237    -- myAlphabet("abcdef");
 238    -- myAlphabet.Center(9,' ');
 239    -- assert ( myAlphabet == "
 240    -- abcdef " );
 241    is static;
 242
 243    ChangeAll(me : out; aChar, NewChar : Character;
 244            CaseSensitive : Boolean=Standard_True)
 245    ---Level: Public
 246    ---Purpose: Substitutes all the characters equal to aChar by NewChar
 247    -- in the AsciiString <me>.
 248    -- The substitution can be case sensitive.
 249    -- If you don't use default case sensitive, no matter wether aChar
 250    -- is uppercase or not.
 251    --  Example: me = "Histake" -> ChangeAll('H','M',Standard_True)
 252    -- gives me = "Mistake"
 253    is static;
 254
 255    Clear (me : out)
 256    ---Level: Public
 257    ---Purpose: Removes all characters contained in <me>.
 258    -- This produces an empty AsciiString.
 259    is static;
 260
 261    Copy (me : out ; fromwhere : CString from Standard)
 262    ---Level: Public
 263    ---Purpose: Copy <fromwhere> to <me>.
 264    -- Used as operator =
 265    --  Example: aString = anotherCString;
 266    ---C++: alias operator =
 267    is static;
 268
 269    Copy (me : out ; fromwhere : AsciiString from TCollection)
 270    ---Level: Public
 271    ---Purpose: Copy <fromwhere> to <me>.
 272    -- Used as operator =
 273    --  Example: aString = anotherString;
 274    ---C++: alias operator =
 275    is static;
 276
 277    Destroy (me : in out)
 278    ---Level: Public
 279    ---Purpose: Frees memory allocated by AsciiString.
 280    ---C++: alias ~
 281    is static;
 282
 283    FirstLocationInSet(me; Set : AsciiString from TCollection;
 284                       FromIndex : Integer from Standard;
 285                       ToIndex   : Integer from Standard)
 286    returns Integer
 287    raises OutOfRange from Standard
 288    is static;
 289    ---Level: Public
 290    ---Purpose: Returns the index of the first character of <me> that is
 291    -- present in <Set>.
 292    -- The search begins to the index FromIndex and ends to the
 293    -- the index ToIndex.
 294    -- Returns zero if failure.
 295    -- Raises an exception if FromIndex or ToIndex is out of range.
 296    --  Example: before
 297    --   me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
 298    -- after
 299    --   me = "aabAcAa"
 300    -- returns
 301    --   1
 302
 303    FirstLocationNotInSet(me; Set : AsciiString from TCollection;
 304                          FromIndex : Integer;
 305                          ToIndex   : Integer) returns Integer
 306    raises OutOfRange from Standard
 307    is static;
 308    ---Level: Public
 309    ---Purpose: Returns the index of the first character of <me>
 310    -- that is not present in the set <Set>.
 311    -- The search begins to the index FromIndex and ends to the
 312    -- the index ToIndex in <me>.
 313    -- Returns zero if failure.
 314    -- Raises an exception if FromIndex or ToIndex is out of range.
 315    --  Example: before
 316    --   me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
 317    -- after
 318    --   me = "aabAcAa"
 319    -- returns
 320    --   3
 321
 322    Insert (me : out; where : Integer; what : Character)
 323    ---Level: Public
 324    ---Purpose: Inserts a Character at position <where>.
 325    --  Example:
 326    --    aString contains "hy not ?"
 327    --    aString.Insert(1,'W'); gives "Why not ?"
 328    --    aString contains "Wh"
 329    --    aString.Insert(3,'y'); gives "Why"
 330    --    aString contains "Way"
 331    --    aString.Insert(2,'h'); gives "Why"
 332    raises OutOfRange from Standard
 333    is static;
 334
 335    Insert (me : out; where : Integer; what : CString)
 336    ---Level: Public
 337    ---Purpose: Inserts a CString at position <where>.
 338    --  Example:
 339    --    aString contains "O more"
 340    --    aString.Insert(2,"nce");  gives "Once more"
 341    raises NullObject from Standard,
 342           OutOfRange from Standard
 343    is static;
 344
 345    Insert (me : out; where : Integer; what : AsciiString from TCollection)
 346    ---Level: Public
 347    ---Purpose: Inserts a AsciiString at position <where>.
 348    raises OutOfRange;
 349
 350    InsertAfter(me : out; Index : Integer;
 351                other : AsciiString from TCollection)
 352    raises OutOfRange from Standard
 353    is static;
 354    ---Level: Public
 355    ---Purpose: Pushing a string after a specific index in the string <me>.
 356    -- Raises an exception if Index is out of bounds.
 357    -- -   less than 0 (InsertAfter), or less than 1 (InsertBefore), or
 358    -- -   greater than the number of characters in this ASCII string.
 359    --  Example:
 360    -- before
 361    --   me = "cde" , Index = 0 , other = "ab"
 362    -- after
 363    --   me = "abcde" , other = "ab"
 364
 365    InsertBefore(me : out; Index : Integer;
 366                 other : AsciiString from TCollection)
 367    raises OutOfRange from Standard
 368    is static;
 369    ---Level: Public
 370    ---Purpose: Pushing a string before a specific index in the string <me>.
 371    -- Raises an exception if Index is out of bounds.
 372    -- -   less than 0 (InsertAfter), or less than 1 (InsertBefore), or
 373    -- -   greater than the number of characters in this ASCII string.
 374    --  Example:
 375    -- before
 376    --   me = "cde" , Index = 1 , other = "ab"
 377    -- after
 378    --   me = "abcde" , other = "ab"
 379
 380    IsEmpty(me) returns Boolean from Standard
 381    is static;
 382    ---Level: Public
 383    ---Purpose: Returns True if the string <me> contains zero character.
 384
 385    IsEqual (me ; other : CString) returns Boolean
 386    ---Purpose:  Returns true if the characters in this ASCII string
 387     -- are identical to the characters in ASCII string other.
 388     -- Note that this method is an alias of operator ==.
 389    raises NullObject from Standard
 390    is static;
 391    ---C++: alias operator ==
 392
 393    IsEqual (me ; other : AsciiString from TCollection)
 394    returns Boolean from Standard
 395    is static;
 396    ---Purpose:  Returns true if the characters in this ASCII string
 397     -- are identical to the characters in ASCII string other.
 398     -- Note that this method is an alias of operator ==.
 399    ---C++: alias operator ==
 400
 401    IsDifferent (me ; other : CString)
 402    returns Boolean from Standard
 403    ---Level: Public
 404    ---Purpose:  Returns true if there are differences between the
 405    -- characters in this ASCII string and ASCII string other.
 406    -- Note that this method is an alias of operator !=
 407    raises NullObject from Standard
 408    is static;
 409    ---C++: alias operator !=
 410
 411    IsDifferent (me ; other : AsciiString from TCollection)
 412    returns Boolean from Standard
 413    is static;
 414    ---Purpose:  Returns true if there are differences between the
 415    -- characters in this ASCII string and ASCII string other.
 416    -- Note that this method is an alias of operator !=
 417    ---C++: alias operator !=
 418
 419    IsLess (me ; other : CString) returns Boolean from Standard
 420    ---Level: Public
 421    ---Purpose: Returns TRUE if <me> is 'ASCII' less than <other>.
 422    raises NullObject from Standard
 423    ---C++: alias operator <
 424    is static;
 425
 426    IsLess (me ; other : AsciiString from TCollection)
 427    returns Boolean from Standard
 428    ---Level: Public
 429    ---Purpose: Returns TRUE if <me> is 'ASCII' less than <other>.
 430    ---C++: alias operator <
 431    is static;
 432
 433    IsGreater (me ; other : CString) returns Boolean from Standard
 434    ---Level: Public
 435    ---Purpose: Returns TRUE if <me> is 'ASCII' greater than <other>.
 436    raises NullObject from Standard
 437    is static;
 438    ---C++: alias operator >
 439
 440    IsGreater (me ; other : AsciiString from TCollection)
 441    returns Boolean from Standard
 442    is static;
 443    ---Level: Public
 444    ---Purpose: Returns TRUE if <me> is 'ASCII' greater than <other>.
 445    ---C++: alias operator >
 446
 447    IntegerValue(me)
 448    returns Integer from Standard
 449    ---Level: Public
 450    ---Purpose: Converts a AsciiString containing a numeric expression to
 451    -- an Integer.
 452    --  Example: "215" returns 215.
 453    raises NumericError from Standard
 454    is static;
 455
 456    IsIntegerValue(me) returns Boolean from Standard
 457    is static;
 458    ---Level: Public
 459    ---Purpose: Returns True if the AsciiString contains an integer value.
 460    -- Note: an integer value is considered to be a real value as well.
 461
 462    IsRealValue(me) returns Boolean from Standard
 463    is static;
 464    ---Level: Public
 465    ---Purpose: Returns True if the AsciiString contains a real value.
 466    --  Note: an integer value is considered to be a real value as well.
 467
 468    IsAscii(me) returns Boolean from Standard
 469    is static;
 470    ---Level: Public
 471    ---Purpose: Returns True if the AsciiString contains only ASCII characters
 472    -- between ' ' and '~'.
 473    -- This means no control character and no extended ASCII code.
 474
 475    LeftAdjust(me :  out)
 476    is static;
 477    ---Level: Public
 478    ---Purpose: Removes all space characters in the begining of the string.
 479
 480    LeftJustify(me : out; Width : Integer;
 481                Filler : Character from Standard)
 482    raises NegativeValue from Standard
 483    is static;
 484    ---Level: Public
 485    ---Purpose: left justify
 486    -- Length becomes equal to Width and the new characters are
 487    -- equal to Filler.
 488    -- If Width < Length nothing happens.
 489    -- Raises an exception if Width is less than zero.
 490    --  Example:
 491    -- before
 492    --   me = "abcdef" , Width = 9 , Filler = ' '
 493    -- after
 494    --   me = "abcdef   "
 495
 496    Length (me) returns Integer
 497    is static;
 498    ---C++: inline
 499    ---Level: Public
 500    ---Purpose: Returns number of characters in <me>.
 501    -- This is the same functionality as 'strlen' in C.
 502    -- Example
 503    --  TCollection_AsciiString myAlphabet("abcdef");
 504    -- assert ( myAlphabet.Length() == 6 );
 505    -- -   1 is the position of the first character in this string.
 506    -- -   The length of this string gives the position of its last character.
 507    -- -   Positions less than or equal to zero, or
 508    --   greater than the length of this string are
 509    --   invalid in functions which identify a character
 510    --   of this string by its position.
 511
 512    Location(me; other : AsciiString from TCollection;
 513             FromIndex : Integer;
 514             ToIndex   : Integer)
 515    returns Integer from Standard
 516    raises OutOfRange from Standard
 517    is static;
 518    ---Level: Public
 519    ---Purpose: Returns an index in the string <me> of the first occurence
 520    -- of the string S in the string <me> from the starting index
 521    -- FromIndex to the ending index ToIndex
 522    -- returns zero if failure
 523    -- Raises an exception if FromIndex or ToIndex is out of range.
 524    --  Example:
 525    -- before
 526    --   me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
 527    -- after
 528    --   me = "aabAaAa"
 529    -- returns
 530    --   4
 531
 532    Location(me; N : Integer; C : Character from Standard;
 533             FromIndex : Integer;
 534             ToIndex   : Integer)
 535    returns Integer from Standard
 536    raises OutOfRange from Standard
 537    is static;
 538    ---Level: Public
 539    ---Purpose: Returns the index of the nth occurence of the character C
 540    -- in the string <me> from the starting index FromIndex to the
 541    -- ending index ToIndex.
 542    -- Returns zero if failure.
 543    -- Raises an exception if FromIndex or ToIndex is out of range.
 544    --  Example:
 545    -- before
 546    --   me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
 547    -- after
 548    --   me = "aabAa"
 549    -- returns
 550    --   5
 551
 552    LowerCase (me : out)
 553    is static;
 554    ---Level: Public
 555    ---Purpose: Converts <me> to its lower-case equivalent.
 556    -- Example
 557    -- TCollection_AsciiString myString("Hello Dolly");
 558    -- myString.UpperCase();
 559    -- assert ( myString == "HELLO DOLLY" );
 560    -- myString.LowerCase();
 561    -- assert ( myString == "hello dolly" );
 562
 563    Prepend(me : out; other : AsciiString from TCollection)
 564    is static;
 565    ---Level: Public
 566    ---Purpose: Inserts the string other at the beginning of this ASCII string.
 567    -- Example
 568    -- TCollection_AsciiString myAlphabet("cde");
 569    -- TCollection_AsciiString myBegin("ab");
 570    -- myAlphabet.Prepend(myBegin);
 571    -- assert ( myAlphabet == "abcde" );
 572
 573    Print (me ; astream : out OStream)
 574    is static;
 575    ---Level: Public
 576    ---Purpose: Displays <me> on a stream.
 577    ---C++: alias "friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_AsciiString& astring);"
 578
 579    Read (me : out; astream : out IStream)
 580    is static;
 581    ---Level: Public
 582    ---Purpose: Read <me> from a stream.
 583    ---C++: alias "friend Standard_EXPORT Standard_IStream& operator >> (Standard_IStream& astream, TCollection_AsciiString& astring);"
 584
 585    RealValue(me) returns Real from Standard
 586    ---Level: Public
 587    ---Purpose: Converts an AsciiString containing a numeric expression.
 588    -- to a Real.
 589    --  Example: ex: "215" returns 215.0.
 590    -- ex: "3.14159267" returns 3.14159267.
 591    raises NumericError from Standard
 592    is static;
 593
 594    RemoveAll(me :out; C : Character from Standard;
 595              CaseSensitive : Boolean from Standard)
 596    is static;
 597    ---Level: Public
 598    ---Purpose: Remove all the occurences of the character C in the string.
 599    --  Example:
 600    -- before
 601    --   me = "HellLLo", C = 'L' , CaseSensitive = True
 602    -- after
 603    --   me = "Hello"
 604
 605    RemoveAll(me : out; what : Character)
 606    is static;
 607    ---Level: Public
 608    ---Purpose: Removes every <what> characters from <me>.
 609
 610    Remove (me : out ; where : Integer ; ahowmany : Integer=1)
 611    ---Level: Public
 612    ---Purpose: Erases <ahowmany> characters from position <where>,
 613    -- <where> included.
 614    --  Example:
 615    --   aString contains "Hello"
 616    --   aString.Remove(2,2) erases 2 characters from position 2
 617    -- This gives "Hlo".
 618    raises OutOfRange from Standard
 619    is static;
 620
 621    RightAdjust(me : out)
 622    is static;
 623    ---Level: Public
 624    ---Purpose: Removes all space characters at the end of the string.
 625
 626    RightJustify(me : out;
 627                 Width : Integer;
 628                 Filler : Character from Standard)
 629    raises NegativeValue from Standard
 630    is static;
 631    ---Level: Public
 632    ---Purpose: Right justify.
 633    -- Length becomes equal to Width and the new characters are
 634    -- equal to Filler.
 635    -- if Width < Length nothing happens.
 636    -- Raises an exception if Width is less than zero.
 637    --  Example:
 638    -- before
 639    --   me = "abcdef" , Width = 9 , Filler = ' '
 640    -- after
 641    --   me = "   abcdef"
 642
 643
 644    Search (me ; what : CString) returns Integer from Standard
 645    ---Level: Public
 646    ---Purpose: Searches a CString in <me> from the beginning
 647    -- and returns position of first item <what> matching.
 648    -- it returns -1 if not found.
 649    --  Example:
 650    --  aString contains "Sample single test"
 651    --  aString.Search("le") returns 5
 652    raises NullObject from Standard
 653    is static;
 654
 655    Search (me ; what : AsciiString from TCollection)
 656    returns Integer from Standard
 657    is static;
 658    ---Level: Public
 659    ---Purpose: Searches an AsciiString in <me> from the beginning
 660    -- and returns position of first item <what> matching.
 661    -- It returns -1 if not found.
 662
 663    SearchFromEnd (me ; what : CString)
 664    returns Integer from Standard
 665    ---Level: Public
 666    ---Purpose: Searches a CString in a AsciiString from the end
 667    -- and returns position of first item <what> matching.
 668    -- It returns -1 if not found.
 669    --  Example:
 670    --  aString contains "Sample single test"
 671    --  aString.SearchFromEnd("le") returns 12
 672    raises NullObject from Standard
 673    is static;
 674
 675    SearchFromEnd (me ; what : AsciiString from TCollection)
 676    returns Integer from Standard
 677    is static;
 678    ---Level: Public
 679    ---Purpose: Searches a AsciiString in another AsciiString from the end
 680    -- and returns position of first item <what> matching.
 681    -- It returns -1 if not found.
 682
 683    SetValue(me : out; where : Integer; what : Character)
 684    ---Level: Public
 685    ---Purpose: Replaces one character in the AsciiString at position <where>.
 686    -- If <where> is less than zero or greater than the length of <me>
 687    -- an exception is raised.
 688    --  Example:
 689    -- aString contains "Garbake"
 690    -- astring.Replace(6,'g')  gives <me> = "Garbage"
 691    raises OutOfRange from Standard
 692    is static;
 693
 694    SetValue(me : out; where : Integer; what : CString)
 695    ---Level: Public
 696    ---Purpose: Replaces a part of <me> by a CString.
 697    -- If <where> is less than zero or greater than the length of <me>
 698    -- an exception is raised.
 699    --  Example:
 700    --  aString contains "abcde"
 701    --  aString.SetValue(4,"1234567") gives <me> = "abc1234567"
 702    raises OutOfRange from Standard
 703    is static;
 704
 705    SetValue(me : out; where : Integer; what : AsciiString from TCollection)
 706    ---Level: Public
 707    ---Purpose: Replaces a part of <me> by another AsciiString.
 708    raises OutOfRange from Standard
 709    is static;
 710
 711    Split(me : out; where : Integer; result : out AsciiString from TCollection)
 712    is private;
 713
 714    Split(me : out; where : Integer)
 715    returns AsciiString from TCollection
 716    ---Level: Public
 717    ---Purpose: Splits a AsciiString into two sub-strings.
 718    --  Example:
 719    -- aString contains "abcdefg"
 720    -- aString.Split(3) gives <me> = "abc" and returns "defg"
 721    raises OutOfRange from Standard
 722    is static;
 723
 724
 725    SubString(me; FromIndex, ToIndex : Integer;
 726                  result : out AsciiString from TCollection)
 727    is private;
 728
 729    SubString(me; FromIndex, ToIndex : Integer)
 730    ---Level: Public
 731    ---Purpose: Creation of a sub-string of the string <me>.
 732    -- The sub-string starts to the index Fromindex and ends
 733    -- to the index ToIndex.
 734    -- Raises an exception if ToIndex or FromIndex is out of bounds
 735    --  Example:
 736    -- before
 737    --   me = "abcdefg", ToIndex=3, FromIndex=6
 738    -- after
 739    --   me = "abcdefg"
 740    -- returns
 741    --   "cdef"
 742    ---C++: inline
 743    returns AsciiString from TCollection
 744    raises OutOfRange from Standard
 745    is static;
 746
 747    ToCString(me)
 748    returns CString from Standard
 749    is static;
 750    ---Level: Public
 751    ---Purpose: Returns pointer to AsciiString (char *).
 752    -- This is useful for some casual manipulations.
 753    --  Warning: Because this "char *" is 'const', you can't modify its contents.
 754    ---C++: inline
 755
 756    Token (me ; separators : CString ;
 757                whichone   : Integer;
 758                result     : out AsciiString from TCollection)
 759    is private;
 760
 761    Token (me ; separators : CString=" \t" ; whichone : Integer=1)
 762    returns AsciiString from TCollection
 763    ---Level: Public
 764    ---Purpose: Extracts <whichone> token from <me>.
 765    -- By default, the <separators> is set to space and tabulation.
 766    -- By default, the token extracted is the first one (whichone = 1).
 767    -- <separators> contains all separators you need.
 768    -- If no token indexed by <whichone> is found, it returns empty AsciiString.
 769    --  Example:
 770    --    aString contains "This is a     message"
 771    --    aString.Token()  returns "This"
 772    --    aString.Token(" ",4) returns "message"
 773    --    aString.Token(" ",2) returns "is"
 774    --    aString.Token(" ",9) returns ""
 775    -- Other separators than space character and tabulation are allowed :
 776    --    aString contains "1234; test:message   , value"
 777    --    aString.Token("; :,",4) returns "value"
 778    --    aString.Token("; :,",2) returns "test"
 779    raises NullObject from Standard
 780    is static;
 781
 782    Trunc (me : out ; ahowmany  : Integer)
 783    ---Level: Public
 784    ---Purpose: Truncates <me> to <ahowmany> characters.
 785    --  Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
 786    raises OutOfRange from Standard
 787    is static;
 788
 789    UpperCase (me : out)
 790    is static;
 791    ---Level: Public
 792    ---Purpose: Converts <me> to its upper-case equivalent.
 793
 794    UsefullLength(me)
 795    returns Integer from Standard
 796    is static;
 797    ---Level: Public
 798    ---Purpose: Length of the string ignoring all spaces (' ') and the
 799    -- control character at the end.
 800
 801    Value(me ; where : Integer)
 802    returns Character from Standard
 803    ---Level: Public
 804    ---Purpose: Returns character at position <where> in <me>.
 805    -- If <where> is less than zero or greater than the lenght of <me>,
 806    -- an exception is raised.
 807    --  Example:
 808    --    aString contains "Hello"
 809    --    aString.Value(2) returns 'e'
 810    raises OutOfRange from Standard
 811    is static;
 812
 813    HashCode(myclass ; astring : AsciiString from TCollection; Upper : Integer)
 814    returns Integer;
 815    ---Level: Internal
 816    ---Purpose: Hash function for AsciiString
 817    --  (returns the same Integer value that the hash function for ExtendedString)
 818    ---C++: inline
 819
 820    IsEqual(myclass ; string1 : AsciiString from TCollection;
 821            string2 : AsciiString from TCollection)
 822    returns Boolean;
 823    ---Level: Internal
 824    ---Purpose: Returns True  when the two  strings are the same.
 825    --          (Just for HashCode for AsciiString)
 826    ---C++: inline
 827
 828    IsEqual(myclass ; string1 : AsciiString from TCollection;
 829            string2 : CString from Standard)
 830    returns Boolean;
 831    ---Level: Internal
 832    ---Purpose: Returns True  when the two  strings are the same.
 833    --          (Just for HashCode for AsciiString)
 834    ---C++: inline
 835
 836 fields
 837   mystring      : PCharacter;
 838   mylength      : Integer;
 839
 840 friends
 841     class HAsciiString from TCollection
 842 end AsciiString from TCollection;
 843