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
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _TCollection_AsciiString_HeaderFile
18 #define _TCollection_AsciiString_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
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;
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).
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.
52 class TCollection_AsciiString
59 //! Initializes a AsciiString to an empty AsciiString.
60 Standard_EXPORT TCollection_AsciiString();
62 //! Initializes a AsciiString with a CString.
63 Standard_EXPORT TCollection_AsciiString(const Standard_CString message);
65 //! Initializes a AsciiString with a CString.
66 Standard_EXPORT TCollection_AsciiString(const Standard_CString message, const Standard_Integer aLen);
68 //! Initializes a AsciiString with a single character.
69 Standard_EXPORT TCollection_AsciiString(const Standard_Character aChar);
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);
75 //! Initializes an AsciiString with an integer value
76 Standard_EXPORT TCollection_AsciiString(const Standard_Integer value);
78 //! Initializes an AsciiString with a real value
79 Standard_EXPORT TCollection_AsciiString(const Standard_Real value);
81 //! Initializes a AsciiString with another AsciiString.
82 Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring);
84 #ifndef OCCT_NO_RVALUE_REFERENCE
86 TCollection_AsciiString (TCollection_AsciiString&& theOther)
87 : mystring (theOther.mystring),
88 mylength (theOther.mylength)
90 theOther.mystring = NULL;
91 theOther.mylength = 0;
95 //! Initializes a AsciiString with copy of another AsciiString
96 //! concatenated with the message character.
97 Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_Character message);
99 //! Initializes a AsciiString with copy of another AsciiString
100 //! concatenated with the message string.
101 Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_CString message);
103 //! Initializes a AsciiString with copy of another AsciiString
104 //! concatenated with the message string.
105 Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const TCollection_AsciiString& message);
107 //! Creation by converting an extended string to an ascii string.
108 //! If replaceNonAscii is non-null charecter, it will be used
109 //! in place of any non-ascii character found in the source string.
110 //! Otherwise, creates UTF-8 unicode string.
111 Standard_EXPORT TCollection_AsciiString(const TCollection_ExtendedString& astring, const Standard_Character replaceNonAscii = 0);
113 #if !defined(_MSC_VER) || defined(_NATIVE_WCHAR_T_DEFINED)
114 //! Initialize UTF-8 Unicode string from wide-char string considering it as Unicode string
115 //! (the size of wide char is a platform-dependent - e.g. on Windows wchar_t is UTF-16).
117 //! This constructor is unavailable if application is built with deprecated msvc option "-Zc:wchar_t-",
118 //! since OCCT itself is never built with this option.
119 Standard_EXPORT TCollection_AsciiString (const Standard_WideChar* theStringUtf);
122 //! Appends <other> to me. This is an unary operator.
123 Standard_EXPORT void AssignCat (const Standard_Character other);
124 void operator += (const Standard_Character other)
129 //! Appends <other> to me. This is an unary operator.
130 Standard_EXPORT void AssignCat (const Standard_Integer other);
131 void operator += (const Standard_Integer other)
136 //! Appends <other> to me. This is an unary operator.
137 Standard_EXPORT void AssignCat (const Standard_Real other);
138 void operator += (const Standard_Real other)
143 //! Appends <other> to me. This is an unary operator.
144 //! ex: aString += "Dummy"
145 //! To catenate more than one CString, you must put a
146 //! AsciiString before.
147 //! Example: aString += "Hello " + "Dolly" IS NOT VALID !
148 //! But astring += anotherString + "Hello " + "Dolly" is valid.
149 Standard_EXPORT void AssignCat (const Standard_CString other);
150 void operator += (const Standard_CString other)
155 //! Appends <other> to me. This is an unary operator.
156 //! Example: aString += anotherString
157 Standard_EXPORT void AssignCat (const TCollection_AsciiString& other);
158 void operator += (const TCollection_AsciiString& other)
163 //! Converts the first character into its corresponding
164 //! upper-case character and the other characters into lowercase
169 Standard_EXPORT void Capitalize();
171 //! Appends <other> to me.
173 //! aString = aString + "Dummy"
174 //! Example: aString contains "I say "
175 //! aString = aString + "Hello " + "Dolly"
176 //! gives "I say Hello Dolly"
177 //! To catenate more than one CString, you must put a String before.
178 //! So the following example is WRONG !
179 //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED
180 //! This rule is applicable to AssignCat (operator +=) too.
181 TCollection_AsciiString Cat (const Standard_Character other) const;
182 TCollection_AsciiString operator + (const Standard_Character other) const
187 //! Appends <other> to me.
189 //! aString = aString + 15;
190 //! Example: aString contains "I say "
192 //! To catenate more than one CString, you must put a String before.
193 //! So the following example is WRONG !
194 //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED
195 //! This rule is applicable to AssignCat (operator +=) too.
196 TCollection_AsciiString Cat (const Standard_Integer other) const;
197 TCollection_AsciiString operator + (const Standard_Integer other) const
202 //! Appends <other> to me.
204 //! aString = aString + 15.15;
205 //! Example: aString contains "I say "
206 //! gives "I say 15.15"
207 //! To catenate more than one CString, you must put a String before.
208 //! So the following example is WRONG !
209 //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED
210 //! This rule is applicable to AssignCat (operator +=) too.
211 TCollection_AsciiString Cat (const Standard_Real other) const;
212 TCollection_AsciiString operator + (const Standard_Real other) const
217 //! Appends <other> to me.
219 //! aString = aString + "Dummy"
220 //! Example: aString contains "I say "
221 //! aString = aString + "Hello " + "Dolly"
222 //! gives "I say Hello Dolly"
223 //! To catenate more than one CString, you must put a String before.
224 //! So the following example is WRONG !
225 //! aString = "Hello " + "Dolly" THIS IS NOT ALLOWED
226 //! This rule is applicable to AssignCat (operator +=) too.
227 TCollection_AsciiString Cat (const Standard_CString other) const;
228 TCollection_AsciiString operator + (const Standard_CString other) const
233 //! Appends <other> to me.
234 //! Example: aString = aString + anotherString
235 TCollection_AsciiString Cat (const TCollection_AsciiString& other) const;
236 TCollection_AsciiString operator + (const TCollection_AsciiString& other) const
241 //! Modifies this ASCII string so that its length
242 //! becomes equal to Width and the new characters
243 //! are equal to Filler. New characters are added
244 //! both at the beginning and at the end of this string.
245 //! If Width is less than the length of this ASCII string, nothing happens.
247 //! TCollection_AsciiString
248 //! myAlphabet("abcdef");
249 //! myAlphabet.Center(9,' ');
250 //! assert ( myAlphabet == "
252 Standard_EXPORT void Center (const Standard_Integer Width, const Standard_Character Filler);
254 //! Substitutes all the characters equal to aChar by NewChar
255 //! in the AsciiString <me>.
256 //! The substitution can be case sensitive.
257 //! If you don't use default case sensitive, no matter wether aChar
258 //! is uppercase or not.
259 //! Example: me = "Histake" -> ChangeAll('H','M',Standard_True)
260 //! gives me = "Mistake"
261 Standard_EXPORT void ChangeAll (const Standard_Character aChar, const Standard_Character NewChar, const Standard_Boolean CaseSensitive = Standard_True);
263 //! Removes all characters contained in <me>.
264 //! This produces an empty AsciiString.
265 Standard_EXPORT void Clear();
267 //! Copy <fromwhere> to <me>.
268 //! Used as operator =
269 //! Example: aString = anotherCString;
270 Standard_EXPORT void Copy (const Standard_CString fromwhere);
271 void operator = (const Standard_CString fromwhere)
276 //! Copy <fromwhere> to <me>.
277 //! Used as operator =
278 //! Example: aString = anotherString;
279 Standard_EXPORT void Copy (const TCollection_AsciiString& fromwhere);
280 void operator = (const TCollection_AsciiString& fromwhere)
285 //! Exchange the data of two strings (without reallocating memory).
286 Standard_EXPORT void Swap (TCollection_AsciiString& theOther);
288 #ifndef OCCT_NO_RVALUE_REFERENCE
289 //! Move assignment operator
290 TCollection_AsciiString& operator= (TCollection_AsciiString&& theOther) { Swap (theOther); return *this; }
293 //! Frees memory allocated by AsciiString.
294 Standard_EXPORT ~TCollection_AsciiString();
296 //! Returns the index of the first character of <me> that is
297 //! present in <Set>.
298 //! The search begins to the index FromIndex and ends to the
299 //! the index ToIndex.
300 //! Returns zero if failure.
301 //! Raises an exception if FromIndex or ToIndex is out of range.
303 //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
308 Standard_EXPORT Standard_Integer FirstLocationInSet (const TCollection_AsciiString& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
310 //! Returns the index of the first character of <me>
311 //! that is not present in the set <Set>.
312 //! The search begins to the index FromIndex and ends to the
313 //! the index ToIndex in <me>.
314 //! Returns zero if failure.
315 //! Raises an exception if FromIndex or ToIndex is out of range.
317 //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
322 Standard_EXPORT Standard_Integer FirstLocationNotInSet (const TCollection_AsciiString& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
324 //! Inserts a Character at position <where>.
326 //! aString contains "hy not ?"
327 //! aString.Insert(1,'W'); gives "Why not ?"
328 //! aString contains "Wh"
329 //! aString.Insert(3,'y'); gives "Why"
330 //! aString contains "Way"
331 //! aString.Insert(2,'h'); gives "Why"
332 Standard_EXPORT void Insert (const Standard_Integer where, const Standard_Character what);
334 //! Inserts a CString at position <where>.
336 //! aString contains "O more"
337 //! aString.Insert(2,"nce"); gives "Once more"
338 Standard_EXPORT void Insert (const Standard_Integer where, const Standard_CString what);
340 //! Inserts a AsciiString at position <where>.
341 Standard_EXPORT void Insert (const Standard_Integer where, const TCollection_AsciiString& what);
343 //! Pushing a string after a specific index in the string <me>.
344 //! Raises an exception if Index is out of bounds.
345 //! - less than 0 (InsertAfter), or less than 1 (InsertBefore), or
346 //! - greater than the number of characters in this ASCII string.
349 //! me = "cde" , Index = 0 , other = "ab"
351 //! me = "abcde" , other = "ab"
352 Standard_EXPORT void InsertAfter (const Standard_Integer Index, const TCollection_AsciiString& other);
354 //! Pushing a string before a specific index in the string <me>.
355 //! Raises an exception if Index is out of bounds.
356 //! - less than 0 (InsertAfter), or less than 1 (InsertBefore), or
357 //! - greater than the number of characters in this ASCII string.
360 //! me = "cde" , Index = 1 , other = "ab"
362 //! me = "abcde" , other = "ab"
363 Standard_EXPORT void InsertBefore (const Standard_Integer Index, const TCollection_AsciiString& other);
365 //! Returns True if the string <me> contains zero character.
366 Standard_Boolean IsEmpty() const { return mylength == 0; }
368 //! Returns true if the characters in this ASCII string
369 //! are identical to the characters in ASCII string other.
370 //! Note that this method is an alias of operator ==.
371 Standard_EXPORT Standard_Boolean IsEqual (const Standard_CString other) const;
372 Standard_Boolean operator == (const Standard_CString other) const
374 return IsEqual(other);
377 //! Returns true if the characters in this ASCII string
378 //! are identical to the characters in ASCII string other.
379 //! Note that this method is an alias of operator ==.
380 Standard_EXPORT Standard_Boolean IsEqual (const TCollection_AsciiString& other) const;
381 Standard_Boolean operator == (const TCollection_AsciiString& other) const
383 return IsEqual(other);
386 //! Returns true if there are differences between the
387 //! characters in this ASCII string and ASCII string other.
388 //! Note that this method is an alias of operator !=
389 Standard_EXPORT Standard_Boolean IsDifferent (const Standard_CString other) const;
390 Standard_Boolean operator != (const Standard_CString other) const
392 return IsDifferent(other);
395 //! Returns true if there are differences between the
396 //! characters in this ASCII string and ASCII string other.
397 //! Note that this method is an alias of operator !=
398 Standard_EXPORT Standard_Boolean IsDifferent (const TCollection_AsciiString& other) const;
399 Standard_Boolean operator != (const TCollection_AsciiString& other) const
401 return IsDifferent(other);
404 //! Returns TRUE if <me> is 'ASCII' less than <other>.
405 Standard_EXPORT Standard_Boolean IsLess (const Standard_CString other) const;
406 Standard_Boolean operator < (const Standard_CString other) const
408 return IsLess(other);
411 //! Returns TRUE if <me> is 'ASCII' less than <other>.
412 Standard_EXPORT Standard_Boolean IsLess (const TCollection_AsciiString& other) const;
413 Standard_Boolean operator < (const TCollection_AsciiString& other) const
415 return IsLess(other);
418 //! Returns TRUE if <me> is 'ASCII' greater than <other>.
419 Standard_EXPORT Standard_Boolean IsGreater (const Standard_CString other) const;
420 Standard_Boolean operator > (const Standard_CString other) const
422 return IsGreater(other);
425 //! Returns TRUE if <me> is 'ASCII' greater than <other>.
426 Standard_EXPORT Standard_Boolean IsGreater (const TCollection_AsciiString& other) const;
427 Standard_Boolean operator > (const TCollection_AsciiString& other) const
429 return IsGreater(other);
432 //! Determines whether the beginning of this string instance matches the specified string.
433 Standard_EXPORT Standard_Boolean StartsWith (const TCollection_AsciiString& theStartString) const;
435 //! Determines whether the end of this string instance matches the specified string.
436 Standard_EXPORT Standard_Boolean EndsWith (const TCollection_AsciiString& theEndString) const;
438 //! Converts a AsciiString containing a numeric expression to
440 //! Example: "215" returns 215.
441 Standard_EXPORT Standard_Integer IntegerValue() const;
443 //! Returns True if the AsciiString contains an integer value.
444 //! Note: an integer value is considered to be a real value as well.
445 Standard_EXPORT Standard_Boolean IsIntegerValue() const;
447 //! Returns True if the AsciiString contains a real value.
448 //! Note: an integer value is considered to be a real value as well.
449 Standard_EXPORT Standard_Boolean IsRealValue() const;
451 //! Returns True if the AsciiString contains only ASCII characters
452 //! between ' ' and '~'.
453 //! This means no control character and no extended ASCII code.
454 Standard_EXPORT Standard_Boolean IsAscii() const;
456 //! Removes all space characters in the begining of the string.
457 Standard_EXPORT void LeftAdjust();
460 //! Length becomes equal to Width and the new characters are
462 //! If Width < Length nothing happens.
463 //! Raises an exception if Width is less than zero.
466 //! me = "abcdef" , Width = 9 , Filler = ' '
469 Standard_EXPORT void LeftJustify (const Standard_Integer Width, const Standard_Character Filler);
471 //! Returns number of characters in <me>.
472 //! This is the same functionality as 'strlen' in C.
474 //! TCollection_AsciiString myAlphabet("abcdef");
475 //! assert ( myAlphabet.Length() == 6 );
476 //! - 1 is the position of the first character in this string.
477 //! - The length of this string gives the position of its last character.
478 //! - Positions less than or equal to zero, or
479 //! greater than the length of this string are
480 //! invalid in functions which identify a character
481 //! of this string by its position.
482 Standard_Integer Length() const;
484 //! Returns an index in the string <me> of the first occurence
485 //! of the string S in the string <me> from the starting index
486 //! FromIndex to the ending index ToIndex
487 //! returns zero if failure
488 //! Raises an exception if FromIndex or ToIndex is out of range.
491 //! me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
496 Standard_EXPORT Standard_Integer Location (const TCollection_AsciiString& other, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
498 //! Returns the index of the nth occurence of the character C
499 //! in the string <me> from the starting index FromIndex to the
500 //! ending index ToIndex.
501 //! Returns zero if failure.
502 //! Raises an exception if FromIndex or ToIndex is out of range.
505 //! me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
510 Standard_EXPORT Standard_Integer Location (const Standard_Integer N, const Standard_Character C, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
512 //! Converts <me> to its lower-case equivalent.
514 //! TCollection_AsciiString myString("Hello Dolly");
515 //! myString.UpperCase();
516 //! assert ( myString == "HELLO DOLLY" );
517 //! myString.LowerCase();
518 //! assert ( myString == "hello dolly" );
519 Standard_EXPORT void LowerCase();
521 //! Inserts the string other at the beginning of this ASCII string.
523 //! TCollection_AsciiString myAlphabet("cde");
524 //! TCollection_AsciiString myBegin("ab");
525 //! myAlphabet.Prepend(myBegin);
526 //! assert ( myAlphabet == "abcde" );
527 Standard_EXPORT void Prepend (const TCollection_AsciiString& other);
529 //! Displays <me> on a stream.
530 Standard_EXPORT void Print (Standard_OStream& astream) const;
531 friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_AsciiString& astring);
533 //! Read <me> from a stream.
534 Standard_EXPORT void Read (Standard_IStream& astream);
535 friend Standard_EXPORT Standard_IStream& operator >> (Standard_IStream& astream, TCollection_AsciiString& astring);
537 //! Converts an AsciiString containing a numeric expression.
539 //! Example: ex: "215" returns 215.0.
540 //! ex: "3.14159267" returns 3.14159267.
541 Standard_EXPORT Standard_Real RealValue() const;
543 //! Remove all the occurences of the character C in the string.
546 //! me = "HellLLo", C = 'L' , CaseSensitive = True
549 Standard_EXPORT void RemoveAll (const Standard_Character C, const Standard_Boolean CaseSensitive);
551 //! Removes every <what> characters from <me>.
552 Standard_EXPORT void RemoveAll (const Standard_Character what);
554 //! Erases <ahowmany> characters from position <where>,
555 //! <where> included.
557 //! aString contains "Hello"
558 //! aString.Remove(2,2) erases 2 characters from position 2
559 //! This gives "Hlo".
560 Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1);
562 //! Removes all space characters at the end of the string.
563 Standard_EXPORT void RightAdjust();
566 //! Length becomes equal to Width and the new characters are
568 //! if Width < Length nothing happens.
569 //! Raises an exception if Width is less than zero.
572 //! me = "abcdef" , Width = 9 , Filler = ' '
575 Standard_EXPORT void RightJustify (const Standard_Integer Width, const Standard_Character Filler);
577 //! Searches a CString in <me> from the beginning
578 //! and returns position of first item <what> matching.
579 //! it returns -1 if not found.
581 //! aString contains "Sample single test"
582 //! aString.Search("le") returns 5
583 Standard_EXPORT Standard_Integer Search (const Standard_CString what) const;
585 //! Searches an AsciiString in <me> from the beginning
586 //! and returns position of first item <what> matching.
587 //! It returns -1 if not found.
588 Standard_EXPORT Standard_Integer Search (const TCollection_AsciiString& what) const;
590 //! Searches a CString in a AsciiString from the end
591 //! and returns position of first item <what> matching.
592 //! It returns -1 if not found.
594 //! aString contains "Sample single test"
595 //! aString.SearchFromEnd("le") returns 12
596 Standard_EXPORT Standard_Integer SearchFromEnd (const Standard_CString what) const;
598 //! Searches a AsciiString in another AsciiString from the end
599 //! and returns position of first item <what> matching.
600 //! It returns -1 if not found.
601 Standard_EXPORT Standard_Integer SearchFromEnd (const TCollection_AsciiString& what) const;
603 //! Replaces one character in the AsciiString at position <where>.
604 //! If <where> is less than zero or greater than the length of <me>
605 //! an exception is raised.
607 //! aString contains "Garbake"
608 //! astring.Replace(6,'g') gives <me> = "Garbage"
609 Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_Character what);
611 //! Replaces a part of <me> by a CString.
612 //! If <where> is less than zero or greater than the length of <me>
613 //! an exception is raised.
615 //! aString contains "abcde"
616 //! aString.SetValue(4,"1234567") gives <me> = "abc1234567"
617 Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_CString what);
619 //! Replaces a part of <me> by another AsciiString.
620 Standard_EXPORT void SetValue (const Standard_Integer where, const TCollection_AsciiString& what);
622 //! Splits a AsciiString into two sub-strings.
624 //! aString contains "abcdefg"
625 //! aString.Split(3) gives <me> = "abc" and returns "defg"
626 Standard_EXPORT TCollection_AsciiString Split (const Standard_Integer where);
628 //! Creation of a sub-string of the string <me>.
629 //! The sub-string starts to the index Fromindex and ends
630 //! to the index ToIndex.
631 //! Raises an exception if ToIndex or FromIndex is out of bounds
634 //! me = "abcdefg", ToIndex=3, FromIndex=6
639 TCollection_AsciiString SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
641 //! Returns pointer to AsciiString (char *).
642 //! This is useful for some casual manipulations.
643 //! Warning: Because this "char *" is 'const', you can't modify its contents.
644 Standard_CString ToCString() const;
646 //! Extracts <whichone> token from <me>.
647 //! By default, the <separators> is set to space and tabulation.
648 //! By default, the token extracted is the first one (whichone = 1).
649 //! <separators> contains all separators you need.
650 //! If no token indexed by <whichone> is found, it returns empty AsciiString.
652 //! aString contains "This is a message"
653 //! aString.Token() returns "This"
654 //! aString.Token(" ",4) returns "message"
655 //! aString.Token(" ",2) returns "is"
656 //! aString.Token(" ",9) returns ""
657 //! Other separators than space character and tabulation are allowed :
658 //! aString contains "1234; test:message , value"
659 //! aString.Token("; :,",4) returns "value"
660 //! aString.Token("; :,",2) returns "test"
661 Standard_EXPORT TCollection_AsciiString Token (const Standard_CString separators = " \t", const Standard_Integer whichone = 1) const;
663 //! Truncates <me> to <ahowmany> characters.
664 //! Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
665 Standard_EXPORT void Trunc (const Standard_Integer ahowmany);
667 //! Converts <me> to its upper-case equivalent.
668 Standard_EXPORT void UpperCase();
670 //! Length of the string ignoring all spaces (' ') and the
671 //! control character at the end.
672 Standard_EXPORT Standard_Integer UsefullLength() const;
674 //! Returns character at position <where> in <me>.
675 //! If <where> is less than zero or greater than the lenght of <me>,
676 //! an exception is raised.
678 //! aString contains "Hello"
679 //! aString.Value(2) returns 'e'
680 Standard_EXPORT Standard_Character Value (const Standard_Integer where) const;
682 //! Hash function for AsciiString
683 //! (returns the same Integer value that the hash function for ExtendedString)
684 static Standard_Integer HashCode (const TCollection_AsciiString& astring, const Standard_Integer Upper);
686 //! Returns True when the two strings are the same.
687 //! (Just for HashCode for AsciiString)
688 static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const TCollection_AsciiString& string2);
690 //! Returns True when the two strings are the same.
691 //! (Just for HashCode for AsciiString)
692 static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const Standard_CString string2);
694 //! Returns True if the strings contain same characters.
695 Standard_EXPORT static Standard_Boolean IsSameString (const TCollection_AsciiString& theString1,
696 const TCollection_AsciiString& theString2,
697 const Standard_Boolean theIsCaseSensitive);
699 friend class TCollection_HAsciiString;
703 Standard_EXPORT void Split (const Standard_Integer where, TCollection_AsciiString& result);
705 Standard_EXPORT void SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex, TCollection_AsciiString& result) const;
707 Standard_EXPORT void Token (const Standard_CString separators, const Standard_Integer whichone, TCollection_AsciiString& result) const;
711 Standard_PCharacter mystring; //!< NULL-terminated string
712 Standard_Integer mylength; //!< length in bytes (excluding terminating NULL symbol)
716 #include <TCollection_AsciiString.lxx>
718 #endif // _TCollection_AsciiString_HeaderFile