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    IsEqual (me ; other : ExtString )
 152    returns Boolean from Standard
 153    is static;
 154    ---Level: Public
 155    ---Purpose: Returns true if the characters in this extended
 156    -- string are identical to the characters in the other extended string.
 157    -- Note that this method is an alias of operator ==
 158    ---C++: alias operator ==
 159
 160     IsEqual (me ; other : ExtendedString from TCollection)
 161    returns Boolean from Standard
 162    is static;
 163    ---Purpose: Returns true if the characters in this extended
 164    -- string are identical to the characters in the other extended string.
 165    -- Note that this method is an alias of operator ==
 166    ---C++: alias operator ==
 167
 168    IsDifferent (me ; other : ExtString )
 169    returns Boolean from Standard
 170    is static;
 171    ---Purpose: Returns true if there are differences between the
 172    -- characters in this extended string and the other extended string.
 173    -- Note that this method is an alias of operator !=.
 174    ---C++: alias operator !=
 175
 176    IsDifferent (me ; other : ExtendedString from TCollection)
 177    returns Boolean from Standard
 178    is static;
 179    ---Purpose: Returns true if there are differences between the
 180    -- characters in this extended string and the other extended string.
 181    -- Note that this method is an alias of operator !=.
 182    ---C++: alias operator !=
 183
 184    IsLess (me ; other : ExtString )
 185    returns Boolean from Standard
 186    is static;
 187    ---Level: Public
 188    ---Purpose: Returns TRUE if <me> is less than <other>.
 189    ---C++: alias operator <
 190
 191    IsLess (me ; other : ExtendedString from TCollection)
 192    returns Boolean from Standard
 193    is static;
 194    ---Level: Public
 195    ---Purpose: Returns TRUE if <me> is less than <other>.
 196    ---C++: alias operator <
 197
 198    IsGreater (me ; other : ExtString )
 199    returns Boolean from Standard
 200    is static;
 201    ---Level: Public
 202    ---Purpose: Returns TRUE if <me> is greater than <other>.
 203    ---C++: alias operator >
 204
 205    IsGreater (me ; other : ExtendedString from TCollection)
 206    returns Boolean from Standard
 207    is static;
 208    ---Level: Public
 209    ---Purpose: Returns TRUE if <me> is greater than <other>.
 210    ---C++: alias operator >
 211
 212    IsAscii(me)
 213    returns Boolean from Standard
 214    is static;
 215    ---Level: Public
 216    ---Purpose: Returns True if the ExtendedString contains only
 217    -- "Ascii Range" characters .
 218
 219    Length (me) returns Integer from Standard
 220    is static;
 221    ---Level: Public
 222    ---Purpose: Returns number of characters in <me>.
 223    -- This is the same functionality as 'strlen' in C.
 224
 225    Print (me ; astream : out OStream)
 226    is static;
 227    ---Level: Public
 228    ---Purpose: Displays <me> .
 229    ---C++: alias "friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_ExtendedString& astring);"
 230
 231    RemoveAll(me : out; what : ExtCharacter)
 232    is static;
 233    ---Level: Public
 234    ---Purpose: Removes every <what> characters from <me>.
 235
 236    Remove (me : out ; where : Integer ; ahowmany : Integer=1)
 237    ---Level: Public
 238    ---Purpose: Erases <ahowmany> characters from position <where>,<where> included.
 239    ---Example:
 240    --   aString contains "Hello"
 241    --   aString.Erase(2,2) erases 2 characters from position 1
 242    --   This gives "Hlo".
 243    raises OutOfRange from Standard
 244    is static;
 245
 246
 247    Search (me ; what : ExtendedString from TCollection)
 248    returns Integer from Standard
 249    is static;
 250    ---Level: Public
 251    ---Purpose: Searches a ExtendedString in <me> from the beginning
 252    -- and returns position of first item <what> matching.
 253    -- it returns -1 if not found.
 254
 255    SearchFromEnd (me ; what : ExtendedString from TCollection)
 256    returns Integer from Standard
 257    is static;
 258    ---Level: Public
 259    ---Purpose: Searches a ExtendedString in another ExtendedString from the
 260    -- end and returns position of first item <what> matching.
 261    -- it returns -1 if not found.
 262
 263    SetValue(me : out; where : Integer; what : ExtCharacter)
 264    ---Level: Public
 265    ---Purpose: Replaces one character in the ExtendedString at position <where>.
 266    -- If <where> is less than zero or greater than the length of <me>
 267    -- an exception is raised.
 268    ---Example:
 269    --   aString contains "Garbake"
 270    --   astring.Replace(6,'g')  gives <me> = "Garbage"
 271    raises OutOfRange from Standard
 272    is static;
 273
 274    SetValue(me : out; where : Integer; what : ExtendedString from TCollection)
 275    ---Level: Public
 276    ---Purpose: Replaces a part of <me> by another ExtendedString see above.
 277    raises OutOfRange from Standard
 278    is static;
 279
 280    Split(me : out; where : Integer) returns ExtendedString from TCollection
 281    ---Purpose: Splits this extended string into two sub-strings at position where.
 282    -- -   The second sub-string (from position
 283    --   where + 1 of this string to the end) is
 284    --   returned in a new extended string.
 285    -- -   this extended string is modified: its last
 286    --   characters are removed, it becomes equal to
 287    --   the first sub-string (from the first character to position where).
 288    -- Example:
 289    --   aString contains "abcdefg"
 290    --   aString.Split(3) gives <me> = "abc" and returns "defg"
 291    raises OutOfRange from Standard
 292    is static;
 293
 294    Token (me ; separators : ExtString; whichone : Integer=1)
 295    returns ExtendedString from TCollection
 296    ---Purpose: Extracts <whichone> token from <me>.
 297    -- By default, the <separators> is set to space and tabulation.
 298    -- By default, the token extracted is the first one (whichone = 1).
 299    -- <separators> contains all separators you need.
 300    -- If no token indexed by <whichone> is found, it returns an empty AsciiString.
 301    -- Example:
 302    --    aString contains "This is a     message"
 303    --    aString.Token()  returns "This"
 304    --    aString.Token(" ",4) returns "message"
 305    --    aString.Token(" ",2) returns "is"
 306    --    aString.Token(" ",9) returns ""
 307    -- Other separators than space character and tabulation are allowed :
 308    --    aString contains "1234; test:message   , value"
 309    --    aString.Token("; :,",4) returns "value"
 310    --    aString.Token("; :,",2) returns "test"
 311    raises NullObject from Standard
 312    is static;
 313
 314    ToExtString(me) returns ExtString
 315    ---Level: Public
 316    ---Purpose: Returns pointer to ExtString
 317    ---C++: return const
 318    is static;
 319
 320    Trunc (me : out ; ahowmany  : Integer)
 321    ---Purpose: Truncates <me> to <ahowmany> characters.
 322    -- Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
 323    --   Exceptions
 324    -- Standard_OutOfRange if ahowmany is greater
 325    -- than the length of this string.
 326     raises OutOfRange from Standard
 327    is static;
 328
 329    Value(me ; where : Integer) returns ExtCharacter
 330    ---Purpose: Returns character at position <where> in <me>.
 331    -- If <where> is less than zero or greater than the lenght of
 332    -- <me>, an exception is raised.
 333    -- Example:
 334    --   aString contains "Hello"
 335    --   aString.Value(2) returns 'e'
 336    -- Exceptions
 337    -- Standard_OutOfRange if where lies outside
 338    -- the bounds of this extended string.
 339     raises OutOfRange from Standard
 340    is static;
 341
 342    HashCode(myclass ; astring : ExtendedString from TCollection; Upper : Integer)
 343    returns Integer;
 344    ---Level: Internal
 345    ---Purpose: Returns a hashed value for the extended string
 346    -- astring within the range 1..Upper.
 347    -- Note: if astring is ASCII, the computed value is
 348    -- the same as the value computed with the HashCode function on a
 349    -- TCollection_AsciiString string composed with equivalent ASCII characters
 350    ---C++: inline
 351
 352    IsEqual(myclass ; string1 : ExtendedString from TCollection;
 353            string2 : ExtendedString from TCollection)
 354    returns Boolean;
 355    ---Purpose: Returns true if the characters in this extended
 356    -- string are identical to the characters in the other extended string.
 357    -- Note that this method is an alias of operator ==.
 358    ---C++: inline
 359
 360    ToUTF8CString(me; theCString : out PCharacter from Standard)
 361    returns Integer from Standard;
 362    ---Purpose: Converts the internal <mystring> to UTF8 coding and
 363    --          returns length of the out CString. A memory for the
 364    --          <theCString> should be allocated before call!
 365
 366    LengthOfCString(me)
 367    returns Integer from Standard;
 368    ---Purpose: Returns expected CString length in UTF8 coding.
 369    --          It can be used for  memory  calculation  before converting
 370    --          to CString containing symbols in UTF8 coding.
 371
 372    ConvertToUnicode(me : out; astring : CString)
 373    returns Boolean is private;
 374    ---Purpose: Returns true if the input CString was successfuly converted
 375    --          to UTF8 coding
 376 fields
 377   mystring      : PExtCharacter from Standard;
 378   mylength      : Integer from Standard;
 379
 380
 381 end ExtendedString from TCollection;
 382
 383