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