42cf5bc1 |
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 | #ifndef _TCollection_AsciiString_HeaderFile |
18 | #define _TCollection_AsciiString_HeaderFile |
19 | |
20 | #include <Standard.hxx> |
21 | #include <Standard_DefineAlloc.hxx> |
22 | #include <Standard_Handle.hxx> |
23 | |
24 | #include <Standard_PCharacter.hxx> |
25 | #include <Standard_Integer.hxx> |
26 | #include <Standard_CString.hxx> |
27 | #include <Standard_Character.hxx> |
28 | #include <Standard_Real.hxx> |
29 | #include <Standard_Boolean.hxx> |
30 | #include <Standard_OStream.hxx> |
31 | #include <Standard_IStream.hxx> |
32 | class Standard_NullObject; |
33 | class Standard_OutOfRange; |
34 | class Standard_NumericError; |
35 | class Standard_NegativeValue; |
36 | class TCollection_HAsciiString; |
37 | class TCollection_ExtendedString; |
38 | |
fb0b0531 |
39 | //! Class defines a variable-length sequence of 8-bit characters. |
40 | //! Despite class name (kept for historical reasons), it is intended to store UTF-8 string, not just ASCII characters. |
41 | //! However, multi-byte nature of UTF-8 is not considered by the following methods: |
42 | //! - Method ::Length() return the number of bytes, not the number of Unicode symbols. |
43 | //! - Methods taking/returning symbol index work with 8-bit code units, not true Unicode symbols, |
44 | //! including ::Remove(), ::SetValue(), ::Value(), ::Search(), ::Trunc() and others. |
45 | //! If application needs to process multi-byte Unicode symbols explicitly, NCollection_Utf8Iter class can be used |
46 | //! for iterating through Unicode string (UTF-32 code unit will be returned for each position). |
47 | //! |
48 | //! Class provides editing operations with built-in memory management to make AsciiString objects easier to use than ordinary character arrays. |
49 | //! AsciiString objects follow value semantics; in other words, they are the actual strings, |
50 | //! not handles to strings, and are copied through assignment. |
51 | //! You may use HAsciiString objects to get handles to strings. |
42cf5bc1 |
52 | class TCollection_AsciiString |
53 | { |
54 | public: |
55 | |
56 | DEFINE_STANDARD_ALLOC |
57 | |
58 | |
59 | //! Initializes a AsciiString to an empty AsciiString. |
60 | Standard_EXPORT TCollection_AsciiString(); |
61 | |
62 | //! Initializes a AsciiString with a CString. |
63 | Standard_EXPORT TCollection_AsciiString(const Standard_CString message); |
64 | |
65 | //! Initializes a AsciiString with a CString. |
66 | Standard_EXPORT TCollection_AsciiString(const Standard_CString message, const Standard_Integer aLen); |
67 | |
68 | //! Initializes a AsciiString with a single character. |
69 | Standard_EXPORT TCollection_AsciiString(const Standard_Character aChar); |
70 | |
71 | //! Initializes an AsciiString with <length> space allocated. |
72 | //! and filled with <filler>. This is usefull for buffers. |
73 | Standard_EXPORT TCollection_AsciiString(const Standard_Integer length, const Standard_Character filler); |
74 | |
75 | //! Initializes an AsciiString with an integer value |
76 | Standard_EXPORT TCollection_AsciiString(const Standard_Integer value); |
77 | |
78 | //! Initializes an AsciiString with a real value |
79 | Standard_EXPORT TCollection_AsciiString(const Standard_Real value); |
80 | |
81 | //! Initializes a AsciiString with another AsciiString. |
82 | Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring); |
83 | |
84 | //! Initializes a AsciiString with copy of another AsciiString |
85 | //! concatenated with the message character. |
86 | Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_Character message); |
87 | |
88 | //! Initializes a AsciiString with copy of another AsciiString |
89 | //! concatenated with the message string. |
90 | Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_CString message); |
91 | |
92 | //! Initializes a AsciiString with copy of another AsciiString |
93 | //! concatenated with the message string. |
94 | Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const TCollection_AsciiString& message); |
95 | |
96 | //! Creation by converting an extended string to an ascii string. |
97 | //! If replaceNonAscii is non-null charecter, it will be used |
98 | //! in place of any non-ascii character found in the source string. |
99 | //! Otherwise, creates UTF-8 unicode string. |
100 | Standard_EXPORT TCollection_AsciiString(const TCollection_ExtendedString& astring, const Standard_Character replaceNonAscii = 0); |
fb0b0531 |
101 | |
15173be5 |
102 | #if !defined(_MSC_VER) || defined(_NATIVE_WCHAR_T_DEFINED) |
fb0b0531 |
103 | //! Initialize UTF-8 Unicode string from wide-char string considering it as Unicode string |
104 | //! (the size of wide char is a platform-dependent - e.g. on Windows wchar_t is UTF-16). |
105 | //! |
106 | //! This constructor is unavailable if application is built with deprecated msvc option "-Zc:wchar_t-", |
107 | //! since OCCT itself is never built with this option. |
108 | Standard_EXPORT TCollection_AsciiString (const Standard_WideChar* theStringUtf); |
109 | #endif |
110 | |
42cf5bc1 |
111 | //! Appends <other> to me. This is an unary operator. |
112 | Standard_EXPORT void AssignCat (const Standard_Character other); |
113 | void operator += (const Standard_Character other) |
114 | { |
115 | AssignCat(other); |
116 | } |
117 | |
118 | //! Appends <other> to me. This is an unary operator. |
119 | Standard_EXPORT void AssignCat (const Standard_Integer other); |
120 | void operator += (const Standard_Integer other) |
121 | { |
122 | AssignCat(other); |
123 | } |
124 | |
125 | //! Appends <other> to me. This is an unary operator. |
126 | Standard_EXPORT void AssignCat (const Standard_Real other); |
127 | void operator += (const Standard_Real other) |
128 | { |
129 | AssignCat(other); |
130 | } |
131 | |
132 | //! Appends <other> to me. This is an unary operator. |
133 | //! ex: aString += "Dummy" |
134 | //! To catenate more than one CString, you must put a |
135 | //! AsciiString before. |
136 | //! Example: aString += "Hello " + "Dolly" IS NOT VALID ! |
137 | //! But astring += anotherString + "Hello " + "Dolly" is valid. |
138 | Standard_EXPORT void AssignCat (const Standard_CString other); |
139 | void operator += (const Standard_CString other) |
140 | { |
141 | AssignCat(other); |
142 | } |
143 | |
144 | //! Appends <other> to me. This is an unary operator. |
145 | //! Example: aString += anotherString |
146 | Standard_EXPORT void AssignCat (const TCollection_AsciiString& other); |
147 | void operator += (const TCollection_AsciiString& other) |
148 | { |
149 | AssignCat(other); |
150 | } |
151 | |
152 | //! Converts the first character into its corresponding |
153 | //! upper-case character and the other characters into lowercase |
154 | //! Example: before |
155 | //! me = "hellO " |
156 | //! after |
157 | //! me = "Hello " |
158 | Standard_EXPORT void Capitalize(); |
159 | |
160 | //! Appends <other> to me. |
161 | //! Syntax: |
162 | //! aString = aString + "Dummy" |
163 | //! Example: aString contains "I say " |
164 | //! aString = aString + "Hello " + "Dolly" |
165 | //! gives "I say Hello Dolly" |
166 | //! To catenate more than one CString, you must put a String before. |
167 | //! So the following example is WRONG ! |
168 | //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED |
169 | //! This rule is applicable to AssignCat (operator +=) too. |
170 | TCollection_AsciiString Cat (const Standard_Character other) const; |
171 | TCollection_AsciiString operator + (const Standard_Character other) const |
172 | { |
173 | return Cat(other); |
174 | } |
175 | |
176 | //! Appends <other> to me. |
177 | //! Syntax: |
178 | //! aString = aString + 15; |
179 | //! Example: aString contains "I say " |
180 | //! gives "I say 15" |
181 | //! To catenate more than one CString, you must put a String before. |
182 | //! So the following example is WRONG ! |
183 | //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED |
184 | //! This rule is applicable to AssignCat (operator +=) too. |
185 | TCollection_AsciiString Cat (const Standard_Integer other) const; |
186 | TCollection_AsciiString operator + (const Standard_Integer other) const |
187 | { |
188 | return Cat(other); |
189 | } |
190 | |
191 | //! Appends <other> to me. |
192 | //! Syntax: |
193 | //! aString = aString + 15.15; |
194 | //! Example: aString contains "I say " |
195 | //! gives "I say 15.15" |
196 | //! To catenate more than one CString, you must put a String before. |
197 | //! So the following example is WRONG ! |
198 | //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED |
199 | //! This rule is applicable to AssignCat (operator +=) too. |
200 | TCollection_AsciiString Cat (const Standard_Real other) const; |
201 | TCollection_AsciiString operator + (const Standard_Real other) const |
202 | { |
203 | return Cat(other); |
204 | } |
205 | |
206 | //! Appends <other> to me. |
207 | //! Syntax: |
208 | //! aString = aString + "Dummy" |
209 | //! Example: aString contains "I say " |
210 | //! aString = aString + "Hello " + "Dolly" |
211 | //! gives "I say Hello Dolly" |
212 | //! To catenate more than one CString, you must put a String before. |
213 | //! So the following example is WRONG ! |
214 | //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED |
215 | //! This rule is applicable to AssignCat (operator +=) too. |
216 | TCollection_AsciiString Cat (const Standard_CString other) const; |
217 | TCollection_AsciiString operator + (const Standard_CString other) const |
218 | { |
219 | return Cat(other); |
220 | } |
221 | |
222 | //! Appends <other> to me. |
223 | //! Example: aString = aString + anotherString |
224 | TCollection_AsciiString Cat (const TCollection_AsciiString& other) const; |
225 | TCollection_AsciiString operator + (const TCollection_AsciiString& other) const |
226 | { |
227 | return Cat(other); |
228 | } |
229 | |
230 | //! Modifies this ASCII string so that its length |
231 | //! becomes equal to Width and the new characters |
232 | //! are equal to Filler. New characters are added |
233 | //! both at the beginning and at the end of this string. |
234 | //! If Width is less than the length of this ASCII string, nothing happens. |
235 | //! Example |
236 | //! TCollection_AsciiString |
237 | //! myAlphabet("abcdef"); |
238 | //! myAlphabet.Center(9,' '); |
239 | //! assert ( myAlphabet == " |
240 | //! abcdef " ); |
241 | Standard_EXPORT void Center (const Standard_Integer Width, const Standard_Character Filler); |
242 | |
243 | //! Substitutes all the characters equal to aChar by NewChar |
244 | //! in the AsciiString <me>. |
245 | //! The substitution can be case sensitive. |
246 | //! If you don't use default case sensitive, no matter wether aChar |
247 | //! is uppercase or not. |
248 | //! Example: me = "Histake" -> ChangeAll('H','M',Standard_True) |
249 | //! gives me = "Mistake" |
250 | Standard_EXPORT void ChangeAll (const Standard_Character aChar, const Standard_Character NewChar, const Standard_Boolean CaseSensitive = Standard_True); |
251 | |
252 | //! Removes all characters contained in <me>. |
253 | //! This produces an empty AsciiString. |
254 | Standard_EXPORT void Clear(); |
255 | |
256 | //! Copy <fromwhere> to <me>. |
257 | //! Used as operator = |
258 | //! Example: aString = anotherCString; |
259 | Standard_EXPORT void Copy (const Standard_CString fromwhere); |
260 | void operator = (const Standard_CString fromwhere) |
261 | { |
262 | Copy(fromwhere); |
263 | } |
264 | |
265 | //! Copy <fromwhere> to <me>. |
266 | //! Used as operator = |
267 | //! Example: aString = anotherString; |
268 | Standard_EXPORT void Copy (const TCollection_AsciiString& fromwhere); |
269 | void operator = (const TCollection_AsciiString& fromwhere) |
270 | { |
271 | Copy(fromwhere); |
272 | } |
273 | |
274 | //! Frees memory allocated by AsciiString. |
fb0b0531 |
275 | Standard_EXPORT ~TCollection_AsciiString(); |
42cf5bc1 |
276 | |
277 | //! Returns the index of the first character of <me> that is |
278 | //! present in <Set>. |
279 | //! The search begins to the index FromIndex and ends to the |
280 | //! the index ToIndex. |
281 | //! Returns zero if failure. |
282 | //! Raises an exception if FromIndex or ToIndex is out of range. |
283 | //! Example: before |
284 | //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7 |
285 | //! after |
286 | //! me = "aabAcAa" |
287 | //! returns |
288 | //! 1 |
289 | Standard_EXPORT Standard_Integer FirstLocationInSet (const TCollection_AsciiString& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
290 | |
291 | //! Returns the index of the first character of <me> |
292 | //! that is not present in the set <Set>. |
293 | //! The search begins to the index FromIndex and ends to the |
294 | //! the index ToIndex in <me>. |
295 | //! Returns zero if failure. |
296 | //! Raises an exception if FromIndex or ToIndex is out of range. |
297 | //! Example: before |
298 | //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7 |
299 | //! after |
300 | //! me = "aabAcAa" |
301 | //! returns |
302 | //! 3 |
303 | Standard_EXPORT Standard_Integer FirstLocationNotInSet (const TCollection_AsciiString& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
304 | |
305 | //! Inserts a Character at position <where>. |
306 | //! Example: |
307 | //! aString contains "hy not ?" |
308 | //! aString.Insert(1,'W'); gives "Why not ?" |
309 | //! aString contains "Wh" |
310 | //! aString.Insert(3,'y'); gives "Why" |
311 | //! aString contains "Way" |
312 | //! aString.Insert(2,'h'); gives "Why" |
313 | Standard_EXPORT void Insert (const Standard_Integer where, const Standard_Character what); |
314 | |
315 | //! Inserts a CString at position <where>. |
316 | //! Example: |
317 | //! aString contains "O more" |
318 | //! aString.Insert(2,"nce"); gives "Once more" |
319 | Standard_EXPORT void Insert (const Standard_Integer where, const Standard_CString what); |
320 | |
321 | //! Inserts a AsciiString at position <where>. |
322 | Standard_EXPORT void Insert (const Standard_Integer where, const TCollection_AsciiString& what); |
323 | |
324 | //! Pushing a string after a specific index in the string <me>. |
325 | //! Raises an exception if Index is out of bounds. |
326 | //! - less than 0 (InsertAfter), or less than 1 (InsertBefore), or |
327 | //! - greater than the number of characters in this ASCII string. |
328 | //! Example: |
329 | //! before |
330 | //! me = "cde" , Index = 0 , other = "ab" |
331 | //! after |
332 | //! me = "abcde" , other = "ab" |
333 | Standard_EXPORT void InsertAfter (const Standard_Integer Index, const TCollection_AsciiString& other); |
334 | |
335 | //! Pushing a string before a specific index in the string <me>. |
336 | //! Raises an exception if Index is out of bounds. |
337 | //! - less than 0 (InsertAfter), or less than 1 (InsertBefore), or |
338 | //! - greater than the number of characters in this ASCII string. |
339 | //! Example: |
340 | //! before |
341 | //! me = "cde" , Index = 1 , other = "ab" |
342 | //! after |
343 | //! me = "abcde" , other = "ab" |
344 | Standard_EXPORT void InsertBefore (const Standard_Integer Index, const TCollection_AsciiString& other); |
345 | |
346 | //! Returns True if the string <me> contains zero character. |
fb0b0531 |
347 | Standard_Boolean IsEmpty() const { return mylength == 0; } |
348 | |
42cf5bc1 |
349 | //! Returns true if the characters in this ASCII string |
350 | //! are identical to the characters in ASCII string other. |
351 | //! Note that this method is an alias of operator ==. |
352 | Standard_EXPORT Standard_Boolean IsEqual (const Standard_CString other) const; |
353 | Standard_Boolean operator == (const Standard_CString other) const |
354 | { |
355 | return IsEqual(other); |
356 | } |
357 | |
358 | //! Returns true if the characters in this ASCII string |
359 | //! are identical to the characters in ASCII string other. |
360 | //! Note that this method is an alias of operator ==. |
361 | Standard_EXPORT Standard_Boolean IsEqual (const TCollection_AsciiString& other) const; |
362 | Standard_Boolean operator == (const TCollection_AsciiString& other) const |
363 | { |
364 | return IsEqual(other); |
365 | } |
366 | |
367 | //! Returns true if there are differences between the |
368 | //! characters in this ASCII string and ASCII string other. |
369 | //! Note that this method is an alias of operator != |
370 | Standard_EXPORT Standard_Boolean IsDifferent (const Standard_CString other) const; |
371 | Standard_Boolean operator != (const Standard_CString other) const |
372 | { |
373 | return IsDifferent(other); |
374 | } |
375 | |
376 | //! Returns true if there are differences between the |
377 | //! characters in this ASCII string and ASCII string other. |
378 | //! Note that this method is an alias of operator != |
379 | Standard_EXPORT Standard_Boolean IsDifferent (const TCollection_AsciiString& other) const; |
380 | Standard_Boolean operator != (const TCollection_AsciiString& other) const |
381 | { |
382 | return IsDifferent(other); |
383 | } |
384 | |
385 | //! Returns TRUE if <me> is 'ASCII' less than <other>. |
386 | Standard_EXPORT Standard_Boolean IsLess (const Standard_CString other) const; |
387 | Standard_Boolean operator < (const Standard_CString other) const |
388 | { |
389 | return IsLess(other); |
390 | } |
391 | |
392 | //! Returns TRUE if <me> is 'ASCII' less than <other>. |
393 | Standard_EXPORT Standard_Boolean IsLess (const TCollection_AsciiString& other) const; |
394 | Standard_Boolean operator < (const TCollection_AsciiString& other) const |
395 | { |
396 | return IsLess(other); |
397 | } |
398 | |
399 | //! Returns TRUE if <me> is 'ASCII' greater than <other>. |
400 | Standard_EXPORT Standard_Boolean IsGreater (const Standard_CString other) const; |
401 | Standard_Boolean operator > (const Standard_CString other) const |
402 | { |
403 | return IsGreater(other); |
404 | } |
405 | |
406 | //! Returns TRUE if <me> is 'ASCII' greater than <other>. |
407 | Standard_EXPORT Standard_Boolean IsGreater (const TCollection_AsciiString& other) const; |
408 | Standard_Boolean operator > (const TCollection_AsciiString& other) const |
409 | { |
410 | return IsGreater(other); |
411 | } |
fb0b0531 |
412 | |
413 | //! Determines whether the beginning of this string instance matches the specified string. |
414 | Standard_EXPORT Standard_Boolean StartsWith (const TCollection_AsciiString& theStartString) const; |
415 | |
416 | //! Determines whether the end of this string instance matches the specified string. |
417 | Standard_EXPORT Standard_Boolean EndsWith (const TCollection_AsciiString& theEndString) const; |
418 | |
42cf5bc1 |
419 | //! Converts a AsciiString containing a numeric expression to |
420 | //! an Integer. |
421 | //! Example: "215" returns 215. |
422 | Standard_EXPORT Standard_Integer IntegerValue() const; |
423 | |
424 | //! Returns True if the AsciiString contains an integer value. |
425 | //! Note: an integer value is considered to be a real value as well. |
426 | Standard_EXPORT Standard_Boolean IsIntegerValue() const; |
427 | |
428 | //! Returns True if the AsciiString contains a real value. |
429 | //! Note: an integer value is considered to be a real value as well. |
430 | Standard_EXPORT Standard_Boolean IsRealValue() const; |
431 | |
432 | //! Returns True if the AsciiString contains only ASCII characters |
433 | //! between ' ' and '~'. |
434 | //! This means no control character and no extended ASCII code. |
435 | Standard_EXPORT Standard_Boolean IsAscii() const; |
436 | |
437 | //! Removes all space characters in the begining of the string. |
438 | Standard_EXPORT void LeftAdjust(); |
439 | |
440 | //! left justify |
441 | //! Length becomes equal to Width and the new characters are |
442 | //! equal to Filler. |
443 | //! If Width < Length nothing happens. |
444 | //! Raises an exception if Width is less than zero. |
445 | //! Example: |
446 | //! before |
447 | //! me = "abcdef" , Width = 9 , Filler = ' ' |
448 | //! after |
449 | //! me = "abcdef " |
450 | Standard_EXPORT void LeftJustify (const Standard_Integer Width, const Standard_Character Filler); |
451 | |
452 | //! Returns number of characters in <me>. |
453 | //! This is the same functionality as 'strlen' in C. |
454 | //! Example |
455 | //! TCollection_AsciiString myAlphabet("abcdef"); |
456 | //! assert ( myAlphabet.Length() == 6 ); |
457 | //! - 1 is the position of the first character in this string. |
458 | //! - The length of this string gives the position of its last character. |
459 | //! - Positions less than or equal to zero, or |
460 | //! greater than the length of this string are |
461 | //! invalid in functions which identify a character |
462 | //! of this string by its position. |
463 | Standard_Integer Length() const; |
464 | |
465 | //! Returns an index in the string <me> of the first occurence |
466 | //! of the string S in the string <me> from the starting index |
467 | //! FromIndex to the ending index ToIndex |
468 | //! returns zero if failure |
469 | //! Raises an exception if FromIndex or ToIndex is out of range. |
470 | //! Example: |
471 | //! before |
472 | //! me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7 |
473 | //! after |
474 | //! me = "aabAaAa" |
475 | //! returns |
476 | //! 4 |
477 | Standard_EXPORT Standard_Integer Location (const TCollection_AsciiString& other, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
478 | |
479 | //! Returns the index of the nth occurence of the character C |
480 | //! in the string <me> from the starting index FromIndex to the |
481 | //! ending index ToIndex. |
482 | //! Returns zero if failure. |
483 | //! Raises an exception if FromIndex or ToIndex is out of range. |
484 | //! Example: |
485 | //! before |
486 | //! me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5 |
487 | //! after |
488 | //! me = "aabAa" |
489 | //! returns |
490 | //! 5 |
491 | Standard_EXPORT Standard_Integer Location (const Standard_Integer N, const Standard_Character C, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
492 | |
493 | //! Converts <me> to its lower-case equivalent. |
494 | //! Example |
495 | //! TCollection_AsciiString myString("Hello Dolly"); |
496 | //! myString.UpperCase(); |
497 | //! assert ( myString == "HELLO DOLLY" ); |
498 | //! myString.LowerCase(); |
499 | //! assert ( myString == "hello dolly" ); |
500 | Standard_EXPORT void LowerCase(); |
501 | |
502 | //! Inserts the string other at the beginning of this ASCII string. |
503 | //! Example |
504 | //! TCollection_AsciiString myAlphabet("cde"); |
505 | //! TCollection_AsciiString myBegin("ab"); |
506 | //! myAlphabet.Prepend(myBegin); |
507 | //! assert ( myAlphabet == "abcde" ); |
508 | Standard_EXPORT void Prepend (const TCollection_AsciiString& other); |
509 | |
510 | //! Displays <me> on a stream. |
511 | Standard_EXPORT void Print (Standard_OStream& astream) const; |
512 | friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_AsciiString& astring); |
513 | |
514 | //! Read <me> from a stream. |
515 | Standard_EXPORT void Read (Standard_IStream& astream); |
516 | friend Standard_EXPORT Standard_IStream& operator >> (Standard_IStream& astream, TCollection_AsciiString& astring); |
517 | |
518 | //! Converts an AsciiString containing a numeric expression. |
519 | //! to a Real. |
520 | //! Example: ex: "215" returns 215.0. |
521 | //! ex: "3.14159267" returns 3.14159267. |
522 | Standard_EXPORT Standard_Real RealValue() const; |
523 | |
524 | //! Remove all the occurences of the character C in the string. |
525 | //! Example: |
526 | //! before |
527 | //! me = "HellLLo", C = 'L' , CaseSensitive = True |
528 | //! after |
529 | //! me = "Hello" |
530 | Standard_EXPORT void RemoveAll (const Standard_Character C, const Standard_Boolean CaseSensitive); |
531 | |
532 | //! Removes every <what> characters from <me>. |
533 | Standard_EXPORT void RemoveAll (const Standard_Character what); |
534 | |
535 | //! Erases <ahowmany> characters from position <where>, |
536 | //! <where> included. |
537 | //! Example: |
538 | //! aString contains "Hello" |
539 | //! aString.Remove(2,2) erases 2 characters from position 2 |
540 | //! This gives "Hlo". |
541 | Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1); |
542 | |
543 | //! Removes all space characters at the end of the string. |
544 | Standard_EXPORT void RightAdjust(); |
545 | |
546 | //! Right justify. |
547 | //! Length becomes equal to Width and the new characters are |
548 | //! equal to Filler. |
549 | //! if Width < Length nothing happens. |
550 | //! Raises an exception if Width is less than zero. |
551 | //! Example: |
552 | //! before |
553 | //! me = "abcdef" , Width = 9 , Filler = ' ' |
554 | //! after |
555 | //! me = " abcdef" |
556 | Standard_EXPORT void RightJustify (const Standard_Integer Width, const Standard_Character Filler); |
557 | |
558 | //! Searches a CString in <me> from the beginning |
559 | //! and returns position of first item <what> matching. |
560 | //! it returns -1 if not found. |
561 | //! Example: |
562 | //! aString contains "Sample single test" |
563 | //! aString.Search("le") returns 5 |
564 | Standard_EXPORT Standard_Integer Search (const Standard_CString what) const; |
565 | |
566 | //! Searches an AsciiString in <me> from the beginning |
567 | //! and returns position of first item <what> matching. |
568 | //! It returns -1 if not found. |
569 | Standard_EXPORT Standard_Integer Search (const TCollection_AsciiString& what) const; |
570 | |
571 | //! Searches a CString in a AsciiString from the end |
572 | //! and returns position of first item <what> matching. |
573 | //! It returns -1 if not found. |
574 | //! Example: |
575 | //! aString contains "Sample single test" |
576 | //! aString.SearchFromEnd("le") returns 12 |
577 | Standard_EXPORT Standard_Integer SearchFromEnd (const Standard_CString what) const; |
578 | |
579 | //! Searches a AsciiString in another AsciiString from the end |
580 | //! and returns position of first item <what> matching. |
581 | //! It returns -1 if not found. |
582 | Standard_EXPORT Standard_Integer SearchFromEnd (const TCollection_AsciiString& what) const; |
583 | |
584 | //! Replaces one character in the AsciiString at position <where>. |
585 | //! If <where> is less than zero or greater than the length of <me> |
586 | //! an exception is raised. |
587 | //! Example: |
588 | //! aString contains "Garbake" |
589 | //! astring.Replace(6,'g') gives <me> = "Garbage" |
590 | Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_Character what); |
591 | |
592 | //! Replaces a part of <me> by a CString. |
593 | //! If <where> is less than zero or greater than the length of <me> |
594 | //! an exception is raised. |
595 | //! Example: |
596 | //! aString contains "abcde" |
597 | //! aString.SetValue(4,"1234567") gives <me> = "abc1234567" |
598 | Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_CString what); |
599 | |
600 | //! Replaces a part of <me> by another AsciiString. |
601 | Standard_EXPORT void SetValue (const Standard_Integer where, const TCollection_AsciiString& what); |
602 | |
603 | //! Splits a AsciiString into two sub-strings. |
604 | //! Example: |
605 | //! aString contains "abcdefg" |
606 | //! aString.Split(3) gives <me> = "abc" and returns "defg" |
607 | Standard_EXPORT TCollection_AsciiString Split (const Standard_Integer where); |
608 | |
609 | //! Creation of a sub-string of the string <me>. |
610 | //! The sub-string starts to the index Fromindex and ends |
611 | //! to the index ToIndex. |
612 | //! Raises an exception if ToIndex or FromIndex is out of bounds |
613 | //! Example: |
614 | //! before |
615 | //! me = "abcdefg", ToIndex=3, FromIndex=6 |
616 | //! after |
617 | //! me = "abcdefg" |
618 | //! returns |
619 | //! "cdef" |
620 | TCollection_AsciiString SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex) const; |
621 | |
622 | //! Returns pointer to AsciiString (char *). |
623 | //! This is useful for some casual manipulations. |
624 | //! Warning: Because this "char *" is 'const', you can't modify its contents. |
625 | Standard_CString ToCString() const; |
626 | |
627 | //! Extracts <whichone> token from <me>. |
628 | //! By default, the <separators> is set to space and tabulation. |
629 | //! By default, the token extracted is the first one (whichone = 1). |
630 | //! <separators> contains all separators you need. |
631 | //! If no token indexed by <whichone> is found, it returns empty AsciiString. |
632 | //! Example: |
633 | //! aString contains "This is a message" |
634 | //! aString.Token() returns "This" |
635 | //! aString.Token(" ",4) returns "message" |
636 | //! aString.Token(" ",2) returns "is" |
637 | //! aString.Token(" ",9) returns "" |
638 | //! Other separators than space character and tabulation are allowed : |
639 | //! aString contains "1234; test:message , value" |
640 | //! aString.Token("; :,",4) returns "value" |
641 | //! aString.Token("; :,",2) returns "test" |
642 | Standard_EXPORT TCollection_AsciiString Token (const Standard_CString separators = " \t", const Standard_Integer whichone = 1) const; |
643 | |
644 | //! Truncates <me> to <ahowmany> characters. |
645 | //! Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel" |
646 | Standard_EXPORT void Trunc (const Standard_Integer ahowmany); |
647 | |
648 | //! Converts <me> to its upper-case equivalent. |
649 | Standard_EXPORT void UpperCase(); |
650 | |
651 | //! Length of the string ignoring all spaces (' ') and the |
652 | //! control character at the end. |
653 | Standard_EXPORT Standard_Integer UsefullLength() const; |
654 | |
655 | //! Returns character at position <where> in <me>. |
656 | //! If <where> is less than zero or greater than the lenght of <me>, |
657 | //! an exception is raised. |
658 | //! Example: |
659 | //! aString contains "Hello" |
660 | //! aString.Value(2) returns 'e' |
661 | Standard_EXPORT Standard_Character Value (const Standard_Integer where) const; |
662 | |
663 | //! Hash function for AsciiString |
664 | //! (returns the same Integer value that the hash function for ExtendedString) |
665 | static Standard_Integer HashCode (const TCollection_AsciiString& astring, const Standard_Integer Upper); |
666 | |
667 | //! Returns True when the two strings are the same. |
668 | //! (Just for HashCode for AsciiString) |
669 | static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const TCollection_AsciiString& string2); |
670 | |
671 | //! Returns True when the two strings are the same. |
672 | //! (Just for HashCode for AsciiString) |
673 | static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const Standard_CString string2); |
674 | |
26d9c835 |
675 | //! Returns True if the strings contain same characters. |
676 | Standard_EXPORT static Standard_Boolean IsSameString (const TCollection_AsciiString& theString1, |
677 | const TCollection_AsciiString& theString2, |
678 | const Standard_Boolean theIsCaseSensitive); |
42cf5bc1 |
679 | |
680 | friend class TCollection_HAsciiString; |
681 | |
42cf5bc1 |
682 | private: |
683 | |
42cf5bc1 |
684 | Standard_EXPORT void Split (const Standard_Integer where, TCollection_AsciiString& result); |
685 | |
686 | Standard_EXPORT void SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex, TCollection_AsciiString& result) const; |
687 | |
688 | Standard_EXPORT void Token (const Standard_CString separators, const Standard_Integer whichone, TCollection_AsciiString& result) const; |
689 | |
fb0b0531 |
690 | private: |
42cf5bc1 |
691 | |
fb0b0531 |
692 | Standard_PCharacter mystring; //!< NULL-terminated string |
693 | Standard_Integer mylength; //!< length in bytes (excluding terminating NULL symbol) |
42cf5bc1 |
694 | |
695 | }; |
696 | |
42cf5bc1 |
697 | #include <TCollection_AsciiString.lxx> |
698 | |
42cf5bc1 |
699 | #endif // _TCollection_AsciiString_HeaderFile |