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
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_HAsciiString_HeaderFile
18 #define _TCollection_HAsciiString_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <TCollection_AsciiString.hxx>
24 #include <Standard_Transient.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;
39 class TCollection_HAsciiString;
40 DEFINE_STANDARD_HANDLE(TCollection_HAsciiString, Standard_Transient)
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 Standard_Transient
56 //! Initializes a HAsciiString to an empty AsciiString.
57 Standard_EXPORT TCollection_HAsciiString();
59 //! Initializes a HAsciiString with a CString.
60 Standard_EXPORT TCollection_HAsciiString(const Standard_CString message);
62 //! Initializes a HAsciiString with a single character.
63 Standard_EXPORT TCollection_HAsciiString(const Standard_Character aChar);
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);
69 //! Initializes a HAsciiString with an integer value
70 Standard_EXPORT TCollection_HAsciiString(const Standard_Integer value);
72 //! Initializes a HAsciiString with a real value
73 Standard_EXPORT TCollection_HAsciiString(const Standard_Real value);
75 //! Initializes a HAsciiString with a HAsciiString.
76 Standard_EXPORT TCollection_HAsciiString(const TCollection_AsciiString& aString);
78 //! Initializes a HAsciiString with a HAsciiString.
79 Standard_EXPORT TCollection_HAsciiString(const Handle(TCollection_HAsciiString)& aString);
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);
88 //! Appends <other> to me.
89 void AssignCat (const Standard_CString other);
91 //! Appends <other> to me.
92 //! Example: aString = aString + anotherString
93 void AssignCat (const Handle(TCollection_HAsciiString)& other);
95 //! Converts the first character into its corresponding
96 //! upper-case character and the other characters into lowercase.
102 Standard_EXPORT void Capitalize();
104 //! Creates a new string by concatenation of this
105 //! ASCII string and the other ASCII string.
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;
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;
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.
129 //! Handle(TCollection_HAsciiString)
132 //! TCollection_HAsciiString
134 //! myAlphabet->Center(9,' ');
135 //! assert ( !strcmp(
136 //! myAlphabet->ToCString(),
138 Standard_EXPORT void Center (const Standard_Integer Width, const Standard_Character Filler);
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.
146 //! Handle(TCollection_HAsciiString)
148 //! TCollection_HAsciiString
150 //! myMistake->ChangeAll('H','F');
151 //! assert ( !strcmp(
152 //! myMistake->ToCString(),
154 Standard_EXPORT void ChangeAll (const Standard_Character aChar, const Standard_Character NewChar, const Standard_Boolean CaseSensitive = Standard_True);
156 //! Removes all characters contained in <me>.
157 //! This produces an empty HAsciiString.
158 Standard_EXPORT void Clear();
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
168 //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
173 Standard_EXPORT Standard_Integer FirstLocationInSet (const Handle(TCollection_HAsciiString)& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
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.
183 //! me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
188 Standard_EXPORT Standard_Integer FirstLocationNotInSet (const Handle(TCollection_HAsciiString)& Set, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
190 //! Insert a Character at position <where>.
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);
200 //! Insert a HAsciiString at position <where>.
201 Standard_EXPORT void Insert (const Standard_Integer where, const Standard_CString what);
203 //! Insert a HAsciiString at position <where>.
204 Standard_EXPORT void Insert (const Standard_Integer where, const Handle(TCollection_HAsciiString)& what);
206 //! Inserts the other ASCII string a after a specific index in the string <me>
209 //! me = "cde" , Index = 0 , other = "ab"
211 //! me = "abcde" , other = "ab"
212 Standard_EXPORT void InsertAfter (const Standard_Integer Index, const Handle(TCollection_HAsciiString)& other);
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
218 //! me = "cde" , Index = 1 , other = "ab"
220 //! me = "abcde" , other = "ab"
221 Standard_EXPORT void InsertBefore (const Standard_Integer Index, const Handle(TCollection_HAsciiString)& other);
223 //! Returns True if the string <me> contains zero character
224 Standard_EXPORT Standard_Boolean IsEmpty() const;
226 //! Returns TRUE if <me> is 'ASCII' less than <other>.
227 Standard_EXPORT Standard_Boolean IsLess (const Handle(TCollection_HAsciiString)& other) const;
229 //! Returns TRUE if <me> is 'ASCII' greater than <other>.
230 Standard_EXPORT Standard_Boolean IsGreater (const Handle(TCollection_HAsciiString)& other) const;
232 //! Converts a HAsciiString containing a numeric expression to
234 //! Example: "215" returns 215.
235 Standard_EXPORT Standard_Integer IntegerValue() const;
237 //! Returns True if the string contains an integer value.
238 Standard_EXPORT Standard_Boolean IsIntegerValue() const;
240 //! Returns True if the string contains a real value.
241 Standard_EXPORT Standard_Boolean IsRealValue() const;
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;
248 //! Returns True if the string S not contains same characters than
250 Standard_EXPORT Standard_Boolean IsDifferent (const Handle(TCollection_HAsciiString)& S) const;
252 //! Returns True if the string S contains same characters than the
254 Standard_EXPORT Standard_Boolean IsSameString (const Handle(TCollection_HAsciiString)& S) const;
256 //! Returns True if the string S contains same characters than the
258 Standard_EXPORT Standard_Boolean IsSameString (const Handle(TCollection_HAsciiString)& S, const Standard_Boolean CaseSensitive) const;
260 //! Removes all space characters in the begining of the string
261 Standard_EXPORT void LeftAdjust();
264 //! Length becomes equal to Width and the new characters are
266 //! if Width < Length nothing happens
267 //! Raises an exception if Width is less than zero
270 //! me = "abcdef" , Width = 9 , Filler = ' '
273 Standard_EXPORT void LeftJustify (const Standard_Integer Width, const Standard_Character Filler);
275 //! Returns number of characters in <me>.
276 //! This is the same functionality as 'strlen' in C.
277 Standard_Integer Length() const;
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.
286 //! me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
291 Standard_EXPORT Standard_Integer Location (const Handle(TCollection_HAsciiString)& other, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
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
300 //! me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
304 Standard_EXPORT Standard_Integer Location (const Standard_Integer N, const Standard_Character C, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
306 //! Converts <me> to its lower-case equivalent.
307 Standard_EXPORT void LowerCase();
309 //! Inserts the other string at the begining of the string <me>
312 //! me = "cde" , S = "ab"
314 //! me = "abcde" , S = "ab"
315 Standard_EXPORT void Prepend (const Handle(TCollection_HAsciiString)& other);
317 //! Prints this string on the stream <astream>.
318 Standard_EXPORT void Print (Standard_OStream& astream) const;
320 //! Converts a string containing a numeric expression to a Real.
322 //! "215" returns 215.0.
323 //! "3.14159267" returns 3.14159267.
324 Standard_EXPORT Standard_Real RealValue() const;
326 //! Remove all the occurences of the character C in the string
329 //! me = "HellLLo", C = 'L' , CaseSensitive = True
332 Standard_EXPORT void RemoveAll (const Standard_Character C, const Standard_Boolean CaseSensitive);
334 //! Removes every <what> characters from <me>
335 Standard_EXPORT void RemoveAll (const Standard_Character what);
337 //! Erases <ahowmany> characters from position <where>,
338 //! <where> included.
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);
345 //! Removes all space characters at the end of the string.
346 Standard_EXPORT void RightAdjust();
349 //! Length becomes equal to Width and the new characters are
351 //! if Width < Length nothing happens
352 //! Raises an exception if Width is less than zero
355 //! me = "abcdef" , Width = 9 , Filler = ' '
358 Standard_EXPORT void RightJustify (const Standard_Integer Width, const Standard_Character Filler);
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.
364 //! aString contains "Sample single test"
365 //! aString.Search("le") returns 5
366 Standard_EXPORT Standard_Integer Search (const Standard_CString what) const;
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;
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.
377 //! aString contains "Sample single test"
378 //! aString.SearchFromEnd("le") returns 12
379 Standard_EXPORT Standard_Integer SearchFromEnd (const Standard_CString what) const;
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;
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.
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);
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.
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);
402 //! Replaces a part of <me> by another string.
403 Standard_EXPORT void SetValue (const Standard_Integer where, const Handle(TCollection_HAsciiString)& what);
405 //! Splits a HAsciiString into two sub-strings.
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);
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
418 //! me = "abcdefg", ToIndex=3, FromIndex=6
423 Standard_EXPORT Handle(TCollection_HAsciiString) SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
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;
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.
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;
447 //! Truncates <me> to <ahowmany> characters.
448 //! Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
449 Standard_EXPORT void Trunc (const Standard_Integer ahowmany);
451 //! Converts <me> to its upper-case equivalent.
452 Standard_EXPORT void UpperCase();
454 //! Length of the string ignoring all spaces (' ') and the
455 //! control character at the end.
456 Standard_EXPORT Standard_Integer UsefullLength() const;
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.
462 //! aString contains "Hello"
463 //! aString.Value(2) returns 'e'
464 Standard_EXPORT Standard_Character Value (const Standard_Integer where) const;
466 //! Returns the field myString.
467 const TCollection_AsciiString& String() const;
469 Standard_EXPORT Standard_Boolean IsSameState (const Handle(TCollection_HAsciiString)& other) const;
474 DEFINE_STANDARD_RTTIEXT(TCollection_HAsciiString,Standard_Transient)
484 TCollection_AsciiString myString;
490 #include <TCollection_HAsciiString.lxx>
496 #endif // _TCollection_HAsciiString_HeaderFile