0027960: Configuration - fix compilation of OSD_Directory with MinGW-w64
[occt.git] / src / TCollection / TCollection_AsciiString.hxx
CommitLineData
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>
32class Standard_NullObject;
33class Standard_OutOfRange;
34class Standard_NumericError;
35class Standard_NegativeValue;
36class TCollection_HAsciiString;
37class 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 52class TCollection_AsciiString
53{
54public:
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);
113void 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);
120void 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);
127void 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);
139void 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);
147void 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);
260void 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);
269void 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;
353Standard_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;
362Standard_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;
371Standard_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;
380Standard_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;
387Standard_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;
394Standard_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;
401Standard_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;
408Standard_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;
512friend 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);
516friend 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
680friend class TCollection_HAsciiString;
681
42cf5bc1 682private:
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 690private:
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