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