src/TCollection/TCollection_AsciiString.hxx

   1 // Created on: 1993-02-22
   2 // Created by: Mireille MERCIEN
   3 // Copyright (c) 1993-1999 Matra Datavision
   4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 //
   6 // This file is part of Open CASCADE Technology software library.
   7 //
   8 // This library is free software; you can redistribute it and/or modify it under
   9 // the terms of the GNU Lesser General Public License version 2.1 as published
  10 // by the Free Software Foundation, with special exception defined in the file
  11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 // distribution for complete text of the license and disclaimer of any warranty.
  13 //
  14 // Alternatively, this file may be used under the terms of Open CASCADE
  15 // commercial license or contractual agreement.
  16
  17 #ifndef _TCollection_AsciiString_HeaderFile
  18 #define _TCollection_AsciiString_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_DefineAlloc.hxx>
  22 #include <Standard_Handle.hxx>
  23
  24 #include <Standard_PCharacter.hxx>
  25 #include <Standard_Integer.hxx>
  26 #include <Standard_CString.hxx>
  27 #include <Standard_Character.hxx>
  28 #include <Standard_Real.hxx>
  29 #include <Standard_Boolean.hxx>
  30 #include <Standard_OStream.hxx>
  31 #include <Standard_IStream.hxx>
  32 class Standard_NullObject;
  33 class Standard_OutOfRange;
  34 class Standard_NumericError;
  35 class Standard_NegativeValue;
  36 class TCollection_HAsciiString;
  37 class TCollection_ExtendedString;
  38
  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.
  52 class TCollection_AsciiString
  53 {
  54 public:
  55
  56   DEFINE_STANDARD_ALLOC
  57
  58
  59   //! Initializes a AsciiString to an empty AsciiString.
  60   Standard_EXPORT TCollection_AsciiString();
  61
  62   //! Initializes a AsciiString with a CString.
  63   Standard_EXPORT TCollection_AsciiString(const Standard_CString message);
  64
  65   //! Initializes a AsciiString with a CString.
  66   Standard_EXPORT TCollection_AsciiString(const Standard_CString message, const Standard_Integer aLen);
  67
  68   //! Initializes a AsciiString with a single character.
  69   Standard_EXPORT TCollection_AsciiString(const Standard_Character aChar);
  70
  71   //! Initializes an AsciiString with <length> space allocated.
  72   //! and filled with <filler>. This is usefull for buffers.
  73   Standard_EXPORT TCollection_AsciiString(const Standard_Integer length, const Standard_Character filler);
  74
  75   //! Initializes an AsciiString with an integer value
  76   Standard_EXPORT TCollection_AsciiString(const Standard_Integer value);
  77
  78   //! Initializes an AsciiString with a real value
  79   Standard_EXPORT TCollection_AsciiString(const Standard_Real value);
  80
  81   //! Initializes a AsciiString with another AsciiString.
  82   Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring);
  83
  84   //! Initializes a AsciiString with copy of another AsciiString
  85   //! concatenated with the message character.
  86   Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_Character message);
  87
  88   //! Initializes a AsciiString with copy of another AsciiString
  89   //! concatenated with the message string.
  90   Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const Standard_CString message);
  91
  92   //! Initializes a AsciiString with copy of another AsciiString
  93   //! concatenated with the message string.
  94   Standard_EXPORT TCollection_AsciiString(const TCollection_AsciiString& astring, const TCollection_AsciiString& message);
  95
  96   //! Creation by converting an extended string to an ascii string.
  97   //! If replaceNonAscii is non-null charecter, it will be used
  98   //! in place of any non-ascii character found in the source string.
  99   //! Otherwise, creates UTF-8 unicode string.
 100   Standard_EXPORT TCollection_AsciiString(const TCollection_ExtendedString& astring, const Standard_Character replaceNonAscii = 0);
 101
 102 #if !defined(_WIN32) || defined(_NATIVE_WCHAR_T_DEFINED)
 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
 111   //! Appends <other>  to me. This is an unary operator.
 112   Standard_EXPORT void AssignCat (const Standard_Character other);
 113 void operator += (const Standard_Character other)
 114 {
 115   AssignCat(other);
 116 }
 117
 118   //! Appends <other>  to me. This is an unary operator.
 119   Standard_EXPORT void AssignCat (const Standard_Integer other);
 120 void operator += (const Standard_Integer other)
 121 {
 122   AssignCat(other);
 123 }
 124
 125   //! Appends <other>  to me. This is an unary operator.
 126   Standard_EXPORT void AssignCat (const Standard_Real other);
 127 void operator += (const Standard_Real other)
 128 {
 129   AssignCat(other);
 130 }
 131
 132   //! Appends <other>  to me. This is an unary operator.
 133   //! ex: aString += "Dummy"
 134   //! To catenate more than one CString, you must put a
 135   //! AsciiString before.
 136   //! Example: aString += "Hello " + "Dolly"  IS NOT VALID !
 137   //! But astring += anotherString + "Hello " + "Dolly" is valid.
 138   Standard_EXPORT void AssignCat (const Standard_CString other);
 139 void operator += (const Standard_CString other)
 140 {
 141   AssignCat(other);
 142 }
 143
 144   //! Appends <other> to me. This is an unary operator.
 145   //! Example: aString += anotherString
 146   Standard_EXPORT void AssignCat (const TCollection_AsciiString& other);
 147 void operator += (const TCollection_AsciiString& other)
 148 {
 149   AssignCat(other);
 150 }
 151
 152   //! Converts the first character into its corresponding
 153   //! upper-case character and the other characters into lowercase
 154   //! Example: before
 155   //! me = "hellO "
 156   //! after
 157   //! me = "Hello "
 158   Standard_EXPORT void Capitalize();
 159
 160   //! Appends <other>  to me.
 161   //! Syntax:
 162   //! aString = aString + "Dummy"
 163   //! Example: aString contains "I say "
 164   //! aString = aString + "Hello " + "Dolly"
 165   //! gives "I say Hello Dolly"
 166   //! To catenate more than one CString, you must put a String before.
 167   //! So the following example is WRONG !
 168   //! aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 169   //! This rule is applicable to AssignCat (operator +=) too.
 170     TCollection_AsciiString Cat (const Standard_Character other) const;
 171   TCollection_AsciiString operator + (const Standard_Character other) const
 172 {
 173   return Cat(other);
 174 }
 175
 176   //! Appends <other>  to me.
 177   //! Syntax:
 178   //! aString = aString + 15;
 179   //! Example: aString contains "I say "
 180   //! gives "I say 15"
 181   //! To catenate more than one CString, you must put a String before.
 182   //! So the following example is WRONG !
 183   //! aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 184   //! This rule is applicable to AssignCat (operator +=) too.
 185     TCollection_AsciiString Cat (const Standard_Integer other) const;
 186   TCollection_AsciiString operator + (const Standard_Integer other) const
 187 {
 188   return Cat(other);
 189 }
 190
 191   //! Appends <other>  to me.
 192   //! Syntax:
 193   //! aString = aString + 15.15;
 194   //! Example: aString contains "I say "
 195   //! gives "I say 15.15"
 196   //! To catenate more than one CString, you must put a String before.
 197   //! So the following example is WRONG !
 198   //! aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 199   //! This rule is applicable to AssignCat (operator +=) too.
 200     TCollection_AsciiString Cat (const Standard_Real other) const;
 201   TCollection_AsciiString operator + (const Standard_Real other) const
 202 {
 203   return Cat(other);
 204 }
 205
 206   //! Appends <other>  to me.
 207   //! Syntax:
 208   //! aString = aString + "Dummy"
 209   //! Example: aString contains "I say "
 210   //! aString = aString + "Hello " + "Dolly"
 211   //! gives "I say Hello Dolly"
 212   //! To catenate more than one CString, you must put a String before.
 213   //! So the following example is WRONG !
 214   //! aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
 215   //! This rule is applicable to AssignCat (operator +=) too.
 216     TCollection_AsciiString Cat (const Standard_CString other) const;
 217   TCollection_AsciiString operator + (const Standard_CString other) const
 218 {
 219   return Cat(other);
 220 }
 221
 222   //! Appends <other> to me.
 223   //! Example: aString = aString + anotherString
 224     TCollection_AsciiString Cat (const TCollection_AsciiString& other) const;
 225   TCollection_AsciiString operator + (const TCollection_AsciiString& other) const
 226 {
 227   return Cat(other);
 228 }
 229
 230   //! Modifies this ASCII string so that its length
 231   //! becomes equal to Width and the new characters
 232   //! are equal to Filler. New characters are added
 233   //! both at the beginning and at the end of this string.
 234   //! If Width is less than the length of this ASCII string, nothing happens.
 235   //! Example
 236   //! TCollection_AsciiString
 237   //! myAlphabet("abcdef");
 238   //! myAlphabet.Center(9,' ');
 239   //! assert ( myAlphabet == "
 240   //! abcdef " );
 241   Standard_EXPORT void Center (const Standard_Integer Width, const Standard_Character Filler);
 242
 243   //! Substitutes all the characters equal to aChar by NewChar
 244   //! in the AsciiString <me>.
 245   //! The substitution can be case sensitive.
 246   //! If you don't use default case sensitive, no matter wether aChar
 247   //! is uppercase or not.
 248   //! Example: me = "Histake" -> ChangeAll('H','M',Standard_True)
 249   //! gives me = "Mistake"
 250   Standard_EXPORT void ChangeAll (const Standard_Character aChar, const Standard_Character NewChar, const Standard_Boolean CaseSensitive = Standard_True);
 251
 252   //! Removes all characters contained in <me>.
 253   //! This produces an empty AsciiString.
 254   Standard_EXPORT void Clear();
 255
 256   //! Copy <fromwhere> to <me>.
 257   //! Used as operator =
 258   //! Example: aString = anotherCString;
 259   Standard_EXPORT void Copy (const Standard_CString fromwhere);
 260 void operator = (const Standard_CString fromwhere)
 261 {
 262   Copy(fromwhere);
 263 }
 264
 265   //! Copy <fromwhere> to <me>.
 266   //! Used as operator =
 267   //! Example: aString = anotherString;
 268   Standard_EXPORT void Copy (const TCollection_AsciiString& fromwhere);
 269 void operator = (const TCollection_AsciiString& fromwhere)
 270 {
 271   Copy(fromwhere);
 272 }
 273
 274   //! Frees memory allocated by AsciiString.
 275   Standard_EXPORT ~TCollection_AsciiString();
 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.
 347   Standard_Boolean IsEmpty() const { return mylength == 0; }
 348
 349   //! Returns true if the characters in this ASCII string
 350   //! are identical to the characters in ASCII string other.
 351   //! Note that this method is an alias of operator ==.
 352   Standard_EXPORT Standard_Boolean IsEqual (const Standard_CString other) const;
 353 Standard_Boolean operator == (const Standard_CString other) const
 354 {
 355   return IsEqual(other);
 356 }
 357
 358   //! Returns true if the characters in this ASCII string
 359   //! are identical to the characters in ASCII string other.
 360   //! Note that this method is an alias of operator ==.
 361   Standard_EXPORT Standard_Boolean IsEqual (const TCollection_AsciiString& other) const;
 362 Standard_Boolean operator == (const TCollection_AsciiString& other) const
 363 {
 364   return IsEqual(other);
 365 }
 366
 367   //! Returns true if there are differences between the
 368   //! characters in this ASCII string and ASCII string other.
 369   //! Note that this method is an alias of operator !=
 370   Standard_EXPORT Standard_Boolean IsDifferent (const Standard_CString other) const;
 371 Standard_Boolean operator != (const Standard_CString other) const
 372 {
 373   return IsDifferent(other);
 374 }
 375
 376   //! Returns true if there are differences between the
 377   //! characters in this ASCII string and ASCII string other.
 378   //! Note that this method is an alias of operator !=
 379   Standard_EXPORT Standard_Boolean IsDifferent (const TCollection_AsciiString& other) const;
 380 Standard_Boolean operator != (const TCollection_AsciiString& other) const
 381 {
 382   return IsDifferent(other);
 383 }
 384
 385   //! Returns TRUE if <me> is 'ASCII' less than <other>.
 386   Standard_EXPORT Standard_Boolean IsLess (const Standard_CString other) const;
 387 Standard_Boolean operator < (const Standard_CString other) const
 388 {
 389   return IsLess(other);
 390 }
 391
 392   //! Returns TRUE if <me> is 'ASCII' less than <other>.
 393   Standard_EXPORT Standard_Boolean IsLess (const TCollection_AsciiString& other) const;
 394 Standard_Boolean operator < (const TCollection_AsciiString& other) const
 395 {
 396   return IsLess(other);
 397 }
 398
 399   //! Returns TRUE if <me> is 'ASCII' greater than <other>.
 400   Standard_EXPORT Standard_Boolean IsGreater (const Standard_CString other) const;
 401 Standard_Boolean operator > (const Standard_CString other) const
 402 {
 403   return IsGreater(other);
 404 }
 405
 406   //! Returns TRUE if <me> is 'ASCII' greater than <other>.
 407   Standard_EXPORT Standard_Boolean IsGreater (const TCollection_AsciiString& other) const;
 408 Standard_Boolean operator > (const TCollection_AsciiString& other) const
 409 {
 410   return IsGreater(other);
 411 }
 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
 419   //! Converts a AsciiString containing a numeric expression to
 420   //! an Integer.
 421   //! Example: "215" returns 215.
 422   Standard_EXPORT Standard_Integer IntegerValue() const;
 423
 424   //! Returns True if the AsciiString contains an integer value.
 425   //! Note: an integer value is considered to be a real value as well.
 426   Standard_EXPORT Standard_Boolean IsIntegerValue() const;
 427
 428   //! Returns True if the AsciiString contains a real value.
 429   //! Note: an integer value is considered to be a real value as well.
 430   Standard_EXPORT Standard_Boolean IsRealValue() const;
 431
 432   //! Returns True if the AsciiString contains only ASCII characters
 433   //! between ' ' and '~'.
 434   //! This means no control character and no extended ASCII code.
 435   Standard_EXPORT Standard_Boolean IsAscii() const;
 436
 437   //! Removes all space characters in the begining of the string.
 438   Standard_EXPORT void LeftAdjust();
 439
 440   //! left justify
 441   //! Length becomes equal to Width and the new characters are
 442   //! equal to Filler.
 443   //! If Width < Length nothing happens.
 444   //! Raises an exception if Width is less than zero.
 445   //! Example:
 446   //! before
 447   //! me = "abcdef" , Width = 9 , Filler = ' '
 448   //! after
 449   //! me = "abcdef   "
 450   Standard_EXPORT void LeftJustify (const Standard_Integer Width, const Standard_Character Filler);
 451
 452   //! Returns number of characters in <me>.
 453   //! This is the same functionality as 'strlen' in C.
 454   //! Example
 455   //! TCollection_AsciiString myAlphabet("abcdef");
 456   //! assert ( myAlphabet.Length() == 6 );
 457   //! -   1 is the position of the first character in this string.
 458   //! -   The length of this string gives the position of its last character.
 459   //! -   Positions less than or equal to zero, or
 460   //! greater than the length of this string are
 461   //! invalid in functions which identify a character
 462   //! of this string by its position.
 463     Standard_Integer Length() const;
 464
 465   //! Returns an index in the string <me> of the first occurence
 466   //! of the string S in the string <me> from the starting index
 467   //! FromIndex to the ending index ToIndex
 468   //! returns zero if failure
 469   //! Raises an exception if FromIndex or ToIndex is out of range.
 470   //! Example:
 471   //! before
 472   //! me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
 473   //! after
 474   //! me = "aabAaAa"
 475   //! returns
 476   //! 4
 477   Standard_EXPORT Standard_Integer Location (const TCollection_AsciiString& other, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
 478
 479   //! Returns the index of the nth occurence of the character C
 480   //! in the string <me> from the starting index FromIndex to the
 481   //! ending index ToIndex.
 482   //! Returns zero if failure.
 483   //! Raises an exception if FromIndex or ToIndex is out of range.
 484   //! Example:
 485   //! before
 486   //! me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
 487   //! after
 488   //! me = "aabAa"
 489   //! returns
 490   //! 5
 491   Standard_EXPORT Standard_Integer Location (const Standard_Integer N, const Standard_Character C, const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
 492
 493   //! Converts <me> to its lower-case equivalent.
 494   //! Example
 495   //! TCollection_AsciiString myString("Hello Dolly");
 496   //! myString.UpperCase();
 497   //! assert ( myString == "HELLO DOLLY" );
 498   //! myString.LowerCase();
 499   //! assert ( myString == "hello dolly" );
 500   Standard_EXPORT void LowerCase();
 501
 502   //! Inserts the string other at the beginning of this ASCII string.
 503   //! Example
 504   //! TCollection_AsciiString myAlphabet("cde");
 505   //! TCollection_AsciiString myBegin("ab");
 506   //! myAlphabet.Prepend(myBegin);
 507   //! assert ( myAlphabet == "abcde" );
 508   Standard_EXPORT void Prepend (const TCollection_AsciiString& other);
 509
 510   //! Displays <me> on a stream.
 511   Standard_EXPORT void Print (Standard_OStream& astream) const;
 512 friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_AsciiString& astring);
 513
 514   //! Read <me> from a stream.
 515   Standard_EXPORT void Read (Standard_IStream& astream);
 516 friend Standard_EXPORT Standard_IStream& operator >> (Standard_IStream& astream, TCollection_AsciiString& astring);
 517
 518   //! Converts an AsciiString containing a numeric expression.
 519   //! to a Real.
 520   //! Example: ex: "215" returns 215.0.
 521   //! ex: "3.14159267" returns 3.14159267.
 522   Standard_EXPORT Standard_Real RealValue() const;
 523
 524   //! Remove all the occurences of the character C in the string.
 525   //! Example:
 526   //! before
 527   //! me = "HellLLo", C = 'L' , CaseSensitive = True
 528   //! after
 529   //! me = "Hello"
 530   Standard_EXPORT void RemoveAll (const Standard_Character C, const Standard_Boolean CaseSensitive);
 531
 532   //! Removes every <what> characters from <me>.
 533   Standard_EXPORT void RemoveAll (const Standard_Character what);
 534
 535   //! Erases <ahowmany> characters from position <where>,
 536   //! <where> included.
 537   //! Example:
 538   //! aString contains "Hello"
 539   //! aString.Remove(2,2) erases 2 characters from position 2
 540   //! This gives "Hlo".
 541   Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1);
 542
 543   //! Removes all space characters at the end of the string.
 544   Standard_EXPORT void RightAdjust();
 545
 546   //! Right justify.
 547   //! Length becomes equal to Width and the new characters are
 548   //! equal to Filler.
 549   //! if Width < Length nothing happens.
 550   //! Raises an exception if Width is less than zero.
 551   //! Example:
 552   //! before
 553   //! me = "abcdef" , Width = 9 , Filler = ' '
 554   //! after
 555   //! me = "   abcdef"
 556   Standard_EXPORT void RightJustify (const Standard_Integer Width, const Standard_Character Filler);
 557
 558   //! Searches a CString in <me> from the beginning
 559   //! and returns position of first item <what> matching.
 560   //! it returns -1 if not found.
 561   //! Example:
 562   //! aString contains "Sample single test"
 563   //! aString.Search("le") returns 5
 564   Standard_EXPORT Standard_Integer Search (const Standard_CString what) const;
 565
 566   //! Searches an AsciiString in <me> from the beginning
 567   //! and returns position of first item <what> matching.
 568   //! It returns -1 if not found.
 569   Standard_EXPORT Standard_Integer Search (const TCollection_AsciiString& what) const;
 570
 571   //! Searches a CString in a AsciiString from the end
 572   //! and returns position of first item <what> matching.
 573   //! It returns -1 if not found.
 574   //! Example:
 575   //! aString contains "Sample single test"
 576   //! aString.SearchFromEnd("le") returns 12
 577   Standard_EXPORT Standard_Integer SearchFromEnd (const Standard_CString what) const;
 578
 579   //! Searches a AsciiString in another AsciiString from the end
 580   //! and returns position of first item <what> matching.
 581   //! It returns -1 if not found.
 582   Standard_EXPORT Standard_Integer SearchFromEnd (const TCollection_AsciiString& what) const;
 583
 584   //! Replaces one character in the AsciiString at position <where>.
 585   //! If <where> is less than zero or greater than the length of <me>
 586   //! an exception is raised.
 587   //! Example:
 588   //! aString contains "Garbake"
 589   //! astring.Replace(6,'g')  gives <me> = "Garbage"
 590   Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_Character what);
 591
 592   //! Replaces a part of <me> by a CString.
 593   //! If <where> is less than zero or greater than the length of <me>
 594   //! an exception is raised.
 595   //! Example:
 596   //! aString contains "abcde"
 597   //! aString.SetValue(4,"1234567") gives <me> = "abc1234567"
 598   Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_CString what);
 599
 600   //! Replaces a part of <me> by another AsciiString.
 601   Standard_EXPORT void SetValue (const Standard_Integer where, const TCollection_AsciiString& what);
 602
 603   //! Splits a AsciiString into two sub-strings.
 604   //! Example:
 605   //! aString contains "abcdefg"
 606   //! aString.Split(3) gives <me> = "abc" and returns "defg"
 607   Standard_EXPORT TCollection_AsciiString Split (const Standard_Integer where);
 608
 609   //! Creation of a sub-string of the string <me>.
 610   //! The sub-string starts to the index Fromindex and ends
 611   //! to the index ToIndex.
 612   //! Raises an exception if ToIndex or FromIndex is out of bounds
 613   //! Example:
 614   //! before
 615   //! me = "abcdefg", ToIndex=3, FromIndex=6
 616   //! after
 617   //! me = "abcdefg"
 618   //! returns
 619   //! "cdef"
 620     TCollection_AsciiString SubString (const Standard_Integer FromIndex, const Standard_Integer ToIndex) const;
 621
 622   //! Returns pointer to AsciiString (char *).
 623   //! This is useful for some casual manipulations.
 624   //! Warning: Because this "char *" is 'const', you can't modify its contents.
 625     Standard_CString ToCString() const;
 626
 627   //! Extracts <whichone> token from <me>.
 628   //! By default, the <separators> is set to space and tabulation.
 629   //! By default, the token extracted is the first one (whichone = 1).
 630   //! <separators> contains all separators you need.
 631   //! If no token indexed by <whichone> is found, it returns empty AsciiString.
 632   //! Example:
 633   //! aString contains "This is a     message"
 634   //! aString.Token()  returns "This"
 635   //! aString.Token(" ",4) returns "message"
 636   //! aString.Token(" ",2) returns "is"
 637   //! aString.Token(" ",9) returns ""
 638   //! Other separators than space character and tabulation are allowed :
 639   //! aString contains "1234; test:message   , value"
 640   //! aString.Token("; :,",4) returns "value"
 641   //! aString.Token("; :,",2) returns "test"
 642   Standard_EXPORT TCollection_AsciiString Token (const Standard_CString separators = " \t", const Standard_Integer whichone = 1) const;
 643
 644   //! Truncates <me> to <ahowmany> characters.
 645   //! Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
 646   Standard_EXPORT void Trunc (const Standard_Integer ahowmany);
 647
 648   //! Converts <me> to its upper-case equivalent.
 649   Standard_EXPORT void UpperCase();
 650
 651   //! Length of the string ignoring all spaces (' ') and the
 652   //! control character at the end.
 653   Standard_EXPORT Standard_Integer UsefullLength() const;
 654
 655   //! Returns character at position <where> in <me>.
 656   //! If <where> is less than zero or greater than the lenght of <me>,
 657   //! an exception is raised.
 658   //! Example:
 659   //! aString contains "Hello"
 660   //! aString.Value(2) returns 'e'
 661   Standard_EXPORT Standard_Character Value (const Standard_Integer where) const;
 662
 663   //! Hash function for AsciiString
 664   //! (returns the same Integer value that the hash function for ExtendedString)
 665     static Standard_Integer HashCode (const TCollection_AsciiString& astring, const Standard_Integer Upper);
 666
 667   //! Returns True  when the two  strings are the same.
 668   //! (Just for HashCode for AsciiString)
 669     static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const TCollection_AsciiString& string2);
 670
 671   //! Returns True  when the two  strings are the same.
 672   //! (Just for HashCode for AsciiString)
 673     static Standard_Boolean IsEqual (const TCollection_AsciiString& string1, const Standard_CString string2);
 674
 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);
 679
 680 friend class TCollection_HAsciiString;
 681
 682 private:
 683
 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
 690 private:
 691
 692   Standard_PCharacter mystring; //!< NULL-terminated string
 693   Standard_Integer    mylength; //!< length in bytes (excluding terminating NULL symbol)
 694
 695 };
 696
 697 #include <TCollection_AsciiString.lxx>
 698
 699 #endif // _TCollection_AsciiString_HeaderFile