src/TCollection/TCollection_ExtendedString.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 ExtendedString from TCollection
  18     ---Purpose: A variable-length sequence of "extended"
  19     -- (UNICODE) characters (16-bit character type). It
  20     -- provides editing operations with built-in memory
  21     -- management to make ExtendedString objects
  22     -- easier to use than ordinary extended character arrays.
  23     -- ExtendedString objects follow "value
  24     -- semantics", that is, they are the actual strings,
  25     -- not handles to strings, and are copied through
  26     -- assignment. You may use HExtendedString
  27     -- objects to get handles to strings.
  28
  29 uses   AsciiString from TCollection
  30
  31 raises
  32     NullObject,
  33     OutOfRange,
  34     NumericError,
  35     NegativeValue
  36
  37 is
  38     Create returns ExtendedString from TCollection;
  39     ---Purpose: Initializes a ExtendedString to an empty ExtendedString.
  40
  41     Create( astring : CString; isMultiByte : Boolean = Standard_False)
  42             returns ExtendedString from TCollection
  43             raises NullObject;
  44     ---Purpose: Creation by converting a CString to an extended
  45     --          string.  If <isMultiByte> is true then the string is
  46     --          treated as having UTF-8 coding.  If it is not a UTF-8
  47     --          then <isMultiByte> is ignored and each character is
  48     --          copied to ExtCharacter.
  49
  50
  51     Create( astring : ExtString)
  52             returns ExtendedString from TCollection
  53             raises NullObject;
  54     ---Purpose: Creation by converting an ExtString to an extended string.
  55
  56     Create ( aChar : Character) returns ExtendedString from TCollection;
  57     ---Purpose: Initializes a AsciiString with a single character.
  58
  59     Create ( aChar : ExtCharacter) returns ExtendedString from TCollection;
  60     ---Purpose: Initializes a ExtendedString with a single character.
  61
  62     Create ( length : Integer; filler : ExtCharacter)
  63               returns ExtendedString from TCollection;
  64     ---Purpose: Initializes a ExtendedString with <length> space allocated.
  65     -- and filled with <filler>.This is useful for buffers.
  66
  67     Create ( value : Integer ) returns ExtendedString from TCollection
  68     ---Purpose: Initializes an ExtendedString with an integer value
  69     raises NullObject;
  70
  71     Create ( value : Real ) returns ExtendedString from TCollection
  72     ---Purpose: Initializes an ExtendedString with a real value
  73     raises NullObject;
  74
  75     Create ( astring : ExtendedString from TCollection )
  76             returns ExtendedString from TCollection;
  77     ---Purpose: Initializes a ExtendedString with another ExtendedString.
  78
  79     Create( astring : AsciiString from TCollection)
  80             returns ExtendedString from TCollection;
  81     ---Purpose: Creation by converting an Ascii string to an extended
  82     --          string. The string is treated as having UTF-8 coding.
  83     --          If it is not a UTF-8 then each character is copied to ExtCharacter.
  84
  85    AssignCat (me : out ; other : ExtendedString from TCollection)
  86    is static;
  87    ---Purpose:  Appends the other extended string to this extended string.
  88    -- Note that this method is an alias of operator +=.
  89    -- Example: aString += anotherString
  90    ---C++: alias operator +=
  91
  92    Cat (me ; other : ExtendedString from TCollection)
  93    returns ExtendedString from TCollection
  94    is static;
  95    ---Level: Public
  96    ---Purpose: Appends <other> to me.
  97    ---Example:  aString = aString + anotherString
  98    ---C++: alias operator +
  99
 100    ChangeAll(me : out; aChar, NewChar : ExtCharacter)
 101    is static;
 102    ---Level: Public
 103    ---Purpose: Substitutes all the characters equal to aChar by NewChar
 104    -- in the ExtendedString <me>.
 105    -- The substitution can be case sensitive.
 106    -- If you don't use default case sensitive, no matter wether aChar
 107    -- is uppercase or not.
 108    ---Example:
 109    --   me = "Histake" -> ChangeAll('H','M',Standard_True)
 110    --   gives me = "Mistake"
 111
 112    Clear (me : out)
 113    is static;
 114    ---Level: Public
 115    ---Purpose: Removes all characters contained in <me>.
 116    -- This produces an empty ExtendedString.
 117
 118    Copy (me : out ; fromwhere : ExtendedString from TCollection)
 119    is static;
 120    ---Level: Public
 121    ---Purpose: Copy <fromwhere> to <me>.
 122    -- Used as operator =
 123    ---Example: aString = anotherString;
 124    ---C++: alias operator =
 125
 126    Destroy (me : in out)
 127    is static;
 128    ---Level: Public
 129    ---Purpose: Frees memory allocated by ExtendedString.
 130    ---C++: alias ~
 131
 132    Insert (me : out; where : Integer; what : ExtCharacter)
 133    ---Level: Public
 134    ---Purpose: Insert a Character at position <where>.
 135    ---Example:
 136    --   aString contains "hy not ?"
 137    --   aString.Insert(1,'W'); gives "Why not ?"
 138    --   aString contains "Wh"
 139    --   aString.Insert(3,'y'); gives "Why"
 140    --   aString contains "Way"
 141    --   aString.Insert(2,'h'); gives "Why"
 142    raises OutOfRange from Standard
 143    is static;
 144
 145    Insert (me : out; where : Integer; what : ExtendedString from TCollection)
 146    ---Level: Public
 147    ---Purpose: Insert a ExtendedString at position <where>.
 148    raises OutOfRange from Standard
 149    is static;
 150
 151    IsEmpty(me) returns Boolean from Standard
 152    is static;
 153    ---Level: Public
 154    ---C++: inline
 155    ---Purpose: Returns True if this string contains no characters.
 156
 157    IsEqual (me ; other : ExtString )
 158    returns Boolean from Standard
 159    is static;
 160    ---Level: Public
 161    ---Purpose: Returns true if the characters in this extended
 162    -- string are identical to the characters in the other extended string.
 163    -- Note that this method is an alias of operator ==
 164    ---C++: alias operator ==
 165
 166     IsEqual (me ; other : ExtendedString from TCollection)
 167    returns Boolean from Standard
 168    is static;
 169    ---Purpose: Returns true if the characters in this extended
 170    -- string are identical to the characters in the other extended string.
 171    -- Note that this method is an alias of operator ==
 172    ---C++: alias operator ==
 173
 174    IsDifferent (me ; other : ExtString )
 175    returns Boolean from Standard
 176    is static;
 177    ---Purpose: Returns true if there are differences between the
 178    -- characters in this extended string and the other extended string.
 179    -- Note that this method is an alias of operator !=.
 180    ---C++: alias operator !=
 181
 182    IsDifferent (me ; other : ExtendedString from TCollection)
 183    returns Boolean from Standard
 184    is static;
 185    ---Purpose: Returns true if there are differences between the
 186    -- characters in this extended string and the other extended string.
 187    -- Note that this method is an alias of operator !=.
 188    ---C++: alias operator !=
 189
 190    IsLess (me ; other : ExtString )
 191    returns Boolean from Standard
 192    is static;
 193    ---Level: Public
 194    ---Purpose: Returns TRUE if <me> is less than <other>.
 195    ---C++: alias operator <
 196
 197    IsLess (me ; other : ExtendedString from TCollection)
 198    returns Boolean from Standard
 199    is static;
 200    ---Level: Public
 201    ---Purpose: Returns TRUE if <me> is less than <other>.
 202    ---C++: alias operator <
 203
 204    IsGreater (me ; other : ExtString )
 205    returns Boolean from Standard
 206    is static;
 207    ---Level: Public
 208    ---Purpose: Returns TRUE if <me> is greater than <other>.
 209    ---C++: alias operator >
 210
 211    IsGreater (me ; other : ExtendedString from TCollection)
 212    returns Boolean from Standard
 213    is static;
 214    ---Level: Public
 215    ---Purpose: Returns TRUE if <me> is greater than <other>.
 216    ---C++: alias operator >
 217
 218    IsAscii(me)
 219    returns Boolean from Standard
 220    is static;
 221    ---Level: Public
 222    ---Purpose: Returns True if the ExtendedString contains only
 223    -- "Ascii Range" characters .
 224
 225    Length (me) returns Integer from Standard
 226    is static;
 227    ---Level: Public
 228    ---Purpose: Returns number of characters in <me>.
 229    -- This is the same functionality as 'strlen' in C.
 230
 231    Print (me ; astream : out OStream)
 232    is static;
 233    ---Level: Public
 234    ---Purpose: Displays <me> .
 235    ---C++: alias "friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_ExtendedString& astring);"
 236
 237    RemoveAll(me : out; what : ExtCharacter)
 238    is static;
 239    ---Level: Public
 240    ---Purpose: Removes every <what> characters from <me>.
 241
 242    Remove (me : out ; where : Integer ; ahowmany : Integer=1)
 243    ---Level: Public
 244    ---Purpose: Erases <ahowmany> characters from position <where>,<where> included.
 245    ---Example:
 246    --   aString contains "Hello"
 247    --   aString.Erase(2,2) erases 2 characters from position 1
 248    --   This gives "Hlo".
 249    raises OutOfRange from Standard
 250    is static;
 251
 252
 253    Search (me ; what : ExtendedString from TCollection)
 254    returns Integer from Standard
 255    is static;
 256    ---Level: Public
 257    ---Purpose: Searches a ExtendedString in <me> from the beginning
 258    -- and returns position of first item <what> matching.
 259    -- it returns -1 if not found.
 260
 261    SearchFromEnd (me ; what : ExtendedString from TCollection)
 262    returns Integer from Standard
 263    is static;
 264    ---Level: Public
 265    ---Purpose: Searches a ExtendedString in another ExtendedString from the
 266    -- end and returns position of first item <what> matching.
 267    -- it returns -1 if not found.
 268
 269    SetValue(me : out; where : Integer; what : ExtCharacter)
 270    ---Level: Public
 271    ---Purpose: Replaces one character in the ExtendedString at position <where>.
 272    -- If <where> is less than zero or greater than the length of <me>
 273    -- an exception is raised.
 274    ---Example:
 275    --   aString contains "Garbake"
 276    --   astring.Replace(6,'g')  gives <me> = "Garbage"
 277    raises OutOfRange from Standard
 278    is static;
 279
 280    SetValue(me : out; where : Integer; what : ExtendedString from TCollection)
 281    ---Level: Public
 282    ---Purpose: Replaces a part of <me> by another ExtendedString see above.
 283    raises OutOfRange from Standard
 284    is static;
 285
 286    Split(me : out; where : Integer) returns ExtendedString from TCollection
 287    ---Purpose: Splits this extended string into two sub-strings at position where.
 288    -- -   The second sub-string (from position
 289    --   where + 1 of this string to the end) is
 290    --   returned in a new extended string.
 291    -- -   this extended string is modified: its last
 292    --   characters are removed, it becomes equal to
 293    --   the first sub-string (from the first character to position where).
 294    -- Example:
 295    --   aString contains "abcdefg"
 296    --   aString.Split(3) gives <me> = "abc" and returns "defg"
 297    raises OutOfRange from Standard
 298    is static;
 299
 300    Token (me ; separators : ExtString; whichone : Integer=1)
 301    returns ExtendedString from TCollection
 302    ---Purpose: Extracts <whichone> token from <me>.
 303    -- By default, the <separators> is set to space and tabulation.
 304    -- By default, the token extracted is the first one (whichone = 1).
 305    -- <separators> contains all separators you need.
 306    -- If no token indexed by <whichone> is found, it returns an empty AsciiString.
 307    -- Example:
 308    --    aString contains "This is a     message"
 309    --    aString.Token()  returns "This"
 310    --    aString.Token(" ",4) returns "message"
 311    --    aString.Token(" ",2) returns "is"
 312    --    aString.Token(" ",9) returns ""
 313    -- Other separators than space character and tabulation are allowed :
 314    --    aString contains "1234; test:message   , value"
 315    --    aString.Token("; :,",4) returns "value"
 316    --    aString.Token("; :,",2) returns "test"
 317    raises NullObject from Standard
 318    is static;
 319
 320    ToExtString(me) returns ExtString
 321    ---Level: Public
 322    ---Purpose: Returns pointer to ExtString
 323    ---C++: return const
 324    is static;
 325
 326    Trunc (me : out ; ahowmany  : Integer)
 327    ---Purpose: Truncates <me> to <ahowmany> characters.
 328    -- Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
 329    --   Exceptions
 330    -- Standard_OutOfRange if ahowmany is greater
 331    -- than the length of this string.
 332     raises OutOfRange from Standard
 333    is static;
 334
 335    Value(me ; where : Integer) returns ExtCharacter
 336    ---Purpose: Returns character at position <where> in <me>.
 337    -- If <where> is less than zero or greater than the lenght of
 338    -- <me>, an exception is raised.
 339    -- Example:
 340    --   aString contains "Hello"
 341    --   aString.Value(2) returns 'e'
 342    -- Exceptions
 343    -- Standard_OutOfRange if where lies outside
 344    -- the bounds of this extended string.
 345     raises OutOfRange from Standard
 346    is static;
 347
 348    HashCode(myclass ; astring : ExtendedString from TCollection; Upper : Integer)
 349    returns Integer;
 350    ---Level: Internal
 351    ---Purpose: Returns a hashed value for the extended string
 352    -- astring within the range 1..Upper.
 353    -- Note: if astring is ASCII, the computed value is
 354    -- the same as the value computed with the HashCode function on a
 355    -- TCollection_AsciiString string composed with equivalent ASCII characters
 356    ---C++: inline
 357
 358    IsEqual(myclass ; string1 : ExtendedString from TCollection;
 359            string2 : ExtendedString from TCollection)
 360    returns Boolean;
 361    ---Purpose: Returns true if the characters in this extended
 362    -- string are identical to the characters in the other extended string.
 363    -- Note that this method is an alias of operator ==.
 364    ---C++: inline
 365
 366    ToUTF8CString(me; theCString : out PCharacter from Standard)
 367    returns Integer from Standard;
 368    ---Purpose: Converts the internal <mystring> to UTF8 coding and
 369    --          returns length of the out CString. A memory for the
 370    --          <theCString> should be allocated before call!
 371
 372    LengthOfCString(me)
 373    returns Integer from Standard;
 374    ---Purpose: Returns expected CString length in UTF8 coding.
 375    --          It can be used for  memory  calculation  before converting
 376    --          to CString containing symbols in UTF8 coding.
 377
 378    ConvertToUnicode(me : out; astring : CString)
 379    returns Boolean is private;
 380    ---Purpose: Returns true if the input CString was successfuly converted
 381    --          to UTF8 coding
 382 fields
 383   mystring      : PExtCharacter from Standard;
 384   mylength      : Integer from Standard;
 385
 386
 387 end ExtendedString from TCollection;
 388
 389