0025684: Extend TCollection_ExtendedString with method IsEmpty()
[occt.git] / 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