src/TCollection/TCollection_HExtendedString.hxx

   1 // Created on: 1993-03-17
   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_HExtendedString_HeaderFile
  18 #define _TCollection_HExtendedString_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_Type.hxx>
  22
  23 #include <TCollection_ExtendedString.hxx>
  24 #include <Standard_Transient.hxx>
  25 #include <Standard_CString.hxx>
  26 #include <Standard_ExtString.hxx>
  27 #include <Standard_ExtCharacter.hxx>
  28 #include <Standard_Integer.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_ExtendedString;
  36 class TCollection_HAsciiString;
  37
  38
  39 class TCollection_HExtendedString;
  40 DEFINE_STANDARD_HANDLE(TCollection_HExtendedString, Standard_Transient)
  41
  42 //! A variable-length sequence of "extended"
  43 //! (UNICODE) characters (16-bit character
  44 //! type). It provides editing operations with
  45 //! built-in memory management to make
  46 //! ExtendedString objects easier to use than
  47 //! ordinary extended character arrays.
  48 //! HExtendedString objects are handles to strings.
  49 //! - HExtendedString strings may be shared by several objects.
  50 //! - You may use an ExtendedString object to get the actual string.
  51 //! Note: HExtendedString objects use an
  52 //! ExtendedString string as a field.
  53 class TCollection_HExtendedString : public Standard_Transient
  54 {
  55
  56 public:
  57
  58
  59   //! Initializes a HExtendedString to an empty ExtendedString.
  60   Standard_EXPORT TCollection_HExtendedString();
  61
  62   //! Initializes a HExtendedString with a CString.
  63   Standard_EXPORT TCollection_HExtendedString(const Standard_CString message);
  64
  65   //! Initializes a HExtendedString with an ExtString.
  66   Standard_EXPORT TCollection_HExtendedString(const Standard_ExtString message);
  67
  68   //! Initializes a HExtendedString with a single character.
  69   Standard_EXPORT TCollection_HExtendedString(const Standard_ExtCharacter aChar);
  70
  71   //! Initializes a HExtendedString with <length> space allocated.
  72   //! and filled with <filler>.This is usefull for buffers.
  73   Standard_EXPORT TCollection_HExtendedString(const Standard_Integer length, const Standard_ExtCharacter filler);
  74
  75   //! Initializes a HExtendedString with a HExtendedString.
  76   Standard_EXPORT TCollection_HExtendedString(const TCollection_ExtendedString& aString);
  77
  78   //! Initializes a HExtendedString with an HAsciiString.
  79   Standard_EXPORT TCollection_HExtendedString(const Handle(TCollection_HAsciiString)& aString);
  80
  81   //! Initializes a HExtendedString with a HExtendedString.
  82   Standard_EXPORT TCollection_HExtendedString(const Handle(TCollection_HExtendedString)& aString);
  83
  84   //! Appends <other>  to me.
  85   Standard_EXPORT void AssignCat (const Handle(TCollection_HExtendedString)& other);
  86
  87   //! Returns a string appending <other>  to me.
  88   Standard_EXPORT Handle(TCollection_HExtendedString) Cat (const Handle(TCollection_HExtendedString)& other) const;
  89
  90   //! Substitutes all the characters equal to aChar by NewChar
  91   //! in the string <me>.
  92   Standard_EXPORT void ChangeAll (const Standard_ExtCharacter aChar, const Standard_ExtCharacter NewChar);
  93
  94   //! Removes all characters contained in <me>.
  95   //! This produces an empty ExtendedString.
  96   Standard_EXPORT void Clear();
  97
  98   //! Returns True if the string <me> contains zero character
  99   Standard_EXPORT Standard_Boolean IsEmpty() const;
 100
 101   //! Insert a ExtCharacter at position <where>.
 102   //! Example:
 103   //! aString contains "hy not ?"
 104   //! aString.Insert(1,'W'); gives "Why not ?"
 105   //! aString contains "Wh"
 106   //! aString.Insert(3,'y'); gives "Why"
 107   //! aString contains "Way"
 108   //! aString.Insert(2,'h'); gives "Why"
 109   Standard_EXPORT void Insert (const Standard_Integer where, const Standard_ExtCharacter what);
 110
 111   //! Insert a HExtendedString at position <where>.
 112   Standard_EXPORT void Insert (const Standard_Integer where, const Handle(TCollection_HExtendedString)& what);
 113
 114   //! Returns TRUE if <me> is less than <other>.
 115   Standard_EXPORT Standard_Boolean IsLess (const Handle(TCollection_HExtendedString)& other) const;
 116
 117   //! Returns TRUE if <me> is greater than <other>.
 118   Standard_EXPORT Standard_Boolean IsGreater (const Handle(TCollection_HExtendedString)& other) const;
 119
 120   //! Returns True if the string contains only "Ascii Range"  characters
 121   Standard_EXPORT Standard_Boolean IsAscii() const;
 122
 123   //! Returns number of characters in <me>.
 124   //! This is the same functionality as 'strlen' in C.
 125   Standard_EXPORT Standard_Integer Length() const;
 126
 127   //! Erases <ahowmany> characters from position <where>,
 128   //! <where> included.
 129   //! Example:
 130   //! aString contains "Hello"
 131   //! aString.Erase(2,2) erases 2 characters from position 1
 132   //! This gives "Hlo".
 133   Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1);
 134
 135   //! Removes every <what> characters from <me>.
 136   Standard_EXPORT void RemoveAll (const Standard_ExtCharacter what);
 137
 138   //! Replaces one character in the string at position <where>.
 139   //! If <where> is less than zero or greater than the length of <me>
 140   //! an exception is raised.
 141   //! Example:
 142   //! aString contains "Garbake"
 143   //! astring.Replace(6,'g')  gives <me> = "Garbage"
 144   Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_ExtCharacter what);
 145
 146   //! Replaces a part of <me> by another string.
 147   Standard_EXPORT void SetValue (const Standard_Integer where, const Handle(TCollection_HExtendedString)& what);
 148
 149   //! Splits a ExtendedString into two sub-strings.
 150   //! Example:
 151   //! aString contains "abcdefg"
 152   //! aString.Split(3) gives <me> = "abc" and returns "defg"
 153   Standard_EXPORT Handle(TCollection_HExtendedString) Split (const Standard_Integer where);
 154
 155   //! Searches a String in <me> from the beginning
 156   //! and returns position of first item <what> matching.
 157   //! It returns -1 if not found.
 158   Standard_EXPORT Standard_Integer Search (const Handle(TCollection_HExtendedString)& what) const;
 159
 160   //! Searches a ExtendedString in another ExtendedString from the end
 161   //! and returns position of first item <what> matching.
 162   //! It returns -1 if not found.
 163   Standard_EXPORT Standard_Integer SearchFromEnd (const Handle(TCollection_HExtendedString)& what) const;
 164
 165   //! Returns pointer to ExtString
 166   Standard_ExtString ToExtString() const
 167   {
 168     return myString.ToExtString();
 169   }
 170
 171   //! Extracts <whichone> token from <me>.
 172   //! By default, the <separators> is set to space and tabulation.
 173   //! By default, the token extracted is the first one (whichone = 1).
 174   //! <separators> contains all separators you need.
 175   //! If no token indexed by <whichone> is found, it returns an empty String.
 176   //! Example:
 177   //! aString contains "This is a     message"
 178   //! aString.Token()  returns "This"
 179   //! aString.Token(" ",4) returns "message"
 180   //! aString.Token(" ",2) returns "is"
 181   //! aString.Token(" ",9) returns ""
 182   //! Other separators than space character and tabulation are allowed
 183   //! aString contains "1234; test:message   , value"
 184   //! aString.Token("; :,",4) returns "value"
 185   //! aString.Token("; :,",2) returns "test"
 186   Standard_EXPORT Handle(TCollection_HExtendedString) Token (const Standard_ExtString separators, const Standard_Integer whichone = 1) const;
 187
 188   //! Truncates <me> to <ahowmany> characters.
 189   //! Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
 190   Standard_EXPORT void Trunc (const Standard_Integer ahowmany);
 191
 192   //! Returns ExtCharacter at position <where> in <me>.
 193   //! If <where> is less than zero or greater than the length of
 194   //! <me>, an exception is raised.
 195   //! Example:
 196   //! aString contains "Hello"
 197   //! aString.Value(2) returns 'e'
 198   Standard_EXPORT Standard_ExtCharacter Value (const Standard_Integer where) const;
 199
 200   //! Returns the field myString
 201   Standard_EXPORT const TCollection_ExtendedString& String() const;
 202
 203   //! Displays <me> .
 204   Standard_EXPORT void Print (Standard_OStream& astream) const;
 205
 206   Standard_EXPORT Standard_Boolean IsSameState (const Handle(TCollection_HExtendedString)& other) const;
 207
 208
 209
 210
 211   DEFINE_STANDARD_RTTIEXT(TCollection_HExtendedString,Standard_Transient)
 212
 213 protected:
 214
 215
 216
 217
 218 private:
 219
 220
 221   //! Returns the field myString
 222   Standard_EXPORT TCollection_ExtendedString& ChangeString() const;
 223
 224   TCollection_ExtendedString myString;
 225
 226
 227 };
 228
 229
 230
 231
 232
 233
 234
 235 #endif // _TCollection_HExtendedString_HeaderFile