42cf5bc1 |
1 | // Created on: 1992-12-15 |
2 | // Created by: Mireille MERCIEN |
3 | // Copyright (c) 1992-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 | #ifndef _TCollection_HAsciiString_HeaderFile |
18 | #define _TCollection_HAsciiString_HeaderFile |
19 | |
20 | #include <Standard.hxx> |
21 | #include <Standard_Type.hxx> |
22 | |
23 | #include <TCollection_AsciiString.hxx> |
24 | #include <MMgt_TShared.hxx> |
25 | #include <Standard_CString.hxx> |
26 | #include <Standard_Character.hxx> |
27 | #include <Standard_Integer.hxx> |
28 | #include <Standard_Real.hxx> |
29 | #include <Standard_Boolean.hxx> |
30 | #include <Standard_OStream.hxx> |
31 | class Standard_NullObject; |
32 | class Standard_OutOfRange; |
33 | class Standard_NumericError; |
34 | class Standard_NegativeValue; |
35 | class TCollection_AsciiString; |
36 | class TCollection_HExtendedString; |
37 | |
38 | |
39 | class TCollection_HAsciiString; |
40 | DEFINE_STANDARD_HANDLE(TCollection_HAsciiString, MMgt_TShared) |
41 | |
42 | //! A variable-length sequence of ASCII characters |
43 | //! (normal 8-bit character type). It provides editing |
44 | //! operations with built-in memory management to |
45 | //! make HAsciiString objects easier to use than ordinary character arrays. |
46 | //! HAsciiString objects are handles to strings. |
47 | //! - HAsciiString strings may be shared by several objects. |
48 | //! - You may use an AsciiString object to get the actual string. |
49 | //! Note: HAsciiString objects use an AsciiString string as a field. |
50 | class TCollection_HAsciiString : public MMgt_TShared |
51 | { |
52 | |
53 | public: |
54 | |
55 | |
56 | //! Initializes a HAsciiString to an empty AsciiString. |
57 | Standard_EXPORT TCollection_HAsciiString(); |
58 | |
59 | //! Initializes a HAsciiString with a CString. |
60 | Standard_EXPORT TCollection_HAsciiString(const Standard_CString message); |
61 | |
62 | //! Initializes a HAsciiString with a single character. |
63 | Standard_EXPORT TCollection_HAsciiString(const Standard_Character aChar); |
64 | |
65 | //! Initializes a HAsciiString with <length> space allocated. |
66 | //! and filled with <filler>.This is useful for buffers. |
67 | Standard_EXPORT TCollection_HAsciiString(const Standard_Integer length, const Standard_Character filler); |
68 | |
69 | //! Initializes a HAsciiString with an integer value |
70 | Standard_EXPORT TCollection_HAsciiString(const Standard_Integer value); |
71 | |
72 | //! Initializes a HAsciiString with a real value |
73 | Standard_EXPORT TCollection_HAsciiString(const Standard_Real value); |
74 | |
75 | //! Initializes a HAsciiString with a HAsciiString. |
76 | Standard_EXPORT TCollection_HAsciiString(const TCollection_AsciiString& aString); |
77 | |
78 | //! Initializes a HAsciiString with a HAsciiString. |
79 | Standard_EXPORT TCollection_HAsciiString(const Handle(TCollection_HAsciiString)& aString); |
80 | |
81 | //! Initializes a HAsciiString with a HAsciiString. |
82 | //! If replaceNonAscii is non-null charecter, it will be used |
83 | //! in place of any non-ascii character found in the source string. |
84 | //! Otherwise, raises OutOfRange exception if at least one character |
85 | //! in the source string is not in the "Ascii range". |
86 | Standard_EXPORT TCollection_HAsciiString(const Handle(TCollection_HExtendedString)& aString, const Standard_Character replaceNonAscii); |
87 | |
88 | //! Appends <other> to me. |
89 | void AssignCat (const Standard_CString other); |
90 | |
91 | //! Appends <other> to me. |
92 | //! Example: aString = aString + anotherString |
93 | void AssignCat (const Handle(TCollection_HAsciiString)& other); |
94 | |
95 | //! Converts the first character into its corresponding |
96 | //! upper-case character and the other characters into lowercase. |
97 | //! Example: |
98 | //! before |
99 | //! me = "hellO " |
100 | //! after |
101 | //! me = "Hello " |
102 | Standard_EXPORT void Capitalize(); |
103 | |
104 | //! Creates a new string by concatenation of this |
105 | //! ASCII string and the other ASCII string. |
106 | //! Example: |
107 | //! aString = aString + anotherString |
108 | //! aString = aString + "Dummy" |
109 | //! aString contains "I say " |
110 | //! aString = aString + "Hello " + "Dolly" |
111 | //! gives "I say Hello Dolly" |
112 | //! Warning: To catenate more than one CString, you must put a String before. |
113 | //! So the following example is WRONG ! |
114 | //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED |
115 | //! This rule is applicable to AssignCat (operator +=) too. |
116 | Standard_EXPORT Handle(TCollection_HAsciiString) Cat (const Standard_CString other) const; |
117 | |
118 | //! Creates a new string by concatenation of this |
119 | //! ASCII string and the other ASCII string. |
120 | //! Example: aString = aString + anotherString |
121 | Standard_EXPORT Handle(TCollection_HAsciiString) Cat (const Handle(TCollection_HAsciiString)& other) const; |
122 | |
123 | //! Modifies this ASCII string so that its length |
124 | //! becomes equal to Width and the new characters |
125 | //! are equal to Filler. New characters are added |
126 | //! both at the beginning and at the end of this string. |
127 | //! If Width is less than the length of this ASCII string, nothing happens. |
128 | //! Example |
129 | //! Handle(TCollection_HAsciiString) |
130 | //! myAlphabet |
131 | //! = new |
132 | //! TCollection_HAsciiString |
133 | //! ("abcdef"); |
134 | //! myAlphabet->Center(9,' '); |
135 | //! assert ( !strcmp( |
136 | //! myAlphabet->ToCString(), |
137 | //! " abcdef ") ); |
138 | Standard_EXPORT void Center (const Standard_Integer Width, const Standard_Character Filler); |
139 | |
140 | //! Replaces all characters equal to aChar by |
141 | //! NewChar in this ASCII string. The substitution is |
142 | //! case sensitive if CaseSensitive is true (default value). |
143 | //! If you do not use the default case sensitive |
144 | //! option, it does not matter whether aChar is upper-case or not. |
145 | //! Example |
146 | //! Handle(TCollection_HAsciiString) |
147 | //! myMistake = new |
148 | //! TCollection_HAsciiString |
149 | //! ("Hather"); |
150 | //! myMistake->ChangeAll('H','F'); |
151 | //! assert ( !strcmp( |
152 | //! myMistake->ToCString(), |
153 | //! "Father") ); |
154 | Standard_EXPORT void ChangeAll (const Standard_Character aChar, const Standard_Character NewChar, const Standard_Boolean CaseSensitive = Standard_True); |
155 | |
156 | //! Removes all characters contained in <me>. |
157 | //! This produces an empty HAsciiString. |
158 | Standard_EXPORT void Clear(); |
159 | |
160 | //! Returns the index of the first character of <me> that is |
161 | //! present in <Set>. |
162 | //! The search begins to the index FromIndex and ends to the |
163 | //! the index ToIndex. |
164 | //! Returns zero if failure. |
165 | //! Raises an exception if FromIndex or ToIndex is out of range |
166 | //! Example: |
167 | //! before |
168 | //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7 |
169 | //! after |
170 | //! me = "aabAcAa" |
171 | //! returns |
172 | //! 1 |
173 | Standard_EXPORT Standard_Integer FirstLocationInSet (const Handle(TCollection_HAsciiString)& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
174 | |
175 | //! Returns the index of the first character of <me> |
176 | //! that is not present in the set <Set>. |
177 | //! The search begins to the index FromIndex and ends to the |
178 | //! the index ToIndex in <me>. |
179 | //! Returns zero if failure. |
180 | //! Raises an exception if FromIndex or ToIndex is out of range. |
181 | //! Example: |
182 | //! before |
183 | //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7 |
184 | //! after |
185 | //! me = "aabAcAa" |
186 | //! returns |
187 | //! 3 |
188 | Standard_EXPORT Standard_Integer FirstLocationNotInSet (const Handle(TCollection_HAsciiString)& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
189 | |
190 | //! Insert a Character at position <where>. |
191 | //! Example: |
192 | //! aString contains "hy not ?" |
193 | //! aString.Insert(1,'W'); gives "Why not ?" |
194 | //! aString contains "Wh" |
195 | //! aString.Insert(3,'y'); gives "Why" |
196 | //! aString contains "Way" |
197 | //! aString.Insert(2,'h'); gives "Why" |
198 | Standard_EXPORT void Insert (const Standard_Integer where, const Standard_Character what); |
199 | |
200 | //! Insert a HAsciiString at position <where>. |
201 | Standard_EXPORT void Insert (const Standard_Integer where, const Standard_CString what); |
202 | |
203 | //! Insert a HAsciiString at position <where>. |
204 | Standard_EXPORT void Insert (const Standard_Integer where, const Handle(TCollection_HAsciiString)& what); |
205 | |
206 | //! Inserts the other ASCII string a after a specific index in the string <me> |
207 | //! Example: |
208 | //! before |
209 | //! me = "cde" , Index = 0 , other = "ab" |
210 | //! after |
211 | //! me = "abcde" , other = "ab" |
212 | Standard_EXPORT void InsertAfter (const Standard_Integer Index, const Handle(TCollection_HAsciiString)& other); |
213 | |
214 | //! Inserts the other ASCII string a before a specific index in the string <me> |
215 | //! Raises an exception if Index is out of bounds |
216 | //! Example: |
217 | //! before |
218 | //! me = "cde" , Index = 1 , other = "ab" |
219 | //! after |
220 | //! me = "abcde" , other = "ab" |
221 | Standard_EXPORT void InsertBefore (const Standard_Integer Index, const Handle(TCollection_HAsciiString)& other); |
222 | |
223 | //! Returns True if the string <me> contains zero character |
224 | Standard_EXPORT Standard_Boolean IsEmpty() const; |
225 | |
226 | //! Returns TRUE if <me> is 'ASCII' less than <other>. |
227 | Standard_EXPORT Standard_Boolean IsLess (const Handle(TCollection_HAsciiString)& other) const; |
228 | |
229 | //! Returns TRUE if <me> is 'ASCII' greater than <other>. |
230 | Standard_EXPORT Standard_Boolean IsGreater (const Handle(TCollection_HAsciiString)& other) const; |
231 | |
232 | //! Converts a HAsciiString containing a numeric expression to |
233 | //! an Integer. |
234 | //! Example: "215" returns 215. |
235 | Standard_EXPORT Standard_Integer IntegerValue() const; |
236 | |
237 | //! Returns True if the string contains an integer value. |
238 | Standard_EXPORT Standard_Boolean IsIntegerValue() const; |
239 | |
240 | //! Returns True if the string contains a real value. |
241 | Standard_EXPORT Standard_Boolean IsRealValue() const; |
242 | |
243 | //! Returns True if the string contains only ASCII characters |
244 | //! between ' ' and '~'. |
245 | //! This means no control character and no extended ASCII code. |
246 | Standard_EXPORT Standard_Boolean IsAscii() const; |
247 | |
248 | //! Returns True if the string S not contains same characters than |
249 | //! the string <me>. |
250 | Standard_EXPORT Standard_Boolean IsDifferent (const Handle(TCollection_HAsciiString)& S) const; |
251 | |
252 | //! Returns True if the string S contains same characters than the |
253 | //! string <me>. |
254 | Standard_EXPORT Standard_Boolean IsSameString (const Handle(TCollection_HAsciiString)& S) const; |
255 | |
256 | //! Returns True if the string S contains same characters than the |
257 | //! string <me>. |
258 | Standard_EXPORT Standard_Boolean IsSameString (const Handle(TCollection_HAsciiString)& S, const Standard_Boolean CaseSensitive) const; |
259 | |
260 | //! Removes all space characters in the begining of the string |
261 | Standard_EXPORT void LeftAdjust(); |
262 | |
263 | //! Left justify. |
264 | //! Length becomes equal to Width and the new characters are |
265 | //! equal to Filler |
266 | //! if Width < Length nothing happens |
267 | //! Raises an exception if Width is less than zero |
268 | //! Example: |
269 | //! before |
270 | //! me = "abcdef" , Width = 9 , Filler = ' ' |
271 | //! after |
272 | //! me = "abcdef " |
273 | Standard_EXPORT void LeftJustify (const Standard_Integer Width, const Standard_Character Filler); |
274 | |
275 | //! Returns number of characters in <me>. |
276 | //! This is the same functionality as 'strlen' in C. |
277 | Standard_Integer Length() const; |
278 | |
279 | //! returns an index in the string <me> of the first occurence |
280 | //! of the string S in the string <me> from the starting index |
281 | //! FromIndex to the ending index ToIndex |
282 | //! returns zero if failure |
283 | //! Raises an exception if FromIndex or ToIndex is out of range. |
284 | //! Example: |
285 | //! before |
286 | //! me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7 |
287 | //! after |
288 | //! me = "aabAaAa" |
289 | //! returns |
290 | //! 4 |
291 | Standard_EXPORT Standard_Integer Location (const Handle(TCollection_HAsciiString)& other, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
292 | |
293 | //! Returns the index of the nth occurence of the character C |
294 | //! in the string <me> from the starting index FromIndex to the |
295 | //! ending index ToIndex. |
296 | //! Returns zero if failure. |
297 | //! Raises an exception if FromIndex or ToIndex is out of range |
298 | //! Example: |
299 | //! before |
300 | //! me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5 |
301 | //! after |
302 | //! me = "aabAa" |
303 | //! returns 5 |
304 | Standard_EXPORT Standard_Integer Location (const Standard_Integer N, const Standard_Character C, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
305 | |
306 | //! Converts <me> to its lower-case equivalent. |
307 | Standard_EXPORT void LowerCase(); |
308 | |
309 | //! Inserts the other string at the begining of the string <me> |
310 | //! Example: |
311 | //! before |
312 | //! me = "cde" , S = "ab" |
313 | //! after |
314 | //! me = "abcde" , S = "ab" |
315 | Standard_EXPORT void Prepend (const Handle(TCollection_HAsciiString)& other); |
316 | |
317 | //! Prints this string on the stream <astream>. |
318 | Standard_EXPORT void Print (Standard_OStream& astream) const; |
319 | |
320 | //! Converts a string containing a numeric expression to a Real. |
321 | //! Example: |
322 | //! "215" returns 215.0. |
323 | //! "3.14159267" returns 3.14159267. |
324 | Standard_EXPORT Standard_Real RealValue() const; |
325 | |
326 | //! Remove all the occurences of the character C in the string |
327 | //! Example: |
328 | //! before |
329 | //! me = "HellLLo", C = 'L' , CaseSensitive = True |
330 | //! after |
331 | //! me = "Hello" |
332 | Standard_EXPORT void RemoveAll (const Standard_Character C, const Standard_Boolean CaseSensitive); |
333 | |
334 | //! Removes every <what> characters from <me> |
335 | Standard_EXPORT void RemoveAll (const Standard_Character what); |
336 | |
337 | //! Erases <ahowmany> characters from position <where>, |
338 | //! <where> included. |
339 | //! Example: |
340 | //! aString contains "Hello" |
341 | //! aString.Erase(2,2) erases 2 characters from position 1 |
342 | //! This gives "Hlo". |
343 | Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1); |
344 | |
345 | //! Removes all space characters at the end of the string. |
346 | Standard_EXPORT void RightAdjust(); |
347 | |
348 | //! Right justify. |
349 | //! Length becomes equal to Width and the new characters are |
350 | //! equal to Filler |
351 | //! if Width < Length nothing happens |
352 | //! Raises an exception if Width is less than zero |
353 | //! Example: |
354 | //! before |
355 | //! me = "abcdef" , Width = 9 , Filler = ' ' |
356 | //! after |
357 | //! me = " abcdef" |
358 | Standard_EXPORT void RightJustify (const Standard_Integer Width, const Standard_Character Filler); |
359 | |
360 | //! Searches a CString in <me> from the beginning |
361 | //! and returns position of first item <what> matching. |
362 | //! It returns -1 if not found. |
363 | //! Example: |
364 | //! aString contains "Sample single test" |
365 | //! aString.Search("le") returns 5 |
366 | Standard_EXPORT Standard_Integer Search (const Standard_CString what) const; |
367 | |
368 | //! Searches a String in <me> from the beginning |
369 | //! and returns position of first item <what> matching. |
370 | //! it returns -1 if not found. |
371 | Standard_EXPORT Standard_Integer Search (const Handle(TCollection_HAsciiString)& what) const; |
372 | |
373 | //! Searches a CString in a String from the end |
374 | //! and returns position of first item <what> matching. |
375 | //! It returns -1 if not found. |
376 | //! Example: |
377 | //! aString contains "Sample single test" |
378 | //! aString.SearchFromEnd("le") returns 12 |
379 | Standard_EXPORT Standard_Integer SearchFromEnd (const Standard_CString what) const; |
380 | |
381 | //! Searches a HAsciiString in another HAsciiString from the end |
382 | //! and returns position of first item <what> matching. |
383 | //! It returns -1 if not found. |
384 | Standard_EXPORT Standard_Integer SearchFromEnd (const Handle(TCollection_HAsciiString)& what) const; |
385 | |
386 | //! Replaces one character in the string at position <where>. |
387 | //! If <where> is less than zero or greater than the length of <me> |
388 | //! an exception is raised. |
389 | //! Example: |
390 | //! aString contains "Garbake" |
391 | //! astring.Replace(6,'g') gives <me> = "Garbage" |
392 | Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_Character what); |
393 | |
394 | //! Replaces a part of <me> in the string at position <where>. |
395 | //! If <where> is less than zero or greater than the length of <me> |
396 | //! an exception is raised. |
397 | //! Example: |
398 | //! aString contains "Garbake" |
399 | //! astring.Replace(6,'g') gives <me> = "Garbage" |
400 | Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_CString what); |
401 | |
402 | //! Replaces a part of <me> by another string. |
403 | Standard_EXPORT void SetValue (const Standard_Integer where, const Handle(TCollection_HAsciiString)& what); |
404 | |
405 | //! Splits a HAsciiString into two sub-strings. |
406 | //! Example: |
407 | //! aString contains "abcdefg" |
408 | //! aString.Split(3) gives <me> = "abc" and returns "defg" |
409 | Standard_EXPORT Handle(TCollection_HAsciiString) Split (const Standard_Integer where); |
410 | |
411 | //! Creation of a sub-string of the string <me>. |
412 | //! The sub-string starts to the index Fromindex and ends |
413 | //! to the index ToIndex. |
414 | //! Raises an exception if ToIndex or FromIndex is out of |
415 | //! bounds |
416 | //! Example: |
417 | //! before |
418 | //! me = "abcdefg", ToIndex=3, FromIndex=6 |
419 | //! after |
420 | //! me = "abcdefg" |
421 | //! returns |
422 | //! "cdef" |
423 | Standard_EXPORT Handle(TCollection_HAsciiString) SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
424 | |
425 | //! Returns pointer to string (char *) |
426 | //! This is useful for some casual manipulations |
427 | //! Because this "char *" is 'const', you can't modify its contents. |
428 | Standard_CString ToCString() const; |
429 | |
430 | //! Extracts <whichone> token from <me>. |
431 | //! By default, the <separators> is set to space and tabulation. |
432 | //! By default, the token extracted is the first one (whichone = 1). |
433 | //! <separators> contains all separators you need. |
434 | //! If no token indexed by <whichone> is found, it returns an empty String. |
435 | //! Example: |
436 | //! aString contains "This is a message" |
437 | //! aString.Token() returns "This" |
438 | //! aString.Token(" ",4) returns "message" |
439 | //! aString.Token(" ",2) returns "is" |
440 | //! aString.Token(" ",9) returns "" |
441 | //! Other separators than space character and tabulation are allowed |
442 | //! aString contains "1234; test:message , value" |
443 | //! aString.Token("; :,",4) returns "value" |
444 | //! aString.Token("; :,",2) returns "test" |
445 | Standard_EXPORT Handle(TCollection_HAsciiString) Token (const Standard_CString separators = " \t", const Standard_Integer whichone = 1) const; |
446 | |
447 | //! Truncates <me> to <ahowmany> characters. |
448 | //! Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel" |
449 | Standard_EXPORT void Trunc (const Standard_Integer ahowmany); |
450 | |
451 | //! Converts <me> to its upper-case equivalent. |
452 | Standard_EXPORT void UpperCase(); |
453 | |
454 | //! Length of the string ignoring all spaces (' ') and the |
455 | //! control character at the end. |
456 | Standard_EXPORT Standard_Integer UsefullLength() const; |
457 | |
458 | //! Returns character at position <where> in <me>. |
459 | //! If <where> is less than zero or greater than the lenght of |
460 | //! <me>, an exception is raised. |
461 | //! Example: |
462 | //! aString contains "Hello" |
463 | //! aString.Value(2) returns 'e' |
464 | Standard_EXPORT Standard_Character Value (const Standard_Integer where) const; |
465 | |
466 | //! Returns the field myString. |
467 | const TCollection_AsciiString& String() const; |
468 | |
469 | Standard_EXPORT Standard_Boolean IsSameState (const Handle(TCollection_HAsciiString)& other) const; |
470 | |
471 | |
472 | |
473 | |
92efcf78 |
474 | DEFINE_STANDARD_RTTIEXT(TCollection_HAsciiString,MMgt_TShared) |
42cf5bc1 |
475 | |
476 | protected: |
477 | |
478 | |
479 | |
480 | |
481 | private: |
482 | |
483 | |
484 | TCollection_AsciiString myString; |
485 | |
486 | |
487 | }; |
488 | |
489 | |
490 | #include <TCollection_HAsciiString.lxx> |
491 | |
492 | |
493 | |
494 | |
495 | |
496 | #endif // _TCollection_HAsciiString_HeaderFile |