0027960: Configuration - fix compilation of OSD_Directory with MinGW-w64
[occt.git] / src / TCollection / TCollection_ExtendedString.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_ExtendedString_HeaderFile
18#define _TCollection_ExtendedString_HeaderFile
19
20#include <Standard.hxx>
21#include <Standard_DefineAlloc.hxx>
22#include <Standard_Handle.hxx>
23
24#include <Standard_PExtCharacter.hxx>
25#include <Standard_Integer.hxx>
26#include <Standard_CString.hxx>
27#include <Standard_Boolean.hxx>
28#include <Standard_ExtString.hxx>
29#include <Standard_Character.hxx>
30#include <Standard_ExtCharacter.hxx>
31#include <Standard_Real.hxx>
32#include <Standard_OStream.hxx>
33#include <Standard_PCharacter.hxx>
34class Standard_NullObject;
35class Standard_OutOfRange;
36class Standard_NumericError;
37class Standard_NegativeValue;
38class TCollection_AsciiString;
39
40
fb0b0531 41//! A variable-length sequence of "extended" (UNICODE) characters (16-bit character type).
42//! It provides editing operations with built-in memory management
43//! to make ExtendedString objects easier to use than ordinary extended character arrays.
44//! ExtendedString objects follow "value semantics", that is, they are the actual strings,
45//! not handles to strings, and are copied through assignment.
46//! You may use HExtendedString objects to get handles to strings.
47//!
48//! Beware that class can transparently store UTF-16 string with surrogate pairs
49//! (Unicode symbol represented by two 16-bit code units).
50//! However, surrogate pairs are not considered by the following methods:
51//! - Method ::Length() return the number of 16-bit code units, not the number of Unicode symbols.
52//! - Methods taking/returning symbol index work with 16-bit code units, not true Unicode symbols,
53//! including ::Remove(), ::SetValue(), ::Value(), ::Search(), ::Trunc() and others.
54//! If application needs to process surrogate pairs, NCollection_Utf16Iter class can be used
55//! for iterating through Unicode string (UTF-32 code unit will be returned for each position).
42cf5bc1 56class TCollection_ExtendedString
57{
58public:
59
60 DEFINE_STANDARD_ALLOC
61
62
63 //! Initializes a ExtendedString to an empty ExtendedString.
64 Standard_EXPORT TCollection_ExtendedString();
65
66 //! Creation by converting a CString to an extended
67 //! string. If <isMultiByte> is true then the string is
68 //! treated as having UTF-8 coding. If it is not a UTF-8
69 //! then <isMultiByte> is ignored and each character is
70 //! copied to ExtCharacter.
71 Standard_EXPORT TCollection_ExtendedString(const Standard_CString astring, const Standard_Boolean isMultiByte = Standard_False);
72
73 //! Creation by converting an ExtString to an extended string.
74 Standard_EXPORT TCollection_ExtendedString(const Standard_ExtString astring);
fb0b0531 75
15173be5 76#if !defined(_MSC_VER) || defined(_NATIVE_WCHAR_T_DEFINED)
fb0b0531 77 //! Initialize from wide-char string considering it as Unicode string
78 //! (the size of wide char is a platform-dependent - e.g. on Windows wchar_t is UTF-16).
79 //!
80 //! This constructor is unavailable if application is built with deprecated msvc option "-Zc:wchar_t-",
81 //! since OCCT itself is never built with this option.
82 Standard_EXPORT TCollection_ExtendedString (const Standard_WideChar* theStringUtf);
83#endif
42cf5bc1 84
85 //! Initializes a AsciiString with a single character.
86 Standard_EXPORT TCollection_ExtendedString(const Standard_Character aChar);
87
88 //! Initializes a ExtendedString with a single character.
89 Standard_EXPORT TCollection_ExtendedString(const Standard_ExtCharacter aChar);
90
91 //! Initializes a ExtendedString with <length> space allocated.
92 //! and filled with <filler>.This is useful for buffers.
93 Standard_EXPORT TCollection_ExtendedString(const Standard_Integer length, const Standard_ExtCharacter filler);
94
95 //! Initializes an ExtendedString with an integer value
96 Standard_EXPORT TCollection_ExtendedString(const Standard_Integer value);
97
98 //! Initializes an ExtendedString with a real value
99 Standard_EXPORT TCollection_ExtendedString(const Standard_Real value);
100
101 //! Initializes a ExtendedString with another ExtendedString.
102 Standard_EXPORT TCollection_ExtendedString(const TCollection_ExtendedString& astring);
103
104 //! Creation by converting an Ascii string to an extended
105 //! string. The string is treated as having UTF-8 coding.
106 //! If it is not a UTF-8 then each character is copied to ExtCharacter.
107 Standard_EXPORT TCollection_ExtendedString(const TCollection_AsciiString& astring);
108
109 //! Appends the other extended string to this extended string.
110 //! Note that this method is an alias of operator +=.
111 //! Example: aString += anotherString
112 Standard_EXPORT void AssignCat (const TCollection_ExtendedString& other);
113void operator += (const TCollection_ExtendedString& other)
114{
115 AssignCat(other);
116}
117
118 //! Appends <other> to me.
119 Standard_EXPORT TCollection_ExtendedString Cat (const TCollection_ExtendedString& other) const;
120TCollection_ExtendedString operator + (const TCollection_ExtendedString& other) const
121{
122 return Cat(other);
123}
124
125 //! Substitutes all the characters equal to aChar by NewChar
126 //! in the ExtendedString <me>.
127 //! The substitution can be case sensitive.
128 //! If you don't use default case sensitive, no matter wether aChar
129 //! is uppercase or not.
130 Standard_EXPORT void ChangeAll (const Standard_ExtCharacter aChar, const Standard_ExtCharacter NewChar);
131
132 //! Removes all characters contained in <me>.
133 //! This produces an empty ExtendedString.
134 Standard_EXPORT void Clear();
135
136 //! Copy <fromwhere> to <me>.
137 //! Used as operator =
138 Standard_EXPORT void Copy (const TCollection_ExtendedString& fromwhere);
139void operator = (const TCollection_ExtendedString& fromwhere)
140{
141 Copy(fromwhere);
142}
143
144 //! Frees memory allocated by ExtendedString.
fb0b0531 145 Standard_EXPORT ~TCollection_ExtendedString();
42cf5bc1 146
147 //! Insert a Character at position <where>.
148 Standard_EXPORT void Insert (const Standard_Integer where, const Standard_ExtCharacter what);
149
150 //! Insert a ExtendedString at position <where>.
151 Standard_EXPORT void Insert (const Standard_Integer where, const TCollection_ExtendedString& what);
fb0b0531 152
42cf5bc1 153 //! Returns True if this string contains no characters.
fb0b0531 154 Standard_Boolean IsEmpty() const { return mylength == 0; }
155
42cf5bc1 156 //! Returns true if the characters in this extended
157 //! string are identical to the characters in the other extended string.
158 //! Note that this method is an alias of operator ==
159 Standard_EXPORT Standard_Boolean IsEqual (const Standard_ExtString other) const;
160Standard_Boolean operator == (const Standard_ExtString other) const
161{
162 return IsEqual(other);
163}
164
165 //! Returns true if the characters in this extended
166 //! string are identical to the characters in the other extended string.
167 //! Note that this method is an alias of operator ==
168 Standard_EXPORT Standard_Boolean IsEqual (const TCollection_ExtendedString& other) const;
169Standard_Boolean operator == (const TCollection_ExtendedString& other) const
170{
171 return IsEqual(other);
172}
173
174 //! Returns true if there are differences between the
175 //! characters in this extended string and the other extended string.
176 //! Note that this method is an alias of operator !=.
177 Standard_EXPORT Standard_Boolean IsDifferent (const Standard_ExtString other) const;
178Standard_Boolean operator != (const Standard_ExtString other) const
179{
180 return IsDifferent(other);
181}
182
183 //! Returns true if there are differences between the
184 //! characters in this extended string and the other extended string.
185 //! Note that this method is an alias of operator !=.
186 Standard_EXPORT Standard_Boolean IsDifferent (const TCollection_ExtendedString& other) const;
187Standard_Boolean operator != (const TCollection_ExtendedString& other) const
188{
189 return IsDifferent(other);
190}
191
192 //! Returns TRUE if <me> is less than <other>.
193 Standard_EXPORT Standard_Boolean IsLess (const Standard_ExtString other) const;
194Standard_Boolean operator < (const Standard_ExtString other) const
195{
196 return IsLess(other);
197}
198
199 //! Returns TRUE if <me> is less than <other>.
200 Standard_EXPORT Standard_Boolean IsLess (const TCollection_ExtendedString& other) const;
201Standard_Boolean operator < (const TCollection_ExtendedString& other) const
202{
203 return IsLess(other);
204}
205
206 //! Returns TRUE if <me> is greater than <other>.
207 Standard_EXPORT Standard_Boolean IsGreater (const Standard_ExtString other) const;
208Standard_Boolean operator > (const Standard_ExtString other) const
209{
210 return IsGreater(other);
211}
212
213 //! Returns TRUE if <me> is greater than <other>.
214 Standard_EXPORT Standard_Boolean IsGreater (const TCollection_ExtendedString& other) const;
215Standard_Boolean operator > (const TCollection_ExtendedString& other) const
216{
217 return IsGreater(other);
218}
fb0b0531 219
220 //! Determines whether the beginning of this string instance matches the specified string.
221 Standard_EXPORT Standard_Boolean StartsWith (const TCollection_ExtendedString& theStartString) const;
222
223 //! Determines whether the end of this string instance matches the specified string.
224 Standard_EXPORT Standard_Boolean EndsWith (const TCollection_ExtendedString& theEndString) const;
225
42cf5bc1 226 //! Returns True if the ExtendedString contains only
227 //! "Ascii Range" characters .
228 Standard_EXPORT Standard_Boolean IsAscii() const;
fb0b0531 229
230 //! Returns the number of 16-bit code units
231 //! (might be greater than number of Unicode symbols if string contains surrogate pairs).
42cf5bc1 232 Standard_EXPORT Standard_Integer Length() const;
233
234 //! Displays <me> .
235 Standard_EXPORT void Print (Standard_OStream& astream) const;
236friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_ExtendedString& astring);
237
238 //! Removes every <what> characters from <me>.
239 Standard_EXPORT void RemoveAll (const Standard_ExtCharacter what);
240
241 //! Erases <ahowmany> characters from position <where>,<where> included.
242 Standard_EXPORT void Remove (const Standard_Integer where, const Standard_Integer ahowmany = 1);
243
244 //! Searches a ExtendedString in <me> from the beginning
245 //! and returns position of first item <what> matching.
246 //! it returns -1 if not found.
247 Standard_EXPORT Standard_Integer Search (const TCollection_ExtendedString& what) const;
248
249 //! Searches a ExtendedString in another ExtendedString from the
250 //! end and returns position of first item <what> matching.
251 //! it returns -1 if not found.
252 Standard_EXPORT Standard_Integer SearchFromEnd (const TCollection_ExtendedString& what) const;
253
254 //! Replaces one character in the ExtendedString at position <where>.
255 //! If <where> is less than zero or greater than the length of <me>
256 //! an exception is raised.
257 Standard_EXPORT void SetValue (const Standard_Integer where, const Standard_ExtCharacter what);
258
259 //! Replaces a part of <me> by another ExtendedString see above.
260 Standard_EXPORT void SetValue (const Standard_Integer where, const TCollection_ExtendedString& what);
261
262 //! Splits this extended string into two sub-strings at position where.
263 //! - The second sub-string (from position
264 //! where + 1 of this string to the end) is
265 //! returned in a new extended string.
266 //! - this extended string is modified: its last
267 //! characters are removed, it becomes equal to
268 //! the first sub-string (from the first character to position where).
269 //! Example:
270 //! aString contains "abcdefg"
271 //! aString.Split(3) gives <me> = "abc" and returns "defg"
272 Standard_EXPORT TCollection_ExtendedString Split (const Standard_Integer where);
273
274 //! Extracts <whichone> token from <me>.
275 //! By default, the <separators> is set to space and tabulation.
276 //! By default, the token extracted is the first one (whichone = 1).
277 //! <separators> contains all separators you need.
278 //! If no token indexed by <whichone> is found, it returns an empty AsciiString.
279 //! Example:
280 //! aString contains "This is a message"
281 //! aString.Token() returns "This"
282 //! aString.Token(" ",4) returns "message"
283 //! aString.Token(" ",2) returns "is"
284 //! aString.Token(" ",9) returns ""
285 //! Other separators than space character and tabulation are allowed :
286 //! aString contains "1234; test:message , value"
287 //! aString.Token("; :,",4) returns "value"
288 //! aString.Token("; :,",2) returns "test"
289 Standard_EXPORT TCollection_ExtendedString Token (const Standard_ExtString separators, const Standard_Integer whichone = 1) const;
290
291 //! Returns pointer to ExtString
487bf1ce 292 Standard_EXPORT Standard_ExtString ToExtString() const;
fb0b0531 293
294#ifdef _WIN32
295 //! Returns pointer to string as wchar_t* on Windows platform where wchar_t* is considered as UTF-16 string.
296 //! This method is useful to pass string into wide-char system APIs,
297 //! and makes sense only on Windows (other systems use UTF-8 and can miss wide-char functions at all).
298 const Standard_WideChar* ToWideString() const { return (const Standard_WideChar*)ToExtString(); }
299#endif
300
42cf5bc1 301 //! Truncates <me> to <ahowmany> characters.
302 //! Example: me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
303 //! Exceptions
304 //! Standard_OutOfRange if ahowmany is greater
305 //! than the length of this string.
306 Standard_EXPORT void Trunc (const Standard_Integer ahowmany);
307
308 //! Returns character at position <where> in <me>.
309 //! If <where> is less than zero or greater than the lenght of
310 //! <me>, an exception is raised.
311 //! Example:
312 //! aString contains "Hello"
313 //! aString.Value(2) returns 'e'
314 //! Exceptions
315 //! Standard_OutOfRange if where lies outside
316 //! the bounds of this extended string.
317 Standard_EXPORT Standard_ExtCharacter Value (const Standard_Integer where) const;
fb0b0531 318
319 //! Returns a hashed value for the extended string within the range 1..theUpper.
320 //! Note: if string is ASCII, the computed value is the same as the value computed with the HashCode function on a
321 //! TCollection_AsciiString string composed with equivalent ASCII characters.
322 static Standard_Integer HashCode (const TCollection_ExtendedString& theString,
323 const Standard_Integer theUpper)
324 {
325 return ::HashCode (theString.ToExtString(), theUpper);
326 }
327
42cf5bc1 328 //! Returns true if the characters in this extended
329 //! string are identical to the characters in the other extended string.
330 //! Note that this method is an alias of operator ==.
fb0b0531 331 static Standard_Boolean IsEqual (const TCollection_ExtendedString& theString1,
332 const TCollection_ExtendedString& theString2)
333 {
334 return theString1.IsEqual (theString2);
335 }
336
42cf5bc1 337 //! Converts the internal <mystring> to UTF8 coding and
338 //! returns length of the out CString. A memory for the
339 //! <theCString> should be allocated before call!
340 Standard_EXPORT Standard_Integer ToUTF8CString (Standard_PCharacter& theCString) const;
341
342 //! Returns expected CString length in UTF8 coding.
343 //! It can be used for memory calculation before converting
344 //! to CString containing symbols in UTF8 coding.
345 Standard_EXPORT Standard_Integer LengthOfCString() const;
346
42cf5bc1 347private:
348
42cf5bc1 349 //! Returns true if the input CString was successfuly converted
350 //! to UTF8 coding
351 Standard_EXPORT Standard_Boolean ConvertToUnicode (const Standard_CString astring);
352
fb0b0531 353private:
42cf5bc1 354
fb0b0531 355 Standard_PExtCharacter mystring; //!< NULL-terminated string
356 Standard_Integer mylength; //!< length in 16-bit code units (excluding terminating NULL symbol)
42cf5bc1 357
358};
359
fb0b0531 360//! Compute hash code for extended string
361inline Standard_Integer HashCode (const TCollection_ExtendedString& theString,
362 const Standard_Integer theUpper)
363{
364 return TCollection_ExtendedString::HashCode (theString, theUpper);
365}
42cf5bc1 366
367#endif // _TCollection_ExtendedString_HeaderFile